HOWTO · TypeScript
TypeScript-Kommentare
Die Doc-Kommentare werden von jeder Programmiersprache verwendet, um ihre eigene API-Dokumentation zu generieren. Dementsprechend verwendet TypeScript die TSDoc-Spezifikation, um seine Dokumentation und Metadaten für die Codebasis zu generieren.
In diesem Artikel geht es um Dokumentkommentare in TypeScript.
Die Notwendigkeit von Doc-Kommentaren
Die Dokumentkommentare können in den meisten Programmiersprachen angezeigt werden. Sein Hauptzweck ist es, Dokumentation für die gegebene Codebasis zu generieren.
Wir verwenden JavaDoc, um die Dokumentation in Java zu generieren, und JSDoc ist der API-Dokumentationsgenerator für JavaScript. Das TypeScript verwendet TSDoc, um seine API-Dokumentation zu generieren.
Verwenden Sie TSDoc, um API-Dokumentation in TypeScript zu generieren
Das TSDoc ist eine Spezifikation, die Programmierern sagt, wie sie ihre Codebasis kommentieren können. Damit Tools API-Dokumentation generieren und Metadaten für die TypeScript-Codebasis erstellen können.
Das Microsoft TypeScript-Team pflegt die TSDoc-Spezifikation. In JSDoc müssen wir die Annotationen verwenden, um die Typen explizit anzugeben.
Da TypeScript eine typisierte Sprache ist, müssen wir in TSDoc keine Anmerkungen verwenden, und es hilft, ohne Probleme informativere Dokumentationen zu erstellen.
TSDoc-Kommentare beginnen mit zwei Sternchen, wie im Folgenden gezeigt.
/**
*
*
*/
Außerdem bietet es eine Anmerkungsmarkierung @, um spezielle Informationen wie Parameter, Rückgabetypen und vieles mehr anzugeben, wie im Folgenden gezeigt.
export class Square {
/**
* @Returns the area of the given square.
*
* @param width - width of the square
* @param height - the height of the square
* @returns The multiplication of `width` and `height`.
*/
static calculateArea(width: number, height: number): number {
return width * height;
}
}
Verwenden Sie Visual Studio Code zum Generieren der API-Dokumentation
Der Dokumentkommentar begann mit zwei Sternchen und wird fortgesetzt. Die Annotationen @Returns, @param haben zusätzliche Informationen bezüglich der Codebasis gegeben.
Wir können Visual Studio Code verwenden, um die generierte API-Dokumentation für die Funktion calculateArea anzuzeigen.
Verwenden Sie TypeDoc, um TSDoc-Kommentare in HTML-Dokumentation umzuwandeln
Die TSDoc-Kommentare können auch zur Generierung von HTML-Dokumentation verwendet werden. Dann müssen wir das Dienstprogramm TypeDoc verwenden, um TSDoc-Kommentare in gerenderte HTML-Dokumentation umzuwandeln.
Zuerst muss unbedingt typedoc installiert werden, wie unten gezeigt.
npm install --save-dev typedoc
Dann können wir die HTML-Dokumentation einfach mit dem Befehlszeilenprogramm typedoc generieren.
typedoc --out docs .
Verschiedene Tools können TSDoc-Kommentare in Ihrem TypeScript-Code verwenden und diese analysieren, um API-Dokumentation, HTML-Dokumentation und andere nützliche Informationen zur Codebasis zu generieren.
