SAPUI5 und JSDoc: Codedokumentation optimieren

von | Nov 16, 2023 | Unkategorisiert | 0 Kommentare

In umfangreichen SAPUI5-Projekten kann das dynamische Verhalten von JavaScript in den Controllern zu Herausforderungen bezüglich Lesbarkeit und Wartbarkeit führen. Durch die Nutzung von JSDoc, einem standardisierten Dokumentationstool, wird diesem Problem entgegengewirkt.

Was ist JSDoc?

JSDoc ist ein Hilfsmittel in der JavaScript-Entwicklung, das dazu dient, Code durch spezielle Kommentare zu dokumentieren. Es ermöglicht Entwicklern, Funktionen, Klassen und Variablen klar zu beschreiben und automatisch gut strukturierte Dokumentationsseiten zu generieren.

Welche Vorteile bietet JSDoc?

Die Verwendung von JSDoc in einem SAPUI5-Projekt bietet einige Vorteile, unter anderem: 

  • Lesbarkeit: JSDoc verbessert die Lesbarkeit von JavaScript-Code, indem es Entwicklern ermöglicht, Funktionen, Klassen und Variablen mit Kommentaren zu dokumentieren.
  • Typsicherheit: Durch das Hinzufügen von Typinformationen in JSDoc-Kommentaren wird die Sicherstellung von Typkorrektheit unterstützt und die Fehlererkennung während der Entwicklung erleichtert.
  • Automatische Generierung: JSDoc ermöglicht die automatische Generierung von gut strukturierten Dokumentationsseiten, die Parameter, Rückgabetypen etc. übersichtlich darstellen.

Installation von JSDoc und Generierung der Code Dokumentation

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

npm install -g jsdoc

Zum Erstellen des Dokumentations-Files kann auf zwei unterschiedliche Varianten zurückgegriffen werden. Es ist möglich, mithilfe des Konsolenbefehls jsdoc die Standardeinstellungen zu verwenden. Nach Eingabe des Befehls wird die Dokumentation automatisch erstellt.

jsdoc webapp/controller

Die zweite Möglichkeit wäre eine Konfigurationsdatei zu benutzen. Diese ermöglicht es Entwicklern, die JSDoc-Ausgabe an die Anforderungen des Projekts anzupassen

Konfigurationsdatei anlegen

Die Konfigurationsdatei befindet sich üblicherweise im Hauptverzeichnis der UI5-App.

{
 "source": {
 "include": ["webapp/controller"],
 "includePattern": ".js$"
 },
 "plugins": ["plugins/markdown"],
 "templates": {
 "recurse": true,
 "monospaceLinks": true
 },
 "opts": {
 "recurse": true,
 "destination": "./docs/"
 }
}

Nach Anlegen der Datei muss dementsprechend die package.json Datei im selbigen Projekt erweitert werden.

Im Anschluss kann nun folgender Konsolenbefehl benutzt werden

npm run doc

Wichtig zu Beachten hierbei ist, dass beide Commands nach Änderungen im Code immer neu ausgeführt werden müssen um eine neue Dokumenation zu erstellen. 

Preview

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

Code-Dokumentation

Wie bereits erwähnt, startet ein JSDoc-Kommentar immer mit /**. Es ist wichtig zu beachten, dass genau zwei * eingefügt werden müssen. Andernfalls wird die Syntax nicht erkannt, und das beschriebene Element wird nicht in die generierte Dokumentation aufgenommen.

Aufbau von JSDoc

Der allgemeine Aufbau eines JSDoc Kommentars besteht aus einer Beschreibung und Block Tags

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

Welche Block Tags gibt es?

Auf der offiziellen JSDoc-Website findet sich eine umfassende Dokumentation zu Block Tags. Die SAP hat jedoch in ihren SAPUI5-Richtlinien bezüglich JSDoc das Spektrum der zulässigen Block Tags etwas begrenzt.

JSDoc in UI5 implementieren

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

Dokumentation von Klassen

Gemäß den SAP Design Guidelines sollten Klassen immer die folgenden Block-Tags enthalten:

  • @class: Fügt der Kategorie „Classes“ in der API ein Element hinzu.
  • @extends: Gibt an, ob und von welcher Klasse geerbt wird.
  • @author: Verantwortliche(r) Autor(in).
  • @since: Version, in der die Klasse erstellt wurde.
sap.ui.define([
 "at/clouddna/controller/BaseController",
 "sap/m/MessageBox",
 "sap/ui/model/json/JSONModel",
 "sap/ui/core/Fragment",
 "sap/ui/core/Item"
],
 function (BaseController, MessageBox, JSONModel, Fragment, Item) {
 "use strict";
 /**
 * This class manages a Customer
 * 
 * Detailed description of the class
 * @class Customer
 * @extends BaseController
 * @author Example Author
 * @since 1.96.0
 */
 return BaseController.extend("at.clouddna.training.controller.Customer", {
 ...
 });

Dokumentation von Funktionen und Parametern

Folgende Block-Tags sollten laut SAP Design Guidelines immer für die Beschreibung von Funktionen und Parametern vorhanden sein:

  • @public/@protected/@private: Gibt die Sichtbarkeit der Methoden in der API an. Private-Methoden werden NICHT in der API angezeigt.
  • @param: Gibt den Typen des Parameters an.
  • @returns: Gibt den Return-Type an.
/**
 * Creates a Path where Documents can be uploaded and returns it
 * @public
 * @param {string} sDocId - Document ID
 * @param {string} sCustomerId - Customer ID
 * @returns {string}
 */
 formatUrl: function(sDocId, sCustomerId){
 let sPath = this.getView().getModel().createKey("/CustomerDocumentSet", {
 DocId: sDocId,
 CustomerId: sCustomerId
 });
 return this.getView().getModel().sServiceUrl + sPath + "/$value";
 },
/**
 * Refreshes the UploadSet
 * @public
 */
 onUploadCompleted: function(){
 this.getView().getModel().refresh(true);
 },
/**
 * Removes an Item from the UploadSet
 * @param {object} oEvent - Event object
 * @public 
 */
 onRemovePressed: function(oEvent){
 oEvent.preventDefault();
 let sPath = oEvent.getSource().getBindingContext().getPath();
 this.getView().getModel().remove(sPath);
 }

Fazit

In SAPUI5 ist die Nutzung von JSDoc ein echter Gamechanger. Durch die Dokumentation von Klassen und Methoden nach den SAP Design Guidelines wird nicht nur der Code verständlicher, sondern auch die Zusammenarbeit im Team deutlich verbessert. Die Verwendung von Block-Tags wie @public oder @private wir die Sichtbarkeit gesteuert, und das Ganze trägt dazu bei, dass SAPUI5 Projekte nicht nur effizienter, sondern auch leichter wartbar sind. JSDoc ist sozusagen der zuverlässige Begleiter für einen gut strukturierten und transparenten SAPUI5-Code.