---

SAP NetWeaver AS ABAP Release 752, ©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

• Parameterschnittstelle von Prozeduren

• Formatierungen

• Kurztexte und deren Synchronisation

• Dokumentationsverweise

• Richtlinien

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 ABAP-Doc-Kommentar ist entweder

• eine einzelne Kommentarzeile, die nichts außer dem Kommentar enthält,

• oder ein mehrzeiliger Block direkt aufeinander folgender solcher Kommentarzeilen. Der Inhalt eines Blocks wird zu einem einzigen ABAP-Doc-Kommentar zusammengefasst.

• Ein ABAP-Doc-Kommentar (eine Zeile oder ein Zeilenblock) muss wie folgt mit genau einer Deklarationsanweisung verknüpft sein:

• Wenn die Deklarationsanweisung keinen Kettensatz bildet, darf ein ABAP-Doc-Kommentar direkt vor der Deklarationsanweisung stehen und nicht durch Leerzeilen abgetrennt sein.

• Wenn die Deklarationsanweisung einen Kettensatz bildet, muss der Doppelpunkt hinter dem Schlüsselwort stehen und ein ABAP-Doc-Kommentar darf direkt vor dem Bezeichner jeder deklarierten Entität stehen.

An anderen Stellen darf kein ABAP-Doc-Kommentar aufgeführt werden.

• Ein einzeiliger ABAP-Doc-Kommentar darf nicht leer sein. In Blöcken sind Zeilen ohne Inhalt als Formatierungsmittel erlaubt.

• Ein ABAP-Doc-Kommentar kann spezielle Tokens und Tags enthalten um die Parameterschnittstelle von Prozeduren zu dokumentieren oder um Formatierungen vorzunehmen (siehe unten).

• Die Sonderzeichen ", ', <, >, @, {, |, } können bei Bedarf durch &quot;, &apos;, &lt;, &gt;, &#64;, &#123;, &#124;, &#125; maskiert 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.

"! Basic usage of ABAP Doc
CLASS demo DEFINITION.
  PUBLIC SECTION.
    "! Constant character string for a single blank.
    CONSTANTS blank TYPE string VALUE ` `.
    "! Method to fill the private structure struct with values
    "! and append it to internal table itab.
    METHODS meth.
  PRIVATE SECTION.
    DATA:
      "! Three-component structure
      BEGIN OF struct,
        "! Component one
        comp1 TYPE i,
        "! Component two
        comp2 TYPE i,
        "! Component three
        comp3 TYPE i,
      END OF struct,
      "! Internal table of structure struct
      itab LIKE TABLE OF struct.
ENDCLASS.

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

Die Angaben @parameter, @raising, @exception müssen direkt hinter "! stehen und damit eine eigene Zeile einleiten. 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 Reihenfolge der entsprechenden Deklarationen. Aus Gründen der Lesbarkeit sollte aber 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.

"! Method to check if two sources are identical
"! and that returns a corresponding boolean value.
"!
"! @parameter source1     | First source
"! @parameter source2     | Second source
"! @parameter ignore_case | Pass abap_true to ignore case
"!
"! @parameter result      | Returns abap_true if sources are identic
"!
"! @raising   cx_invalid_source
"!                        | One of the sources is empty
METHODS compare
  IMPORTING
    source1       TYPE text
    source2       TYPE text
    ignore_case   TYPE abap_bool DEFAULT abap_false
  RETURNING
    VALUE(result) TYPE abap_bool
  RAISING
    cx_invalid_source.

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. Die Tags sind eine Teilmenge von HTML-Tags.

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>

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.

Es sind folgende Attribute möglich:

• Im <ol>-Tag können die Attribute reversed, start und type mit ihrer in HTML üblichen Bedeutung angegeben werden.

• Im <p>-Tag können die Attribute class und lang angegeben werden. Für die Bedeutung dieser Attribute siehe unten "Kurztexte und deren Synchronisation".

Beispiel

Verwendung von Formatierungen in einem ABAP-Doc-Kommentar zu einer Klasse. Die ABAP Development Tools stellen die Dokumentation entsprechend formatiert dar.

"!<h1>Class demo</h1>
"!<p>This class must <strong>not</strong> be used productively.</p>
"!The class serves the following tasks:
"!<ul><li>Demo 1</li>
"!    <li>Demo 2</li>
"!    <li>Demo 3</li></ul>
"!<br><br>
CLASS demo DEFINITION.
  ...
ENDCLASS.

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:

<p class="shorttext">...</p>

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:

<p class="shorttext synchronized">...</p>

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:

• Wenn ein Kurztext in ABAP Doc im Quelltext angelegt oder geändert wird, wird der zugehörige Kurztext des Repository Objekts beim Speichern des Quelltexts übernommen. Bei einem leeren Kurztext in ABAP Doc wird der Kurztext des Repository Objekts gelöscht. Beim Entfernen eines gesamten Absatzes mit class="shorttext synchronized" bleibt der Kurztext des Repository Objekts erhalten. Diese Synchronisation funktioniert unabhängig vom verwendeten Werkzeug.

• Wenn in der ABAP Workbench ein Kurztext einer Methode oder eines Funktionsbausteins geändert wird, zu dem in ABAP Doc ein Absatz mit class="shorttext synchronized" vorkommt, wird der Kurztext im Quelltext beim Speichern entsprechend ersetzt. Das Löschen eines Kurztexts in der ABAP Workbench führt zu einem leeren Absatz. Das Anlegen eines neuen Kurztexts in der ABAP Workbench, zu dem es noch keinen Kurztext in ABAP Doc gibt, führt derzeit noch nicht zum Anlegen des Absatzes im Quelltext.

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:

<p class="shorttext" lang="...">...</p>

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.

Dokumentationsverweise

In einem ABAP-Doc-Kommentar kann mit folgender Syntax auf die Dokumentation anderer Repository-Objekte verwiesen werden:

... {@link [[[kind:]name.]...][kind:]name} ...

In geschweiften Klammern wird hinter @link eine Pfadangabe zu einem Repository-Objekt angegeben, wodurch auf dessen Dokumentation verwiesen wird. Bei der Anzeige der Dokumentation in den ADT wird an dieser Stelle ein Verweis erzeugt, bei dessen Auswahl die Dokumentation des Repository-Objekts angezeigt wird, falls sie vorhanden ist.

• Mit name wird der Name eines Repository-Objekts oder einer Komponente eines Repository-Objekts angegeben, wobei die Groß-/Kleinschreibung keine Rolle spielt.

• Mit kind wird die Art des Repository-Objekts oder einer Komponente eines Repository-Objekts angegeben. Für folgende Repository-Objekte muss kind wie gezeigt angegeben werden:

• DATA für Konstante, Variable, Prozedurparameter in einem entsprechenden Kontext

• DOMA für Domänen

• EVNT für Ereignisse in Klassen

• FUNC für Funktionsbausteine in Funktionsgruppen

• FORM für Unterprogramme in Programmen

• FUGR für Funktionsgruppen

• INTF für Interfaces, die in einer Klasse implementiert sind, um auf deren Komponenten zuzugreifen.

• METH für Methoden

• PROG für ABAP-Programme

• SEAM für Testseams

• XSLT für XSLT-Programme und Simple Transformations

Für globale Datentypen und Objekttypen (Klassen und Interfaces) muss und darf kind nicht angegeben werden. Diese Repository-Objekte werden allein über ihren Namen adressiert. Dies gilt insbesondere auch für CDS-Entitäten.

• Wenn ein Repository-Objekt adressiert wird, ist die Pfadangabe in aller Regel einstufig. Wenn eine Komponente eines Repository-Objekts adressiert wird, wie z.B. eine Methode einer Klasse oder eine lokale Klasse eines Programms, ist die Pfadangabe in aller Regel mehrstufig, wobei die einzelnen Abschnitte durch einen Punkt (.) getrennt werden. Die Abschnitte zwischen den Punkten können auch leer sein. Dann handelt es sich um eine relative Pfadangabe und es wird der jeweils nächsthöhere Kontext des aktuellen Kontexts adressiert.

Beispiel

Dokumentation einer lokalen Klasse html eines Programms mit ABAP-Doc-Kommentaren, die Verweise auf die Dokumentation einer globalen Klasse und auf die ABAP-Doc-Dokumentation des aktuellen Programm enthalten.

"! Default html string for method {@link .html.METH:show}
"! of local class {@link .html}.
CONSTANTS
  default TYPE string VALUE `<html><body>Default</body><html>`.

"! <h1>Class html</h1>
"! Wraps {@link cl_abap_browser}.
CLASS html DEFINITION.
  PUBLIC SECTION.
    "! <h1>Method show</h1>
    "! Calls {@link cl_abap_browser.METH:show_html}
    "! of {@link cl_abap_browser}
    "! and passes parameter {@link .METH:show.DATA:html }.
    "! @parameter html | Parameter for
    "! {@link cl_abap_browser.METH:show_html.DATA:html_string}.
    "! The default value is {@link ..DATA:default}.
    METHODS show
      IMPORTING
        html TYPE string DEFAULT default.
ENDCLASS.

CLASS html IMPLEMENTATION.
  METHOD show.
    cl_abap_browser=>show_html( html_string = html ).
  ENDMETHOD.
ENDCLASS.

Richtlinien

Programmierrichtlinien

Die folgenden Richtlinien für allgemeine Kommentare gelten insbesondere auch ABAP-DOC-Kommentare.

• Programme englisch kommentieren
  Die Einhaltung dieser Regel ist besonders wichtig, da eine in ABAP Doc vorgenommene Dokumentation als Teil des Quelltexts nicht in andere Sprachen übersetzt wird. Eine Ausnahme sind synchronisierte Kurztexte.
  
  
• Kommentare richtig anordnen
  Diese Regel betrifft die horizontalen Einrückungen, da die vertikale Anordnung vor Deklarationen syntaktisch festgeschrieben ist.
  
  
• Zeichensatz von Quelltexten
  Diese Regel wird von der Syntaxprüfung überprüft.