Schreiben von Dokumentation für TypeScript-Projekte: von A bis Z

Einleitung: Warum ist Dokumentation in TypeScript-Projekten wichtig?

Qualitativ hochwertige Dokumentation ist nicht nur ein netter Bonus, sondern ein kritisches Element jedes professionellen TypeScript-Projekts. Sie dient als Brücke zwischen Entwicklern, erleichtert das Onboarding neuer Teammitglieder und hilft, Fehler bei der Nutzung von APIs zu vermeiden. TypeScript bietet mit seinem leistungsstarken Typsystem einzigartige Möglichkeiten zur Generierung präziser und selbstdokumentierender Dokumentation. In diesem Artikel werden wir den gesamten Prozess durchgehen: vom Schreiben von Kommentaren im Code bis zur Veröffentlichung der fertigen Dokumentation.

Grundlagen: JSDoc und Annotationen für TypeScript

TypeScript unterstützt die JSDoc-Syntax, die es ermöglicht, strukturierte Kommentare direkt in den Code einzufügen. Dies ist die Grundlage für die Erstellung von Dokumentation, die sowohl für Menschen als auch für Werkzeuge verständlich ist.

Basis-JSDoc-Tags

Beginnen wir mit einem einfachen Beispiel einer Funktion, die zwei Zahlen addiert:

/**\n * Addiert zwei Zahlen.\n * @param a - Erster Summand.\n * @param b - Zweiter Summand.\n * @returns Summe der beiden Zahlen.\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

Wichtige Tags:

\n
• @param — beschreibt ein Funktionsargument. Es wird empfohlen, Typ und Zweck anzugeben.
\n
• @returns — beschreibt den Rückgabewert.
\n
• @throws — gibt an, welche Ausnahmen die Funktion auslösen kann.
\n
• @example — zeigt ein Anwendungsbeispiel.
\n

Dokumentation komplexer Typen

Für Interfaces und Typen verwenden Sie @property oder beschreiben Sie die Felder innerhalb des Blocks:

interface UserConfig {\n    /** Benutzername */\n    name: string;\n    /** Alter des Benutzers (optional) */\n    age?: number;\n    /** Rolle im System */\n    role: 'admin' | 'user';\n}\n\n/**\n * Erstellt eine Benutzerkonfiguration.\n * @param config - Objekt mit Benutzereinstellungen.\n * @returns Konfigurationsobjekt.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

Verwenden Sie @template für Generics:

/**\n * Wrapper zum Speichern eines Werts.\n * @template T - Typ des gespeicherten Werts.\n */\nclass Box<T> {\n    /** Gespeicherter Wert */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

Werkzeuge zur Dokumentationsgenerierung: TypeDoc

TypeDoc ist das primäre Werkzeug zur automatischen Generierung von Dokumentation aus JSDoc-Annotationen in TypeScript. Es erstellt eine statische HTML-Website mit benutzerfreundlicher Navigation.

Installation und Konfiguration

Installieren Sie TypeDoc als dev-Abhängigkeit:

npm install --save-dev typedoc

Erstellen Sie eine Konfigurationsdatei typedoc.json im Projektstammverzeichnis:

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

Konfigurationsparameter:

\n
• entryPoints — Einstiegspunkt in Ihr Projekt (normalerweise die Hauptexportdatei).
\n
• out — Ordner, in den die Dokumentation generiert wird.
\n
• excludePrivate — private Klassenmitglieder ausblenden.
\n
• includeVersion — Projektversion zur Dokumentation hinzufügen.
\n

Generierung starten

Fügen Sie ein Skript in package.json hinzu:

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

Führen Sie den Befehl aus:

npm run docs:generate

Danach erscheint im Ordner docs eine statische Website. Öffnen Sie docs/index.html im Browser.

Best Practices für das Schreiben von Dokumentation

Damit die Dokumentation nützlich ist, befolgen Sie einige Regeln.

1. Schreiben Sie Kommentare