We all know the a well documented code with inline comments and descriptions is easy to understand, fix post development issues and above all gives better look.
We have been using the comments in the code in GUI from a long time be it in the code based or form based options. but there are couple of issues:
- No spell check for the comments
- Hard to achieve proper styling
But now with the help of ABAP Doc many of things can be improved. In this blog we are going to see how to document our code properly in Eclipse ADT. 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. Lets discover how you can document your ABAP source code development objects using ABAP Doc and where you can read the documentation written in ABAP Doc.
A comment for ABAP Doc is introduced using the string “!
ABAP Doc comments consist of a single comment line or a coherent block of several comment lines. In the source code editor, they can be placed in an empty line directly in front of a declarative statement like data declarations, method definition, class definitions, and so on.
ABAP Doc comments can be added in ABAP classes, ABAP interfaces, ABAP programs, or ABAP function groups to describe functionality in the code element. In addition, you can generate ABAP Doc by importing the existing descriptions of global classes and interfaces including their attributes, methods, parameters, and so on.
Lets compare two classes/methods in Eclipse ADT with and without ABAP Doc.
With ABAP Doc:
Here we have added ABAP Doc comments using “!
There are various elements into it for example to highlight importing parameters we can use @parameter. Also different HTML formatting can also be done like paragraph <p>. We can define the text as short text using the shorttext class.
Formatting
The following tags are used in documentation texts for ABAP Doc comments, to format the documentation display in a development environment. These tags are a subset of the HTML tags.
| 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> |
More help can be found at https://help.sap.com/doc/abapdocu_752_index_htm/7.52/en-us/abendoccomment.htm
Lets see how this class method documentation looks like while consuming in other objects.
We can see when we try to use the methods and gives CTRL+SPACE the documentation is shown which gives clear picture of the method.
Without ABAP Doc:
We have commented the ABAP Doc from the main method so unable to see that description here. what are able to see here is because of description maintained in SE24 in SAP GUI.
Stay tuned for more articles on ABAP Doc and other SAP stuffs till then keep learning keep sharing!
