Правильный способ документирования открытых аргументов в 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 - Как документировать переменное количество параметров

Ответы

Ответ 1

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

@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, и он использует эллипсис, например, документы Closure.

@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

Ответ 3

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

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

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

Ответ 4

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

Нет официального пути, но одно из возможных решений:
/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */
Квадратные скобки указывают необязательный параметр, и... будет (для меня) указывать "какое-то произвольное число".

Другая возможность - это...
/**
 * @param [arguments] The child nodes.
 */
В любом случае вы должны сообщить, что вы имеете в виду.

Это немного устарело, хотя (2007), но я не знаю ничего более текущего.

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