Find/Define - Documentation standards for COBOL

[brunopacheco1]

Before really coding how generate documentation, it is quite important to check with COBOL developers how they document their code.

[aswinvenkey]

What we generally do is, after the identification division to have a program overview on what the code does for 4-5 lines. After which we have some documentation of how the code processes data like how it starts, business logic on what is added, checked, changed and removed from the input files or verified against a table, calls to any subprograms. Basically, a step by step by view on what the code does. After which we outline what the input, output files are and what tables/DBs are used in the code. After this, we add a program maintenance log, where we specify each release, developer, and release notes. Additionally, if the code is really complex and long. We tend to add a couple of lines before each paragraph starts to understand what the subsequent para does. Hope this helps.

[brunopacheco1]

@aswinvenkey Thanks for your feedback! I have some follow-up questions.

Do you add specific comments to data storage and fields, describing what they are?

Is there any standard for commenting on the source code (besides starting at col 7 with an asterisk)? For instance, in java, to be considered a Javadoc comment it has to start with \** instead of \*, and you may have annotations to describe for example arguments and return of a function.

If it is not that much, I would appreciate it if you could share a sample on how you usually do comments on a "real" COBOL source code.

[aswinvenkey]

@brunopacheco1 Answering, the data storage field question usually we don't since the fields are self explanatory and according to principles of well structured cobol code they have to be meaningful as to what they contain. Regarding, different ways of adding documentation I would say no to that too! Cos, whatever documentation we do we just do it with an asterisk but sometimes we do add a full line of asterisks before and after the comments but that is just for formatting and readability. But there could be other shops/developers who might have different ways of adding documentation.

Sure, I'll share one across to your email id tomorrow.

[jellypuno]

In my experience we have the flowerbox. It looks like this:

*****************************************************************
* DATE       CHANGED BY    DESCRIPTION                          *
* --------   ------------  -------------------------------------* 
* 99.99.99   USERNAME      INITIAL CHANGE (change number)       *
*****************************************************************
* A100 - MAIN PROCESS                                           *
* P100 - PRINTING                                               *
*****************************************************************

Then the number in column 1-6 or 72-80 is used as change number

[aswinvenkey]

@brunopacheco1 @jellypuno just conveyed what I was trying to say with so many lines.😂😂😂

[brunopacheco1]

@aswinvenkey @jellypuno Thanks again for your feedback.

Are these flowerbox comments placed before or after the IDENTIFICATION DIVISION?

Would you also consider commenting variables and functions when it's needed?

I mean, sometimes it is not possible to synthesize the meaning of a variable or a function in a short name. And the idea of documentation is rather to be as more explicit as possible to ease the reader's understanding, even sometimes with samples or possible exceptional flows.

What do you do in this kind of situation?

[aswinvenkey]

@brunopacheco1 we generally place these comments after the IDENTIFICATION DIVISION. But @jellypuno can correct me if I'm wrong.
Regarding, the variables yes I understand but I myself have not faced a situation where I need to explain exactly what this variable is or does more than its name. But for paragraphs aka functions yes we tend to add some lines above each paragraph definition to understand what is being passed to it and what the paragraph does with the data.

[brunopacheco1]

I just found this link where some standards are suggested and one is about having these flower boxes before each paragraph, with some description and paragraph calling chain.

Do you do it similarly?

[aswinvenkey]

@brunopacheco1 yes we do that flower box for each paragraph with the description but we don't do the para calling chain. But maybe that's just because we're too lazy 😂 🤣. But it does sound useful and can eliminate some analysis time.

[brunopacheco1]

@aswinvenkey @jellypuno Would you say that this sample is reasonably documented? Perhaps would you do it in a different way?

petstore.txt

[aswinvenkey]

I think this is more than sufficient as for documentation, but generally, some programs tend to go a bit more complex. So, in this case, yes I understand that the paragraph flow description after the identification division also serves as a program overview but in more complex cases I believe having a couple to lines to just know what the program does. And also, when input files, tables, adabas files are involved we tend to add that as separate sections in this flowerbox.

[brunopacheco1]

@aswinvenkey I got it, and it makes sense if you have flowerboxes over paragraphs, perhaps this initial list of paragraphs is useless and could be built automatically anyway.

[brunopacheco1]

@aswinvenkey @jellypuno Could both of you share some code sample with comments/flowerboxes? I think I've got something to start working on, but it would be great if I have more code scenarios, preferably more complex cases and not coded by me.

[aswinvenkey]

@brunopacheco1 sure! I'll check for cases like that. but it might take a while and I have to figure out how to give you the code without breaking some kind of NDA.😂 🤣

[OlegKunitsyn]

Backward compatibility is good and COBOL comments might be helpful for maintenance of the legacy code.
IMHO, a comment-only approach is the way to nowhere. Javadoc and its successors use tags @param, @return etc to refer the linkage with the textual description. In my COBOLget libraries e.g. https://github.com/OlegKunitsyn/core-string/blob/master/src/string.cbl you may see this approach in action.

Successors

• https://en.wikipedia.org/wiki/Javadoc
• https://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html
• https://en.wikipedia.org/wiki/JSDoc

@brunopacheco1 may I have contribution rights to your project?

[brunopacheco1]

@OlegKunitsyn You are right, I was thinking to go to that direction, but I was just checking out with @aswinvenkey @jellypuno what they usually do, in order to find something in between, to be more appealing.

So my idea was to combine this flowerbox standard with tags or annotations, to simplify the matching process.

[brunopacheco1]

@OlegKunitsyn the tool is already going through the code looking for modules and functions and all possible coboldoc comments.
Now it is a matter of defining a coboldoc markers to help to CLI tool to identify the documentation. In the samples you provided, comment starting with *>** contains general info about the file, and comment starting with *>* contains general info about the following module/function.

I just followed this pattern, but perhaps that is not the usual approach, where did you get it from? I also thought it could be open, which means the CLI tool would have options to extend this step in the parsing process.

[OlegKunitsyn]

A Javadoc fantasy. :) I'll change that to standard coboldoc specs, anytime.

We don't need to invent the wheel, I think. Any existing specs and open-source implementation of the tools for typed language is a good starting point. I vote for https://en.wikipedia.org/wiki/Javadoc, having few basic tags at the beginning.

[jellypuno]

@brunopacheco1 The COBOL Programming course has COBOL programs with reasonable comments. I think it looks good.

https://github.com/openmainframeproject/cobol-programming-course/tree/master/COBOL%20Programming%20Course%20%231%20-%20Getting%20Started/Labs/cbl

[brunopacheco1]

Hey you. I believe I've got an MVP for the documentation generator. Please, fill free to have a look at it and comment out.

[OlegKunitsyn]

1.0.4 fails

$ coboldoc
internal/modules/cjs/loader.js:983
  throw err;
  ^

Error: Cannot find module '../lib/index.js'
Require stack:
- /usr/local/lib/node_modules/coboldoc/bin/coboldoc
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:980:15)
    at Function.Module._load (internal/modules/cjs/loader.js:862:27)
    at Module.require (internal/modules/cjs/loader.js:1042:19)
    at require (internal/modules/cjs/helpers.js:77:18)
    at Object.<anonymous> (/usr/local/lib/node_modules/coboldoc/bin/coboldoc:2:1)
    at Module._compile (internal/modules/cjs/loader.js:1156:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1176:10)
    at Module.load (internal/modules/cjs/loader.js:1000:32)
    at Function.Module._load (internal/modules/cjs/loader.js:899:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/usr/local/lib/node_modules/coboldoc/bin/coboldoc' ]
}

[brunopacheco1]

I have to spend more time investigating it, but this problem looks something related to the environment you are using. For some reason, it is not finding correctly the files. I pushed a new version with some changes but it looks like on Linux it is working correctly, but not on Windows.

[OlegKunitsyn]

$ sudo npm uninstall -g coboldoc
removed 21 packages in 0.194s
$ sudo npm install -g coboldoc
npm ERR! code ENOENT
npm ERR! syscall chmod
npm ERR! path /usr/local/lib/node_modules/coboldoc/lib/index.js
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, chmod '/usr/local/lib/node_modules/coboldoc/lib/index.js'
npm ERR! enoent This is related to npm not being able to find a file.
npm ERR! enoent 

npm ERR! A complete log of this run can be found in:
npm ERR!     /root/.npm/_logs/2020-08-15T15_15_44_587Z-debug.log

[OlegKunitsyn]

2020-08-15T15_15_44_587Z-debug.log

[OlegKunitsyn]

Seems the package was packed incorrectly.
wget https://registry.npmjs.org/coboldoc/-/coboldoc-1.0.5.tgz
Inside I see TypeScript files instead of compiled JavaScript.
NPM is platform-independent, my Linux in not an exception. For a cli tool I was using extremely simple packaging/publishing by Yarn. You could check this out.

[brunopacheco1]

Hey, thanks for the support. I was missing a .npmignore file. When running npm publish, the process was checking out the .gitignore, which was ignoring the transpilation output folder.

[OlegKunitsyn]

It works now. Thank you!

[OlegKunitsyn]

What do you think about line-breaks (2 spaces at the end of line in Markdown)?
Please compare
https://gitlab.com/OlegKunitsyn/core-datetime/-/blob/master/coboldoc/datetime.cbl.md
and
https://gitlab.com/OlegKunitsyn/core-datetime/-/blob/master/src/datetime.cbl

[brunopacheco1]

Yes, I thought about that before, but then there may be a situation where those lines should be merged instead. If you put deliberately a <br>? I believe the tool is not escaping HTML.

[OlegKunitsyn]

True. And br is visible in the docblock in the COBOL file. We need an invisible linebreak...

…

On Mon, 17 Aug 2020, 22:52 Bruno Pacheco, ***@***.***> wrote: Yes, I thought about that before, but then there may be a situation where those lines should be merged instead. If you put deliberately a <br>? I believe the tool is not escaping HTML. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAV4WDFZSWU3X3IBB35B7NDSBGJ7BANCNFSM4PMB3ZFQ> .

[OlegKunitsyn]

Envyr ICOBOL uses * comment at the first column. No free-text, nor auto-documentation tags found.

IDENTIFICATION DIVISION.
PROGRAM-ID.      SAMPLE.
* Sample program
* sample.
*
WORKING-STORAGE SECTION.
* Sample structure
01 VAR-GROUP.
    02 VAR-COUNT PIC 9(4) COMP-5 VALUE 0.  *> sample element

[OlegKunitsyn]

isCOBOL uses Javadoc. Attached example demonstrates a documentation via OOP statement, shared by Veryant.
isCOBOL sample.txt

[OlegKunitsyn]

IBM Z Open Editor inserts this snippet:

      *****************************************************************
      * Program name:    MYPROG                               
      * Original author: MYNAME                                
      *
      * Maintenence Log                                              
      * Date      Author        Maintenance Requirement               
      * --------- ------------  --------------------------------------- 
      * 01/01/08 MYNAME  Created for COBOL class         
      *                                                               
      *****************************************************************
       IDENTIFICATION DIVISION.
       PROGRAM-ID.  MYPROG.
       AUTHOR. MYNAME. 
       INSTALLATION. COBOL DEVELOPMENT CENTER. 
       DATE-WRITTEN. 01/01/08. 
       DATE-COMPILED. 01/01/08. 
       SECURITY. NON-CONFIDENTIAL.
      *****************************************************************

[OlegKunitsyn]

Fujitsu NetCOBOL uses free-text comments:
https://github.com/dauvanthang1993/CoboruDemo/blob/2cf03a0a700022e6ab78bc38a686de527911df6c/Cobol/Sample15/Address.cob

ExlService adopted NetCOBOL to the format based on *@**, *D for the description and *H for the history:
https://github.com/tajinder-mygithub/LifePROCunaShared/blob/ef9cde12cf2429d7be63f8ffec77271ab273ba10/SRC-COB/CBYTECHG.COB

[spgennard]

@brunopacheco1 , @OlegKunitsyn - Question.

When I build and install a "local" version of coboldoc, I get the following.. is there something else I need todo (or install)?

Error: Missing required @injectable annotation in: BaseCommentsParser.
    at getTargets (C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\reflection_utils.js:21:15)
    at Object.getBaseClassDependencyCount (C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\reflection_utils.js:93:23)
    at C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\planner.js:108:67
    at Array.forEach (<anonymous>)
    at _createSubRequests (C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\planner.js:94:20)
    at C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\planner.js:115:17
    at Array.forEach (<anonymous>)
    at C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\planner.js:114:26
    at Array.forEach (<anonymous>)
    at _createSubRequests (C:\OpenSource\coboldoc\node_modules\inversify\lib\planning\planner.js:94:20)
]

[spgennard]

Have you seen https://rosettacode.org/wiki/Documentation#COBOL

[OlegKunitsyn]

robodoc
https://gnucobol.sourceforge.io/faq/index.html#a-robodoc-experiment
ocdoc
https://gnucobol.sourceforge.io/faq/index.html#what-is-ocdoc

[OlegKunitsyn]

MicroFocus
"Insert XML documentation comments - Visual Studio | Microsoft Docs" https://docs.microsoft.com/en-us/visualstudio/ide/reference/generate-xml-documentation-comments?view=vs-2019
https://community.microfocus.com/t5/Visual-COBOL-Tips-Information/Generate-code-documentation-when-building-Visual-COBOL/ta-p/1741229

   *>  for more examples see https://docs.microsoft.com/en-us/dotnet/csharp/codedoc
   *>> <summary>... what ever</summary/>
   *>>
   *>> <example>
   *>>   Insert example on how to use the class here
   *>>  <code>
   *>>    declare a as ilexample
   *>>    display a.MyProperty
   *>>  </code>
   *>> </example>
   class-id ilexample public.

   *>> <value>Get MyProperty</value>
   01 MyProperty       public string.
   *>> <summary>A constructor for this class</summary>
   *>> <remark>This is an example</remark>
   method-id new public.
   procedure division.

       exit method.
   end method.

   *>> <summary>method sample</summary>
   *>> <remarks>
   *>>   <para>Some information</para>
   *>>   <para>... and again </para>
   *>> </remarks>
   *>> <returns>something...</returns>
   *>> <exception cref="member">description</exception>
   *>> <param name="a-name">a name of something</param>
   *>> <see cref="other" />
   *>> <seealso cref="elsewherfe" />
   method-id sample.
   linkage section.
   01 a-name   pic x(10).
   procedure division using by reference a-name.

   end method.

   end class.

[OlegKunitsyn]

RechInformatica rech-editor-cobol, https://github.com/RechInformatica/rech-editor-cobol/blob/master/src/cobol/rechdoc/CobolDocParser.ts

*>->

and then has javadoc style identifiers eg: @param, @return, @throws, @enum.

[OlegKunitsyn]

Auto-doc bitlang.cobol, see spgennard/vscode_cobol#189