Правильный способ документирования открытых функций аргументов в JSDoc
скажем, у вас есть что-то вроде следующего:
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-как документировать переменное количество параметров
4 ответа:
The спецификации JSDoc и компилятор закрытия Google сделайте это так:
@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`. }
как это сделать рассказал в документации JSDoc, и он использует многоточие, как это делают документы закрытия.
@param {...<type>} <argName> <Argument description>
вам нужно указать тип, чтобы идти после многоточия, но вы можете использовать
*
чтобы описать принятие чего-либо, или использовать|
для разделения нескольких допустимых типов. В сгенерированной документации 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
Я довольно долго с этим справлялся. Вот как это сделать с помощью компилятора закрытия Google:
/** * @param {...*} var_args */ function my_function(var_args) { // code that accesses the magic 'arguments' variable... }
ключ должен дать вашей функции a
var_args
параметр (или как вы его называете в вашем@param
утверждение) даже если функция не использует этот параметр.
нет никакого официального способа, но одно из возможных решений заключается в следующем:
/** * @param [...] Zero or more child nodes. If zero then ... otherwise .... */
квадратные скобки указывают на необязательный параметр, и ... будет (мне) указывать "какое-то произвольное число."
другая возможность заключается в следующем...
/** * @param [arguments] The child nodes. */
в любом случае должен сообщить, что вы имеете в виду.
это немного устарело, хотя (2007), но я не знаю ни о чем более актуальном.
если вам нужно документировать тип param как "смешанный", используйте
{*}
, а в@param {*} [arguments]
.