Правильный способ документирования функций с открытым аргументом в JSDoc

84

Допустим, у вас есть что-то вроде следующего:

var someFunc = function() {
    // do something here with arguments
}

Как бы вы правильно задокументировали, что эта функция может принимать любое количество аргументов в JSDoc? Это мое лучшее предположение, но я не уверен, что оно верное.

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

Относится к: php - Как документировать переменное количество параметров

Kflorence
источник

Ответы:

119

Спецификации JSDoc и компилятор Google Closure делают это следующим образом:

@param {...number} var_args

Где «число» - это тип ожидаемых аргументов.

Таким образом, полное использование этого будет выглядеть следующим образом:

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

Обратите внимание на комментарий об использовании arguments(или некотором смещении arguments) для доступа к вашим дополнительным аргументам. var_argsон просто используется для того, чтобы сообщить вашей IDE, что аргумент действительно существует.

Остальные параметры в ES6 могут продвинуть реальный параметр на один шаг дальше, чтобы охватить предоставленные значения (поэтому больше использовать их argumentsне нужно):

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}
Доусон Тот
источник
Вероятно, это
самый
2
Также стоит отметить, что внутренние файлы JSDoc WebStorm (DHTML.js и т. Д.) Используют тот же синтаксис. Может это де-факто стандарт.
Скотт Риппи
2
это также довольно хорошо описано здесь: usejsdoc.org/tags-param.html (раздел «Позволяет повторять параметр»)
Francois
Этот ответ следует отредактировать, чтобы интегрировать ответ Адриана Головати: должна быть фактическая вызываемая переменная var_argsили все, что вы хотите вызвать в качестве единственного параметра. Печальный хак.
Оли
1
С добавлением остальных параметров в ES6 это имеет больше смысла. /** @param {...Function} tasks The tasks. */ function waterfallTasks(...tasks) {Остальные параметры всегда функционально присутствуют в параметрах.
Shibumi
27

Как это сделать, теперь описано в документации JSDoc, и в ней используется многоточие, как в документации Closure.

@param {...<type>} <argName> <Argument description>

Вам необходимо указать тип после многоточия, но вы можете использовать a *для описания принятия чего-либо или использовать |для разделения нескольких приемлемых типов. В сгенерированной документации JSDoc будет описывать этот аргумент как повторяемый , так же как он описывает необязательные аргументы как необязательные .

В ходе тестирования не было никакой необходимости иметь аргумент в самом определении функции JavaScript, поэтому ваш фактический код может просто иметь пустые круглые скобки, то есть function whatever() { ... }.

Единый тип:

@param {...number} terms Terms to multiply together

Любой тип (в приведенном ниже примере квадратные скобки itemsбудут помечены как необязательные и повторяющиеся):

@param {...*} [items] - zero or more items to log.

Для нескольких типов необходимо заключить список типов в круглые скобки с многоточием перед открывающей скобкой:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects
Дэниел Бэрд
источник
1
А как насчет объекта, используемого в качестве пар ключ-значение? В настоящее время я использую: @param {{...(key: value)}} [config] - specific configs for this transferно интересно, правильно ли это?
Макс
@Max Я не могу сказать из документации, является ли это официальным правильным способом сделать это, но похоже, что он должен работать, как ожидалось. Так что, если он сгенерирует вывод, с которым вы согласны, я бы использовал его :)
Дэниел Бэрд
10

Из группы пользователей JSDoc :

Официального способа не существует, но одно из возможных решений:

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

Квадратные скобки указывают на необязательный параметр, а ... (для меня) означает «какое-то произвольное число».

Другая возможность - это ...

/**
 * @param [arguments] The child nodes.
 */

В любом случае следует передать то, что вы имеете в виду.

Хотя он немного устарел (2007 год), но я не знаю ничего более актуального.

Если вам нужно задокументировать тип параметра как «смешанный», используйте {*}, как в @param {*} [arguments].

хэш-обмен
источник
6
Я не возражаю против того, чтобы за мой ответ проголосовали против, но я ожидаю комментария, объясняющего, почему вы это сделали (кем бы вы ни были). Если вы думаете, что это неправильно, позвольте мне - и всем нам - знать, почему.
hashchange
2
Моя предпочтительная среда IDE (WebStorm 8.0.1) поддерживает синтаксис № 2 @param [arguments](или @param {*} [arguments]в этом отношении), а также синтаксис, установленный компилятором Google Closure (упомянутый в другом ответе). @param [...]не поддерживается.
mistaecko
@mistaecko, но только с указанными параметрами правильно? Это то, что я не использую, так что это неприемлемый ответ для меня ...
Себастьян
10

Я долго с этим размышлял. Вот как это сделать с помощью Google Closure Compiler:

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

Ключ состоит в том, чтобы дать вашей функции var_argsпараметр (или как вы его называете в своем @paramоператоре), даже если функция фактически не использует этот параметр.

Адриан Головатый
источник