ABAP News for Release 7.40 – ABAP Doc for ADT
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 Thomas Fiedler 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 😉 .
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?
–
With ADT, AIE i can hear the death knell for the ubiquitous SE80 & Co 😥
I am already feeling so outdated!
Just my personal opinion: Unless there's a full two-way transfer between the current documentation capabilities in the Class Builder and ABAP Doc, I wouldn't start using ABAP Doc. There are quite a number of classes and interfaces that already have an on-line documentation. H*ll, it's even translateable into other languages which does not appear to be the case for ABAP Doc. So why bother when you can't even see, much less edit the documentation that is already in place?
Hi Horst,
I agree with you regarding the documentation. I am trying to get used to ADT using 7.31 and I think we should put effort in a better integration of the old way doc with ADT. Some Examples:
- If I create an object in ADT no short text is given. If I change to Se80 the short text is a must have.
- In the past I have also put a lot of effort in documenting function modules . It's a pitty that this is not available and editable in ADT
- also when I create a methods in ADT I can not give a short text.
Up to now I am working with both editors, because at my customers place the ADT is usable only in the development environment . But for debugging in the test environment no ADT is available .So I have to go back to Se80. That's what is live like out in the wild .
Regards
Peter
I certainly like it. I hope for the future more and more (SAP 😉 )Developers will document their stuff and produce good reliable API's/Frameworks with good documentation. I don't care for translation API for me is always in English. But i have to agree the ADT support could be better and easier and a direct link to standard documentation would be brilliant, but hopefully ADT will be the only editor in the near future 😈
Hi,
maybe a short outlook what is on the road concerning ABAP Doc.
For sure we know the problem of having short descriptions in parallel to the ABAP doc comments. Therefore we are currently working on a mechanism that transforms the short descriptions into ABAP Doc and vice versa. That means you will see the ABAP Doc comments also in SE24 and you can maintain the ABAP Doc comments partially via the short descriptions input fields in SE24/SE37. Hope this overcomes the adoption issues of ABAP Doc.
Next is that we also include the old long text documentation in the Elementinfo of ABAP in Eclipse. That means when you press F2 on a function modules or class you will also see the docu written in SAP Script.
There is one more thing 🙂 We are also working on generation of offline documents for ABAP Doc.
Regards,
Thomas.
Hi Thomas,
thank you very much for the outlook. Could you already say something about how and when the feature will be released / delivered?
For us it is really important to have an integration / migration between the to kinds of documentation.
Regards
Wolfgang
Hi Wolfgang,
the new features are available with AS ABAP 7.50. See our blog post about it:
New ABAP Doc Features with NetWeaver 7.5
Regards,
Thomas.
Hi,
ABAP Doc convinces me more than the documentation in the class builder ever did.
I see the option to document in different languages rather as a problem. What happens, if someone used another language than the developer actually working on the problem? We do not speak about end user documentation, but about developer documentation. And developers usually use the same language.
In the function builder, there was a green sign, if a documentation exists. In the class builder this nice function was omitted (why?). In most projects I work, documentation is only rarely done; So no one expects documentation. And even if it exists, people will not see it for classes, as they is no sign like the green dot for function modules anymore.
So people use inline comments. But inline comments are not easily accessible from the calling code.
The option to document in the coding, and even use ABAP Doc to document local variables and methods is a great advantage. Codings with all too many lines and not readable variable and method names is still common. So when we have to maintain codings like this, we need all available tools to solve the problems that tend to come with long not perfect code. You have to imagine, that developers in this case often work under strict time and cost limitations and face very complex (and if errors occur also dangerous) coding. I can use ABAP Doc to make my work easier by document local variables instead of being forced to rename them (In some cases, there is no correct name with 30 characters).
Best Regards,
Rainer
PS: And thanks for you gorgeous blog about ABAP 7.40 !
Hi Rainer,
we are currently working on a feature to generate HTML pages out of ABAP doc comments. That means you can for example generate a complete documentation for all classes in a specific package and store it as a zip-File or on a web server.
Is this also interesting for you?
Regards,
Thomas.
Hi Thomas,
I learned, that html exports can also easily be imported into a word document. The imported headings and texts are then automatically correctly formatted. I use this to export requirements maintained in Excel to Word documents.
My impression is, that documentation will gradually become more important. And documentation that is done directly in the system is in my opinion easier to maintain than separate documents. So it is a good idea, to improve the possibility to export the documentation if required.
What I miss is an integrated approach. There are more places to documentate, and all this information should be centrally available.
ABAP ( Doc ) documentation for:
All objects and settings in the SAP system. And not hidden under a menu point, but directly visible on the screen. Small or big as the user wants it, take Eclipse as an example how to do this.
Fields of customizing tables - The Buffer Size for the Quantity Conversion is set to 500 (RSADMINCV24-UOM_BUFF_SIZE) - Why is it not possible to write the reason for the 500 next to the field in the maintainance screen? "Do not set the buffer higher than 500, because ...". And to automatically assure that the documentation written here is the same as in all other places. Like an UML modelling tool, that changes all diagrams consistently, if the model is corrected.
Applications like SAP use complex logic to manage data flows and data processing - It is programmed in either a graphical language or using checkboxes, input fields, ... . In ABAP commenting can be used to explain the reason why certain things are done in the coding in a specific way. In case of SAP BW, this is typically documentated in separate documents. If the documentation is done in the system, the user has to open it explicitely. This worked never fast when I did this. It costs time and is often not used, because people do not expect a documentation. Why not posting it on a virtual "Post-it" directly on the screen? Next to the box, field or arrow that is to be documentated. Even Excel has a commenting function for cells, why not SAP for field values on a screen?
Best Regards,
Rainer
Further question from a colleque, I can not answer: Multi-row comments:
"! @parameter any_flag | 'X' flag is active
"! | ' ' flag is inactive
This is more readable in coding than both in one long row. Does this work fine? Or are we supposed to write both in one row?
You can spread a comment over several lines. But in your example, the second | is not allowed. Instead, you can use formatting tags. More about ...
Is it possible to export the API to HTML like Javadoc? Without it will still be nearly impossible to get a full overview of an API because who really knows which set of classes exists?
Hi Sven,
yes, this is possible with NW 7.50. See our blog post for more details:
New ABAP Doc Features with NetWeaver 7.5
Regards,
Thomas.
PS: Feedback welcome 🙂