How to write comment in TypeCobol ?

[smedilol]

Report of Meeting of 2018/04/05

History of Cobol comment in our company

An custom Cobol comment has been developed.
The purpose was to document the

• function name
• description
• parameters (with info if input or output)

This doc is then exported to a documentation repository.
This doc was also used to produce a Control-flow analysis graph.

This documentation use XML syntax:
*<tag> value
*</tag>
If the end tag is not useful, then the following syntax can be used:
*[tag] value

Example

*[Dsc] My description`
 FOO-PARAGRAPH.
   move a to b
*<DBG> This code is used for debugging
   if xxx
   end-if
*</DBG>

Available tags

Tags use 3 letters of a french word:

• DSC Description
  • target in TypeCobol : We use a special comment marker to track description part
• BLC Block
  • target: use #region like C#
• DBG Debug : to indicate debug code
  • target : use #IF DEBUG and #END-IF like C#
• AST Assert
  • target : use an assert API or a keyword
• TRC Tracing: to indicate tracing code
  • target : use a log API or a keyword
• ERR Error : this code is relative to error management
  • this was useful to remove all code related to error in control-flow analysis graph
  • target : our error management framework will allow us to identify this kind of code easily. No need to keep it
• PRV Provisional: Provisional code that can be pushed to production
  • target : use #region like C#
• TMP Temporary : very temporary code. Cannot be pushed to production
  • target : use #region like C#
• DPC Deprecated
  • target : better use @annotation or [Attribute] system.
• COM Comment: Block of commented code
  • was useful with PDS/Librarian when you want to release your code but omit certain part
  • target : not useful with tools like RTC or Git
• CST Constant
  • target : use a constant keyword (like Cobol 2002)
• PRS Persistence : alter the persistence of data
  • target : use a keyword
• LNG Lenght : length that the data must respect. This is useful for redefines
  • With our parser we can deduce the length and control the length directly on the fly
  • But this can be useful to set the total length of a type or a copy
  • target : better use @annotation or [Attribute] system but keep as comment in generated code
• LGV Variable-length: variable length data (example pic X(50))
  • target : Not useful if we create a string type
• ENT Input : input parameter
  • target : use keyword input
• SOR output : output parameter
  • target : use keyword output
• PRM Parameter : input and output
  • target : use keyword in-out
• MSQ Mask : data in linkage but not in procedure division.
  • target : all data in linkage should be mask.
  • better use @annotation or [Attribute] system but keep as comment in generated code
• IDC Index : to declare data used as an index. Control that the data is only used as an index
  • in some cases, indexed by can not be used (when the same index must be used for 2 tables)
  • target : enhance Cobol syntax to bypass limitation of indexed by
• ADR Address : data only manipulated as a pointer but declared as pic X
  • target : same logic as MSQ but a keyword like buffer could be useful
  • also useful to display the beginning of a buffer
• PRV Private : To indicate that a Copy can only be used by specified programs
  • target : not useful with RTC or intermediate keyword like protected, internal
• HSV HostVariable: To indicate that a data is a Host variable for DB2
  • this kind of data must be declared in working-storage
  • target : not useful anymore with our last Cobol compiler

So we'll only keep [LNG] in generated code

Questions

• Do TypeCobol doc need to be used to produce a control-flow analysis?
  • No, because today, IDZ can produce this kind of analysis for Cobol.
  • IDZ is not able to remove common paragraph, like error paragraphs but this can be an improvement when our control-flow analyzer is avaiable
• Do we need to be compatible with this syntax?
  • No?

Proposals for documentation

Here we want to define a special comment syntax to identify comment that need to be extracted.

Multi-line syntax

1. • XML Syntax

*<DSC>
*
*</DSC>

2. *<< and *>> (our choice)

*<< 
    Comment line 1
	Comment line 2
*>>
declare procedure foo public.

There is no * on column 7.
The IDE can add * on column 7 to ensure compatibility with IDZ.
This is optional.

Our choice

We will use the second syntax because it's more like Cobol.

Single line comment

1. Use normal Cobol comment

* Date in gregorian format (YYYYMMDD)
 01 Date typedef strict public.

But if you don't comment the type, the previous comment will be used.

2. Use multi-line comment

*<< Date in gregorian format (YYYYMMDD)
*>>
 01 Date typedef strict public.

3. Use multi-line comment and close it on the same line (our choice)

*<< Date in gregorian format (YYYYMMDD)   *>>
 01 Date typedef strict public.

4. *>> with something on the line

*>> Date in gregorian format (YYYYMMDD)
 01 Date typedef strict public.

But *>> is used to close a multi-line comment.
Using the same keyword *>> to start and end a comment can be problematic.

5. Use *<<<

*<<<Date in gregorian format (YYYYMMDD)
 01 Date typedef strict public.

6. *<< with something on the line

*<< Date in gregorian format (YYYYMMDD)
 01 Date typedef strict public.

And change the syntax of Multi-line comment.
A multi-line comment must start with *<< and blank on the rest on the line.
Can be confusing for developers.

7. Slash

*//Date in gregorian format (YYYYMMDD)
 01 Date typedef strict public.

We retain this syntax

Multi-line

*<< 
    Comment line 1
	Comment line 2
*>>
declare procedure foo public.

There is no * on column 7.
The IDE can add * on column 7 to ensure compatibility with IDZ.
This is optional.

Single line

Use multi-line comment and close it on the same line

*<< Date in gregorian format (YYYYMMDD)   *>>
 01 Date typedef strict public.

Procedure comment

Do we need a special comment for procedure/function parameters?

Comment parameter directly after them

*<<
 Description of foo.
*>>
 declare procedure foo public
    input param1 type Date    *> BirthDate
	                          *> uhfujghf hjfdhf 
	      param2 type Person. *> Beneficiary

3 - Comment above parameters

*<<
 Description of foo.
*>>
 declare procedure foo public
*         BirthDate uhfujghf hjfdhf 
    input param1 type Date
*         Beneficiary
          param2 type Person.

4 - Swift / NaturalDocs (our choice)

This use a markdown syntax

*<< Description of foo.

  - parameters:
     - param1 : BirthDate uhfujghf hjfdhf 
     - param2 : Beneficiary
*>>
declare procedure foo public
    input param1 type Date
          param2 type Person

5 - Javadoc

*<< Description of foo.

  @param param1 : BirthDate uhfujghf hjfdhf 
  @param param2 : Beneficiary
*>>
declare procedure foo public
    input param1 type Date
          param2 type Person

Our choice

Use Swift like comment with markdown support.
TODO details all special keyword to support
This will be more or less the same as swift. Expect for throw that will be replacec with something like error

Compilation directive

We want to support compilation directive like this:

	#IF DEBUG
        *code only compiled when debug mode is activated*
	#END-IF

Syntax to use:

• #IF
• #END-IF

We will make another meeting to details how compilation directive works

Region proposal

How to handle #region like C#?
We want to delimit block of code and associate a comment.

Proposals of syntax

• Our new comment system above the region

   *<< comment
   *>>
   #Temp
      temporary code
   #end-Temp

• Our new comment system inside the region

   #Temp
   *<< comment
   *>>
      temporary code
   #end-Temp

• Comment on the same line of the region. But this is not compatible with multiline.

   #Temp comment
      temporary code
   #end-Temp

Generated code

The generated code will simply comment the #region

*  #Temp commentaire
      code temporaire
*  #end-Temp

Special regions

2 specials regions must be created for our purpose:

• Temp for Temporary
  • A release must ensure that there is no temporary code.
• Provisional
  • Can be integrated into a release

[smedilol]

As first version of TC-Comment is now include in future version v1.3, I close this debate.
Further proposals for TC-Comment can be done in new issues.

[smedilol]

See #1329 for an update in syntax.