Manière correcte de documenter les fonctions d'arguments ouvertes dans JSDoc
disons que vous avez quelque chose comme ceci:
var someFunc = function() {
// do something here with arguments
}
comment documentez-vous correctement que cette fonction peut prendre un certain nombre d'arguments dans JSDoc? C'est ma meilleure supposition, 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
}
Relative à: php - Comment doc un nombre variable de paramètres
4 réponses
Le JSDoc specs et Google Closure compiler faire de cette façon:
@param {...number} var_args
Où "nombre" est le type d'arguments attendus.
l'usage complet de ceci, alors, ressemblerait à ce qui suit:
/**
* @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 décalage de arguments ) pour accéder à vos arguments supplémentaires. var_args " il utilisé pour signaler votre IDE que l'argument existe bel et bien.
Reste paramètres dans l'ES6 peut prendre le paramètre réel plus loin pour englober les valeurs fournies (donc ne plus utiliser de arguments est nécessaire):
/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
// Utilize the `var_args` array here, not `arguments`.
}
Comment faire, c'est maintenant dans le JSDoc de la documentation, et il utilise des points de suspension, comme la Fermeture docs ne.
@param {...<type>} <argName> <Argument description>
vous devez fournir un type pour aller après l'ellipse, mais vous pouvez utiliser un * pour décrire accepter quoi que ce soit, ou utiliser le | pour séparer plusieurs types acceptables. Dans la documentation générée, JSDoc va décrire cet argument comme répétable , de la même manière il décrit les arguments optionnels comme optionnel .
dans mes tests, il n'était pas nécessaire d'avoir un argument dans la définition actuelle de la fonction javascript, donc votre code actuel peut juste avoir des parenthèses vides, i.e. function whatever() { ... } .
Seul type:
@param {...number} terms Terms to multiply together
n'Importe quel type (dans l'exemple ci-dessous, les crochets signifient "151970920 sera étiqueté comme optionnel 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 ellipses avant le paren d'ouverture:
@param {...(Person|string)} attendees - Meeting attendees, listed as either
String names or {@link Person} objects
j'ai joué avec ça pendant un certain temps. Voici comment le 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 un paramètre var_args (ou quel que soit le nom que vous lui donnez dans votre énoncé @param ) même si la fonction n'utilise pas ce paramètre.
De la JSDoc groupe d'utilisateurs de :
il n'y a pas de voie officielle, mais une solution possible est celle-ci:
/** * @param [...] Zero or more child nodes. If zero then ... otherwise .... */les crochets indiquent un paramètre optionnel, et le ... serait (pour moi) indiquer "certains nombre arbitraire."
une autre possibilité est celle-ci...
/** * @param [arguments] The child nodes. */d'une façon ou d'une autre devrait communiquer ce que vous voulez dire.
C'est un peu daté, (2007), mais je ne suis pas au courant de quelque chose de plus actuel.
si vous devez documenter le type param comme 'mixed', utilisez {*} , comme dans @param {*} [arguments] .