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

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

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

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

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


javascript jsdoc
person billc.cn    schedule 21.05.2012    source источник
comment
Ваш вопрос очень похож на этот: stackoverflow.com/questions/6460604/   -  person Levi Hackwith    schedule 10.06.2012
comment
@LeviHackwith Да, это похоже, но, как я описал в самом вопросе, у меня нет места, где я мог бы использовать тег @param, потому что ребята из jQuery реализовали весь шаблонный код (включая функцию options() где обычно используется тег @param.)   -  person billc.cn    schedule 15.06.2012
comment
/** @param {Object.<string,*>} options */ кажется быть одним из способов сделать это.   -  person Paul Sweatte    schedule 23.08.2012
comment
Я не думаю, что это дубликат связанного вопроса, поскольку он относится к виджетам jQuery. У меня та же проблема, и я пришел к выводу, что, поскольку параметры обычно (по крайней мере, в нашем случае) указываются при создании экземпляра виджета, я помещаю @param {Object} [options], как показано в ответе ниже, в объявлении виджета $. виджет (мой виджет, { ... })   -  person d4kris    schedule 16.11.2016

Ответы (1)


arrow_upward
93
arrow_downward

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

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

/**
 * @description
 * Compliment someone on their something.
 *
 * @param {Object} options
 * @param {String} options.name    A person's name
 * @param {String} options.feature A person's property
 */
function flatter (options) {
  options = options || {};
  console.log('%s, loving your %s!', options.name, options.feature);
}
person Jamie Mason    schedule 11.02.2013
comment
Можно ли задокументировать свойство, в котором есть пробел, например. options['some property']? - person M Miller; 15.12.2014
comment
Не то, что я пробовал, попробуйте несколько вариантов цитирования значения и запустите генератор jsdoc, чтобы увидеть. Пожалуйста, дайте нам знать после. - person Jamie Mason; 20.12.2014
comment
Что ж, поскольку этот вопрос постоянно поднимался, я просто поясню здесь: это не ответ на мой конкретный вопрос, потому что, как я уже сказал, jQuery предоставляет метод option, поэтому у меня нет метода, где литерал options является аргументом . - person billc.cn; 23.12.2014
comment
@fold_left нам действительно нужно @description? Ни разу не видел, чтобы его использовали. Когда я это вижу, предполагается, что первая строка — это описание. - person pcatre; 23.01.2015
comment
Вы правы насчет @pcatre, я все равно использую его, потому что он соответствует моим предпочтениям, но его можно без проблем опустить. - person Jamie Mason; 23.01.2015