ABAP Doc

[schneidermic0]

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?