在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-如何记录可变数量的参数

Answer 1

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

Answer 2

现在 ，JSDoc文档中描述了如何执行此操作，并且它与Closure文档一样使用省略号。

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

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

在我的测试中，实际的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

Answer 3

我对此赞不绝口。 使用Google Closure编译器的方法如下：

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

关键是为函数提供var_args参数（或您在@param语句中调用的任何@param ），即使函数实际上并未使用该参数。

Answer 4

在JSDoc用户组中 ：

没有任何官方方法，但是一个可能的解决方案是：

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

方括号表示可选参数，而...（对我而言）表示“某些任意数字”。

另一个可能性是...

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

两种方式都可以传达您的意思。

虽然有点过时（2007年），但我不知道还有什么最新的。

如果您需要将参数类型记录为'mixed'，请使用{*} ，如@param {*} [arguments] 。