TypeDoc in SAPUI5: Automatische Code-Dokumentation

von | Jan. 3, 2024 | Blog, Unkategorisiert | 0 Kommentare

TypeDoc in SAPUI5

Ihr erfahrt alles über TypeDOC in SAPUI5

In der Welt der SAPUI5-Entwicklung hat sich in den letzten Jahren eine interessante Veränderung vollzogen, nämlich die Integration von TypeScript als alternative Programmiersprache. TypeScript bietet Entwicklern die Möglichkeit, SAPUI5-Anwendungen mit statischer Typisierung zu entwickeln, was zur Verbesserung der Code-Qualität beiträgt. Daher wird TypeScript unter SAPUI5-Entwicklern als Alternative zu dem extrem dynamischen JavaScript immer beliebter.

Trotz der Vorteile, die TypeScript bietet, kann man, wie auch in JavaScript, den Code umfassend dokumentieren. Hierfür eignet sich vor allem TypeDoc.

Was ist TypeDoc?

TypeDoc ist, wie auch JSDoc, ein Code-Dokumentationstool. Es generiert automatisch aus dem TypeScript-Quellcode eine übersichtliche und strukturierte Dokumentation, die die Verständlichkeit der Codebasis deutlich verbessert. Durch die klare Darstellung von Typen, Funktionen und Modulen trägt TypeDoc dazu bei, die Wartbarkeit des Codes zu verbessern und einen schnellen Überblick über die Projektarchitektur zu ermöglichen.

Hier kommt ihr zu den CloudDNA Büchern | Rheinwerk Verlag
CloudDNA Bücher

Installation von TypeDoc und Generierung der Code Dokumentation

Um TypeDoc über die Konsole zu installieren, kann npm (Node Package Manager) verwendet werden. Folgender Konsolenbefehl dient zur Installation von JSDoc:

npm install typedoc

Wie auch in JSDoc gibt es hier ebenfalls die Möglichkeit, ein Konfigurationsfile anzulegen. Allerdings wird hier darauf nicht weiter eingegangen, da die Standardvariante von TypeDoc bereits eine sehr übersichtliche und qualitativ hochwertige Code-Dokumentation generiert.

Um TypeDoc auszuführen und die Dokumentation zu generieren, muss das package.json-File erweitert werden.

"scripts": {
    "doc": "typedoc ./webapp/**/*.ts",
     ...
  },

Nun kann durch Ausführen des folgenden Befehls die Dokumentation generiert werden. Allerdings wird die Dokumentation nicht automatisch aktualisiert, sobald sich der Quellcode ändert. Falls also eine Neue benötigt wird, muss der Befehl erneut ausgeführt werden.

npm run doc

Preview

Nach Ausführung des obigen Befehls zur Dokumentationserstellung wird im Hauptverzeichnis der docs Ordner erstellt. Dieser Folder enthält die gesamte Dokumentation einschließlich aller generierten HTML-Dateien, die im Browser eingesehen werden können.

Durch Klicken auf einen der sichtbaren Links gelangt man zur konkreten Beschreibung des Controllers. Initial werden nur die public Methoden bzw. Variablen angezeigt, allerdings können sowohl protected, private , sowie external über die Einstellungen hinzugefügt werden.

Code-Dokumentation

TypeDoc-Kommentare werden im Code mit /** gekennzeichnet. Wichtig zu beachten ist allerdings, dass der Kommentar mit genau zwei * beginnt, da die Syntax sonst nicht erkannt wird und das beschriebene Element nicht in die generierte Dokumentation aufgenommen wird.

Aufbau von TypeDoc

Im Grunde unterscheiden sich TypeDoc Kommentare nicht von JSDoc Kommentaren. Daher gilt auch hier, der allgemeine Aufbau eines Kommentars besteht aus einer Beschreibung und Block Tags.

/**
 *Kommentar
 *@block-tag
 */
sichtbarkeit funktionsName(parameter){
	...
}

Welche Block Tags gibt es?

Auf der offiziellen TypeDoc-Website findet sich eine umfassende Dokumentation der verfügbaren Block-Tags. Anders als bei JSDoc, gibt es für TypeDoc keine offiziellen Guidelines der SAP. Man sollte sich daher an den JSDoc-Guidelines orientieren.

TypeDoc in UI5 implementiren

Die nachfolgenden Beispiele veranschaulichen eine konkrete Implementierung von TypeDoc in SAPUI5.

Dokumentation von Klassen

Es ist nicht nötig die Klasse selber zu annotieren, da TypeDoc sowohl Base- als auch Parentklassen automatisch erkennt.

Dokumentation von Funktionen

Folgende Block-Tags sollten für die Beschreibung von Funktionen und Parametern vorhanden sein:

  • @public/@protected/@private: Gibt die Sichtbarkeit der Methoden in der API an
  • @param: Gibt den Typen des Parameters an.
  • @returns: Gibt den Return-Type an.
    /**
     * Sets a value state for a DatePicker
     * @private
     * @param dateInput - DatePicker instance
     */
    private setErrorValueState(dateInput: DatePicker){
        dateInput.setValueState("Error");
        dateInput.setValueStateText("No appointment available");
    }

    /**
     * Returns customer Ids
     * @public
     * @param oEvent - Event object
     * @returns {number} - Array containing customer Ids
     */
    public getCustomerIds(oEvent: Event): number[]{
        return [1,2,3,4]
    }

Fazit TypeDOC in SAPUI5

TypeDoc ist in einem SAPUI5-Projekt äußerst nützlich, da es automatisch eine übersichtliche und strukturierte Dokumentation aus dem TypeScript-Quellcode generiert. Diese Dokumentation verbessert die Verständlichkeit der Codebasis und trägt zur Wartbarkeit des Codes bei, indem sie eine klare Darstellung von Typen, Funktionen und Modulen bietet.