ABAP Cloud - Documentation
An important part of ABAP development is good and sustainable documentation, ideally as close as possible to the actual code. In this article, we'll take a closer look at this topic.
Table of contents
In this article, we'll look at different types of documentation and how you can create clean documentation in the ABAP Cloud system.
Introduction
What actually belongs in technical documentation? What should be included in the functional documentation, and how can we as developers make our lives a little easier? When it comes to documentation, many developers start to shy away because they consider it tedious and time-consuming. However, good documentation also reduces the need for training or understanding for other developers and is therefore an important component of software development. So, how can we provide good documentation in the ABAP Cloud environment?
Purpose
Documentation should support familiarization with and understanding of code. If it is close to the actual source code or object, you as a developer don't have to spend a long time searching for the right documentation or completeness. In the documentation, you can provide additional information that the actual code doesn't initially "tell" when it is written in a descriptive manner.
The system and Eclipse offer two methods for storing information, which you can use in addition to comments in the code. These include the ABAP Docs, which have been around for a very long time, and the "relatively" new Knowledge Transfer Document. We will examine both methodologies in more detail in the following chapters.
ABAP Docs
ABAP Docs have been supported in the ABAP Development Tools since the beginning. This gives you an easy way to provide your objects with documentation without overloading the source code. The documentation is defined in the definition of the method, class, and interface and can then be easily accessed at any point via the element info.
Creation
For example, if you want to document a method, you write the documentation before the method; you can do everything manually here. This essentially allows you to document the method in a rough manner, but you don't create documentation for the various parameters.
"! The method takes the parameter and checks the content
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
Using the ABAP Development Tools, you can easily generate the template and then fill in the text and parameters. In this case, you don't need to know the complete syntax for the various parameters.
Finally, our comment should now look like this: the upper part describes the method in general, and the individual parameters are described separately.
"! The method takes the parameter and checks the content
"! @parameter charlike | The parameter is character-like
"! @parameter result | The result is right
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
Formatting
ABAP Docs are parsed as HTML, so you can use many elements from the HTML to add structure and clarity to your documentation. Elements like paragraphs, lists, headings, and formatting like bold or italics work this way. Here's an example:
"! <h1>Start of the document</h1>
"! <p>This is the first line of the text, with a nice little <strong>paragraph.</strong></p>
"! <p>Now we follow with a second paragraph, to make the documentation complete.</p>
"! <ul>
"! <li>Item No. 1</li>
"! <li>Item No. 2</li>
"! <li>Item No. 3</li>
"! </ul>
METHODS formatted_docs.
You can find further information on formatting and the options in the technical documentation on SAP Help or linked below. There you should also look at how you can link different objects in the documentation.
Display
You use ABAP Docs primarily in the context of classes and interfaces. If you want to display the information, you simply have to select the corresponding method or class in the source code and/or place the cursor, and you will see the element info by pressing F2. In principle, you can also display the view permanently and have the display synchronized with the selection.
In the second step, let's look at the formatting of the other method. You may notice that the heading is only displayed in bold, but not necessarily a large heading. This will become important in the next section.
Export
One advantage of ABAP Docs in the system is the export of the complete documentation at various levels. Generally, you have the most up-to-date documentation in the system and should leave it there. However, if the documentation is ever needed externally, for example, for an audit, you can easily export it from the system and make it available in HTML format. To do this, right-click on an object or package in the "Project Explorer" and select "Export." You'll find the corresponding option in the ABAP section.
In the next step, we select the system for the export and can add additional objects or packages. Using the visibility, we can specify whether we want to export the entire documentation or just the public part. In the Target section, you can specify the directory for the export.
The result will display the export status in the console. Since we have defined two private methods, we must set the visibility before exporting. In the folder structure, you'll find the actual documentation alongside a readme file and the HTML design with the CSS file. You can then open the HTML files in your browser and get the formatted result. This is where the defined heading from the documentation is taken.
ABAP Cleaner
The ABAP Cleaner also has a few settings that enhance your ABAP docs accordingly. For example, you can automatically add missing parameters, remove the lang tag, or automatically indent the comment. Perhaps a few more features will be added in the future.
IDE Actions
With IDE Actions, you also use similar annotations to describe types and functions in more detail. Unlike ABAP Docs, the JSON Schema is used for typing and enriching data. Therefore, you should not confuse these annotations with ABAP Doc.
Knowledge Transfer Document
The Knowledge Transfer Document, or KTD for short, has been available since the 2020 release and is a separate Workbench artifact. It is used to document complex and new artifacts, such as service binding, service definition, and behavior definition in RAP. Since a RAP object can become relatively large and complex, documentation is particularly worthwhile here.
Creation
The KTD document is always created in the same package as the actual object to be documented. If you move the object within the packages, the documentation is also automatically moved. You can create the KTD directly via the context menu on the supported objects.
After creating a behavior definition, for example, you can see the entire structure of the object and carry out documentation on the corresponding nodes.
Maintenance
The KTD is maintained in an editor using Markdown, which is a simple way to format text and insert links. The text remains readable, but can be cleanly converted to HTML by an interpreter.
Using the shortcut CTRL + SPACE you can call up the input help for formatting and thus prepare the document without in-depth Markdown knowledge.
Display
If you change from "Source" to "Output" in the editor , you will enter display mode and can view the document and its final formatting.
If you are in a corresponding object that supports KTD, you will find the link in the upper part of the object. In this case, in a behavior definition. This gives you a direct indicator when documentation is available for an object.
Business Configuration
If you create a Knowledge Transfer Document on a "Business Configuration Maintenance Object", you will receive a new button in the Fiori application to display the documentation in the application. This gives the user the opportunity to obtain more details or documentation of the configuration. This is especially useful for complicated maintenance views with a lot of dependent data or complex inputs.
When the button is clicked in the application, you receive the documentation in a popup. Links also work here, for example, to link to further documentation or applications.
Complete Example
You can find the complete class from today's article in this section. We have not linked or stored the Knowledge Transfer Document here.
CLASS zcl_bs_demo_abap_docs DEFINITION
PUBLIC FINAL
CREATE PUBLIC.
PUBLIC SECTION.
INTERFACES if_oo_adt_classrun.
PRIVATE SECTION.
"! The method takes the parameter and checks the content
"! @parameter charlike | The parameter is character-like
"! @parameter result | The result is right
METHODS first_method_with_parameter
IMPORTING charlike TYPE clike
RETURNING VALUE(result) TYPE REF TO abap_boolean.
"! <h1>Start of the document</h1>
"! <p>This is the first line of the text, with a nice little <strong>paragraph.</strong></p>
"! <p>Now we follow with a second paragraph, to make the documentation complete.</p>
"! <ul>
"! <li>Item No. 1</li>
"! <li>Item No. 2</li>
"! <li>Item No. 3</li>
"! </ul>
METHODS formatted_docs.
ENDCLASS.
CLASS zcl_bs_demo_abap_docs IMPLEMENTATION.
METHOD if_oo_adt_classrun~main.
DATA(result) = first_method_with_parameter( 'Dummy Value' ).
out->write( result ).
ENDMETHOD.
METHOD first_method_with_parameter.
ENDMETHOD.
METHOD formatted_docs.
ENDMETHOD.
ENDCLASS.
Conclusion
If you would like to learn more about ADT features and their release dates, you can visit the Feature Matrix and check whether, for example, KTD works on your system. Documentation is an important part of software development and makes your colleagues' lives easier. With our tips, the topic should now be a little easier for you, and you can store documentation in the appropriate places.
Further information:
SAP Help - Long Texts
SAP Help - ABAP Doc Comments
SAP Help - Knowledge Transfer Documents
SAP Help - ABAP Doc
