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

82

假设您有类似以下内容：

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

javascript jsdoc

— 弗洛伦斯
source

117

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

— 道森·托斯
source

这可能是我们所能得到的最接近的答案：）

— kflorence 2011年

2

同样值得注意的是，WebStorm的内部JSDoc文件（DHTML.js等）使用了相同的语法。也许这是事实上的标准。

— Scott Rippey 2012年

2

在这里也有很好的描述：usejsdoc.org/tags-param.html（“允许重复参数”部分）

— Francois

应该对这个答案进行编辑，以整合Adrian Holovaty的答案：需要有一个称为的实际变量var_args或您要调用的唯一参数。悲伤的骇客。

— 奥利（Oli）

1

在ES6中添加了rest参数，这变得更加有意义。/** @param {...Function} tasks The tasks. */ function waterfallTasks(...tasks) {其余参数始终在功能中存在。

— Shibumi

25

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

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

您需要提供省略号后面的类型，但是您可以使用a*来描述接受任何内容，或使用|来分隔多个可接受的类型。在生成的文档中，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

— 丹尼尔·贝尔德
source

1

那么用作键值对的对象呢？目前我使用：@param {{...(key: value)}} [config] - specific configs for this transfer但是想知道这是否正确吗？

— 最多

@Max我无法从文档中得知这是否是正确的官方正确方法，但看起来应该可以正常工作。因此，如果它可以产生输出，您可以使用，我会使用它:)

— Daniel Baird

10

在JSDoc用户组中：

没有任何官方方法，但是一个可能的解决方案是：
/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */
方括号表示可选参数，而...（对我而言）表示“某些任意数字”。

另一个可能性是...
/**
 * @param [arguments] The child nodes.
 */
两种方式都应该传达您的意思。

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

如果您需要将参数类型记录为“混合”，请使用{*}，如中所示@param {*} [arguments]。

— 哈希变化
source

6

我不介意我的回答被否决，但是我确实希望能有一条评论说明您这样做的原因（无论您是谁）。如果您认为这是错误的，请让我-和我们所有人-知道原因。

— hashchange

2

我选择的IDE（WebStorm 8.0.1）支持语法＃2 @param [arguments]（或@param {*} [arguments]就此而言）以及Google Closure编译器建立的语法（在另一个答案中提到）。@param [...]不支持。

— mistaecko 2014年

@mistaecko但仅具有命名参数正确吗？那就是我没有使用的，所以这对我来说不是一个可以接受的答案……

— Sebastian

10

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

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

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

— 阿德里安·霍洛瓦蒂（Adrian Holovaty）
source