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

Спецификации 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`.
}

Как это сделать, теперь описано в документации 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

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

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

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

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

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

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

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

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

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

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

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

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