À l'heure actuelle, il existe 4 façons différentes de documenter les objets en tant que paramètres / types. Chacun a ses propres utilisations. Cependant, seuls 3 d'entre eux peuvent être utilisés pour documenter les valeurs de retour.
Pour les objets avec un ensemble de propriétés connu (variante A)
/**
* @param {{a: number, b: string, c}} myObj description
*/
Cette syntaxe est idéale pour les objets qui ne sont utilisés que comme paramètres pour cette fonction et ne nécessitent pas de description supplémentaire de chaque propriété. Il peut être utilisé pour @returns
aussi bien .
Pour les objets avec un ensemble de propriétés connu (Variante B)
Les paramètres avec la syntaxe des propriétés sont très utiles :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
Cette syntaxe est idéale pour les objets qui ne sont utilisés que comme paramètres pour cette fonction et qui nécessitent une description plus détaillée de chaque propriété. Cela ne peut pas être utilisé pour @returns
.
Pour les objets qui seront utilisés à plus d'un point dans la source
Dans ce cas, un @typedef est très pratique. Vous pouvez définir le type à un moment de votre source et l'utiliser comme type pour @param
ou @returns
ou d'autres balises JSDoc pouvant utiliser un type.
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
Vous pouvez ensuite l'utiliser dans une @param
balise:
/**
* @param {Person} p - Description of p
*/
Ou dans un @returns
:
/**
* @returns {Person} Description
*/
Pour les objets dont les valeurs sont toutes du même type
/**
* @param {Object.<string, number>} dict
*/
Le premier type (chaîne) documente le type des clés qui en JavaScript est toujours une chaîne ou au moins seront toujours contraintes à une chaîne. Le deuxième type (nombre) est le type de la valeur; cela peut être de n'importe quel type. Cette syntaxe peut également être utilisée @returns
.
Ressources
Des informations utiles sur la documentation des types peuvent être trouvées ici:
https://jsdoc.app/tags-type.html
PS:
pour documenter une valeur facultative, vous pouvez utiliser []
:
/**
* @param {number} [opt_number] this number is optional
*/
ou:
/**
* @param {number|undefined} opt_number this number is optional
*/