Forma correcta de documentar funciones de argumentos abiertos en JSDoc

Digamos que tiene algo como lo siguiente:

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

¿Cómo documentaría correctamente que esta función puede tomar cualquier número de argumentos en JSDoc? Esta es mi mejor suposición, pero no estoy seguro de que sea correcta.

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

Relacionado con: php - Cómo documentar un número variable de parámetros

Las especificaciones JSDoc y el compilador de cierre de Google lo hacen de esta manera:

@param {...number} var_args

Donde "número" es el tipo de argumentos esperados.

El uso completo de esto, entonces, se vería así:

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

Tenga en cuenta el comentario sobre la utilización arguments(o alguna compensación de arguments) para acceder a sus argumentos adicionales. var_argssolo solía indicarle a su IDE que el argumento sí existe.

Los parámetros de descanso en ES6 pueden llevar el parámetro real un paso más allá para abarcar los valores proporcionados (por lo que no argumentses necesario usar más ):

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

Cómo hacer esto ahora se describe en la documentación de JSDoc, y usa puntos suspensivos como lo hacen los documentos de Closure.

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

Debe proporcionar un tipo para ir después de los puntos suspensivos, pero puede usar a *para describir la aceptación de cualquier cosa o usar |para separar varios tipos aceptables. En la documentación generada, JSDoc describirá este argumento como repetible , de la misma manera que describe los argumentos opcionales como opcionales .

En mis pruebas no hubo necesidad de tener un argumento en la definición de la función javascript real, por lo que su código real puede tener paréntesis vacíos, es decir function whatever() { ... }.

Tipo único:

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

Cualquier tipo (en el ejemplo siguiente, los corchetes significan itemsque se etiquetará como opcional y repetible):

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

Varios tipos necesitan paréntesis alrededor de la lista de tipos, con puntos suspensivos antes del par de apertura:

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

Desde el grupo de usuarios de JSDoc :

No hay ninguna forma oficial, pero una posible solución es esta:

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

Los corchetes indican un parámetro opcional, y ... (para mí) indicaría "algún número arbitrario".

Otra posibilidad es esta ...

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

De cualquier manera debe comunicar lo que quiere decir.

Aunque está un poco anticuado (2007), pero no conozco nada más actual.

Si necesita documentar el tipo de parámetro como 'mixto', use {*}, como en @param {*} [arguments].

Estuve luchando con esto durante bastante tiempo. A continuación, le indicamos cómo hacerlo con Google Closure Compiler:

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

La clave es darle a tu función un var_argsparámetro (o como lo llames en tu @paramdeclaración) aunque la función no use ese parámetro.