TypeDoc für TypeScript: Komplette Anleitung mit Beispielen

Was ist TypeDoc und warum wird es benötigt?

TypeDoc ist ein leistungsstarker Dokumentationsgenerator für TypeScript-Projekte. Er erstellt automatisch schöne, strukturierte HTML-Seiten basierend auf Ihren Code-Kommentaren im JSDoc-Format. Wenn Sie jemals TypeScript-Code geschrieben haben und schnell eine Dokumentation ähnlich der offiziellen TypeScript-Dokumentation oder beliebter Bibliotheken erstellen wollten, ist TypeDoc genau das Richtige für Sie.

Warum wird es benötigt? In der modernen Softwareentwicklung ist Dokumentation kein Luxus, sondern eine Notwendigkeit. TypeDoc löst mehrere zentrale Aufgaben:

• Automatisierung: Sie müssen keine Dokumentation manuell schreiben. Fügen Sie einfach Kommentare zu Funktionen, Klassen, Interfaces und Typen hinzu, und TypeDoc generiert eine fertige Website.
• Aktualität: Die Dokumentation ist immer auf dem neuesten Stand des Codes, da sie direkt daraus generiert wird.
• Navigation: TypeDoc erstellt eine benutzerfreundliche Navigation durch das Projekt: Baumstruktur, Suche, Typverweise.
• TypeScript-Unterstützung: Es versteht komplexe TypeScript-Typen: Generics, Utility-Types, Funktionsüberladungen, Module und Namespaces.
• Erweiterbarkeit: TypeDoc unterstützt Themes, Plugins und individuelle Anpassungen.

TypeDoc ist ideal geeignet für:

• Bibliotheken und Pakete, die über npm verteilt werden.
• Interne Projekte, bei denen neue Entwickler schnell mit dem Code vertraut gemacht werden müssen.
• API-Dokumentation für serverseitige TypeScript-Anwendungen.
• Bildungsprojekte, bei denen Anschaulichkeit wichtig ist.

Installation von TypeDoc

TypeDoc wird über npm (Node Package Manager) installiert. Stellen Sie sicher, dass Node.js (Version 14 oder höher) installiert ist.

Der einfachste Weg ist die globale Installation von TypeDoc:

npm install -g typedoc

Für Projekte wird jedoch die Installation als lokale Entwicklungsabhängigkeit empfohlen:

npm install --save-dev typedoc

Nach der Installation können Sie die Version überprüfen:

npx typedoc --version

Wenn Sie Yarn verwenden:

yarn add -D typedoc

Für pnpm:

pnpm add -D typedoc

Schnellstart mit einem Codebeispiel

Lassen Sie uns ein einfaches Projekt erstellen und dafür eine Dokumentation generieren.

Schritt 1: Projekt erstellen

mkdir my-typedoc-project
cd my-typedoc-project
npm init -y

Schritt 2: TypeDoc installieren

npm install --save-dev typedoc

Schritt 3: Codedatei src/index.ts erstellen

/**
 * Modul für mathematische Operationen.
 * @module MathUtils
 */

/**
 * Addiert zwei Zahlen.
 * @param a - Erste Zahl
 * @param b - Zweite Zahl
 * @returns Summe von a und b
 * @example
 * ```typescript
 * const result = add(2, 3);
 * console.log(result); // 5
 * ```
 */
export function add(a: number, b: number): number {
    return a + b;
}

/**
 * Subtrahiert die zweite Zahl von der ersten.
 * @param a - Minuend
 * @param b - Subtrahend
 * @returns Differenz von a und b
 */
export function subtract(a: number, b: number): number {
    return a - b;
}

/**
 * Interface zur Darstellung eines Punktes im zweidimensionalen Raum.
 */
export interface Point {
    /** X-Koordinate */
    x: number;
    /** Y-Koordinate */
    y: number;
}

/**
 * Berechnet die Entfernung zwischen zwei Punkten.
 * @param p1 - Erster Punkt
 * @param p2 - Zweiter Punkt
 * @returns Entfernung zwischen den Punkten
 */
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);
}

Schritt 4: Dokumentation generieren

npx typedoc src/index.ts