ABAP Cloud - Dokumentation
Ein wichtiger Teil in der ABAP Entwicklung ist eine gute und nachhaltige Dokumentation die am besten so nah wie möglich am eigentlichen Code ist. In diesem Artikel schauen wir uns das Thema einmal etwas näher an.
Inhaltsverzeichnis
In diesem Artikel schauen wir uns verschiedene Arten der Dokumentation an und wie du unter ABAP Cloud eine saubere Dokumentation im System erstellen kannst.
Einleitung
Was gehört eigentlich in eine technische Dokumentation? Was sollte in der fachlichen Dokumentation stehen und wie können wir uns als Entwickler das Leben etwas leichter machen? Beim Thema Dokumentation fangen viele Entwickler an zu flüchten, da sie es als lästig und zeitintensiv betrachten. Eine gute Dokumentation reduziert allerdings auch das Thema Einarbeitung oder Verständnis von anderen Entwickler und ist dabei ein wichtiger Bestandteil der Software Entwicklung. Wie können wir also im Umfeld von ABAP Cloud gute Dokumentationen zur Verfügung stellen?
Zweck
Eine Dokumentation soll die Einarbeitung und das Verständnis von Code unterstützen. Liegt sie nah am eigentlichen Quellcode oder Objekt, musst du als Entwickler nicht lange nach der richtigen Dokumentation oder der Vollständigkeit suchen. In der Dokumentation kannst du noch weitere Informationen mitgeben, die der eigentliche Code erst einmal nicht "erzählt", wenn er sprechend geschrieben ist.
Für die Ablage von Informationen stehen im System und Eclipse zwei Methodiken zur Verfügung, die du neben den Kommentaren im Code verwenden kannst. Dazu gehören die ABAP Docs, die es bereits sehr lange gibt und "releativ" neu, das Knowledge Transfer Document. Die beiden Methodiken werden wir in den folgenden Kapiteln näher beleuchten.
ABAP Docs
Die ABAP Docs werden in den ABAP Development Tools bereits seit Anfang an unterstützt. Damit hast du eine einfache Möglichkeit deine Objekte mit einer Dokumentation auszustatten, ohne dabei den Quellcode zu überladen. Die Dokumentation wir dabei an der Definition der Methode, Klasse, Interfaces definiert und kann dann einfach an jeder Stelle über die Element Info abgerufen werden.
Anlage
Möchtest du zum Beispiel eine Methode dokumentieren, dann schreibst du die Dokumentation vor die Methode, hier kannst du alles manuell machen. Damit kannst du im Grunde die Methode grob dokumentieren, dabei erzeugst du allerdings keine Dokumentation für die verschiedenen Parameter.
"! The method takes the parameter and checks the content
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
Über die ABAP Development Tools kannst du dir auch ganz einfach das Template generieren lassen und im Anschluss den Text und die Parameter befüllen. In diesem Fall musst du auch nicht die komplette Syntax für die verschiedenen Parameter beherrschen.
Zum Abschluss sollte unser Kommentar nun wie folgt aussehen, der obere Teil beschreibt die Methode im Allgemeinen und die einzelnen Parameter werden separat beschrieben.
"! The method takes the parameter and checks the content
"! @parameter charlike | The parameter is character-like
"! @parameter result | The result is right
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
Formatierung
ABAP Docs werden als HTML geparst, daher kannst du viele Elemente aus dem HTML verwenden, um eine Struktur und eine bessere Übersicht in die Dokumentation zu bringen. So funktionieren Elemente wie ein Paragraph, Listen, Überschriften und Formatierungen wie Fett oder Kursiv. Dazu ein Beispiel:
"! <h1>Start of the document</h1>
"! <p>This is the first line of the text, with a nice little <strong>paragraph.</strong></p>
"! <p>Now we follow with a second paragraph, to make the documentation complete.</p>
"! <ul>
"! <li>Item No. 1</li>
"! <li>Item No. 2</li>
"! <li>Item No. 3</li>
"! </ul>
METHODS formatted_docs.
Weitere Informationen zur Formatierung und den Möglichkeiten findest du in der technischen Dokumentation auf SAP Help bzw. unten verlinkt. Dort solltest du dir auch anschauen, wie du verschiedene Objekte in der Dokumentation miteinander verlinken kannst.
Anzeige
ABAP Docs verwendest du vor allem im Umfeld von Klassen und Interfaces, möchtest du dir die Informationen anzeigen, dann musst du nur die entsprechende Methode oder Klasse im Quellcode markieren und/oder den Cursor platzieren und bekommst mit F2 die Element Info angezeigt. Grundsätzlich kannst du den View auch dauerhaft anzeigen und die Anzeige mit der Auswahl synchronisieren lassen.
Schauen wir uns im zweiten Schritt noch die Formatierung der anderen Methode an. Vielleicht wird dir auffallen, dass die Überschrift nur Fett dargestellt wird, aber nicht unbedingt eine große Überschrift. Das wird dann im nächsten Abschnitt erst wichtig.
Export
Ein Vorteil der ABAP Docs im System ist der Export der kompletten Dokumentation auf verschiedenen Ebenen. Grundsätzlich hast du die aktuelle Dokumentation im System und solltest sie auch dort lassen. Wird allerdings einmal die Dokumentation extern benötigt, zum Beispiel bei einer Prüfung durch die Revision, kannst du sie leicht aus dem System exportieren und als HTML formatiert zur Verfügung stellen. Dazu über den "Project Explorer" auf ein Objekt oder Paket per Rechts-Klick gehen und "Export" wählen. Im Bereich ABAP findest du die entsprechende Option.
Im nächsten Schritt wählen wir das System für den Export und können weitere Objekte oder Pakete hinzufügen. Über die Sichtbarkeit können wir einstellen, ob wir die gesamte Dokumentation oder nur den öffentlichen Teil exportieren wollen. Im Bereich Ziel kannst du das Verzeichnis für den Export angeben.
Als Ergebnis erhältst du den Stand des Exports in die Konsole. Da wir zwei private Methoden definiert haben, müssen wir vor dem Export dann die Sichtbarkeit einstellen. In der Ordnerstruktur findest du neben einer readme Datei und dem htmldesging mit der CSS Datei die eigentlichen Dokumentationen. Die HTML Dateien kannst du dann in deinem Browser öffnen und bekommst das formatierte Ergebnis. Hier zieht dann auch die definierte Überschrift aus der Dokumentation.
ABAP Cleaner
Es gibt im ABAP Cleaner auch ein paar Einstellungen, die deine ABAP Docs auch entsprechend erweitern. So kannst du fehlende Parameter automatisch ergänzen lassen, das lang-Tag entfernen lassen oder den Kommentar automatisch einrücken. Vielleicht kommen in Zukunft auch noch ein paar mehr Features.
IDE Actions
Bei IDE Actions verwendest du auch so ähnliche Annotationen, um die Typen und Funktionen näher zu beschreiben. Anders als ABAP Docs, wird das JSON Schema zur Typisierung und Anreicherung der Daten verwendet. Daher solltest du diese Annotationen nicht mit ABAP Doc verwechseln.
Knowledge Transfer Document
Das Knowledge Transfer Document oder kurz KTD gibt es seit dem Release 2020 und ist ein eigenes Workbench Artefakt. Dabei wird es zur Dokumentation komplexer und neuer Artefakte verwendet, wie dem Service Bindung und der Service Definition und der Verhaltensdefinition im RAP. Da ein RAP Objekt relativ groß und komplex werden kann, lohnt sich hier eine Dokumentation besonders.
Anlage
Das KTD Dokument wird immer im gleichen Paket angelegt, wie das eigentliche Objekt das dokumentiert werden soll. Verschiebst du das Objekt innerhalb der Pakete, wird auch automatisch die Dokumentation verschoben. Du kannst auf den Unterstützten Objekten die KTD direkt über das Kontextmenü anlegen.
Nach der Anlage auf einer Verhaltensdefinition zum Beispiel, siehst du die gesamte Struktur des Objekts und kannst die Dokumentation an den entsprechenden Knoten durchführen.
Pflege
Das KTD wird in einem Editor über Markdown gepflegt, dabei handelt es sich um eine einfache Möglichkeit Texte zu formatieren und Links einzufügen. Dabei bleibt der Text weiterhin lesbar, kann aber von einem Interpreter sauber nach HTML konvertiert werden.
Über den Shortcut STRG + LEER kannst du die Eingabehilfe für die Formatierung aufrufen und so ohne tiefere Markdown Kenntnisse das Dokument aufbereiten.
Anzeige
Wenn du im Editor von "Source" auf "Output" umstellst, gelangst du in den Anzeigemodus und kannst dir das Dokument und die finale Formatierung anschauen.
Bist du in einem entsprechenden Objekt, welches KTD unterstützt, findest du den Absprung im oberen Teil des Objekts. In diesem Fall in einer Verhaltensdefinition. Damit hast du direkt einen Indikator, wenn eine Dokumentation zu einem Objekt vorhanden ist.
Business Configuration
Legst du ein Knowledge Transfer Document auf einem "Business Configuration Maintenance Object" an, dann erhältst du in der Fiori Anwendung einen neuen Button zur Anzeige der Dokumentation in der Anwendung. Damit gibst du dem Anwender die Möglichkeit mehr Details oder eine Dokumentation der Konfiguration zu erhalten. Lohnt sich vor allem bei komplizierten Pflegeviews mit vielen abhängigen Daten oder komplexen Eingaben.
Wenn der Button in der Anwendung betätigt wird, dann erhältst du die Dokumentation in einem Popup, auch hier funktionieren Links, um zum Beispiel weitere Dokumentationen oder Anwendungen zu verlinken.
Vollständiges Beispiel
Die komplette Klasse aus dem heutigen Artikel findest du in diesem Abschnitt. Das Knowledge Transfer Document haben wir hier nicht verlinkt oder abgelegt.
CLASS zcl_bs_demo_abap_docs DEFINITION
PUBLIC FINAL
CREATE PUBLIC.
PUBLIC SECTION.
INTERFACES if_oo_adt_classrun.
PRIVATE SECTION.
"! The method takes the parameter and checks the content
"! @parameter charlike | The parameter is character-like
"! @parameter result | The result is right
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
"! <h1>Start of the document</h1>
"! <p>This is the first line of the text, with a nice little <strong>paragraph.</strong></p>
"! <p>Now we follow with a second paragraph, to make the documentation complete.</p>
"! <ul>
"! <li>Item No. 1</li>
"! <li>Item No. 2</li>
"! <li>Item No. 3</li>
"! </ul>
METHODS formatted_docs.
ENDCLASS.
CLASS zcl_bs_demo_abap_docs IMPLEMENTATION.
METHOD if_oo_adt_classrun~main.
DATA(result) = first_method_with_parameter( 'Dummy Value' ).
out->write( result ).
ENDMETHOD.
METHOD first_method_with_parameter.
ENDMETHOD.
METHOD formatted_docs.
ENDMETHOD.
ENDCLASS.
Fazit
Möchtest du mehr zu den ADT Features und ihrem Release erfahren, kannst du bei der Feature Matrix vorbeischauen und prüfen ob zum Beispiel KTD auf deinem System funktioniert. Dokumentationen sind ein wichtiger Bestandteil der Software Entwicklung und erleichtern das Leben deiner Kollegen. Mit unseren Tipps sollte dir das Thema nun etwas leichter fallen und du kannst an den passenden Stellen eine Dokumentation hinterlegen.
Weitere Informationen:
SAP Help - Long Texts
SAP Help - ABAP Doc Comments
SAP Help - Knowledge Transfer Documents
SAP Help - ABAP Doc
