javascript - for - jsdoc example

Manera correcta de documentar funciones de argumentos abiertos en JSDoc

Question

Digamos que tienes 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 correcto.

/**
 * @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

Answer 1

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

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

Debe proporcionar un tipo para ir después de los puntos suspensivos, pero puede usar un * para describir la aceptación de cualquier cosa, o usar el | para separar múltiples 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 fue necesario 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, la function whatever() { ... } .

Tipo único:

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

Cualquier tipo (en el ejemplo a continuación, los corchetes significan que los items se etiquetarán como opcionales y repetibles):

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

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

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

Answer 2

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 el ... indicaría (para mí) "algún número arbitrario".

Otra posibilidad es esta ...

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

De cualquier manera debe comunicar lo que quiere decir.

Sin embargo, es un poco anticuado (2007), pero no estoy al tanto de nada más actual.

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

Answer 3

Las especificaciones de 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 como el siguiente:

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

Tenga en cuenta el comentario sobre la utilización de arguments (o algún desplazamiento de arguments ) para acceder a sus argumentos adicionales. var_args se usa solo para indicar 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 es necesario usar más arguments ):

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

Answer 4

Me quedé con esto por bastante tiempo. He aquí 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 su función un parámetro var_args (o como se llame en su declaración @param ) aunque la función no use ese parámetro.