SAP NetWeaver AS ABAP Release 751, ©Copyright 2017 SAP AG. Alle Rechte vorbehalten.
ABAP - Schlüsselwortdokumentation → ABAP - Referenz → ABAP-Syntax → Programmdirektiven →ABAP Doc
ABAP Doc ermöglicht die Dokumentation von Deklarationen in ABAP-Programmen auf der Grundlage spezieller ABAP-Doc-Kommentare. In einer ABAP-Entwicklungsumgebung wie den ABAP Development Tools (ADT) , die ABAP Doc unterstützt, wird der Inhalt von ABAP-Doc-Kommentaren ausgewertet, nach HTML konvertiert und geeignet dargestellt.
ABAP-Doc-Kommentare
Ein Kommentar für ABAP Doc wird durch die Zeichenfolge "! eingeleitet. Es handelt sich um eine spezielle Form eines mit " eingeleiteten normalen Zeilenendekommentars. Damit ein ABAP-Doc-Kommentar richtig ausgewertet werden kann, müssen folgende Regeln eingehalten werden:
Ein Verstoß gegen diese Regeln führt zu einer Warnung von der Syntaxprüfung.
Beispiel
Grundlegende Verwendung von ABAP-Doc-Kommentaren als einzelne Zeilen, als Block und in Kettensätzen.
Parameterschnittstelle von Prozeduren
Die Parameterschnittstelle von Prozeduren sowie von Ereignissen in Klassen kann im zugehörigen ABAP-Doc-Kommentar mit einer speziellen Syntax dokumentiert werden:
Dokumentation für | Syntax |
Schnittstellenparameter | @parameter name|documentation |
Klassenbasierte Ausnahme | @raising name|documentation |
Klassische Ausnahme | @exception name|documentation |
Hinter @parameter, @raising, @exception muss der Name name eines vorhandenen Parameters bzw. einer Ausnahme angegeben werden. Dahinter muss abgetrennt durch das Zeichen | die zugehörige Dokumentation folgen. Diese Dokumentation wird durch das nächste @parameter, @raising, @exception oder durch das Ende des ABAP-Doc-Kommentars abgeschlossen. Hinter einer Schnittstellendokumentation darf also keine andere Dokumentation mehr folgen als eine weitere Schnittstellendokumentation. Jeder Schnittstellenparameter bzw. jede Ausnahme darf nur einmal aufgeführt werden.
Hinweis
Die Anordnung der Dokumentation der Parameterschnittstelle von Prozeduren ist unabhängig von der Anordnung der Zeilen in einem ABAP-Doc-Block. Aus Gründen der Lesbarkeit sollte aber jeder Parameter bzw. jede Ausnahme eine eigene Zeile einleiten. Aus den gleichen Gründen sollte die Reihenfolge der Parameter und Ausnahmen im ABAP-Doc-Kommentar der Reihenfolge der Deklarationen entsprechen.
Beispiel
Verwendung von ABAP-Doc-Kommentaren für die Parameterschnittstelle einer Methode.
Formatierungen
Innerhalb der Dokumentationstexte eines ABAP-Doc-Kommentars können folgende Tags verwendet werden, um die Ausgabe der Dokumentation in einer geeigneten Entwicklungsumgebung zu formatieren.
Formatierung | Tag |
Überschrift, Ebene1 | <h1>...</h1> |
Überschrift, Ebene2 | <h2>...</h2> |
Überschrift, Ebene3 | <h3>...</h3> |
Absatz | <p>...</p> |
Kursiv hervorgehobener Text | <em>...</em> |
Stark hervorgehobener Text | <strong>...</strong> |
Unnummerierte Liste | <ul><li>...</li>...<li>...</li></ul> |
Nummerierte Liste | <ol><li>...</li>...<li>...</li></ol> |
Zeilenumbruch | <br/> oder <br></br> |
Ein geöffnetes Tag muss geschlossen werden, bevor ein neuer Abschnitt des ABAP-Doc-Kommentars beginnt. Ein neuer Abschnitt wird durch @parameter, @raising oder @exception eingeleitet.
Die Tags sind eine Teilmenge von HTML-Tags, die in einer XHTML-konformen Notation angegeben werden müssen:
Beispiel
Verwendung von Formatierungen in einem ABAP-Doc-Kommentar zu einer Klasse. Die ABAP Development Tools stellen die Dokumentation entsprechend formatiert dar.
Kurztexte und deren Synchronisation
Teile von ABAP-Doc-Kommentaren können als Kurztexte gekennzeichnet werden und die Kurztexte von Klassen und Funktionsbausteinen und deren Komponenten können mit ABAP-Doc-Kommentaren synchronisiert werden. Um einen Teil eines ABAP-Doc-Kommentars als Kurztext zu kennzeichnen, kann er wie folgt getaggt werden:
Ein solcherart gekennzeichneter Absatz wird bei der Anzeige der Dokumentation in den ADT statt des Kurztexts, der in der ABAP Workbench zu sehen ist, als Überschrift angezeigt.
Um eine Synchronisation der Kurztexte von ABAP Doc und den in der ABAP Workbench angezeigten Kurztexten zu bewirken, kann der Tag optional wie folgt angegeben werden:
In diesem Fall ist die Länge des Kurztexts in ABAP Doc auf die Länge des entsprechenden Kurztexts der ABAP Workbench beschränkt und er wird wie folgt mit dem zugehörigen Kurztext in der Originalsprache der Klasse bzw. des Funktionsbausteins synchronisiert:
Ein Kurztext von ABAP Doc ist als Teil des Quelltexts nicht an die Übersetzung angeschlossen. Da er bei einer Synchronisation den an die Übersetzung angeschlossenen Kurztext des Repository Objekts in dessen Originalsprache ersetzt, muss auch er in der Originalsprache angegeben werden. Das ist eine Abweichung von der Regel, dass ABAP-Doc-Kommentare immer englisch sein sollten. Um die Originalsprache im Quelltext kenntlich zu machen, kann sie wie folgt optional angegeben werden:
Das Attribut lang folgt dem HTML-Standard. Mit ihm muss die Originalsprache des Repository Objekts als zweistelliges ISO-Kürzel angegeben werden, andernfalls kommt es zu einer Warnung von der Syntaxprüfung. Das Attribut macht im Quelltext deutlich, in welcher Sprache der Kurztext angegeben werden sollte. Weiterhin ist es für zukünftige Erweiterungen bezüglich der Übersetzbarkeit von Kurztexten vorgesehen.
Beispiel
Siehe die Klasse CL_DEMO_ABAP_DOC in einem Quelltexteditor. Sie enthält ABAP-Doc-Kommentare für die Klasse selbst, einen Typ, eine Methode und ihre Parameter sowie für ein Attribut. Die ABAP-Doc-Kommentare umfassen Kurztexte, die mit den Kurztexten der ABAP Workbench in der Originalsprache Englisch synchronisiert sind. Sie können die Klasse in eine eigene temporäre Klasse kopieren, um die Synchronisation zu testen.
Richtlinien
Programmierrichtlinien
Die folgenden Richtlinien für allgemeine Kommentare gelten insbesondere auch ABAP-DOC-Kommentare.