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

@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>

Вам потрібно надати тип, щоб піти після еліпсиса, але ви можете використовувати 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:

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

Ключ у тому, щоб надати вашій функції var_argsпараметр (або як би ви його не називали у своєму @paramвиписку), хоча функція насправді не використовує цей параметр.