Comment documenter le code JavaScript à l'aide de JSDoc

Une documentation appropriée du code est un aspect important mais souvent négligé du développement logiciel. En tant que développeur, vous aurez l’habitude d’écrire du code propre et efficace, mais vous serez peut-être moins expérimenté dans la rédaction d’une bonne documentation.

Une bonne documentation est utile à toute personne travaillant avec votre code, qu'il s'agisse d'autres membres de votre équipe ou de vous-même, ultérieurement. Cela peut expliquer pourquoi vous avez implémenté quelque chose d’une manière particulière ou comment utiliser une fonction ou une API particulière.

Pour les développeurs JavaScript, JSDoc est un bon moyen de commencer à documenter votre code.

Qu’est-ce que JSDoc?

Documenter le code peut être complexe et fastidieux. Cependant, de plus en plus de personnes reconnaissent les avantages de

JSDoc génère de la documentation en interprétant les commentaires spéciaux dans votre code source JavaScript, en traitant ces commentaires et en produisant une documentation sur mesure. Il met ensuite cette documentation à disposition dans un format HTML accessible.

Cela conserve la documentation dans le code, donc lorsque vous mettez à jour votre code, il est facile de mettre à jour la documentation.

Configuration de JSDoc

Les créateurs de JSDoc ont facilité le démarrage et la configuration de JSDoc dans votre projet JavaScript.

Pour installer JSDoc localement, exécutez :

npm install --save-dev jsdoc

Cela installera la bibliothèque dans votre projet en tant que dépendance de développement.

Pour utiliser JSDoc, vous utiliserez des commentaires de syntaxe spéciaux dans votre code source. Vous rédigerez tous vos commentaires sur la documentation dans /** et */ Marqueurs. À l’intérieur de ceux-ci, vous pouvez décrire des variables définies, des fonctions, des paramètres de fonction et bien d’autres choses.

Par exemple:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

Le @param et @Retour les balises sont deux des nombreux mots-clés spéciaux pris en charge par JSDoc pour expliquer votre code.

Pour générer la documentation de ce code, exécutez npx jsdoc suivi du chemin d'accès à votre fichier JavaScript.

Par exemple:

npx jsdoc src/main.js

jsdoc path/to/file.js

Cette commande générera un dehors dossier à la racine de votre projet. A l'intérieur du dossier, vous trouverez des fichiers HTML représentant les pages de votre documentation.

Vous pouvez consulter la documentation en configurer un serveur Web local pour l'héberger, ou simplement en ouvrant le fichier out/index.html dans un navigateur. Voici un exemple de ce à quoi ressemblera une page de documentation par défaut :

Configuration de la sortie JSDoc

Vous pouvez créer un fichier de configuration pour modifier le comportement par défaut de JSDoc.

Pour ce faire, créez un conf.js et exportez un module JavaScript à l’intérieur de ce fichier.

Par exemple:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

À l'intérieur du fichier de configuration se trouvent différents Configuration JSDoc choix. Le modèle L’option vous permet d’utiliser un modèle pour personnaliser l’apparence de la documentation. La communauté JSDoc propose de nombreux modèles que vous pouvez utiliser. Le package vous permet également de créer vos propres modèles personnalisés.

Pour modifier l'emplacement de la documentation générée, définissez le destination option de configuration dans un répertoire. L'exemple ci-dessus spécifie un documents dossier à la racine du projet.

Utilisez cette commande pour exécuter JSDoc avec un fichier de configuration :

jsdoc -c /path/to/conf.js

Pour faciliter l'exécution de cette commande, ajoutez-la en tant que scripts entrée à l'intérieur de votre package.json déposer:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Tu peux maintenant exécutez la commande de script npm à l'intérieur d'un terminal.

Un exemple de documentation générée avec JSDoc

Vous trouverez ci-dessous une bibliothèque arithmétique simple avec ajouter et soustraire méthodes.

Voici un exemple de code JavaScript bien documenté :

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

Les commentaires JSDoc fournissent une description claire et complète de la bibliothèque et de ses méthodes, notamment :

• Une description de la bibliothèque et de son objectif.
• Les paramètres de chaque méthode, y compris leur type et une brève description.
• La valeur et le type renvoyés par chaque méthode.
• Les erreurs que chaque méthode peut générer et les conditions qui les provoquent.
• Un exemple de la façon d'utiliser chaque méthode.

Les commentaires incluent également le @module balise pour indiquer que ce fichier est un module et que le @exemple balise pour fournir un exemple de code pour chaque méthode.

Documenter le code du développeur de la bonne manière

Comme vous pouvez le constater, JSDoc est un outil très utile pour commencer à documenter le code JavaScript. Grâce à son intégration facile, vous pouvez générer une documentation rapide et détaillée pendant que vous écrivez votre code. Vous pouvez également gérer et mettre à jour la documentation directement dans votre espace de travail.

Cependant, aussi utile que soit l'automatisation de JSDoc, vous devez toujours respecter certaines directives afin de pouvoir créer une documentation de qualité.