Documentation avec JSDoc

JSDoc permet de documenter du code JavaScript.

Grâce à JSDoc, il devient plus facile de comprendre :

• Le rôle d’une fonction
• Les paramètres attendus
• Les valeurs retournées
• Les types de données utilisés

JSDoc est très utilisé dans les projets professionnels.

1. Pourquoi documenter le code

La documentation aide les développeurs à comprendre le programme.

Elle améliore :

• La lisibilité
• La maintenance
• Le travail en équipe
• La compréhension du code

Même plusieurs semaines plus tard, la documentation aide à retrouver rapidement le fonctionnement d’une fonction.

2. Syntaxe JSDoc

Un commentaire JSDoc commence avec :

/** */

Exemple :

/**
 * Additionne deux nombres.
 */

3. Documentation d’une fonction

JSDoc est souvent utilisé avec les fonctions.

/**
 * Retourne le carré d’un nombre.
 */
function square(number) {

    return number * number;

}

Ici, la documentation explique le rôle de la fonction.

4. @param

L’annotation @param décrit un paramètre de fonction.

/**
 * Additionne deux nombres.
 *
 * @param {number} a
 * @param {number} b
 */
function add(a, b) {

    return a + b;

}

5. @returns

L’annotation @returns décrit la valeur retournée.

/**
 * Additionne deux nombres.
 *
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {

    return a + b;

}

6. Les types primitifs

JSDoc peut documenter plusieurs types JavaScript.

7. Documenter un objet

JSDoc peut documenter des objets complexes.

/**
 * Retourne le nom d’un utilisateur.
 *
 * @param {{name: string}} user
 * @returns {string}
 */
function getUsername(user) {

    return user.name;

}

Ici, l’objet doit contenir une propriété :

name

8. Documenter un tableau

JSDoc peut aussi documenter des tableaux.

/**
 * Retourne le total des nombres.
 *
 * @param {number[]} numbers
 * @returns {number}
 */
function total(numbers) {

    return numbers.reduce((sum, number) => {

        return sum + number;

    }, 0);

}

9. Fonctions fléchées

JSDoc fonctionne aussi avec les fonctions fléchées.

/**
 * Multiplie deux nombres.
 *
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
const multiply = (a, b) => {

    return a * b;

};

10. IntelliSense

Les éditeurs modernes comme VS Code utilisent JSDoc pour améliorer l’IntelliSense.

Cela permet :

• D’afficher les paramètres
• D’afficher les types
• D’aider l’autocomplétion
• D’améliorer la compréhension du code

11. Exemple complet

/**
 * Retourne le prix total avec taxes.
 *
 * @param {number} price
 * @param {number} tax
 * @returns {number}
 */
function calculateTotal(price, tax) {

    return price + tax;

}

Cette documentation explique :

• Le rôle de la fonction
• Les paramètres attendus
• Le type retourné

12. Bonnes pratiques

• Documenter les fonctions importantes
• Utiliser des descriptions claires
• Documenter les paramètres
• Documenter les valeurs retournées
• Garder la documentation simple et lisible

Résumé rapide