DE
RU
EN
ES
ZH
FR
PT
AR
HI
Einleitung: Warum Dokumentation keine langweilige Pflicht, sondern eine Superkraft ist
\n\nStellen Sie sich vor: Sie kehren nach einem halben Jahr zu Ihrem Projekt zurück. Sie öffnen die Datei mit der Autorisierungslogik – und sehen ein Meer von TypeScript-Code. Typen sind vorhanden, Schnittstellen sind definiert, aber was macht diese Funktion? Warum heißt der Parameter opts und welche Felder hat er? Kommt Ihnen das bekannt vor?
Dokumentation in TypeScript ist nicht nur „Kommentare der Form halber". Es ist ein Werkzeug, das Ihren Code in eine verständliche Geschichte verwandelt. Gute Dokumentation spart Stunden beim Debuggen, beschleunigt das Onboarding neuer Teammitglieder und macht Ihre API benutzerfreundlich. In diesem Artikel behandeln wir die besten Praktiken zur Dokumentation von TypeScript-Projekten: von grundlegenden JSDoc-Kommentaren bis hin zur fortgeschrittenen Dokumentationsgenerierung mit TypeDoc. Los geht's!
\n\n1. JSDoc und TSDoc: Das Fundament Ihrer Dokumentation
\n\nTypeScript hat von JavaScript das beliebte Format JSDoc geerbt, und dann hat die Community TSDoc entwickelt – eine standardisierte Syntax für TypeScript. Wenn Sie eine Bibliothek oder API schreiben, ist TSDoc Ihre Wahl. Es ist strenger, besser in Editoren und Dokumentationsgeneratoren integriert.
\n\nBasis-Tags von TSDoc
\n\nHier ist das Minimum, das jeder Entwickler kennen sollte:
\n\n- \n
@param– Beschreibung eines Funktionsparameters \n @returns– Was die Funktion zurückgibt \n @throws– Welche Ausnahmen sie werfen kann \n @example– Anwendungsbeispiel \n @deprecated– Markierung von veraltetem Code \n
/**\n * Berechnet den Rabatt auf einen Artikel unter Berücksichtigung eines Aktionscodes.\n * \n * @param price - Ursprünglicher Preis des Artikels (muss größer als 0 sein)\n * @param discountPercent - Rabatt in Prozent (von 0 bis 100)\n * @param promoCode - Aktionscode, der den Rabatt erhöhen kann\n * @returns Endgültiger Preis nach Anwendung des Rabatts\n * @throws {Error} Wenn Preis oder Prozentwert ungültig sind\n * \n * @example\n * // Beispiel: 20% Rabatt auf einen Artikel für 1000 Rubel\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n price: number,\n discountPercent: number,\n promoCode?: string\n): number {\n if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n throw new Error('Ungültige Parameter');\n }\n \n let discount = discountPercent;\n if (promoCode === 'SUMMER') {\n discount += 10; // zusätzlicher Rabatt\n }\n \n return price * (1 - discount / 100);\n}\nTipp: Beschreiben Sie immer Grenzfälle. Wenn ein Parameter undefined sein kann, geben Sie dies in der Beschreibung an. TypeScript-Typen sind gut, aber die menschliche Sprache fügt Kontext hinzu.
2. Dokumentieren Sie Typen und Schnittstellen
\n\nEine der Hauptfunktionen von TypeScript ist das leistungsstarke Typsystem. Aber selbst der strengste Typ erklärt nicht den Zweck eines Feldes. Dokumentieren Sie Schnittstellen genauso gründlich wie Funktionen.
\n\n/**\n * Konfiguration für die Verbindung zu einer externen Wetter-API.\n */\ninterface WeatherApiConfig {\n /** Basis-URL der API (z. B. https://api.weather.com) */\n baseUrl: string;\n \n /** Authentifizierungsschlüssel, vom Anbieter erhalten */\n apiKey: string;\n \n /** \n * Anzahl der Sekunden, die auf eine Antwort vom Server gewartet wird.\n * Standardwert ist 5 Sekunden.\n */\n timeout?: number;\n \n /**\n * API-Version. Wenn nicht angegeben, wird die neueste stabile Version verwendet.\n * @deprecated Verwenden Sie das Feld `version` in der URL\n */\n apiVersion?: string;\n}\nBeachten Sie: Für timeout haben wir den Standardwert direkt im Kommentar angegeben. Das erspart dem Entwickler den Blick in den Quellcode oder die Tests.
3. Dokumentationsgenerierung: Kommentare in eine Website verwandeln
\n\nKommentare zu schreiben ist die eine Hälfte. Man muss sie in eine benutzerfreundliche Dokumentation verwandeln können. Für TypeScript ist das beste Werkzeug TypeDoc. Es parst Ihre TSDoc-Komment
