Skip to Content

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.

I would like to give you a short overview how you can document your ABAP source code development objects using ABAP Doc and where you can read the documentation written in ABAP Doc. I hope you like the new way of documenting your source code.

Please be aware that ABAP Doc has been introduced with SAP NetWeaver Application Server ABAP 7.4 (support package 2).

How can you write ABAP Doc?

With ABAP Doc, you can write your documentation directly within your source code using special comments in front of a declarative statement. This means you can document globally available artifacts (like classes, interface and their method and attribute), but also local artifacts (like local variables and field-symbols).

ABAP Doc comment block

An ABAP Doc comment block is introduced by the character combination “!. It has to be located directly in front of a declarative statement.

Example

“! This is a documentation for the following constant

constants co_initial_value type i value 0.


You can use multiple lines for your documentation to document your source code elements. In this case you have to add the character combination “! in front of each line.

Example

“! This documentation for the following constant is documented“! in multiple lines.

“! constants co_initial_value type i value 0.

If you want to document a block of statements by using the ABAP colon-comma-semantic the ABAP Doc comment block must be located in front of the identifier but after the colon.

Example

constants:  

  “! Initial value 

  co_initial_value type i value 0, 

  “! Invalid value 

  co_invalid_value type i value -1.


Document Parameters and Exceptions

For methods, events, function modules and form routines you can also document the parameters and exceptions. The following syntax is used to document parameters and exceptions:

Documentation for Syntax
Parameters @parameter <parameter name> | <parameter documentation>
Class-based exceptions @raising <exception name>   | <exception documentation>
Classic exceptions @exception <exception name> | <exception documentation>

Example

“! This method compares two sources and returns whether they

“! are identical.

“!

“! @parameter source1           | First source code text

“! @parameter source2           | Second source code text

“! @parameter ignore_case       | X = text will be compared case insensitive

“! @parameter result            | X = sources are identical

“! @raising   cx_invalid_source | Is raised if an empty source code text is passed

“! @raising   cx_invalid_source | Is raised if an empty source code text is passed

methods compare

  importing

      source1     type text

      source2     type text

      ignore_case   type abap_bool

  returning

      value(result) type abap_bool

  raising

      cx_invalid_source.

You can use quick fixes (Ctrl+1) within a ABAP Doc comment block to generate templates for all parameters and exceptions that have not been documented, yet.

ABAPDocQuickFix.png

Formatting options

The following tags can be used to format the output of your ABAP Doc documentation:

Formattingoption tag
Line break <br/> or <br></br>
Paragraph <p>…</p>
Emphasized text <em>…</em>
Strong emphasized text <strong>…</strong>
Unsorted lists <ul><li>…</li></ul>
Sorted lists <ol><li>…</li></ol>
Headers <h1>…</h1>
<h2>…</h2>
<h3>…</h3>

Example

“! This method compares <em>two</em> sources and returns whether they

“! are <strong>identical</strong>.

“!

“! @parameter source1           | First source code text

“! @parameter source2           | Second source code text

“! @parameter ignore_case       | X = text will be compared case insensitive

“! @parameter result            | X = sources are <strong>identical</strong>

“! @raising   cx_invalid_source | Is raised if an empty source code text is passed

“! @raising   cx_invalid_source | Is raised if an empty source code text is passed

methods compare

  importing

      source1     type text

      source2     type text

      ignore_case   type abap_bool

  returning

      value(result) type abap_bool

  raising

      cx_invalid_source.

Write correct ABAP Doc

To ensure that your ABAP Doc can be interpreted and rendered correctly by the system, we added some new additional checks when you execute the syntax check for your source code. If the position, the syntax or the formatting of your ABAP Doc comment is incorrect you will receive a warning:

ABAPDocWarnings.png

Where can you read the documentation?

The documentation will be displayed in the source code element information that is displayed when you press F2 on an identifier or when you use the ABAP Element Info view:

CodeElementInfo.png

Import ABAP Doc from descriptions

It is possible to generate ABAP Doc by importing the existing descriptions of global class and interfaces including their attributes, methods, parameters, etc.

To import the description in your class or interface, just open the class or interface and use the (context) menu entry “Source > Import ABAP Doc from Descriptions”.

importABAPDoc.png

Afterwards, the corresponding ABAP Doc is inserted into your coding and you can save the changes.

importedABAPDoc.png

ABAP Doc Features with NetWeaver 7.5

The blog New ABAP Doc Features with NetWeaver 7.5 describes following features which have been added with SAP NetWeaver Application Server ABAP 7.5:

  • How can you export your ABAP Doc from the ABAP server?
  • How can you synchronize ABAP Doc with short text descriptions?
To report this post you need to login first.

55 Comments

You must be Logged on to comment or reply to a post.

  1. Nigel James

    This is great.

    I was noticing the other day the the source code based editor for SE24 would add comments like:

    * <SIGNATURE>—————————————————————————————+
    * | Instance Public Method class_name->method_name * +————————————————————————————————-+

    * | [—>] ATTRIBUTE_PATH                 TYPE        STRING
    * | [—>] ITERATOR                       TYPE REF TO IF_BOL_BO_COL_ITERATOR(optional)
    * | [—>] VALUE                          TYPE        STRING
    * +————————————————————————————–</SIGNATURE>

    (apologies for the proportional font)

    This lends itself to ABAPDoc and will it be converted to the type of comments you refer to in this document?

    Thanks,

    Nigel


    (0) 
    1. Michael Schneider Post author

      Nice idea!

      The signature above the method implementation in the source based editor for SE24 has not changed so far.  It’s main purpose is to show the signature of the method implementation in SE24 where you cannot use element information (F2) or method information (Alt+F2) like in Eclipse.

      This could be changed to an ABAP Doc-like syntax. But I have doubts losing the type information for the parameters which is nor part of the ABAP Doc syntax, because we retrieve it from the method definition automatically.

      (0) 
  2. Nigel James

    Just some more thoughts: will there be support for @author @date and even @link given adt link feature available?

    thanks,

    Nigel

    (0) 
    1. Michael Schneider Post author

      Thanks for the feedback.

      We have some concepts for adding also links to the body of ABAP Doc. Unfortunately, I can’t promise, when this will be available.

      We didn’t plan to add the date and the author so far. Depending on the feedback, this might change in the future. 😉

      (0) 
    2. Thomas Fiedler

      Hi Nigel,

      As we already have author and creationDate stored in our metadata I can even think of automatically generate this information into the ABAP Doc block. Reusing the Link mechanism within ABAP Doc is definetly an excellent idea. Would be cool to open the editor with the linked object, right?

      Regards,

      Thomas.

      (0) 
    3. Jürgen Creyaufmüller

      Also a thought of me: it would also be great, if the comments created by pretty printer in SE80 would give the same result like abap doc in eclipse. And, it would be also nice to have some patterns – e.g. like the pattern for transport number in a modification (&$&$&$&$) – that are replace also in backed (CL_WB_SOURCE/Func EDITOR_UPDATE). Or even a BADi to create use own patterns….

      (0) 
  3. Luís Pérez Grau

    Hi Michael,

    I have a strange behaviour, I had ADT 2.0 and I  upgrade  it directly from the eclipse, I see new features like ABAP Resource URL, but I can’t see some of the ones described In your document, like Import ABAP doc from description, also my documentation doesn’t look so cool as yours( colours, icons, etc.). Any Idea?

    “! Get followup document document

    “! @parameter iv_obj_id | Base document type

    “! @parameter rv_result | follow up document type

    Thanks!

    Luis

    (0) 
    1. Michael Schneider Post author

      Hi Luis,

      I guess you are connected to an ABAP system based on NetWeaver 7.31. Unfortunately, ABAP Doc and also the new colours and icons in element info are currently available for NetWeaver 7.4 systems, only.

      I can’t promise whether this will change due to dependencies to the ABAP kernel. 🙁

      Regards,

      Michael

      (0) 
      1. Luís Pérez Grau

        Shame… I didn’t pay attention to this…

        Please be aware that ABAP Doc has been introduced with SAP NetWeaver Application Server ABAP 7.4 (support package 2).

        Man! you need to be too up to date! 😡 well at least I can start preparing the code for future releases 😛

        Thanks Michael!

        (0) 
  4. Thomas Fiedler

    Short Addition:

    You can also use Quick Fix (CTRL-F1) to remove ABAP Doc comments in case you have deleted a parameter from the signature.

    Regards,

    Thomas.

    (0) 
  5. Carsten Kasper

    Some questions, just out of curiosity:

    • This ABAPDoc is only available to ADT and not SE80? I can not use it in SAP GUI development?
    • This ABAPDoc does have nothing to do with the ABABDoc project on CodeExchange? https://cw.sdn.sap.com/cw/groups/abapdoc
    • This ABAPDoc is again unrelated to the AbapDoc Scanner CL_ADOC_SCANNER already shipped by SAP?
    (0) 
    1. Michael Schneider Post author

      This ABAPDoc is only available to ADT and not SE80? I can not use it in SAP GUI development?

      You can also write it in the source code and you will get also warnings when you execute a check, but there is no dedicated tools support like source code element information or quick assist (Ctrl+1)

      This ABAPDoc does have nothing to do with the ABABDoc project on CodeExchange? https://cw.sdn.sap.com/cw/groups/abapdoc

      yes

      This ABAPDoc is again unrelated to the AbapDoc Scanner CL_ADOC_SCANNER already shipped by SAP?

      yes

      (0) 
      1. Carsten Kasper

        Hi Michael,

        thanks for the fast reply and the answers.

        This ABAPDoc is again unrelated to the AbapDoc Scanner CL_ADOC_SCANNER already shipped by SAP?

        yes

                           

        May I ask why? This ABAPDoc does most of the code analyzation and comment extraction. Sadly for me it features a completely different set of markups.

        Is it possible to transform existing “old” code with the “old” style of comment to the new format automatically? Or even better: Is it possibel to customize the new ABAPDoc to respect the comments of the old ABAPDoc or the ABAPDoc project in CodeExchange?

        (0) 
  6. Daniel Ruiz

    I’m visiting this topic for the same reason..

    Can we generate a javadoc out of it? (since it’s basically a copy of javadoc anyways..)

    Cheers,
    D.

    (0) 
    1. Thomas Fiedler

      Hi: Daniel, Rene.

      yes, this is definitely on our ABAP Doc roadmap. But generating of HTML Documentation out of the ABAP Doc snippets is currently not possible.

       

      Regards,

      Thomas.

      (0) 
      1. Daniel Ruiz

        Hi Thomas,

        When is the xdoclet generation coming out? – I mean, there is some sort of usage for such (abapdoc in its current version) to do developer documentation, however most developers would not benefit of such in the format it is (either navigate to a class or start doing code to ‘read’ this documentation).

        Cheers,

        D.

        (0) 
        1. Thomas Fiedler

          Hi Daniel,

          the next feature we want to provide for ABAP Doc is the navigation within the Elementinfo popop in the ABAP editor in Eclipse. Like here in this example I have the Elementinfo opened for an interface that I use my code. Now we want to provide the possibility to navigate within this popup to the documentation of other development objects, e.g. to the documentation of the used DDIC types of the interface. The second option we want to provide is the possibility to open the corresponding editor in eclipse, e.g. the DDIC editor of an used type.

          /wp-content/uploads/2014/02/21_02_393486.png

          What do you think?

          Regards,

          Thomas,

          (0) 
          1. Daniel Ruiz

            Hi Thomas,

            I think its great that doclet generation is part the roadmap, being able to also ‘quick navigate’ while on the code is quite handy but it seems like prettifying something incomplete or missing its main function (which is the generation).

            As far it goes, the main idea behind the Javadoc was not to support documentation while inside an IDE but to support documentation which could be generated out of the source itself, giving developers a way to quickly create and maintain some sort of standard documentation (instead of having some focused person to do such).

            But this is just my two cents, not sure about other ADT users there – I’d personally vote on generation of documentation in HTML as a ‘must have’ feature while navigation within Eclipse a ‘good to have’.

            Cheers,

            D.

            (0) 
            1. Christian Hiller

              Hi Daniel,

              I don’t agree. For me it is more important to have the navigation inside the “Abap Element Info”. Otherwise I have often to interrupt my development by opening the SAP-GUI or the development object in Eclipse to find out the details of a type,…

              In the way it is described by Thomas it helps me to make the development work faster. In my opinion it is more important to set the focus there instead of the generation of HTML documentation.

              Regards,

              Christian

              (0) 
              1. Daniel Ruiz

                Hi Christian,

                I think you can kinda overcome this issue straight away by using some sort of meaningful name to your objects.

                I’m not too sure why you have stuff other than classes there, perhaps too much of procedural code? – As far I understand, you may need structures to persist using ABAP SQL (unless you use statements) but the structure is a 1:1 to a bean anyways.. so I just don’t get it. =(

                Also, we would have the same capability as soon we generate HTML documentation out of it, but instead of using a micro window inside the IDE you would look into the API documentation itself in a browser window — for sure, you shouldn’t be wandering too much in that window while on Eclipse; either you know what you are doing or you should refer to docs anyways right?

                Regards,

                D.

                (0) 
    1. Michael Schneider Post author

      Hi Philipp,

      You can just import the short text descriptions for a class or an interface into ABAP Doc comments (but not for the whole system), currently.This can be done via the menu entry “Source > Import ABAP Doc from Descriptions” (as described above).

      Michael

      (0) 
      1. Philipp Rembold

        Hi,

        so is there no way to see the whole class documentation out of Elipse other than opening the class in SAP GUI and opening it there?

        Best,

        Philipp

        (0) 
        1. Michael Schneider Post author

          Oh, Sorry, I think I got your question wrong.

          Unfortunately, there is currently no way to see the whole documentation of a class in one document in Eclipse. But we plan to provide some export functionality in the future.

          In the mean time, you can use element information (F2) for a class or interfaces. This will give you also an overview about public components, but you can’t drill down.

          (0) 
  7. Ondrej Seman

    Hi,

    I find the featuer of ABAP Doc REALLY GREAT! I use the element information in Eclipse a lot. Any plans for backporting to 7.31?

    Would it be possible, to import the first line of the ABAP Doc as a method’s short description? It is kind of anoying to always open the class in SAP GUI und put the description there. However, there are still some collegues, which are using SE80 (even I do at times, if I don’t have access to Eclipse). Best woud be to synchronize this first line always between the source (ABAP Doc) and DDIC (short description) automatically, by load/save. This way Eclipse fans and SE80 fans are all happy!

    And the rest of the lines could be written in the standard method documentation in SE80? (Does anyone ever used it?) Maybe it would be even possible to import already existing method docs back to ABAP Doc?

    Have a nice day!

    Ondrej

    (0) 
    1. Michael Schneider Post author

      Hi Ondrej,

      Thanks for your feedback.

      Any plans for backporting to 7.31?

      Due to dependencies to the Kernel we don’t plan to downport it to 7.31, currently.

      Would it be possible, to import the first line of the ABAP Doc as a method’s short description?

      We are looking into this topic, currently. We would like to provide a way to show the shorttext description of Class Builder in ABAP Doc comments and we would also like to allow to change them there.

      Best woud be to synchronize this first line always between the source (ABAP Doc) and DDIC (short description) automatically, by load/save

      We don’t plan to use the first line for the shorttext descriptions because this might be incompatible for existing ABAP Doc comments.

      And the rest of the lines could be written in the standard method documentation in SE80? (Does anyone ever used it?) Maybe it would be even possible to import already existing method docs back to ABAP Doc?

      We don’t plan to maintain longtext documentation via ABAP Doc, but we would like to provide a link to longtext documentation (if it exists) in element info (F2).

      Michael

      (0) 
  8. Edison Lim

    Hello Michael,

    Thanks for sharing. ABAP Doc looks just like what I am looking. I have a few questions on it.

    Is ABAP Doc available if I am using SAP ECC to edit code and not Eclipse? If I follow the ABAP Doc comment convention, is there some way to generate documents within SAP ECC?

    Searching within my ECC, I see program PROG_SRC_ADT_ABAPDOC_EXAMPLE that appears to be there to demonstrate ABAPDoc. But not sure if ABAPDoc is directly working inside SAP.

    Thanks and best regards,

    Edi

    (0) 
    1. Michael Schneider Post author

      Hi Edi,

      You can write ABAP Doc using SAP GUI. You should get warnings when you execute syntax check if you use a wrong syntax for it. However, you will get much more support (see above), if you are using it via Eclipse. Maybe you want to give it a try. 😉

      Currently, there is no way to generate whole documents from ABAP Doc. But it is part of our backlog.

      Michael

      (0) 
  9. Andre Wuthenow

    Hi Michael,

    I really like the approach of having an integrated documentation of ABAP Elements that can be reused in eclipse and show information whan hoovering over the Element in the Source Code. Currently we use an own implementation of ABAP Doc based on the code that was originally provided by https://cw.sdn.sap.coom/cw/groups/abapdoc. As we want to have some information about changes and fixed bugs and the used transport requests directly in the code we use the @changelog-tag. I haven’t seen such a feature in the new ABAP Doc. Will this be available in near future?

    An additional advantage of our ABAP Doc solution is the creation of a html documentation. Will this be possible in future with the new ABAP Doc as well?

    Further we have written an extension for the Code Inspector to check, if methods, programs and function modules have a valid ABAP Doc. If not, an error or warning is shown in the Code Inspector. Is something similar planned for ABAP Doc as well.

    Thanks and best regards,

    André

    (0) 
    1. Michael Schneider Post author

      Hi André,

      Thanks for your feedback!

      I try to answer your questions:

      As we want to have some information about changes and fixed bugs and the used transport requests directly in the code we use the @changelog-tag. I haven’t seen such a feature in the new ABAP Doc

      Currently, this is not planned. Why do you want to document this in the source code instead of using version management? What kind of additional information do you usually add to this tag (beside transport request and date)? I could think of showing information in the version management directly in the editor (without adding any coding).

      An additional advantage of our ABAP Doc solution is the creation of a html documentation. Will this be possible in future with the new ABAP Doc as well?

      Yes, this is part of our backlog.

      Further we have written an extension for the Code Inspector to check, if methods, programs and function modules have a valid ABAP Doc. If not, an error or warning is shown in the Code Inspector. Is something similar planned for ABAP Doc as well.

      The validation of ABAP Doc is done when you execute the syntax-check in an ABAP source code editor. I think, it would be possible to integrate the same check also to ABAP Test Cockpit. It is not planned so far, but you are also the first one, who requested it 😉 .

      Michael

      (0) 
      1. Andre Wuthenow

        Hi Michael,

        thanks for coming back to me so quickly.

        I use the changelog task to add a short description about the functional change that has been done in the code and to have a small version history. It allows us to see what has been changed directly without comparing different versions of the code and understanding the code. Currently the tag contains the date of the change, the author, a short functional description and the change request (of course the date, the author and the change request can be found in the system, but this will result in additional effort ).

        The validation of the ABAP Doc in the syntax checker is really helpful, but in case that developer do not use ABAP Doc, this is not highlighted. That’s why we use our own check in the Code Inspector.

        Best regards,

        André

        (0) 
  10. Sonny Mørk Petersen

    Hi Michael,

    Thanks for the blog.

    Really like the ABAP Docs and I am very interested in the extract to html outside the IDE. Do you have any insight on when this will be available.

    Thanks and best regards

    Sonny

    (0) 
      1. Edison Lim

        Hello Thomas,

        Isn’t this feature built in ADT and Eclipse? Just like to clarify why is this available only in S/4?

        Thanks and best regards,

        Edi

        (0) 
  11. Ondrej Seman

    Hi everyone,

    I was wondering, is there a tag to have text formatted as code? This would be very usefull, when you want to provide short example on how to use particular method. Then you could put a few lines of code into the ABAPDoc (similar to HTML <pre> tag. Right now, when I do that, everything is converted to simple text. And using paragraphs for this is rather too much effort.

    Thanx!

    O.

    (0) 
  12. RAO BD

    Hi Micheal,

    How to read ABAP Docs. Is there any class ,service or FM provided to get ABAP docu in SAP GUI.

    Regards,

    Rao.

    (0) 
  13. Dmitrii Iudin

    Hello.

    First of all – great Job out there! this was needed for so much time now.

    On more specific question though – is there any way to Combine the abap doc with inline declarations? For example, I have the inline declaration of data element that is receiving the importing Parameter of the method. How should I put comment for such a declaration?

    /wp-content/uploads/2015/11/test_abap_doc_837773.jpg

    (0) 
    1. Thomas Fiedler

      Hi Dmitrii,

      ABAP Doc is online supported for explicit declarations.

      If you would like to document them I propose to use the Quickassist to generate explicit declaration from out of inline declaration. The type of the explicit declaration is claculated by the tool.

      Once you did that step you can document the declaration with ABAPDoc.

      Regards,

      Thomas.

      (0) 
  14. Mattias Johansson

    I’ve added abap docs to one of my methods, and when I look at the element info in that class it looks good. However if I call my method from another class, and look at the element info, I don’t get the abap docs comments.

    (0) 
  15. Dirk Tyriard

    Great to find this,
    Hello missing 1 thing, what are the Escape chararacters for ABAP-Doc?
    For example parameters/constants/… one gives descriptions like, ‘ReceivingQty@Wharehouse’ in SE37, SE24, SE80, ….
    Then in Eclipse import the descriptions a described => problem with the fact the character ‘@’ is in the text.  So what is the escape to put before the @ to avoid this?
    Dirk
     

    (0) 
  16. Lukas Bartek

    Hi Michael,

    Is the ABAP Doc meant only for the global objects like function modules and global classes/interfaces or is it possible to be able to use it with local classes?

    Thank you,
    Lukas

    (0) 
    1. Michael Schneider Post author

      Hi Lukas,

      Yes, you can use ABAP Doc also for local definitions like local classes or local interfaces. It is even possible to use ABAP Doc for local variables, types or constants.

      Michael

      (0) 

Leave a Reply