ABAP News for Release 7.40 - ABAP Doc for ADT

[horst_keller]

ABAP Doc is a simple documentation tool similar to Javadoc that enables documentation in HTML format to be created automatically from ABAP source code. ABAP Doc is based on special ABAP Doc comments.

ABAP Doc comments

A comment for ABAP Doc is introduced with "!. An ABAP Doc comment (a line or a block of lines) must be linked to exactly one declaration statement.

Example

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

There is a special syntax for the parameter interface of procedures and of events.

Example

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

A subset of HTML-Tags can be used for formatting.

Example

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

The syntax rules of ABAP Doc are checked by the ABAP syntax check.

ABAP Doc display

ABAP Doc comments are evalutated in the ABAP Editor of the ABAP Development Tools (ADT, aka ABAP in Eclipse) but not in the ABAP Editor of SAP GUI (SE80 & Co.). If you place the cursor on an entity that is documented by ABAP Doc comments and hit F2, the formatted documentation is neatly shown in a popup window.

The ABAP Doc mechanism overwrites the display of eventually existing classical class or method documentation.

Remarks

My SAP-buddy thomasfiedler won't like it but I have some remarks to add.

I really like ABAP Doc, but

• it is evaluated in ADT only. If you use ABAP Doc you must be sure that the users of your APIs work in ADT only. In SAP GUI they see the comments but not the formatted documents where they are needed.
• ABAP Doc hides existing classical class builder documentation (short and long texts). Before using ABAP Doc you should have a look if there is documentation already available  (OK, OK, this is rarely the case ...)  and whether you want to reuse it. Up to now, there is no migration tool available.
• The old way of documenting classes and methods has some benefits too: Short description in short texts. Detailed description in long texts including examples for usage and possibility of linking to other documents. Do you want to place example programs in ABAP Doc? Up to now, there is no integration concept that enables the developer to exploit best of both worlds.

That's why I continue to document my classes with long texts in the classical class builder. Maybe I'm a dinosaur but hopefully not yet dying out :wink: .

I tend to say that in its present state ABAP Doc is a good tool for developers who would never document in class builder anyhow (independent of SAP GUI vs. ADT). Such developers have a simple support for documenting by commenting now. Any kind of documentation is better than no documentation.

Any remarks from your side?

-