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, analyze the content of ABAP Doc comments, convert it to HTML and display it appropriately.

Other versions: 7.31 | 7.40 | 7.54

Programming Guidelines

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

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 either
  • or 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 key word. 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 only contain 7 bit ASCII characters.
  • An ABAP Doc comment can contain special tokens and tags for documenting the parameter interface of procedures, or for formatting.
  • In ABAP Doc comments, the special characters ", ', <, > and @ must be escaped using &quot;, &apos;, &lt;, &gt; and &#64;.

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
Classical exceptions @exception name

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 listed once.


Note

The sequence of the documentation for procedure parameters is not dependent on the line sequence in an ABAP Doc block. However, every parameter or exception should occupy a separate line, to make the documentation easier to read. This is also the reason why the sequence of parameters and exceptions in the ABAP Doc comment should be the same as the sequence of 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.

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/> or <br></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 tags are a subset of HTML tags that must be specified in an XHTML notation.

  • The opening and closing tags must be specified in uppercase letters or in lowercase letters. Apart from this, uppercase and lowercase characters are not important.
  • Nesting of lists is not currently supported.
  • The tags <h1>, <h2>, <h3>, <p>, <em> or <strong> cannot contain any <p>, <ul> or <ol> tags.
  • Text cannot be directly entered into <ol>, <ul>, and <br> tags.


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.