Documenting ABAP Code

Objective

After completing this lesson, you will be able to Document ABAP code.

ABAP Code Documentation

If you place the cursor on the name of a class, method, or type, you will see a dialog window containing the corresponding element information – the parameters of the method or the description of a data type.

You can also add documentation to this dialog using ABAP Doc. You create this documentation by adding special comment lines to your code. With ABAP Doc, you can document the following declarative statements:

  • CLASS
  • INTERFACE
  • METHODS
  • TYPES
  • DATA
  • CONSTANTS

You can also document the individual parameters and exceptions of methods and function modules.

Once you have activated the class, your ABAP Doc comments become part of the code element information.

ABAP Doc comments stand before the element that they document. They begin with the characters "! . If you try to create ABAP Doc at a position in the class that is not allowed, the system displays a syntax warning, and the documentation is ignored.

ABAP Doc comments cannot be translated. You should therefore consider carefully, in which language you want to create your documentation.

ABAP Doc uses a subset of HTML tags to allow you to format your documentation. The example uses the <strong> tag for emphasis, and a <br> tag for a line break. (Note that without the line break tag, the two lines of ABAP Doc are displayed next to each other).

As well as emphasis and line break, you can use the following tags:

Additional format tags in ABAP Doc

PurposeFormatting Tags
Header, level 1<h1>...</h1>
Header, level 2<h2>...</h2>
Header, level 3<h3>...</h3>
Italic text<em>...</em>
Paragraph<p>...</p>
Unnumbered list<ul><li>...</li>...<li>...</li></ul>
Numbered list<ol><li>...</li>...<li>...</li></ol>

Hint

Inside an ABAP Doc, you can use code-completion to insert these formatting tags. Simply press Ctrl + Space and choose from the list of available formats.

With ABAP Doc, you can document both, a method and its individual parameters. To document the method, use the normal "! comments. To document a parameter, use the notation "! @parameter <name> | and add your comment after the pipe character (|).

You can add ABAP Doc for a method and its signature using a quick fix. Once you have declared the method, press Ctrl + 1 to open the possible quick fixes, and choose Add ABAP Doc. The editor then generates the corresponding documentation.

If the signature of a method changes, you can use quick fixes to delete the ABAP Doc comments of delete parameters, and to add ABAP Doc comments for new parameters.

You can ensure that an ABAP Doc description of an object is replicated in the description in the object properties, and in the object list. To do this, use a paragraph tag <p> with the addition class="shorttext synchronized".

Changes that you make to the description in the object properties are replicated to the ABAP Doc comment.

You can add navigation links to the ABAP Doc of other objects. To do so, use the notation {@link <object_name>}.

As well as linking to the ABAP Doc of an object, you can also link to its individual elements. in our example, there is a link to the ABAP Doc of the method GET_AIRPORTS. The link "! {@link zif_s4d401_constants.DATA:auth_create} defines a link to the ABAP Doc of the constant auth_create in interface ZIF_S4D401_CONSTANTS.

Use the following IDs for individual elements:

DATA
for constants, variables, and procedure parameters in the appropriate context
DOMA
for domains in the ABAP Dictionary
INTF
for interfaces that are implemented in a class (used to access the interface components)
METH
for methods

How to Use ABAP Doc to Document Code

Watch this video to know how to use ABAP doc to document code.

Add Documentation to ABAP Code

You add some documentation to your code to facilitate the support.

Template:

  • /LRN/CL_S4D401_EXS_CLASS (Global Class)

Solution:

  • /LRN/CL_S4D401_DCS_ABAP_DOC (Global Class)

Task 1: Copy Template (Optional)

Copy the template class. If you finished the previous exercise, you can skip this task and continue editing your class ZCL_##_SOLUTION.

Steps

  1. Copy class /LRN/CL_S4D401_EXS_CLASS to a class in your own package (suggested name: ZCL_##_SOLUTION, where ## stands for your group number).

    1. In the Project Explorer view, right-click class /LRN/CL_S4D401_EXS_CLASS to open the context menu.

    2. From the context menu, choose Duplicate ....

    3. Enter the name of your package in the Package field. In the Name field, enter the name ZCL_##_SOLUTION, where ## stands for your group number.

    4. Adjust the description and choose Next.

    5. Confirm the transport request and choose Finish.

  2. Activate the copy.

    1. Press Ctrl + F3 to activate the class.

Task 2: Add Documentation

Add ABAP Doc documentation to local class LCL_CARRIER and factory method GET_INSTANCE.

Suggested Documentation Texts

TypeCode ElementDocumentation
Local ClassLCL_CARRIER

Flight Carrier - A factory logic ensures that there is only one instance for the same carrier ID.

MethodGET_INSTANCE

Factory method - returns an instance of this class.

Parameteri_carrier_id

Three-character identification of the carrier.

Parameterr_resultReference to the instance - initial if instantiation failed.
ExceptionZCX_##_FAILEDInstantiation failed - evaluate the exception text for details.

Steps

  1. Use a quick fix to add ABAP Doc documentation to local class LCL_CARRIER.

    1. In your global class, navigate to the definition of local class LCL_CARRIER.

    2. In the CLASS … DEFINITION statement, place the cursor on lcl_carrier and press Ctrl + 1 to invoke the quick fix.

    3. From the list of available quick fixes, choose Add ABAP Doc.

    4. The quick fix adjusts the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123
      
CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  2. Maintain the documentation with the text from the table.

    Hint

    When you press Enter, the editor inserts a new code row that starts with "!.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      1234
      
"!  
CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  3. Display the Code Element Information for local class LCL_CARRIER to see the output.

    1. In the CLASS … DEFINITION statement, place the cursor on lcl_carrier and press F2 to show the code element information.

    2. The ABAP Doc text is displayed under the heading Documentation.

  4. Use a quick fix to add ABAP Doc documentation to static method GET_INSTANCE of local class LCL_CARRIER.

    1. In your local class, navigate to the definition of method GET_INSTANCE.

    2. In the CLASS-METHODS statement, place the cursor on get_instance and press Ctrl + 1 to invoke the quick fix.

    3. From the list of available quick fixes, choose Add ABAP Doc.

    4. The quick fix adjusts the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123
        
 CLASS-METHODS get_instance

  5. Maintain the documentation for the method with the text from the table.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123456
      
  "! 
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |
    CLASS-METHODS get_instance

  6. Maintain the documentation for the method parameters and for the exception with the texts from the table.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      1234567
      
"! Factory method - returns an instance of this class.
    "! @parameter i_carrier_id | 
    "! @parameter r_result | 
    "! @raising zcx_##_failed | 
   CLASS-METHODS get_instance

  7. Display the Code Element Information for method GET_INSTANCE of local class LCL_CARRIER to see the output.

    1. In the METHODS statement, place the cursor on get_instance and press F2 to show the code element information.

    2. The ABAP Doc texts are displayed under the heading Documentation.

Task 3: Add Formatted Documentation

Add formatted ABAP Doc documentation for method FIND_PASSENGER_FLIGHT. Optionally, add a similar ABAP Doc documentation for method FIND_CARGO_FLIGHT.

Suggested Documentation Texts

TypeCode ElementDocumentation
MethodFIND_PASSENGER_FLIGHT

Search for a passenger flight between two airports that

  • Lies on or after a given date
  • Has a minimum number of available seats left
Parameteri_airport_from_id

Departure airport

Parameteri_airport_to_idArrival airport
Parameteri_from_dateFirst possible flight date
Parameteri_seatsMinimum number of available seats
Parametere_flightFound flight (object reference)
Parametere_days_laterNumber of days after the requested date

Steps

  1. Use a quick fix to add ABAP Doc documentation to method FIND_PASSENGER_FLIGHT of local class LCL_CARRIER.

    1. In your local class, navigate to the definition of method FIND_PASSENGER_FLIGHT.

    2. In the METHODS statement, place the cursor on find_passenger_flight and press Ctrl + 1 to invoke the quick fix.

    3. From the list of available quick fixes, choose Add ABAP Doc.

    4. The quick fix adjusts the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123
        
  METHODS find_passenger_flight

  2. Maintain the documentation for the method with the text from the table. Make sure to add the formatting directives for passenger flight in bold type and for the unordered list.

    Hint

    You do not have to remember the format directives by heart. Press Ctrl + Space to insert a format directive though code-completion.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910
      
  "! 
  "! @parameter i_airport_from_id |
  "! @parameter i_airport_to_id |
  "! @parameter i_from_date |
  "! @parameter i_seats |
  "! @parameter e_flight |
  "! @parameter e_days_later |
  METHODS find_passenger_flight

  3. Maintain the documentation for the method parameters with the texts from the table. Make sure to add the formatting directives for Destination and Arrival in italic.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      1234567891011121314
      
  "! Search for a <strong>passenger flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available seats left</li>
  "!</ul>
  "! @parameter i_airport_from_id | 
  "! @parameter i_airport_to_id | 
  "! @parameter i_from_date | 
  "! @parameter i_seats | 
  "! @parameter e_flight | 
  "! @parameter e_days_later | 
  METHODS find_passenger_flight

  4. Display the Code Element Information for method FIND_PASSENGER_FLIGHT of local class LCL_CARRIER to see the output.

    1. In the METHODS statement, place the cursor on find_passenger_flight and press F2 to show the code element information.

    2. The ABAP Doc texts are displayed under the heading Documentation.

  5. Optional: Add similar formatted ABAP Doc documentation for method FIND_CARGO_FLIGHT.

    Hint

    Copy and paste the ABAP Doc documentation for method FIND_PASSENGER_FLIGHT and adjust it to method FIND_CARGO_FLIGHT.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123
      
METHODS find_cargo_flight

Task 4: Add Links

Add the following ABAP Doc documentation for local class LCL_FLIGHT:

Suggested Documentation Texts

TypeCode ElementDocumentation
Local ClassLCL_FLIGHT

Abstract superclass for classes lcl_passenger_flight and lcl_cargo_flight.

Every Instance is uniquely identified by attributes carrier_id, connection_id, and flight_date.

Add links to the documentation of local subclasses LCL_PASSENGER_FLIGHT and LCL_CARGO_FLIGHT and to the public attributes carrier_id, connection_id, and flight_date.

Steps

  1. Use a quick fix to add ABAP Doc documentation to local class LCL_FLIGHT.

    1. In your global class, navigate to the definition of local class LCL_FLIGHT.

    2. In the CLASS … DEFINITION statement, place the cursor on lcl_flight and press Ctrl + 1 to invoke the quick fix.

    3. From the list of available quick fixes, choose Add ABAP Doc.

    4. The quick fix adjusts the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      123
      
CLASS lcl_flight DEFINITION ABSTRACT.

  2. Maintain the documentation with the text from the table.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      1234
      
"!  
CLASS lcl_flight DEFINITION ABSTRACT.

  3. Add a line break after the first sentence.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910
      
"! Abstract superclass for classes 
"! lcl_passenger_flight and 
"! lcl_cargo_flight. 
"! Every instance is uniquely identified by attributes
"! carrier_id,
"! connection_id, and
"! flight_date  
CLASS lcl_flight DEFINITION ABSTRACT.

  4. In the first sentence, add a link to the documentation of local class LCL_PASSENGER_FLIGHT and a link to the documentation of local class LCL_CARGO_FLIGHT.

    Note

    Remember that this ABAP Doc documentation lies on global class level and not inside of local class LCL_FLIGHT. This means that a period sign at the beginning of a link addresses the global class. To address a local class in the same global class, you have to place a period sign in front of the class name.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910
      
"! Abstract superclass for classes 
"! lcl_passenger_flight and 
"! lcl_cargo_flight. <br/>
"! Every instance is uniquely identified by attributes
"! carrier_id,
"! connection_id, and
"! flight_date  
CLASS lcl_flight DEFINITION ABSTRACT.

  5. In the second sentence, add links to the attributes of local class LCL_FLIGHT.

    Note

    Remember that if you want to address an attribute or any other data object, you have to insert DATA: immediately before the object name.

    1. Adjust the code as follows:

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910
      
"! Abstract superclass for classes 
"! {@link .lcl_passenger_flight} and 
"! {@link .lcl_cargo_flight}. <br/>
"! Every instance is uniquely identified by attributes
"! carrier_id ,
"! connection_id , and
"! flight_date .
CLASS lcl_flight DEFINITION ABSTRACT.

  6. Display the Code Element Information for local class LCL_FLIGHT to see the output. Choose the links to verify that they work.

    1. In the CLASS … DEFINITION statement, place the cursor on lcl_flight and press F2 to show the code element information.

    2. The ABAP Doc text is displayed under the heading Documentation.

  7. Finally, activate your code.

    1. Press Ctrl + F3 to activate the code.

Log in to track your progress & complete quizzes