Skip to content

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.

Other versions: 7.31 | 7.40 | 7.54

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:

  • An ABAP Doc comment is one of the following:
  • A multiline block of consecutive comment lines The content of a block is summarized into a single ABAP Doc comment.
  • If the declaration statement does not create a chained statement, an ABAP Doc comment can be placed directly in front of the declaration statement, without using spaces as separators.
  • If the declaration statement makes a chained statement, the colon must be placed after the keyword. An ABAP Doc comment can be placed in front of the identifier of every declared entity.
ABAP Doc comments are not allowed anywhere else.
  • A one-line ABAP Doc comment cannot be empty. Lines without content can be used as formatting in blocks.
  • An ABAP Doc comment can contain special tokens and tags for documenting the parameter interface of procedures, or for formatting.
  • The special characters ", ', <, >, @, {, |, and } can, if necessary, be masked using &quot;, &apos;, &lt;, &gt;, &#64;, &#123;, &#124;, and &#125;.

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.

"! 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.

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
Class-based exception @raising name
Classic exceptions @exception name

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.

"! 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.

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:

  • In the <ol> tag, the attributes reversed, start, and type can be specified with their traditional HTML meaning.
  • In the <p> tag, the attributes class and lang can be specified. More information about the meaning of these attributes can be found under "Short Texts and Their Synchronization".


Example

Use of formatting in an ABAP Doc comment for a class. The ABAP Development Tools display the documentation with the appropriate formatting.

"!<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.

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:

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

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 saved as system documentation, the tag can be specified as follows (this is optional):

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

In this case, the length of the short text in ABAP Doc is restricted to the length of the matching short text in in the system documentation and is synchronized with the associated short text in the original language of the class or function module as follows:

  • When an ABAP Doc short text is created or modified in the source code, the associated short text of the repository object is used when the source code is saved. If the short text in ABAP Doc is empty, the short text of the repository object is deleted. If class="shorttext synchronized" is used to remove a full paragraph, the short text of the repository object is preserved. This synchronization works regardless of the tool used.
  • If a short text of a method or a function module is modified in the system documentation in which a paragraph with class="shorttext synchronized" occurs in ABAP Doc, the short text is replaced accordingly in the source text when saved. When a short text in the system documentation is deleted, an empty paragraph is produced. When a new short text is created in the system documentation for which there is not yet a short text in ABAP Doc, the paragraph is not currently created in the source code.

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):

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

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 the system documentation in the original language English. The class can be copied to a standalone temporary class to test the synchronization.

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).

  • name is used to specify the name of a repository object or a component of a repository object (this is not case-sensitive).
  • kind is used to specified the type of the repository object or a component of a repository object. kind must be specified as shown for the following repository objects:
  • DATA for constants, variables, and procedure parameters in the appropriate context
  • INTF for interfaces implemented in a class to access its components.
kind cannot and must not be specified for global data types and object types (classes and interfaces). These repository objects are only addressed using their names. This applies specifically to CDS entities.
  • The path is specified on one level only when repository objects are addressed. When a component of a repository is addressed, for example a method of a class or a local class of a program, the path is usually specified with multiple levels, with each segment separated by a period (.). The segments between the periods are allowed to be empty. This makes the path into a relative path and the next higher context of the current context is addressed.


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.

Test Relations

The following syntax can be used to define relations known as test relations in front of the declaration of a test class or a test method:

"! @testing [kind:]name

This special ABAP Doc comment links the test class or test method with the repository object specified after @testing.

  • name is used to specify the name of a repository object (this is not case-sensitive).
  • Kind is used to specify the type of the repository object The following repository objects are possible and kind must be specified as shown:
kind cannot and must not be specified for global classes and CDS entities. They are only addressed using their names.

When a test class or test method is linked with a repository object, it means that the class or method can be displayed and executed for this object in ADT.


Notes

  • Test relations are used to link repository objects with external unit tests. The current program of the test class or test method cannot be specified.

  • Multiple test relations can be specified for a single test class or test method .


Example

Associates a test class and its test methods with various repository objects.

"! @testing cl_demo1
"! @testing cl_demo2
CLASS test_demo_cds_association DEFINITION FOR TESTING.
  PRIVATE SECTION.
    METHODS:
     test_class1 FOR TESTING,
     test_class2 FOR TESTING,
     "! @testing demo_cds_view
     test_cds_view FOR TESTING,
     "! @testing XSLT:demo_trafo
     test_transformation FOR TESTING.
ENDCLASS.

Guidelines

Programming Guidelines

The following guidelines for general comments also specifically apply to ABAP Doc comments.

  • Write program comments in English
    Adhering to this rule is particularly important, because documentation created in an ABAP Doc as part of the source code is not translated into other languages. One exception are synchronized short texts.
  • Arrange comments correctly
    This rule affects the horizontal indents because the vertical alignment is fixed in the syntax before declarations.
  • Character set in source code
    This rule is checked by the syntax check.