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

假设你有如下的东西:

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

32271 次浏览
小开
最佳答案

The JSDoc specs and Google's Closure Compiler do 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_args it just used to signal to your IDE that the argument does indeed exist.

Rest parameters in ES6 can take the real parameter one step further to encompass provided values (so no more use of arguments is necessary):

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

From the JSDoc users group:

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.

It's a bit dated, though (2007), but I'm not aware of anything more current.

If you need to document the param type as 'mixed', use {*}, as in @param {*} [arguments].

小开

I futzed with this for quite some time. Here's how to do it with 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_args parameter (or whatever you call it in your @param statement) even though the function doesn't actually use that parameter.

小开

How to do this is now described in the JSDoc documentation, and it uses an ellipsis like the Closure docs do.

@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.

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() { ... }.

Single type:

@param {...number} terms Terms to multiply together

Any type (in the example below, the square brackets mean items will get tagged as both optional and repeatable):

@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

提交答案