Skip to Content

In my document ABAP Doc I gave you a short overview about ABAP Doc and how you can use it.

In this blog, I would like to explain to you how you can export your ABAP Doc from the ABAP system and how you can synchronize your ABAP Doc comments with the short text descriptions in classes, interfaces and function modules. I hope you like these two new features which are available with SAP NetWeaver Application Server ABAP 7.5.

How can you export your ABAP Doc from the ABAP server?

We introduced a new functionality to ADT that allows you to export ABAP Doc of your classes and interfaces to local html-files.

In order to export your ABAP Doc you can proceed as follows:

  1. Choose any package, class or interface in Project Explorer and choose „Export …“ from the context menuabapDocExportPEContextMenu.png
  2. In the wizard, choose “ABAP Doc”
    abapDocExportWizardPage1.png
  3. On the next page of the wizard you can add further classes, interfaces or whole packages and define the root directory where the html files shall be stored in your local file system.
    abapDocExportWizard.png
    If you choose a whole package, the ABAP Doc of all classes and interfaces of this package will be exported.

For each class or interface a dedicated html file is rendered that is located in the folder representing the package name.

abapDocExportResultDetail.png

abapDocExportResult.png

If you want to adapt your own design to the exported html-pages, you can overwrite the stylesheet stored in htmldesign\stylesheet.css.

How can you synchronize ABAP Doc with short text descriptions?

Up to now, ABAP Doc and the classic short text descriptions you know from the SAP-GUI-based Class Builder or Function Builder were not linked to each other. This means, users who are still working with SE24 or SE37 and specify the short text descriptions there, didn’t see the documentation written by their colleagues in ABAP Doc and vice versa.

Now, you have the possibility to define or change the short texts of classes, interfaces and function modules by using ABAP Doc. This includes also the short text descriptions of attributes, methods, parameters and so on.

This can be reached by classifying a paragraph in ABAP Doc as a short text. The short text shall be a brief summary of what your element is about. A short text in ABAP Doc looks like this:

“! <p class=”shorttext”>Returns all sales orders</p>

This is just a classification of a text in your ABAP Doc. Nothing special about this so far. However, if you also add the classification „synchronized“ to your short text, the text defined in your short text tag will be taken over to the short text descriptions of SE24 or SE37.

Even more, if a colleague updates the short text in SE24 or SE37, the short text in your ABAP Doc will be updated without touching the rest of your ABAP Doc.

abapDocSyncShorttext.png

A synchronized short text in ABAP Doc looks like this:

“! <p class=”shorttext synchronized”>Returns all sales orders</p>

If you enable the synchronization of the short-text-tag, the length of its content is limited to the length of the corresponding short text description in SE24 or SE37. If you use more than the allowed characters you will get a warning.

The new format of synchronized short texts is also considered if you import ABAP Doc from short text descriptions. importAbapDoc.png

Then the imported texts are automatically synchronized. Additionally, the attribute „lang“ will be added to your paragraph.

“! <p class=”shorttext synchronized” lang=”en”>Returns all sales orders</p>

This attribute will indicate the master language of your development object. The short text should be maintained in the master language, to ensure a correct synchronization. It is not possible to specify other languages than the master language; the editor would show you a warning if you do so.

To report this post you need to login first.

28 Comments

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

  1. Stefan Schmöcker

    Hello Michael,

    I like the idea of the  synchronized shorttexts.
    Question:

    • Will there be quickfixes or anything else to transform existing ABAP Doc to synchronized ABAP Doc?


    (0) 
  2. Attila Laczko

    Hello Michael,

    If Stefan with ABAP Doc means ABAP longtext, then I’m wishing too this feature.

    It comes handy and must not do the same thing twice 🙂

    Wen such plans are existing, will be possible to export them also in HTML files, perhaps along with ABAP Doc from the coding files and so creating a complete documentation of the concerned developing object.

    cheers

    (0) 
  3. Simon Perstorfer

    Hey Michael,

    nice new features, but there are a few points which would be nice to have..

    • If ä, ö or ü is escaped in the synchronized shorttext, SAPGUI displays also “&ouml;” and not an ö..
    • Link to other ABAP Doc, if f. e. a Import parameter is from type of other Class (like JavaDoc)
    • Overview-Page to browse through elements of package and sub-packages
    • Automated Publishing of HTML Documentation on NetWeaver. I think export in Eclipse and upload to some Web-Server is not a convenient way
    • “Regeneration” of ABAP Doc in Eclipse. F. e if someone adds a parameter to class method, just click on “Import from Desc..” and the ABAP Doc (with empty shorttext tag) for this new parameter is added to the existing ABAP Doc of the method. Maybe this can be combined with save actions, so that the ABAP Doc is automatically regenerated when saving or activating an object in Eclipse

    Regards

    Simon

    (0) 
      1. Ondrej Seman

        Hi Thomas,

        I would like to add my wish to the “nice to have” list:

        • <pre> or <code> tag, so it is possible to put short coding examples in the abap doc.

        Regards,

        O.

        (0) 
        1. Thomas Fiedler

          Hi Ondrej,

          we are working on a feature to integrate hyperlinks on development objects within the ABAP Doc comment. You can then write your sample code in an own class/report and link with the ABAP Doc.

          Isn’t this the better option then writing sample code direct in the ABAP Doc?

          Regards,

          Thomas.

          (0) 
          1. Stefan Schmöcker

            Some companies have regulations concerning coding that don’t apply or are less strict than those concerning comments when transporting something to a productive system.

            (0) 
          2. Ondrej Seman

            Hi Thomas,

            feature you are suggesting is also interesting, and I like it. However it is always one more click. Especially when the code example would be only say up to 5 lines long, having it in the ABAP Doc would be more convenient.

            Have a nice day!

            O.

            (0) 
            1. CHIN WEE ONG

              Hi Thomas,

              I have just looked into the Netweaver ABAP roadmap, and find that there are no subsequent release of new features to ABAP Doc. During my current implementation, I’m planning to have my team use ABAP Doc extensively, especially focusing on reusable components.

              The outstanding questions is browse-ability of these reusable components. An overview page of the developed elements would be useful. From collaboration perspective, the team can browse what are the built components out there that can be reused.

              • Overview-Page to browse through elements of package and sub-packages

              Could you be kind enough to let me know if such features is in plan? If not, I have to start looking for alternative to enable browse-ability of built components documentation. The exported HTML documents are useful, it’s only lacking one overview page. =)

              Looking forward to hear from you.
              Thanks.

              Aldern

              (0) 
  4. Daniel Ruiz

    Hi Michael,

    Any special reason for this to be only 7.5 and not 7.4? – I really cannot see anything in particular 7.5 delivered as core functionality to enable ABAP Doc generation…

    Is there a date for a 7.4 patch or release? – Otherwise is another year or so until first customers update to 7.5. (at least around this area I live)

    Cheers,

    Dan.

    (0) 
  5. Florian Barth

    Hi Michael,

    will it be possible to get the ABAP Doc for method parameters in the ABAP Element Info view. I think this would be pretty handy when changing a method that has become very long.

    Regards,

    Florian.

    (0) 
    1. Michael Schneider Post author

      Hi Florian,

      Do you know the feature to show the element info for the current method implementation? Within a method implementation, you can open it via context menu entry “Source Code > Show Method Information” or via short-cut Alt+F2.

      Maybe, this helps.

      Regards,

      Michael

      (0) 
      1. Florian Barth

        Hi Michael,

        yes I know that feature and use it occasionally.

        I had my idea because I have the element Info pinned and synchronized with the active editor so I always see the element info for the element which my cursor sits on. I would have loved to see not only the type of parameters but also its documentation (just for completeness and consistence with other variables)

        Regards,

        Florian

        (0) 
      1. Helder Duarte Da Costa

        Hi Thomas,

        Thanks for such a quick reply.

        Ideally I would have loved to have it in the ABAP workbench.

        I was happy when I saw the compiler was able to interpret it, so I thought maybe this had been now made available in the abap workbench. Abap_doc.png

        Regards,

        Helder

        (0) 
        1. Thomas Fiedler

          Hi Helder,

          you know we are not investing anymore in new features in the ABAP workbench.

          ABAP IDE of choice is eclipse. So my strong recommendation is to switch to eclipse.

          Regards,

          Thomas.

          (0) 
          1. Helder Duarte Da Costa

            Thanks Suhas.

            I was just kind of testing to see if I could get it generated 🙂

            About AiE, to be honest I did gave it a try a while back. I am sure it has improved a lot but back then I was not convinced.

            Will give it a try again.

            Regards,

            Helder

            (0) 
            1. Suhas Saha

              I was also sceptical about AiE in the beginning. But I have been using it for 4 months and I don’t think I can revert back to SE80 🙂

              I just love the “Quick Fix” functionality in Eclipse. Makes refactoring a child’s play. Definitely worth a try.

              (0) 
      2. Suhas Saha

        Hi Guys,

        Actually you can generate the ABAPDoc from SAPGUI if you have the JNet plugin 🙂

        Disp_UML.jpg

        Genr_ABAPDoc.jpg

        ABAPDoc_UML.jpg

        What I have not figured out is why the UML is not displayed in the ABAPDoc 🙂

        (0) 
  6. Florian Dupret

    Will there be a way to automatically (or with a quick fix) generate the documentation skeleton? As of now it is quite tedious to maintain the documentation of a method and its parameters, even with a template because I need to copy the parameters’ and exceptions’ names. For this task I switch to the SAP GUI, not very handy.

    (0) 
      1. Florian Dupret

        Hi Thomas,

        Thanks for your quick answer. I didn’t know this feature, however it is not as complete as I expected. It would be great if the tags “<p class=”shorttext”>…</p>” were added at the same time so that short descriptions are easily synchronized. At the moment I guess I’ll have to add those manually everytime I maintain the documentation so that people still using the SAP GUI can read the documentation.

        A few other suggestions that I think are quick wins:

        – Add an option so that when we create a method (or any component with documentation) using the quick assist, the documentation template is automatically generated with parameters and exceptions.

        – Initialize the short documentation of parameters with the DDIC description just like in the SAP GUI.

        As of now I still find it quite tedious to maintain basic documentation even with the existing quickfix – still quicker to do it in SAP GUI rather than in Eclipse.

        Regards,

        Florian

        (0) 
  7. Aniz Mohammed

    Hello Micahel,

    When we export the ABAP Doc for a class to an html file, we don’t see the documentation that we added for local variables. We get the doc for methods , attributes,  parameters etc but what ever we added before local variable declarations are not in the html file. Are we doing something wrong or is this how it works ?

    Thanks & Regards

    Aniz

    (0) 
  8. Chairat Onyaem

    Hi, is there a plan to add features to ABAP Doc to export local classes (including local test classes), function modules, and programs (and its local subroutines/classes) as well ?

    I ran into a situation that the class and method names are not meaningful enough (as it is limited up to 30 characters) and I was asked to put a comment for documentation purpose. It’d be great if that could be exported as ABAP Doc as well.

    (0) 
    1. Tobias Kieser

      I would also appreciate if we could do that.

      I am also in such a situation I could use this functionallity to drop ABAP documentation for local classes.

      (0) 

Leave a Reply