manera correcta para documentar las funciones de argumentos indefinidos en jsdoc

Question

Digamos que usted tiene algo como lo siguiente:

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

¿Cómo documentar 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 - How to doc a variable number of parameters

Answer 1

El JSDoc specs y Google's Closure Compiler hacerlo de esta manera:

@param {...number} var_args 

donde "número" es el tipo de argumentos se esperaba.

El uso completo de esta, a continuación, se vería como la siguiente:

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

Nota el comentario acerca de la utilización de arguments (o algún desplazamiento de arguments) para acceder a sus argumentos adicionales. var_args solo se usa para indicar a su IDE que el argumento existe realmente.

Rest parameters in ES6 puede tomar el parámetro real de un paso más allá para abarcar los valores previstos (por lo que no es necesario un mayor uso de arguments):

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

Answer 2

Desde el JSDoc users group:

No hay ninguna de manera 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 el ... sería (para mí) indicar "algún número arbitrario".

Otra posibilidad es esto ...

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

cualquier manera debe comunicar lo que quiere decir.

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

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

Answer 3

Me quedé con esto por bastante tiempo. Así es como hacerlo con Google Closure Compiler:

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

La clave es dar a su función de un parámetro var_args (o como se llame en su estado de cuenta @param) a pesar de que la función no utiliza realmente ese parámetro.

Answer 4

Cómo hacer esto es now described en la documentación de JSDoc, y utiliza puntos suspensivos como lo hacen los documentos de Cierre.

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

Debe suministrar un tipo de ir tras los puntos suspensivos, pero se puede utilizar un * para describir aceptar cualquier cosa, o utilizar el | para separar varios tipos aceptables. En la documentación generada, JSDoc describirá este argumento como repetible, del mismo modo que describe argumentos opcionales como opcional.

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

tipo individual:

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

Cualquier tipo (en el ejemplo siguiente, los corchetes significan items obtendrá etiquetado como ambos opcionales y repetible):

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

tipos múltiples necesitan paréntesis alrededor de la lista de tipos, con la elipsis antes de la apertura paren:

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