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

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`.
}
79

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

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

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

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

10

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

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

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

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

другая возможность заключается в следующем...

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

в любом случае должен сообщить, что вы имеете в виду.

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

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

9