Correct way to document open-ended argument functions in JSDoc

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.

/**
 * @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

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

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

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.

Correct way to document open-ended argument functions in JSDoc

Related

Recent Posts