在JSDoc中记录开放式参数函数的正确方法

Question

假设您有以下内容:

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 - 如何doc一个可变数量的参数

Answer 1

该JSDoc规格和谷歌的关闭编译器做这种方式:

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

Answer 2

现在在JSDoc文档中描述了如何执行此操作,它使用类似于Closure docs的省略号.

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

多个类型需要在类型列表周围使用括号,在开头paren之前使用省略号:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects

Answer 3

来自JSDoc用户组:

没有任何官方方式,但一个可能的解决方案是:

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

方括号表示一个可选参数,而...(对我来说)表示"某个任意数字".

另一种可能性是......

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

无论哪种方式都应该传达你的意思.

虽然(2007年)有点过时,但我不知道有什么更新的.

如果您需要将参数类型记录为"混合",请使用{*},如@param {*} [arguments].

Answer 4

我很久以前就对它充满了兴趣.以下是使用Google Closure Compiler的方法:

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

关键是给你的函数一个var_args参数(或你在@param语句中称之为的任何参数),即使该函数实际上没有使用该参数.