JSDoc: как мне документировать литерал объекта "options" для родительского "класса"?

Я использую jQuery $.widget() базовый класс, который предоставляет метод option(). Поскольку метод не находится в моем коде, у меня нет места для документирования аргумента.

Я попытался поместить jsDoc в поля в литере опций по умолчанию, но их просто не подхватили. Затем я попытался использовать теги @class и @lends в одном и том же объектном литерале, но это может быть довольно запутанным, поскольку литерал объекта не является действительно классом.

Еще одна альтернатива, которую я экспериментировал, заключается в том, чтобы добавить что-то вроде @param options.field description в конструкторе jsDoc. Однако это имеет недостаток в том, чтобы отделить документацию от кода. Кроме того, конструктор фактически не имеет аргумента, называемого options, поскольку все его обрабатывает jQuery.

Как вы справляетесь с этим Javascript-гуру? Должен ли предлагаться новый тег?

Ответы

Ответ 1

Если я правильно понял ваш вопрос, у вас есть функция, которая принимает объект options, и вы хотите документировать все ее члены?

Примерный пример того, как это сделать в JSDoc, приведен ниже:

/**
 * @description
 * Compliment someone on their something.
 *
 * @param {Object} options
 * @param {String} options.name    A person name
 * @param {String} options.feature A person property
 */
function flatter (options) {
  options = options || {};
  console.log('%s, loving your %s!', options.name, options.feature);
}