javascript - Correct way to document open-ended argument functions in JSDoc

Question

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

Answer 1

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