Javascript 在 JSDoc 中记录开放式参数函数的正确方法
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/4729516/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Correct way to document open-ended argument functions in JSDoc
提问by kflorence
Let's say you have something like the following:
假设您有以下内容：
var someFunc = function() {
// do something here with arguments
}
How would you correctly document that this function can take any number of arguments in JSDoc? This is my best guess, but I'm not sure it's correct.
在 JSDoc 中，您如何正确记录此函数可以接受任意数量的参数？这是我最好的猜测，但我不确定它是否正确。
/**
* @param {Mixed} [...] Unlimited amount of optional parameters
*/
var someFunc = function() {
// do something here with arguments
}
Related to: php - How to doc a variable number of parameters
回答by Dawson Toth
The JSDoc specsand Google's Closure Compilerdo it this way:
@param {...number} var_args
Where "number" is the type of arguments expected.
其中“数字”是预期的参数类型。
The complete usage of this, then, would look like the following:
然后，它的完整用法如下所示：
/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
// Utilize the `arguments` object here, not `var_args`.
}
Note the comment about utilizing arguments(or some offset of arguments) to access your additional arguments. var_argsit just used to signal to your IDE that the argument does indeed exist.
请注意有关使用arguments（或 的某些偏移量arguments）访问附加参数的注释。var_args它只是用来向您的 IDE 发出信号，表明该参数确实存在。
Rest parameters in ES6can take the real parameter one step further to encompass provided values (so no more use of argumentsis necessary):
ES6 中的 Rest 参数可以将真实参数进一步包含提供的值（因此不再需要使用arguments）：
/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
// Utilize the `var_args` array here, not `arguments`.
}
回答by Daniel Baird
How to do this is now describedin the JSDoc documentation, and it uses an ellipsis like the Closure docs do.
现在在 JSDoc 文档中描述了如何做到这一点，它使用省略号，就像 Closure 文档所做的那样。
@param {...<type>} <argName> <Argument description>
You need to supply a type to go after the ellipsis, but you can use a *to describe accepting anything, or use the |to separate multiple acceptable types. In the generated documentation JSDoc will describe this argument as repeatable, in the same way it describes optional arguments as optional.
您需要在省略号后面提供一个类型，但您可以使用 a*来描述接受任何内容，或使用|来分隔多个可接受的类型。在生成的文档中，JSDoc 将这个参数描述为可重复的，就像它将可选参数描述为optional 一样。
In my testing there was no need to have an argument in the actual javascript function definition, so your actual code can just have empty parentheses, i.e. function whatever() { ... }.
在我的测试中，不需要在实际的 javascript 函数定义中使用参数，因此您的实际代码可以只有空括号，即function whatever() { ... }.
Single type:
单一类型：
@param {...number} terms Terms to multiply together
Any type (in the example below, the square brackets mean itemswill get tagged as both optional and repeatable):
任何类型（在下面的示例中，方括号表示items将被标记为可选和可重复）：
@param {...*} [items] - zero or more items to log.
Multiple types need parentheses around the type list, with the ellipsis before the opening paren:
多个类型需要在类型列表周围加上括号，在左括号前加上省略号：
@param {...(Person|string)} attendees - Meeting attendees, listed as either
String names or {@link Person} objects
回答by hashchange
From the JSDoc users group:
来自JSDoc 用户组：
There isn't any official way, but one possible solution is this:
/** * @param [...] Zero or more child nodes. If zero then ... otherwise .... */The square brackets indicate an optional parameter, and the ... would (to me) indicate "some arbitrary number."
Another possibility is this...
/** * @param [arguments] The child nodes. */Either way should communicate what you mean.
没有任何官方方法，但一种可能的解决方案是：
/** * @param [...] Zero or more child nodes. If zero then ... otherwise .... */方括号表示一个可选参数，而 ... 将（对我而言）表示“某个任意数字”。
另一种可能是这样...
/** * @param [arguments] The child nodes. */无论哪种方式都应该传达您的意思。
It's a bit dated, though (2007), but I'm not aware of anything more current.
虽然（2007 年）有点过时，但我不知道有什么更新的。
If you need to document the param type as 'mixed', use {*}, as in @param {*} [arguments].
如果您需要将 param 类型记录为“混合”，请使用{*}，如@param {*} [arguments].
回答by Adrian Holovaty
I futzed with this for quite some time. Here's how to do it with Google Closure Compiler:
我对此感到困惑了很长一段时间。以下是使用 Google Closure Compiler 执行此操作的方法：
/**
* @param {...*} var_args
*/
function my_function(var_args) {
// code that accesses the magic 'arguments' variable...
}
The key is to give your function a var_argsparameter (or whatever you call it in your @paramstatement) even though the function doesn't actually use that parameter.
关键是为您的函数提供一个var_args参数（或您在@param语句中调用的任何参数），即使该函数实际上并未使用该参数。
