modo corretto per documentare le funzioni argomenti aperti a JSDoc

Question

Diciamo che hanno qualcosa di simile al seguente:

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

Come ti documentare correttamente che questa funzione può prendere qualsiasi numero di argomenti in JSDoc? Questa è la mia ipotesi migliore, ma non sono sicuro che sia corretto.

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

relativi a: php - How to doc a variable number of parameters

Answer 1

Il JSDoc specs e Google's Closure Compiler fare in questo modo:

@param {...number} var_args 

Dove "numero" è il tipo di argomenti previsto.

L'utilizzo completa di questo, poi, sarebbe simile al seguente:

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

nota il commento circa l'utilizzo arguments (o qualche offset arguments) per accedere ai argomenti aggiuntivi. var_args è appena usato per segnalare al tuo IDE che l'argomento esiste davvero.

Rest parameters in ES6 può prendere il parametro reale un ulteriore passo per comprendere valori previsti (quindi non più uso di arguments è necessario):

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

Answer 2

Dal JSDoc users group:

Non c'è alcun modo ufficiale, ma una possibile soluzione è questa:

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

Le parentesi quadre indicano un parametro facoltativo e il ... dovrebbe (per me) indicare "un numero arbitrario".

Un'altra possibilità è questo ...

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

In entrambi i casi dovrebbe comunicare quello che vuoi dire.

È un po 'datato, anche se (2007), ma non sono a conoscenza di qualcosa di più attuale.

Se è necessario documentare il tipo di parametro come "misto", utilizzare {*}, come in @param {*} [arguments].

Answer 3

Ho rinunciato a questo per un bel po 'di tempo. Ecco come farlo con Google Closure Compiler:

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

La chiave è quello di dare la vostra funzione di un parametro var_args (o come si chiamano nel vostro @param economico), anche se la funzione non viene effettivamente utilizzato tale parametro.

Answer 4

Come fare questo è now described nella documentazione di JSDoc e utilizza i puntini di sospensione come i documenti di chiusura.

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

è necessario fornire un tipo di andare dopo i puntini di sospensione, ma è possibile utilizzare un * per descrivere accettare qualsiasi cosa, o utilizzare il | per separare più tipi accettabili. Nella documentazione generata JSDoc descriverà questo argomento come ripetibile, nello stesso modo in cui descrive gli argomenti facoltativi come facoltativo.

Nei miei test non era necessario avere un argomento nella definizione della funzione javascript effettiva, quindi il codice effettivo può avere solo parentesi vuote, ad esempio function whatever() { ... }.

tipo singola:

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

Qualsiasi tipo (nell'esempio qui sotto, le parentesi quadre significano items otterrà contrassegnati come sia opzionale e ripetibile):

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

tipi più bisogno di parentesi intorno alla digitare l'elenco, con i puntini di sospensione prima del paren di apertura:

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