OpenEdge 11.6 - Generate ABL Doc Feature

Posted by atuldalvi123 on 03-Feb-2016 05:08

Hi All,

I am working on OpenEdge 11.6 - Generate ABL Doc Feature. I am trying this feature to generate the standard layout for our team to follow the coding standards mainly for comments section but I don't know exactly where to place the comments so that those can be reflected on the generated layout correctly.

Is there any help available on this new feature of OE11.6 ?

 


All Replies

Posted by Ramadevi Dhavala on 03-Feb-2016 05:57

Hi,

You can find the complete documentation on ABLDoc generation from the following link:

documentation.progress.com/.../index.html

Following is the sample code to generate the comments for method parameters. Unfortunately this is not working for constructor parameters. Will get you back on this whether it is a bug or limitation.

CLASS testClass2:

   /*------------------------------------------------------------------------------

    Purpose:

    Notes:

        @param p1 - character value  input parameter

        @param p2 - integer value input parameter

   ------------------------------------------------------------------------------*/

   METHOD PUBLIC VOID meth1(

       p1 AS CHARACTER,

       p2 AS INTEGER  ):      

       RETURN.

   END METHOD.

END CLASS.

Thanks,

Rama

Posted by Ramadevi Dhavala on 03-Feb-2016 07:11

Hi,

ABLDoc supports only the predefined tags. It won't support '@Purpose:' tag. It support 'Purpose:' tag. ‘@param’ tag has to be used if we want to generate the documentation for method parameters.

Please have a look at the following code and the respective ABLDoc output generated.

My class file:

Generated ABLDoc Output for testClass2:

Thanks & Regards,

Rama

Posted by atuldalvi123 on 03-Feb-2016 07:17

Yes, finally its working for class methods. I am looking the same for class constructor as well.

Posted by atuldalvi123 on 04-Feb-2016 02:43

Any update on class constructor ? Also can we use the same for .p program ?

Posted by srireddy on 04-Feb-2016 03:01

Hi,

I tried generating doc with constructor and this looks like a bug, we will validate and will log a bug for this.

and for procedure you have to do it this way:

PROCEDURE pr :
/*------------------------------------------------------------------------------
 Purpose:
 Notes:
     @param a this is a
------------------------------------------------------------------------------*/
DEFINE INPUT PARAMETER a as INTEGER.
END PROCEDURE.

Posted by atuldalvi123 on 05-Feb-2016 03:51

I found few more interesting things here

1. File tag is not working for both class file and procedure program at the top section

2. Along with the File tag, Purpose, Description, Notes etc these tags also not working at the top section for the procedure file but working for class file.

Are these also OE bugs ?

Posted by DivyaTheja on 09-Feb-2016 01:04
Hello Atul,
 
By default, File name information will be available in the generated ABLDoc as title of that particular file. Regarding other tags, I am able to see file level Purpose and Description information in documentation generated. Here is my procedure code with comments and respective documentation.
 
In case, if you would like to have file information available in documentation, you will be able to customize the template as per your needs. Template files will be available at <DLC>\oeide\eclipse\plug-ins\com.progress.openedge.pdt.abldoc.core_<version>\abldoc-artifacts\templates. To display file name in ABL documentation, add following highlighted line in procedure_template.vm file and restart PDS OE.
 
      <!--Procedure Name -->
               <div class="title_name">$unitName $unitType</div>
               <div class="paragraph">
               <span class="detail_field_title" width="50px">File</span>:
                 #getDisplayString($model "File")<br>
               <span class="detail_field_title" width="50px">Purpose</span>:
                 #getDisplayString($model "Purpose")<br>
 
Here is the documentation generated after changing template file:
 
Hope this helps,
DivyaTheja
Posted by atuldalvi123 on 09-Feb-2016 04:18

Thanks for your update but if u check ur 1st screenshot where Syntax tag missing. that is because you have not added any value for it in the code ?

Posted by atuldalvi123 on 09-Feb-2016 09:03

Strange behavior for few files -

when I am creating a new class file from OpenEdge studio, it is designing defaualt header structure as below where I am putting my comments and those r reflecting as well on the ABLDoc template. No issue

/*------------------------------------------------------------------------

   File              : Batch

   Purpose     : 123

   Syntax         :

   Description : 456

   Author(s)   : H035002

   Created     : Tue Feb 09 15:52:05 CET 2016

   Notes       : 7890

 ----------------------------------------------------------------------*/

But there are few files available in the source where the same header with comments are available but those are not reflecting in the ABL template page, showing blank values against each attribute.  Its also working for METHODS but not for header part of the class. Don't know whether those class files have been designed in OE studio or by normal editor.

Pls help.

Posted by atuldalvi123 on 10-Feb-2016 09:46

Hi

I have generated ABLDoc template for full source code folder and below is the output. If you see there are 2 packages created in left side for a single sub folder. The only difference I am getting is the folder names in lower and upper case.

Any idea on this ?

Posted by Peter Judge on 10-Feb-2016 09:52
May be that the Java code doing the generation is not case-sensitive?
 
In general, I would recommend you be consistent with type names (and the file names containing OOABL types) since you don't always know in advance when it will matter. This is one (minor) case but if your code is deployed to non-Windows platforms you will run into more serious problems (like file-not-found etc).
 
Posted by atuldalvi123 on 10-Feb-2016 10:02

thanks buddy i will check the code for consistent  names. Also as i said in my earlier post that for some old files its not working means header part is not reflecting in the output but reflecting for methods. Do u have any idea on that ?

Posted by srireddy on 10-Feb-2016 23:52

I don't see any other reason why i shouldn't be generating the doc if you are following the same comment format for older files.

Is this the comment format in the old files?

/*------------------------------------------------------------------------

  File              : Batch

  Purpose     : 123

  Syntax         :

  Description : 456

  Author(s)   : H035002

  Created     : Tue Feb 09 15:52:05 CET 2016

  Notes       : 7890

----------------------------------------------------------------------*/

If so it should work, i tried using the above comment in a procedure and it worked fine.

Posted by atuldalvi123 on 11-Feb-2016 08:26

Old files are designed in 10.2B and now I am generating ABLDoc for them from 11.6.

Is that the reason ?

Posted by Bill Wood on 11-Feb-2016 11:02

WRT:

 >>> Old files are designed in 10.2B and now I am generating ABLDoc for them from 11.6.

ABL is ABL.... Source code is not versioned, so it does not matter when you wrote your ABL or what editor you used.   But there has been no proscribed way to write comments over the years and different templates have used different stypes for commenting (and most of the Progress-supplied tools have allowed people to write their own templates for files).   

This means that most existing comments in files were not added with any concept of the 'future' ABLDoc syntax, so you will find that some pre-existing files may randomly have commenting styles that cause unexpected behaviour.

But there is nothing 'version specific' about comments or ABL that makes it work better or worse in 11.6 with regards to ABLDoc.   You can write files in 11.6 that don't adhere to the ABLDoc standards and they will, naturally, also not work with ABLDoc, even if the code compiles.

Posted by atuldalvi123 on 12-Feb-2016 08:39

Yes I am following the same formatting but what I found interesting again is that ABLDoc feature is skipping my include file folder from generating the output page. Refer screenshot below -

any idea on skipping include file while generating ABLDoc pag ?

If I comment .i file in my class program then that is working fine, output reflecting on webpage but if I include any .i program in my class then it's not working.

Posted by Peter Judge on 12-Feb-2016 08:48
I believe that ABLDoc only creates doc for OO types (.cls files) and not procedures/includes.
 
Posted by atuldalvi123 on 12-Feb-2016 09:10

No its working for them as well. I have created sample structure to test and its working, I am trying it on dev machine its not working.

Posted by DivyaTheja on 12-Feb-2016 10:26

Hello Atul,

PDS OE 11.5 version has facility to generate documentation for include files too. This has been changed in 11.6. In 11.6 version, ABLDoc will not be generated to any ABL file (.cls, .p, .i) until the file is compiled and r-code file is generated. This is a known issue and is assigned to be fixed in next major release. Until then, for generating documentation for include files in 11.6, explicitly generating r-code for .i files helps.

Hope this helps,

DivyaTheja

Posted by atuldalvi123 on 13-Feb-2016 05:56

but if u see my above post where i have generated ABLDoc for cls. p & i files without any .r file.

Everything is working fine except for objects having .i file included  in it. See below screenshot where .i file is included in the class file. .r files are available for both the objects. if I comment .i file section in the below class file then its generating ABLDoc else not.

Posted by atuldalvi123 on 15-Feb-2016 02:28

any update ?

Posted by DivyaTheja on 15-Feb-2016 02:46

I am able to generate document for a class file with include. However, when a class file includes a .i file, information from file level comments is not available in generated ABLDoc. Is this the problem you are facing?

Posted by atuldalvi123 on 15-Feb-2016 03:28

i don't know the exact cause of not generating the abldoc for class file having .i included in it.  If i comment .i file in a class, its working fine. That .i file has r code available and progress is generating ABLdoc for that  .i.


Can u suggest .i file comments format ?

Posted by Mike Fechner on 15-Feb-2016 03:31

[quote user="atuldalvi123"] That .i file has r code available and progress is generating ABLdoc for that  .i.

[/quote]

R-code for an include file? Includes are not intended to be a compile unit of their own. Using include files as compile units usually creates chaos.

Posted by srireddy on 15-Feb-2016 03:34

Hi Atul,

I was able to reproduce this issue, There seems to be some problem while parsing file level comments if a file is having an include file, we will log a bug for this.

And the suggested comment format for include files are similar to procedure comments (or default comments generated by the Developer studio)

Posted by atuldalvi123 on 16-Dec-2016 03:44

Hi Guys,

I am again facing one small issue while generating the output. I am generating abldoc output for a particular folder having sub folders and class programs in it. I have created one build XML for ANT job and running the ANT job using a batch file.

Now the issue is, its generating output in the output directory but not creating the hierarchy of sub folders and the output in the sub folders, instead its creating all the output files in the main directory only.

Below is the build XML, pls have a look into this

Posted by Phani Sajja on 16-Dec-2016 04:05

Hi,

We have identified and addressed the issues related to missing Folder(Package) structure for the generated docs. And is addressed in 11.6.3 and and is also part of 11.5.1 hotfix. The problem which you are seeing may or may not be related to what we have addressed.

What is the OE version you are using.

We cannot conclude anything just by looking only at build.xml file. We can have a look at it if you can give a reproducible.

Before that we encourage you to check with 11.6.3/installing latest hotfix if you are using 11.5.1.

--

Regards,

Phani S.

Posted by atuldalvi123 on 16-Dec-2016 04:35

We are using 11.6 version. For reproducible, I have folder structure like same that i have mentioned in the XML.

If you generate the ABLDoc ouput  using a batch file ANT job for the folders having sub folders and class programs in it, you will face the similar issues.

Posted by cwright on 16-Dec-2016 06:40

From the Ant task you are on 11.6.2. I would suggest applying the 11.6.3 service pack.

Posted by Steven Peeters on 17-Oct-2019 08:11

"I tried generating doc with constructor and this looks like a bug, we will validate and will log a bug for this"

Can someone confirm if and in which version this is fixed?

I'm using 11.6.3.

This thread is closed