web-dev-qa-db-fra.com

Manière correcte de documenter les fonctions d'argument ouvertes dans JSDoc

Disons que vous avez quelque chose comme ceci:

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

Comment documenteriez-vous correctement que cette fonction peut prendre un certain nombre d'arguments dans JSDoc? C'est ma meilleure estimation, mais je ne suis pas sûr que ce soit correct.

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

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

javascriptjsdoc
69
kflorence

Les spécifications JSDoc et Compilateur de fermeture de Google le font de cette façon:

@param {...number} var_args

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

L'utilisation complète de ceci ressemblerait alors à ceci:

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

Notez le commentaire sur l'utilisation de arguments (ou un certain décalage de arguments) pour accéder à vos arguments supplémentaires. var_args il vient de signaler à votre IDE que l'argument existe bel et bien.

Rest paramètres dans ES6 peut pousser le paramètre réel un peu plus loin pour englober les valeurs fournies (donc plus besoin d'utiliser arguments n'est nécessaire):

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

Comment faire est maintenant décrit dans la documentation JSDoc, et il utilise des points de suspension comme le font les documents de fermeture.

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

Vous devez fournir un type pour aller après les points de suspension, mais vous pouvez utiliser un * Pour décrire l'acceptation de quoi que ce soit, ou utiliser le | Pour séparer plusieurs types acceptables. Dans la documentation générée, JSDoc décrira cet argument comme répétable , de la même manière qu'il décrit les arguments optionnels comme optionnel .

Lors de mes tests, il n'était pas nécessaire d'avoir un argument dans la définition de la fonction javascript réelle, donc votre code réel peut simplement avoir des parenthèses vides, c'est-à-dire function whatever() { ... }.

Type unique:

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

N'importe quel type (dans l'exemple ci-dessous, les crochets signifient que items sera étiqueté à la fois comme facultatif et répétable):

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

Plusieurs types ont besoin de parenthèses autour de la liste des types, avec les points de suspension avant le paren d'ouverture:

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

J'ai joué avec ça pendant un certain temps. Voici comment procéder 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 un var_args paramètre (ou comme vous l'appelez dans votre @param) même si la fonction n'utilise pas réellement ce paramètre.

10
Adrian Holovaty

Du groupe d'utilisateurs JSDoc :

Il n'y a aucun moyen officiel, mais une solution possible est la suivante:

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

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

Une autre possibilité est la suivante ...

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

Dans les deux cas, vous devez communiquer ce que vous voulez dire.

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

Si vous devez documenter le type de paramètre comme "mixte", utilisez {*}, un péché @param {*} [arguments].

10
hashchange