Une documentation appropriée du code est un aspect important mais souvent négligé du développement logiciel. En tant que développeur, vous serez habitué à é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. Il 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.
Table des matières
Qu’est-ce que JSDoc ?
Documenter le code peut être complexe et fastidieux. Cependant, de plus en plus de personnes reconnaissent les avantages d’une approche « docs as code », et de nombreux langages disposent de bibliothèques qui aident à automatiser le processus. Pour une documentation simple, claire et concise. Tout comme le langage Go dispose de GoDoc pour automatiser la documentation à partir du code, JavaScript dispose de JSDoc.
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 écrirez tous vos commentaires de documentation entre les marqueurs /** et */. À 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
*/function getUser(name) {
const User = name;
return User;
}
Les balises @param et @returns 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
Si vous avez installé JSDoc globalement, vous pouvez omettre l’indicateur npx et exécuter :
Cette commande générera un dossier out à 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 configurant 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 fichier 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. L’option modèle 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 l’option de configuration de destination sur un répertoire. L’exemple ci-dessus spécifie un dossier docs à 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 qu’entrée de script dans votre fichier package.json :
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Vous pouvez maintenant exécuter la commande de script npm dans un terminal.
Un exemple de documentation générée avec JSDoc
Vous trouverez ci-dessous une bibliothèque arithmétique simple avec des méthodes d’ajout et de soustraction.
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);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('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);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
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 la balise @module pour indiquer que ce fichier est un module et la balise @example 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é.