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

Einleitung: Warum Dokumentation eine Investition und keine Zeitverschwendung ist

Jeder Entwickler kennt die Situation: Wenn man nach einem Monat zu seinem eigenen Code zurückkehrt, fällt es einem schwer, sich zu erinnern, wozu der eine oder andere Parameter dient. Ganz zu schweigen von neuen Teammitgliedern, die versuchen, sich in Ihrem Projekt zurechtzufinden. Hochwertige Dokumentation für ein TypeScript-Projekt ist nicht nur eine nette Ergänzung, sondern ein kritisch wichtiges Element, das das Onboarding beschleunigt, die Anzahl der Fehler reduziert und den Code wartbar macht.

TypeScript, als Erweiterung von JavaScript, bietet ein leistungsstarkes Typsystem. Allerdings beantworten Typen allein nicht immer die Frage „Warum?". Die Dokumentation schließt diese Lücke. In diesem Artikel behandeln wir den gesamten Zyklus: von der Wahl des Kommentarstils bis zur Generierung einer statischen Website mit Dokumentation.

1. Grundlagen: JSDoc, TSDoc und TypeScript

Für die Dokumentation von TypeScript-Code haben sich historisch zwei Hauptstandards etabliert: JSDoc und TSDoc. JSDoc ist das altbewährte Format aus der JavaScript-Welt. TSDoc ist ein modernerer Standard, der speziell für TypeScript optimiert ist. Beide Ansätze verwenden Kommentare im Format /** ... */.

Betrachten wir ein einfaches Beispiel mit JSDoc:

/** * Berechnet die Summe zweier Zahlen. * @param a - Erster Summand * @param b - Zweiter Summand * @returns Summe von a und b */function add(a: number, b: number): number {    return a + b;}

Und so sieht es im TSDoc-Stil mit den Tags @param und @returns aus:

/** * Berechnet die Summe zweier Zahlen. * @param a - Erster Summand * @param b - Zweiter Summand * @returns Summe von a und b */function add(a: number, b: number): number {    return a + b;}

Der Unterschied ist minimal, aber TSDoc fügt Unterstützung für TypeScript-spezifische Konstrukte wie Generics und Bedingte Typen hinzu.

1.1 Dokumentation von Interfaces und Typen

Besondere Aufmerksamkeit sollte man Interfaces und Typen widmen. Sie sind das „Skelett" eines TypeScript-Projekts. Hier ist ein Beispiel für ein gut dokumentiertes Interface:

/** * Stellt einen Benutzer des Systems dar. */interface User {    /** Eindeutige Benutzerkennung */    id: string;    /** Vollständiger Name des Benutzers */    name: string;    /** E-Mail-Adresse (muss eindeutig sein) */    email: string;    /** Datum der letzten Anmeldung (optional) */    lastLogin?: Date;    /** Rolle des Benutzers im System */    role: 'admin' | 'user' | 'moderator';}

Beachten Sie: Jeder Parameter des Interfaces hat seinen eigenen /** ... */-Kommentar. Dies ermöglicht es der IDE (z. B. VS Code), bei der Verwendung dieses Interfaces Hinweise anzuzeigen.

2. Fortgeschrittene Techniken: Generics und Bedingte Typen

TypeScript ist bekannt für sein Typsystem, und die Dokumentation sollte dessen Komplexität widerspiegeln. Dies gilt insbesondere für Generics (generische Typen) und Bedingte Typen (conditional types).

Betrachten wir ein Beispiel eines Generics mit Dokumentation:

/** * Erstellt ein Array aus einem Element vom Typ T. * @template T - Der Typ des Elements, das in das Array eingefügt wird * @param item - Das Element zum Einpacken * @returns Array, das das übergebene Element enthält */function wrapInArray<T>(item: T): T[] {    return [item];}

Der Tag @template gibt explizit an, was T ist. Dies ist besonders nützlich, wenn es mehrere Generics gibt oder diese eine komplexe Beziehung zueinander haben.

Für Bedingte Typen wird die Dokumentation noch wichtiger. Beispiel:

/** * Extrahiert den Werttyp aus einem Promise, wenn ein Promise übergeben wird. * Andernfalls wird der ursprüngliche Typ zurückgegeben. * @template T - Der Typ, der ein Promise sein kann oder nicht * @example * // Für Promise<number> wird number zurückgegeben * type Result = UnwrapPromise<Promise<number>>; // number