The source-code documentation of any software program is critical for its later maintenance and coding extensions, especially when it comes to documentation in SAP projects. Numerous tools are available to programmers for storing documentation, ranging from simple word processors to more sophisticated databases. Over time and after numerous program modifications, the documentation can sometimes become outdated and eventually rendered useless, resulting in some programmers wisely using the source code to safely store important information.

If this is the case, then why is proper SAP documentation so important? Picture this scenario—your SAP system went live a few months ago. You have completed the detailed and up-to-date source-code information for the SAP ABAP program. The first days and weeks after the go-live you focused on stabilization, meaning some hot fixes and bug fixes were required. Now some enhancements or modifications must be implemented in your source codes. However, currently the system is up and running and is stable.

This week a newer version of SAP is released (e.g., a Support Package or an entire platform upgrade) and your organization is scheduled to upgrade accordingly. Suddenly, you are not the only person required to access the important and up-to-date information. Coworkers, managers, system integrators, and even clients now require documentation to help assist them in customizing and modifying SAP applications and coding so that they can implement an installation and upgrade.

Installations and upgrades are all done at a very complex, detailed, and customized ABAP code level. When organizations discover they need to do an upgrade to a newer version of an SAP application, maintaining ABAP coding properly often becomes a serious problem.

To implement the new release and to thoroughly understand the changes in the SAP application on a line-by-line basis, the system integrator must relinquish significant time, money, and effort, all of which can rapidly add up to millions of dollars in consultant fees. However, with sufficient documentation, the organization can save a lot of money and time when implementing a new release of the SAP application or even when supporting existing environments and customer developments in ABAP.

In software development, you have to distinguish between the technical specifications and documentation. Both parts are required and are important components of each software project. A technical specification describes the minute details of all or just specific parts of a software design. The specifications may contain:

• Additional technical details, such as the signature of an interface
• Required structures as well as input data types, output data types, and various exceptions
• Class models in detail:
  • Hierarchies and dependencies
  • Attributes
  • Associations
  • Methods
  • Dependencies
• Physical data models, which include attributes and types of each entity
• Data types, which are also detailed, along with specific component algorithms

Technical specifications, in a technical design sense, are part of the design documents, along with additional items, such as requirements lists, user stories, functional designs, graphic design mockups, data model specifications, Unified Modeling Language (UML) diagrams, usability studies, and business process diagrams.

Technical specifications that are written after the fact, documenting the finished product, are usually part of the initial design documents in projects using the waterfall model or V-model. However, they can be included as a reference in design documents of a later version or another product that relies on them.

Source-code documentation, otherwise known as inline documentation, uses source code. This source code consists of programming statements that are created using some form of a visual programming tool or text editor. These statements are then saved. Commenting on the purpose of each major statement (e.g., method calls) in the coding enables other people to understand the expected behavior of the coding more easily.

Figure 1 shows an example of source-code documentation in SAP ABAP. Each major statement is introduced by a comment that explains what the following statement is meant to do.

Figure 1

Source code documentation in ABAP

Most programming languages have third-party tools that parse the source code and extract documentation from comments. Despite the convenience of these tools, comments can become outdated, requiring programmers to regenerate the documentation each time they are used. Different programmers use various documentation generators to fulfill their requirements. These generators include Doxygen, PHPDoc, JSDoc, ScriptDoc, Javadoc, and ABAP Doc. These different generators use different documentation standards, which can create confusion in the documentation, even within the same language space.

Wouldn’t it be nice to have a tool that supports the developers with documentation and partially allows the automatic creation of source-code information and documentation? There are several such tools on the market, but let’s take a look at two specific tools— Javadoc and ABAP Doc.

Javadoc

Javadoc is an early Java language documentation generator created by Oracle that is commonly used for generating Application Programming Interface (API) documentation in HTML format using Java source code. Java uses the HTML format to allow users to hyperlink related documents together.

Javadoc’s comment format is the primary industry standard currently used for documenting Java classes. Being a user-friendly tool, Java uses various file editors that assist users in creating a Javadoc source and allow for Javadoc information to be used as internal references for programmers. Javadoc HTML can also be auto-generated using common integrated development environment (IDE) systems such as Eclipse. Javadoc application structures and change reports can also be analyzed using API-created doclets.

Javadoc Comment Structure

Javadoc comments are differentiated from code through the use of the standard /* and */ multi-line comment tags. The opening “begin-comment delimiter” tag includes an extra asterisk, such as in the example of /**.

The first paragraph of a Javadoc comment is a description of the documented method. After the description, various descriptive tags are displayed to signify certain meanings. Some common tags that are used are @author to describe an author, @return to indicate the method return value, @since to indicate when a certain functionality first existed, @link to link to another symbol, and numerous other commonly and less commonly used tags.

Javadoc Class Declarations

Javadoc comments are written next to the items by embedding the comments inside /** … */ without any new separating line. Class declarations must be preceded by any included import statements. Figure 2 is an example of a class declaration.

Figure 2

Class declaration

Javadoc Methods and Tags

Regarding Javadoc methods, an introductory one-line description is used to explain the method’s purpose. This short description can then be followed by an optional longer, more specific description, containing full details about the item. This longer description is indicated through the use of brackets [] and can span multiple paragraphs. A tag section, used to list accepted input arguments and method return values, is also included. Since Javadoc is similar to HTML and treated as such, the paragraph break tag <p> is used to separate multiple paragraph sections. You can see this introduction part in Figure 3.

Figure 3

Introductory one-line description

Javadoc Variables

Similar to methods, the same process is used to document variables with the exception that the tag section listing accepted input arguments and method return values are omitted. Variables contain only the short description as shown in Figure 4.

Figure 4

Short description

Example: A more complex example of documenting a class and a method using Javadoc is shown in Figure 5.

Figure 5

A complex example of documenting a class

Automatically Generated Documents with Javadoc

If developers consequently use the comments and documentation guidelines that are listed above, it is possible to generate great documentation automatically. Figure 6 shows the overview page of such an automatically generated Javadoc. On the top left, you can find all the involved packages. Below the packages, the contained classes are displayed. In the main Overview section of the screen, all class-contained methods and their descriptions are available.

Figure 6

Overview page of an automatically generated Javadoc

Such an easy-to-use and complete technical documentation website is very useful. On the one hand, it supports compliance requirements for software documentation standards. On the other hand, it supports new team members or even auditors, for example, in obtaining application overviews quickly and easily.

Why should only Java developers have such comfortable tools that support them with documentation topics? With the latest release versions, SAP ABAP is now offering a similar tool for developers, called ABAP Doc.

ABAP Doc

ABAP Doc was introduced with SAP NetWeaver Application Server ABAP 7.40 (Support Package 2). It is an approach by SAP to improve the documentation features of its integrated programming language, ABAP. ABAP Doc is a user-friendly documentation tool similar to Javadoc. It can be used to automatically create developer documentation using HTML statements and formatting options for ABAP source code development objects. Besides normal comments and texts, ABAP Doc includes a set of unique ABAP Doc comments. ABAP Doc comments cannot be formatted automatically, but for those comments, code templates in SAP NetWeaver can be used for formatting.

Like Javadoc, ABAP Doc can be used to write documentation directly within source code through the use of special comments placement in front of a declarative statement. Artifacts that are available globally, such as classes and the methods and attributes of interfaces, can be documented along with local artifacts, such as local variables.

ABAP Doc Comment Block

An ABAP Doc comment (a line or a block of lines) is introduced by the “! character string combination, which is a special form of a normal line-end comment. It must be located directly in front of a declarative statement. The horizontal arrangement of ABAP Doc comments must follow the source code indentations, and end-of-line comments are to be placed only after a concluding or declarative statement.

An ABAP Doc comment must be linked to exactly one declaration statement and can only contain seven-bit ASCII characters. It is important to note that ABAP Doc does not have language support (e.g., like ABAP system texts), meaning all ABAP Doc comments must only be written in the language of the system. This is because documentation created in an ABAP Doc as part of the source text is not translated into other languages.

An ABAP Doc comment is either a single line, containing only the comment, or a multiline block of consecutively placed comment lines. A single, one-line ABAP Doc comment cannot be empty of content, and lines without content can be used as formatting in blocks. The content of a block is summarized into a single ABAP Doc comment. An example of a single comment line can be seen in Figure 7.

Figure 7

Single comment line

Multiple lines of source code elements can also be documented by adding the “! character combination in front of each individual line (Figure 8). When the declaration statement is being used to create a chained statement, placement of the colon must be after the keyword. Note that ABAP Doc comments are not allowed anywhere else other than in front of the declared entity’s identifier.

Figure 8

Multiple lines of source code elements

To document a block of statements using the ABAP colon comma semantic, the ABAP Doc comment must be located after the colon, but in front of the identifier (Figure 9).

Figure 9

Block of statements

ABAP Document Parameters and Exceptions

Parameters and exceptions can also be documented for methods, function modules, events, and form routines. The syntax shown in Table 1 should be used.

Figure 10 is an example of the syntax for parameters and exceptions.

Figure 10

Parameters and exceptions syntax

The name of an existing exception or parameter must be specified after the use of @parameter, @raising, or @exception. The exception or parameter should be followed by the documentation, which is separated by the “|” characters. This documentation is then completed by the next use of @parameter, @raising, @exception, or by the end of the ABAP Doc comment. Additional documentation or interface documentation cannot be inserted after the interface documentation, and every exception or interface parameter can only be used once.

New templates for all undocumented parameters and exceptions can be generated within an ABAP Doc comment block through quick fixes, such as (Ctrl+1).

Figure 11 shows an example of exception or parameter documentation.

Figure 11

Exception or parameter documentation

ABAP Doc Formatting Options

Like Javadoc, ABAP Doc uses a subset of HTML tags to format documentation output.

The example in Figure 12 shows the use of HTML tags in ABAP Docs. Many useful HTML tags can be used in the same way websites use them. The code starts with an opening tag <...> and the related closing tag </...> that marks the end of the highlight part is then displayed.

In line 1 of Figure 12, the HTML header tag <h1> is used to highlight the header line. The <p> and the closing </p> tag shows the use of the paragraph tag and the listing of bullet points can be done with <ul><li>...</li></ul>.

Figure 12

HTML tags in ABAP Docs

See the result of this HTML tag use in Figure 13. Wherever you want to use the method, you get this additional information about the interface, parameters, and everything else you previously commented about using ABAP Doc.

Figure 13

HTML tag use results

Many HTML commands can be used to highlight text or emphasize your comments. An additional example for HTML tag use is shown in Figure 14. Here the tags <em>..</em> are used for emphasizing the word method (line 1) and <strong>..</strong> are used to mark some words as bold.

Figure 14

Emphasize and bold HTML tag use example

Verify how these highlighted words look in Figure 15.

Figure 15

Highlighted words

Writing a Correct ABAP Doc

ABAP Doc syntax checks can be added to the documentation to ensure that the SAP system can extract and interpret documentation correctly. These checks should verify that syntax and source code are both correct upon execution. For example, if the syntax or formatting of your ABAP Doc comment is incorrect, a warning is displayed automatically.

In Figure 16, the @ signs in front of the @parameter tag were removed (lines 12 and 13).

Figure 16

Removed parameter @ signs

Eclipse automatically attaches a warning sign to these lines as shown above (by the yellow exclamation-point icon). For further information regarding the lines with these issue warning signs, Eclipse IDE provides additional information after mouse-over (Figure 17).

Figure 17

Additional Eclipse mouse-over information

In the example shown in Figure 17 the system expects that this line without a keyword, such as @parameter, does not have an explanation marked and is introduced by ‘|’. Therefore, this can either be fixed by adding the @ again or removing or escaping the ‘|’.

Importing an ABAP Doc from Descriptions

You can also generate ABAP Docs by opening the class or interface and selecting the Source > Import ABAP Doc from the Descriptions menu option. After you select Source > Import ABAP Doc from Descriptions, you can import existing interfaces and global class descriptions, including their methods, parameters, and attributes. An example is shown in Figure 18. After making the selection, the system imports the required documentation lines for the parameters as well as the options for the methods.

Figure 18

Source > Import ABAP Doc from the Descriptions menu entry

The correct ABAP Doc is then inserted into your coding, and you can save the changes (Figure 19).

Figure 19

Correct ABAP Doc inserted into the coding

Automated Documentation

The described documentation features from Java (described above) are still ahead of those integrated features of SAP ABAP. ABAP integration in the Eclipse IDE, and the features provided by this IDE, support developers in documentation. However, even with the latest release, there is still a list of supporting features missing in SAP ABAP compared with Javadoc.

For instance, there is currently a lot of room for improvement regarding automated source-code documentation in ABAP. Some SAP customers have even gone so far as to develop their own semi-automatic documentation approaches and tools to fulfill their various documentation requirements.

Some of these newly created documentation tools are ABAP programs that analyze source code and create code-based HTML documentation out of it. The documents generated by these ABAP programs are based mainly on comments extracted from source code, but they also recognize other simple objects, depending on the program. These described customers’ developments are so-called Z-reports; they are not standard SAP tools.

Other documentation outside of ABAP source coding, such as end-user documentation, technical specifications, and functional specifications, is better created using dedicated authoring tools. Compliance may require all these up-to-date documents to be stored in one central location. Standard SAP tools, such as SAP Solution Manager, could fulfill such document management requirements for example.

Current Obstacles with SAP NetWeaver 7.40 and ABAP Doc

There is one major obstacle when you begin working in an already developed ABAP code environment. ABAP Doc hides already existing classical class-builder documentation, including the created long and short texts. The old way of documenting classes and methods in SAP ABAP has some benefits as well (Figure 20). The short description can be found in short texts, and the detailed description can be found in long texts, including use and possibilities of linking to other documents.

Figure 20

Example of the old way of documenting classes and methods

Before you work with ABAP Doc in an environment with multiple documented Z-classes, as shown above, it is important to verify whether reusable documentation already exists in the system prior to using ABAP Doc. Currently, there is no standard SAP migration tool for this purpose. Therefore, to migrate your documentation to ABAP Doc, your own implementation work might first be done.

Until now, an integration concept that allows users to place example programs in ABAP Doc does not exist either. Hence, it may be advantageous to some programmers to continue to document classes in the classical ABAP class builder. In ABAP Doc’s current release state, it may be a good documentation tool for developers who do not use the classical class builder for their documentation requirements.

Lukas M. Dietzsch

Lukas M. Dietzsch is CEO at Blackvard Management Consulting, LLC. He holds an international master’s degree in information technology and is an experienced IT solution architect and project lead. He started software development with Java in 2001 and focused on SAP software development and architecture in 2007. He is SAP certified in various technologies and was involved in numerous global SAP rollouts with various SAP modules such as Logistics, ERP, SRM, MM, and FS-CM. Lukas has a proven expertise in adapting to requirements and processes in different industries and on various software platforms. Due to his knowledge and experience, Lukas frequently works as an SAP coach and trainer. You can follow him on Twitter #dietzslu.

You may contact the author at Lukas@blackvard.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.