Ajouter des métadonnées à votre documentation
Fournir une bonne documentation est une tâche essentielle pour chaque développeur. Non seulement cela aide vos pairs à comprendre rapidement votre raisonnement et peut-être votre processus de réflexion, mais cela vous aide également à entrer plus rapidement dans le code au cas où vous y reviendriez après quelques mois.
J'ai donc pensé à créer une liste (incomplète) de balises spéciales à utiliser avec les commentaires JSDoc. Ce sont ceux que j'utilise personnellement le plus souvent et qui se sont avérés apporter un réel bénéfice.
Un démarreur de base
L'exemple de code suivant montre un exemple simple et basique qui doit être utilisé pour chaque documentation. Il annote le but, les paramètres ainsi que le type de retour.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Exemple de code dans la documentation
Vous pouvez fournir un véritable exemple de code en ligne avec la balise "@example" pour clarifier certains cas d'utilisation. Cette balise peut également être utilisée pour afficher rapidement les cas extrêmes possibles dans un scénario réel.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Membre de quel module
Utilisez la balise « @memberOf » pour définir quel module ou quelle variable parent héberge le code documenté.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Annotation de lien
Vous pouvez utiliser la balise « @see » avec la balise « @link » pour fournir une documentation URL correctement formatée, au lieu de coller certaines URL en ligne de la documentation principale.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Documentation de type générique
Si votre code utilise des types génériques, vous pouvez utiliser la balise "@template" pour définir le nom du type générique. Ce nom est ensuite utilisé dans les balises communes "@param" comme référence de type.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Définir l'auteur d'un morceau de code
Dans certains cas, il est important d'annoter également l'auteur. Cela peut être simplement accompli avec la balise "@author". Vous pouvez non seulement fournir votre nom, mais également un e-mail comme référence de contact.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Code obsolète
Il n'y a pas grand-chose à dire sur la balise "@deprecated", car elle fait exactement ce à quoi vous vous attendez. Cette balise est couramment utilisée dans les API et peut également référencer le nouveau code.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Version
Utilisez la balise "@version" pour documenter une version du code donné. Notez que cette balise ne fait pas référence à la version de l'application, mais bien à la sienne. Un incrément de cette version signifie que ce code spécifique a changé.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Depuis quand le code est disponible
Vous pouvez utiliser la balise « @since » pour documenter à partir de quel numéro de version le code suivant a été ajouté à l'API publique. Il est important de noter ici que la version fait désormais référence à l'application-scope. Cela contraste avec la balise "@version" d'avant, qui est limitée au bloc de code spécifique qu'elle documente.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
