Rédaction de documentation pour un projet TypeScript : de A à Z

Introduction : pourquoi la documentation est-elle nécessaire dans les projets TypeScript

Une documentation de qualité n'est pas simplement un bonus agréable, mais un élément critique de tout projet TypeScript professionnel. Elle sert de pont entre les développeurs, facilite l'intégration des nouveaux membres de l'équipe et aide à éviter les erreurs lors de l'utilisation de l'API. TypeScript, avec son puissant système de types, offre des opportunités uniques pour générer une documentation précise et auto-documentée. Dans cet article, nous allons détailler le processus complet : de l'écriture de commentaires dans le code à la publication de la documentation finale.

Les bases : JSDoc et annotations pour TypeScript

TypeScript prend en charge la syntaxe JSDoc, ce qui permet d'ajouter des commentaires structurés directement dans le code. C'est la base pour créer une documentation compréhensible à la fois par l'homme et par les outils.

Balises JSDoc de base

Commençons par un exemple simple d'une fonction qui additionne deux nombres :

/**\n * Additionne deux nombres.\n * @param a - Le premier terme.\n * @param b - Le second terme.\n * @returns La somme des deux nombres.\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

Balises clés :

\n
• @param — décrit un argument de fonction. Il est recommandé d'indiquer le type et la fonction.
\n
• @returns — décrit la valeur de retour.
\n
• @throws — indique les exceptions que la fonction peut lever.
\n
• @example — montre un exemple d'utilisation.
\n

Documentation des types complexes

Pour les interfaces et les types, utilisez @property ou décrivez les champs à l'intérieur du bloc :

interface UserConfig {\n    /** Nom d'utilisateur */\n    name: string;\n    /** Âge de l'utilisateur (optionnel) */\n    age?: number;\n    /** Rôle dans le système */\n    role: 'admin' | 'user';\n}\n\n/**\n * Crée une configuration utilisateur.\n * @param config - Objet avec les paramètres utilisateur.\n * @returns Objet de configuration.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

Utilisez @template pour les génériques :

/**\n * Wrapper pour stocker une valeur.\n * @template T - Type de la valeur stockée.\n */\nclass Box<T> {\n    /** Valeur stockée */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

Outils de génération de documentation : TypeDoc

TypeDoc est l'outil principal pour la génération automatique de documentation à partir d'annotations JSDoc en TypeScript. Il crée un site HTML statique avec une navigation pratique.

Installation et configuration

Installez TypeDoc comme dépendance de développement :

npm install --save-dev typedoc

Créez un fichier de configuration typedoc.json à la racine du projet :

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

Paramètres de configuration :

\n
• entryPoints — point d'entrée de votre projet (généralement le fichier d'export principal).
\n
• out — dossier où la documentation sera générée.
\n
• excludePrivate — masquer les membres privés des classes.
\n
• includeVersion — ajouter la version du projet dans la documentation.
\n

Lancement de la génération

Ajoutez un script dans package.json :

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

Exécutez la commande :

npm run docs:generate

Après cela, un site statique apparaîtra dans le dossier docs. Ouvrez docs/index.html dans un navigateur.

Bonnes pratiques pour la rédaction de documentation

Pour que la documentation soit utile, suivez quelques règles.

1. Écrivez des commentaires