The right way to document public arguments in JSDoc

Question

Say you have something like the following:

var someFunc = function() { // do something here with arguments } 

How do you correctly document that this function can accept any number of arguments in JSDoc? This is my best guess, but I'm not sure if this is correct.

 /** * @param {Mixed} [...] Unlimited amount of optional parameters */ var someFunc = function() { // do something here with arguments } 

Applies to: php - How to document a variable number of parameters

Answer 1

the JSDoc and Google Closure Compiler specifications do this as follows:

 @param {...number} var_args 

Where "number" is the type of expected argument.

So the full use of this will look like this:

 /** * @param {...*} var_args */ function lookMaImVariadic(var_args) { // Utilize the `arguments` object here, not `var_args`. } 

Check out the comment about using arguments (or some arguments bias) to access your extra arguments. var_args it is simply used to signal your IDE that the argument really exists.

Break options in ES6 can take the real parameter one step further to cover the provided values ​​(so you no longer need to use arguments )

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

Answer 2

How to do this is now described in the JSDoc documentation, and it uses an ellipsis, such as Closure documents.

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

You need to specify the type to use after the ellipsis, but you can use * to describe the acceptance of something or use | to separate several 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 defining the actual javascript function, so your actual code can only have empty parentheses, i.e. function whatever() { ... } .

Single type:

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

Any type (in the example below, square brackets mean items , both optional and repeatable will be marked):

 @param {...*} [items] - zero or more items to log. 

Many types need parentheses around the type list with an ellipsis before opening:

 @param {...(Person|string)} attendees - Meeting attendees, listed as either String names or {@link Person} objects 

Answer 3

I have been working with this for a long time. Here's how to do it with the 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 the var_args parameter (or what you call it in the @param statement), even if the function does not actually use this parameter.

Answer 4

From the JSDoc user group :

There is no official way, but one of the possible solutions:

 /** * @param [...] Zero or more child nodes. If zero then ... otherwise .... */ 

The square brackets indicate an optional parameter, and ... will (for me) indicate "some arbitrary number".

Another possibility is ...

 /** * @param [arguments] The child nodes. */ 

In any case, you must communicate what you mean.

This is a bit dated, although (2007), but I don't know anything more current.

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