在 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

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

那么，它的完整用法如下所示：

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

请注意有关利用参数（或参数的一些偏移量）来访问附加参数的注释。 var_args 它只是用来向您的 IDE 发出信号，表明该参数确实存在。

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

/**
* @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 会将此参数描述为可重复，就像它将可选参数描述为可选一样。

在我的测试中，实际的 javascript 函数定义中不需要有参数，因此您的实际代码可以只包含空括号，即 functionwhatever() { ... }。

单一类型：

@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

来自 JSDoc 用户群组：

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

<前><代码>/**
* @param [...] 零个或多个子节点。如果为零则...否则...
*/

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

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

<前><代码>/**
* @param [参数] 子节点。
*/

无论哪种方式都应该传达您的意思。

虽然它有点过时了（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 语句中调用的任何名称），即使该函数实际上并没有使用该参数。