Manière correcte de document ouvert argument des fonctions dans JSDoc

Question

Disons que vous avez quelque chose comme ce qui suit:

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

Comment voulez-vous correctement document que cette fonction peut prendre n'importe quel nombre d'arguments dans JSDoc? C'est ma meilleure supposition, mais je ne suis pas sûr que c'est correct.

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

Liés à: php - Comment doc un nombre variable de paramètres

Answer 1

Je n'ai pas été en mesure de trouver dans tous les JSDoc specs, mais pour ce que ça vaut...

Google Closure compiler t-il de cette façon:

@param {...number} var_args

Où les "le nombre" est le type d'arguments attendus.

Recherche pour "Variable de paramètres (dans les annotations @param)" sur cette page afin de voir par vous-même: http://code.google.com/closure/compiler/docs/js-for-compiler.html

Answer 2

Je futzed avec cela fait déjà quelques temps. Voici comment faire avec Google Closure compiler:

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

La clé est de donner à votre fonction d'un var_args de paramètre (ou ce que vous appelez dans votre @param déclaration), même si la fonction n'est pas réellement utiliser ce paramètre.

Answer 3

À partir de la JSDoc groupe d'utilisateurs:

Il n'y a pas de manière officielle, mais une solution possible est:

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

Les crochets indiquent un paramètre facultatif, et le ... serait (pour moi) indiquer "certains nombre arbitraire."

Une autre possibilité est de cette...

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

De toute façon devrait communiquer sur ce que vous voulez dire.

C'est un peu daté, mais (2007), mais je ne suis pas au courant de quelque chose de plus actuel.

Si vous avez besoin de documenter les param type "mixte", utilisez {*}, comme en @param {*} [arguments].