OpenEdge 11.6 - Generate ABL Doc Feature

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

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

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

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

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.

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 ?

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 ?

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.

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 ?

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 ?

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.

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

Is that the reason ?

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.

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.

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.

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

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.

any update ?

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?

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 ?

[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.

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)

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

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.

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.

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

"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.