SAP NetWeaver AS ABAP Release 752, ©Copyright 2017 SAP AG. All rights reserved.
ABAP - Keyword Documentation → ABAP - Reference → ABAP Syntax → Program Directives →ABAP Doc
ABAP Doc allows declarations in ABAP programs to be documented, based on special ABAP Doc comments. ABAP development environments that support ABAP Doc, such as ABAP Development Tools (ADT), analyze the content of ABAP Doc comments, convert it to HTML and display it appropriately.
ABAP Doc Comments
A comment for ABAP Doc is introduced using the string "!. This is a special form of a normal line end comment that is introduced using ". The following rules must be applied if an ABAP Doc comment is to be read correctly:
If this rule is broken, a syntax check warning is produced.
Example
Basic use of ABAP Doc - comments as single lines, blocks and chained statements.
Parameter Interface of Procedures
The parameter interface for procedures and for events in classes can be documented in the corresponding ABAP Doc commentary with a special syntax:
Documentation for | Syntax |
Interface parameters | @parameter name|documentation |
Class-based exception | @raising name|documentation |
Classic exceptions | @exception name|documentation |
If specified, @parameter, @raising, and @exception must be placed directly after "! and hence introduce a new line. The name (name) of an existing parameter or an exception must be specified after @parameter, @raising, @exception. This must be followed by the documentation (separated by |). This documentation is completed by the next @parameter, @raising, @exception or by the end of the ABAP Doc comment. In other words, no further documentation or interface documentation can be placed behind the interface documentation. Every interface parameter or every exception can only be specified once.
Note
The arrangement of the parameter interface documentation of procedures is not dependent on the order of the associated declarations. For reasons of readability, however, the order of the parameters and exceptions in the ABAP Doc comment should be the same as the order of the declarations.
Example
Use of ABAP Doc comments for the parameter interface of a method.
Formatting
The following tags are used in documentation texts for ABAP Doc comments, to format the documentation display in a development environment. These tags are a subset of the HTML tags.
Formatting | Tag |
Header, level1 | <h1>...</h1> |
Header, level2 | <h2>...</h2> |
Header, level3 | <h3>...</h3> |
Paragraph | <p>...</p> |
Italic text | <em>...</em> |
Bold text | <strong>...</strong> |
Unnumbered list | <ul><li>...</li>...<li>...</li></ul> |
Numbered list | <ol><li>...</li>...<li>...</li></ol> |
Line break | <br> |
An open tag must be closed before a new section of the ABAP Doc comment is started. A new section is introduced using @parameter, @raising or @exception.
The following attributes are possible:
Example
Use of formatting in an ABAP Doc comment for a class. The ABAP Development Tools display the documentation with the appropriate formatting.
Short Texts and Their Synchronization
Parts of ABAP Doc comments can be flagged as short texts and the short texts of classes and function modules and their components can be synchronized with ABAP Doc comments. A part of an ABAP Doc comment can be flagged as a short text by being tagged as follows:
A paragraph tagged like this is displayed as a header in the display of the ADT documentation, instead of the short text shown in ABAP Workbench.
To synchronize the ABAP Doc short texts and the short texts shown in ABAP Workbench, the tag can be specified as follows (this is optional):
In this case, the length of the short text in ABAP Doc is restricted to the length of the matching short text in ABAP Workbench and is synchronized with the associated short text in the original language of the class or function module as follows:
An ABAP Doc short text is part of the source code and is not translatable. This short text replaces the translatable short text of the repository object in its original language when synchronized, which means it must also be specified in the original language. This is an exception to the rule that ABAP Doc comments must always be in English. The original language can be flagged in the source by being specified as follows (this is optional):
The attribute lang uses the HTML standard. It must be used to specify the original language of the repository object as a two-character ISO ID. If not, a syntax check warning occurs. This attribute makes it clear in the source code which language the short text should be specified in. It is also planned to be used in future extensions for the translatability of short texts.
Example
See the class CL_DEMO_ABAP_DOC in a source code editor. It contains ABAP Doc comments for the class itself, for a type, for a method and its parameters, and for an attribute. The ABAP Doc comments include short texts that are synchronized with the short texts in ABAP Workbench in the original language English. The class can be copied to a standalone temporary class to test the synchronization.
Documentation Links
In an ABAP Doc comment, the following syntax can be used to link to the documentation of other repository objects:
... {@link [[[kind:]name.]...][kind:]name} ...
In curly brackets after @link, a path is specified to a repository object and hence a link to its documentation. When the documentation is displayed in ADT, a link is created here that displays the documentation of the repository object when selected (if this documentation exists).
Example
Documents a local class html of a program using ABAP Doc comments that contain links to the documentation of a global class and to the ABAP Doc documentation of the current program.
"! 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.
Guidelines
Programming Guidelines
The following guidelines for general comments also specifically apply to ABAP-DOC comments.