ARTICLE
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.
ABAP_PGLS 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 text is not
translated into other languages.
Arrange comments correctly
This rule affects the horizontal indents, because the vertical alignment
is syntactically fixed before declarations.
Character Set in Source Code
This rule is checked by the syntax check.
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
an single comment line that only
contains the comment,
or a multiline block of consecutive comment lines. The content of a
block is summarized into a single ABAP-Doc comment.
An ABAP Doc comment (a line or a block of lines) must be linked
to one declaration statement
only:
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|documentation
Class-based exception @raising name|documentation
Classical exceptions @exception name|documentation
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.
Documentation extract taken from SAP system, � Copyright SAP AG. All rights reserved