TypeDoc pour TypeScript : guide complet avec exemples

Qu'est-ce que TypeDoc et pourquoi l'utiliser ?

TypeDoc est un puissant générateur de documentation pour les projets TypeScript. Il crée automatiquement de belles pages HTML structurées à partir de vos commentaires de code au format JSDoc. Si vous avez déjà écrit du code TypeScript et souhaité obtenir rapidement une documentation semblable à celle officielle de TypeScript ou des bibliothèques populaires, TypeDoc est exactement ce qu'il vous faut.

Pourquoi l'utiliser ? Dans le développement moderne, la documentation n'est pas un luxe, mais une nécessité. TypeDoc résout plusieurs problèmes clés :

• Automatisation : Plus besoin de rédiger la documentation manuellement. Ajoutez simplement des commentaires à vos fonctions, classes, interfaces et types, et TypeDoc génère un site prêt à l'emploi.
• Actualité : La documentation est toujours synchronisée avec le code, car elle est générée directement à partir de celui-ci.
• Navigation : TypeDoc crée une navigation pratique dans votre projet : arborescence, recherche, liens vers les types.
• Support TypeScript : Il comprend les types complexes de TypeScript : génériques, types utilitaires, surcharges de fonctions, modules et espaces de noms.
• Extensibilité : TypeDoc prend en charge les thèmes, les plugins et la personnalisation.

TypeDoc est idéal pour :

• Les bibliothèques et paquets distribués via npm.
• Les projets internes où il faut rapidement familiariser les nouveaux développeurs avec le code.
• La documentation d'API pour les applications serveur en TypeScript.
• Les projets éducatifs où la clarté est primordiale.

Installation de TypeDoc

TypeDoc s'installe via npm (Node Package Manager). Assurez-vous d'avoir Node.js (version 14 ou supérieure) installé.

La méthode la plus simple est d'installer TypeDoc globalement :

npm install -g typedoc

Cependant, pour les projets, il est recommandé de l'installer comme dépendance de développement locale :

npm install --save-dev typedoc

Après l'installation, vous pouvez vérifier la version :

npx typedoc --version

Si vous utilisez Yarn :

yarn add -D typedoc

Pour pnpm :

pnpm add -D typedoc

Démarrage rapide avec un exemple de code

Créons un projet simple et générons sa documentation.

Étape 1 : Créez le projet

mkdir mon-projet-typedoc
cd mon-projet-typedoc
npm init -y

Étape 2 : Installez TypeDoc

npm install --save-dev typedoc

Étape 3 : Créez un fichier de code src/index.ts

/**
 * Module pour les opérations mathématiques.
 * @module MathUtils
 */

/**
 * Additionne deux nombres.
 * @param a - Le premier nombre
 * @param b - Le deuxième nombre
 * @returns La somme de a et b
 * @example
 * ```typescript
 * const resultat = addition(2, 3);
 * console.log(resultat); // 5
 * ```
 */
export function addition(a: number, b: number): number {
    return a + b;
}

/**
 * Soustrait le deuxième nombre du premier.
 * @param a - Le nombre à diminuer
 * @param b - Le nombre à soustraire
 * @returns La différence entre a et b
 */
export function soustraction(a: number, b: number): number {
    return a - b;
}

/**
 * Interface représentant un point dans un espace bidimensionnel.
 */
export interface Point {
    /** Coordonnée X */
    x: number;
    /** Coordonnée Y */
    y: number;
}

/**
 * Calcule la distance entre deux points.
 * @param p1 - Le premier point
 * @param p2 - Le deuxième point
 * @returns La distance entre les points
 */
export function distance(p1: Point, p2: Point): number {
    const dx = p2.x - p1.x;
    const dy = p2.y - p1.y;
    return Math.sqrt(dx * dx + dy * dy);
}

Étape 4 : Générez la documentation

npx typedoc src/index.ts