ABAP Doc can be used to provide developer documentation for ABAP source code development objects (like classes, interfaces, function modules, programs) within the ABAP source code by using ABAP comments.
I would like to give you a short overview how you can document your ABAP source code development objects using ABAP Doc and where you can read the documentation written in ABAP Doc. I hope you like the new way of documenting your source code.
Please be aware that ABAP Doc has been introduced with SAP NetWeaver Application Server ABAP 7.4 (support package 2).
How can you write ABAP Doc?
With ABAP Doc, you can write your documentation directly within your source code using special comments in front of a declarative statement. This means you can document globally available artifacts (like classes, interface and their method and attribute), but also local artifacts (like local variables and field-symbols).
ABAP Doc comment block
An ABAP Doc comment block is introduced by the character combination "!. It has to be located directly in front of a declarative statement.
Example
"! This is a documentation for the following constant
constants co_initial_value type i value 0.
You can use multiple lines for your documentation to document your source code elements. In this case you have to add the character combination "! in front of each line.
Example
"! This documentation for the following constant is documented"! in multiple lines.
"! constants co_initial_value type i value 0.
If you want to document a block of statements by using the ABAP colon-comma-semantic the ABAP Doc comment block must be located in front of the identifier but after the colon.
Example
constants:
"! Initial value
co_initial_value type i value 0,
"! Invalid value
co_invalid_value type i value -1.
Document Parameters and Exceptions
For methods, events, function modules and form routines you can also document the parameters and exceptions. The following syntax is used to document parameters and exceptions:
| Documentation for | Syntax |
|---|---|
| Parameters | @parameter <parameter name> | <parameter documentation> |
| Class-based exceptions | @raising <exception name> | <exception documentation> |
| Classic exceptions | @exception <exception name> | <exception documentation> |
Example
"! This method compares two sources and returns whether they
"! are identical.
"!
"! @parameter source1 | First source code text
"! @parameter source2 | Second source code text
"! @parameter ignore_case | X = text will be compared case insensitive
"! @parameter result | X = sources are identical
"! @raising cx_invalid_source | Is raised if an empty source code text is passed
"! @raising cx_invalid_source | Is raised if an empty source code text is passed
methods compare
importing
source1 type text
source2 type text
ignore_case type abap_bool
returning
value(result) type abap_bool
raising
cx_invalid_source.
You can use quick fixes (Ctrl+1) within a ABAP Doc comment block to generate templates for all parameters and exceptions that have not been documented, yet.
Formatting options
The following tags can be used to format the output of your ABAP Doc documentation:
| Formattingoption | tag |
|---|---|
| Line break | <br/> or <br></br> |
| Paragraph | <p>...</p> |
| Emphasized text | <em>...</em> |
| Strong emphasized text | <strong>...</strong> |
| Unsorted lists | <ul><li>...</li></ul> |
| Sorted lists | <ol><li>...</li></ol> |
| Headers | <h1>...</h1> <h2>...</h2> <h3>...</h3> |
Example
"! This method compares <em>two</em> sources and returns whether they
"! are <strong>identical</strong>.
"!
"! @parameter source1 | First source code text
"! @parameter source2 | Second source code text
"! @parameter ignore_case | X = text will be compared case insensitive
"! @parameter result | X = sources are <strong>identical</strong>
"! @raising cx_invalid_source | Is raised if an empty source code text is passed
"! @raising cx_invalid_source | Is raised if an empty source code text is passed
methods compare
importing
source1 type text
source2 type text
ignore_case type abap_bool
returning
value(result) type abap_bool
raising
cx_invalid_source.
Write correct ABAP Doc
To ensure that your ABAP Doc can be interpreted and rendered correctly by the system, we added some new additional checks when you execute the syntax check for your source code. If the position, the syntax or the formatting of your ABAP Doc comment is incorrect you will receive a warning:
Where can you read the documentation?
The documentation will be displayed in the source code element information that is displayed when you press F2 on an identifier or when you use the ABAP Element Info view:
Import ABAP Doc from descriptions
It is possible to generate ABAP Doc by importing the existing descriptions of global class and interfaces including their attributes, methods, parameters, etc.
To import the description in your class or interface, just open the class or interface and use the (context) menu entry "Source > Import ABAP Doc from Descriptions".
Afterwards, the corresponding ABAP Doc is inserted into your coding and you can save the changes.
ABAP Doc Features with NetWeaver 7.5
The blog New ABAP Doc Features with NetWeaver 7.5 describes following features which have been added with SAP NetWeaver Application Server ABAP 7.5:
- How can you export your ABAP Doc from the ABAP server?
- How can you synchronize ABAP Doc with short text descriptions?
- SAP Managed Tags:
64 Comments
| User | Count |
|---|---|
| 4 | |
| 4 | |
| 3 | |
| 2 | |
| 2 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
