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 - How to doc a variable number of parameters

Answer 1

JSDoc specs和Google's Closure Compiler这样做：

@param {...number} var_args

其中“number”是预期参数的类型。

然后，完整的用法如下所示：

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

请注意有关利用arguments（或arguments的某些偏移量）来访问其他参数的注释。 var_args它只是用来向你的IDE发出信号，确认参数确实存在。

Rest parameters in ES6可以将真实参数更进一步包含提供的值（因此不再需要使用arguments）：

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}

Answer 2

如何在JSDoc文档中执行此操作now described，并使用类似Closure文档的省略号。

@param {...<type>} <argName> <Argument description>

您需要提供一个类型来查找省略号，但您可以使用*来描述接受任何内容，或使用|分隔多个可接受的类型。在生成的文档中，JSDoc将此参数描述为 repeatable ，就像它将可选参数描述为可选一样。

在我的测试中，没有必要在实际的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 users group：

没有任何官方方式，但一个可能的解决方案是：
/**
 * @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语句中称之为的任何参数），即使该函数实际上没有使用该参数。

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

4 个答案: