Forma correcta de documentar funciones de argumentos abiertos en JSDoc


82

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

Respuestas:


117

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

Esto es probablemente lo más cercano a una respuesta que podemos obtener :)
kflorence

2
También vale la pena señalar que los archivos JSDoc internos de WebStorm (DHTML.js, etc.) usan esta misma sintaxis. Quizás sea el estándar de facto.
Scott Rippey

2
también se describe bastante bien aquí: usejsdoc.org/tags-param.html (sección 'Permite que se repita un parámetro')
Francois

Esta respuesta debe editarse para integrar la respuesta de Adrian Holovaty: debe haber una variable real llamada var_argso lo que quieras llamar como el único parámetro. Triste truco.
Oli

1
Con la adición de parámetros de descanso en ES6, esto tiene mucho más sentido. /** @param {...Function} tasks The tasks. */ function waterfallTasks(...tasks) {Los parámetros de descanso siempre tienen una presencia funcional en los parámetros.
Shibumi

25

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

1
¿Y qué pasa con los objetos utilizados como pares clave-valor? Actualmente uso: @param {{...(key: value)}} [config] - specific configs for this transferpero me preguntaba si esto es correcto.
Max

@Max No puedo decir por los documentos si esa es la forma oficial correcta de hacerlo, pero parece que debería funcionar como se esperaba. Entonces, si genera una salida con la que está de acuerdo, la usaría :)
Daniel Baird

10

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].


6
No me importa que mi respuesta sea rechazada, pero espero un comentario que explique por qué lo hizo (quienquiera que sea). Si cree que está mal, déjeme saber a mí, y a todos nosotros, por qué.
hashchange

2
Mi IDE de elección (WebStorm 8.0.1) admite la sintaxis # 2 @param [arguments](o @param {*} [arguments]para el caso) así como la sintaxis establecida por el compilador de cierre de Google (mencionado en otra respuesta). @param [...]no es apoyado.
misecko

@mistaecko pero solo con los parámetros con nombre, ¿son correctos? Eso es lo que no estoy usando, así que esta no es una respuesta aceptable para mí ...
Sebastian

10

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.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.