Issue #1023: DocGen step

CLI/test/CLITest.cs

@@ -131,7 +131,18 @@ public void TestReturnCode() {
         [TestMethod]
         public void TestOutputFormat()
         {
-            CLITestHelper.Test("outputSignature_1", ReturnCode.Success);
+            CLITestHelper.Test("outputSignature_1", ReturnCode.Warning);
+        }
+
+
+        /// <summary>
+        /// Try parsing with Documentation Generation as output format.
+        /// Should return success.
+        /// </summary>
+        [TestMethod]
+        public void TestDocGen()
+        {
+            CLITestHelper.Test("documentation", ReturnCode.Warning);
         }
 
         /// <summary>

CLI/test/ressources/documentation/CLIArguments.txt

@@ -0,0 +1 @@
+-1 -i input\DocGen.tcbl -o output\DocGen.json -d output\error.txt -e rdz -f Documentation -s ..\skeletons.xml

CLI/test/ressources/documentation/input/DocGen.tcbl

@@ -0,0 +1,68 @@
+       IDENTIFICATION DIVISION.
+       PROGRAM-ID. DocGen.
+
+       DATA DIVISION.
+       LOCAL-STORAGE SECTION.
+
+      *<<< 
+          @ description : inline typedef
+          @ params:
+            - none: Type doesn't have any params
+          @deprec
+          @Restriction : Do not Use BOOL var 
+          @Params:
+            - Typedefs: should not have any params
+      *>>>
+       01 myType TYPEDEF STRICT PUBLIC pic X(01).
+
+      *<<< Vect2D
+      *>>>
+       01 Vect2D TYPEDEF STRICT PUBLIC.
+         02 Coord2d.
+           03 X PIC 9(4).
+           03 Y PIC 9(4).
+
+
+      *<<< This type is private
+      *>>>
+       01 PrivateType TYPEDEF STRICT pic XXX.
+
+
+      *<<< My program 
+          @ Description  description
+          @deprecated
+          @    replacedBy  MyFonction2
+          @ rEsTrIcTiOn Do not Use BOOL var
+          @ need  some needs
+              - description
+          @ see  Thank you for your attention
+          @ todo 
+              - Add BOOL support 
+              - implement a call counter
+      *>>>
+       PROCEDURE DIVISION.
+
+      *<<< MyProc info
+          @ deprec : It is
+       deprecated
+               @           need : long need
+          @ todo:
+              - todo1
+              - todo 2
+        @ params:
+          - myDate: just a date
+          - bla: bla < 2
+          - toto: toto 
+          -blu: will be ignored
+      *>>>
+       DECLARE PROCEDURE MyProc PUBLIC
+           INPUT    myDate      TYPE Date
+                    bla         Pic S9(1)V9(12)
+           IN-OUT   myBool      TYPE BOOL
+           OUTPUT   toto        TYPE BOOL
+                    bli         Pic PPP999PPP.
+           PROCEDURE DIVISION.
+           CONTINUE.
+       END-DECLARE.
+
+       END PROGRAM DocGen.

CLI/test/ressources/documentation/output_expected/DocGen.json

@@ -0,0 +1,2 @@
+      *TypeCobol_Version:0.1(alpha)
+{"__type":"DocumentationForProgram:#TypeCobol.Compiler.Nodes","Deprecated":"","Description":"My program description ","Name":"DocGen","Namespace":"DocGen","Needs":["some needs","description"],"ReplacedBy":"MyFonction2 ","Restriction":"Do not Use BOOL var ","See":"Thank you for your attention ","ToDos":["Add BOOL support","implement a call counter"]}{"__type":"DocumentationForType:#TypeCobol.Compiler.Nodes","Deprecated":"","Description":"inline typedef ","Name":"myType","Namespace":"DocGen","Restriction":"Do not Use BOOL var ","Visibility":0,"DocDataType":{"MaxOccurence":1,"Picture":"X(01)"}}{"__type":"DocumentationForType:#TypeCobol.Compiler.Nodes","Description":"Vect2D ","Name":"Vect2D","Namespace":"DocGen","Visibility":0,"Childrens":[{"Childrens":[{"DocDataType":{"MaxOccurence":1,"Picture":"9(4)"},"Name":"X"},{"DocDataType":{"MaxOccurence":1,"Picture":"9(4)"},"Name":"Y"}],"DocDataType":{"MaxOccurence":1},"Name":"Coord2d"}],"DocDataType":{"MaxOccurence":1}}{"__type":"DocumentationForFunction:#TypeCobol.Compiler.Nodes","Deprecated":"It is deprecated ","Description":"MyProc info ","Name":"MyProc","Namespace":"DocGen","Needs":["long need"],"ToDos":["todo1","todo 2"],"Visibility":0,"Parameters":[{"DocDataType":{"MaxOccurence":1,"TypeName":"DATE"},"Info":"just a date","Name":"myDate","PassingType":0},{"DocDataType":{"MaxOccurence":1,"Picture":"S9(1)V9(12)"},"Info":"bla < 2","Name":"bla","PassingType":0},{"DocDataType":{"MaxOccurence":1,"TypeName":"BOOL"},"Name":"myBool","PassingType":2},{"DocDataType":{"MaxOccurence":1,"TypeName":"BOOL"},"Info":"toto","Name":"toto","PassingType":1},{"DocDataType":{"MaxOccurence":1,"Picture":"PPP999PPP"},"Name":"bli","PassingType":1}]}

CLI/test/ressources/documentation/output_expected/error.txt

@@ -0,0 +1,8 @@
+ReturnCode=Warning_
+6 errors in "input\DocGen.tcbl":
+Line 9[13,18] <37, Warning, General> - Warning: Type Definition does not support Parameters field
+Line 9[13,18] <37, Warning, General> - Warning: Formalized comment field is declared more than once : params
+Line 13[12,17] <37, Warning, General> - Warning: Formalized comment field is declared more than once : Params
+Line 56[12,14] <37, Warning, General> - Warning: Parameter name does not match to any function parameter: blu
+Line 61[21,26] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: myBool
+Line 63[21,23] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: bli

CLI/test/ressources/outputSignature_1/input/Callee.rdz.tcbl

@@ -1,4 +1,8 @@
        IDENTIFICATION DIVISION.
+      *<<
+        Multiline comment
+        should be commented
+      *>>
        PROGRAM-ID. Callee.
 
        DATA DIVISION.
@@ -8,10 +12,16 @@
           05 Var1 pic X.
 
        01 TOto pic X.
-
+
+      *<<<
+        My public Type 2
+      *>>>
        01  MyType2 TYPEDEF STRICT PUBLIC.
           05 Var2 pic X.
 
+      *<<<
+        My private Type 3
+      *>>>
        01  MyType3 TYPEDEF STRICT.
           05 Var3 pic X.
 
@@ -26,6 +36,19 @@
        01 MyType3 type MyType3.
        01 Mydate  type Date.
 
+      *<<< My program 
+          @ Description  description
+          @deprecated
+          @    replacedBy  MyFonction2
+          @ need  some needs
+          @ todo 
+              - make my second type my first type
+              - get another type
+          @Params:
+            - MyType2: my second type
+            - MyType3: my third type
+            - Mydate: today date
+      *>>>
        PROCEDURE DIVISION.
 
        declare procedure check public
@@ -35,12 +58,22 @@
            CONTINUE.
        END-DECLARE.
 
+      *<<<
+        check if the given date is before today
+        @params:
+          - mydate: tyhe date to test
+      *>>>
        declare procedure check2 public
           input mydate        TYPE Date
          .
          PROCEDURE DIVISION.
            CONTINUE.
        END-DECLARE.
+
+      *<<<
+        Same as check2 but with two dates
+        @see: check2
+      *>>>
        declare procedure check2 public
           input mydate        TYPE Date
                 myDate2       type date
@@ -49,8 +82,27 @@
            CONTINUE.
        END-DECLARE.
 
+      *<<<
+        Private procedure should not have
+        its signature generated 
+      *>>>
+       declare procedure check3 private
+          input mydate        TYPE Date
+                myDate2       type date
+         .
+         PROCEDURE DIVISION.
+           CONTINUE.
+       END-DECLARE.
+
+      *<<
+        Multiline Comment here should be ignored
+      *>>
        DECLARE PROCEDURE MyPublicProcedure PUBLIC
            INPUT mydate        TYPE Date
+      *<<
+              Multiline comment
+              should be commented
+      *>>
                  format        PIC X(08)
           OUTPUT okay          TYPE Bool
                  actual-format PIC X(08).

CLI/test/ressources/outputSignature_1/output_expected/ProcedureCall-Public-Signatures.rdz.tcbl

@@ -1,30 +1,63 @@
       *TypeCobol_Version:0.1(alpha)
        IDENTIFICATION DIVISION.
+      *<<
+      * Multiline comment
+      * should be commented
+      *>>
        PROGRAM-ID. Callee.
        DATA DIVISION.
        working-storage section.                                               
        01  MyType1 TYPEDEF STRICT PUBLIC.
           05 Var1 pic X.
+      *<<<
+      * My public Type 2
+      *>>>
        01  MyType2 TYPEDEF STRICT PUBLIC.
           05 Var2 pic X.
        01  MyType5 TYPEDEF STRICT PUBLIC.
           05 Var5 pic X.
+      *<<< My program 
+      *   @ Description  description
+      *   @deprecated
+      *   @    replacedBy  MyFonction2
+      *   @ need  some needs
+      *   @ todo 
+      *       - make my second type my first type
+      *       - get another type
+      *   @Params:
+      *     - MyType2: my second type
+      *     - MyType3: my third type
+      *     - Mydate: today date
+      *>>>
        PROCEDURE DIVISION.
        declare procedure check public
           input mydate        TYPE Date
          .
        END-DECLARE.
+      *<<<
+      * check if the given date is before today
+      * @params:
+      *   - mydate: tyhe date to test
+      *>>>
        declare procedure check2 public
           input mydate        TYPE Date
          .
        END-DECLARE.
+      *<<<
+      * Same as check2 but with two dates
+      * @see: check2
+      *>>>
        declare procedure check2 public
           input mydate        TYPE Date
                 myDate2       type date
          .
        END-DECLARE.
        DECLARE PROCEDURE MyPublicProcedure PUBLIC
            INPUT mydate        TYPE Date
+      *<<
+      *       Multiline comment
+      *       should be commented
+      *>>
                  format        PIC X(08)
           OUTPUT okay          TYPE Bool
                  actual-format PIC X(08).

CLI/test/ressources/outputSignature_1/output_expected/error.txt

@@ -1,2 +1,6 @@
-ReturnCode=Success_
-No error in "input\Callee.rdz.tcbl".
+ReturnCode=Warning_
+4 errors in "input\Callee.rdz.tcbl":
+Line 78[17,22] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: mydate
+Line 79[17,23] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: myDate2
+Line 90[17,22] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: mydate
+Line 91[17,23] <37, Warning, General> - Warning: Parameter does not have any description inside the formalized comments: myDate2

Codegen/src/GeneratorFactoryManager.cs

@@ -29,10 +29,11 @@ private static GeneratorFactoryManager Singleton
         static GeneratorFactoryManager()
         {
             Singleton = new GeneratorFactoryManager();
-            Instance.RegisterFactory(OutputFormat.Cobol85.ToString(), (id, document, destination, skeletons, typeCobolVersion) => new DefaultGenerator(document, destination, skeletons, typeCobolVersion));
+            Instance.RegisterFactory(OutputFormat.Cobol85.ToString(),          (id, document, destination, skeletons, typeCobolVersion) => new DefaultGenerator(document, destination, skeletons, typeCobolVersion));
             Instance.RegisterFactory(OutputFormat.PublicSignatures.ToString(), (id, document, destination, skeletons, typeCobolVersion) => new SignaturesGenerator(destination, typeCobolVersion));
-            Instance.RegisterFactory(OutputFormat.ExpandingCopy.ToString(), (id, document, destination, skeletons, typeCobolVersion) => new ExpandingCopyGenerator(document, destination));
-            Instance.RegisterFactory(OutputFormat.Cobol85Mixed.ToString(), (id, document, destination, skeletons, typeCobolVersion) => new MixedTransformGenerator(document, destination, skeletons, new DefaultGenerator(document, destination, skeletons, typeCobolVersion)));
+            Instance.RegisterFactory(OutputFormat.ExpandingCopy.ToString(),    (id, document, destination, skeletons, typeCobolVersion) => new ExpandingCopyGenerator(document, destination));
+            Instance.RegisterFactory(OutputFormat.Cobol85Mixed.ToString(),     (id, document, destination, skeletons, typeCobolVersion) => new MixedTransformGenerator(document, destination, skeletons, new DefaultGenerator(document, destination, skeletons, typeCobolVersion)));
+            Instance.RegisterFactory(OutputFormat.Documentation.ToString(),    (id, document, destination, skeletons, typeCobolVersion) => new DocumentationGenerator(destination, typeCobolVersion));
         }
 
         /// <summary>

TypeCobol/Tools/Options-Config/TypeCobolConfiguration.cs

@@ -142,7 +142,8 @@ public enum OutputFormat {
         Cobol85,
         PublicSignatures,
         ExpandingCopy,
-        Cobol85Mixed
+        Cobol85Mixed,
+        Documentation
     }
     public static class TypeCobolOptionSet
     {
@@ -163,7 +164,7 @@ public static OptionSet GetCommonTypeCobolOptions(TypeCobolConfiguration typeCob
                 { "dp|dependencies=", "Path to folder containing programs to load and to use for parsing a generating the input program.", v => typeCobolConfig.Dependencies.Add(v) },
                 { "t|telemetry", "If set to true telemetry will send automatic email in case of bug and it will provide to TypeCobol Team data on your usage.", v => typeCobolConfig.Telemetry = true },
                 { "md|maximumdiagnostics=", "Wait for an int value that will represent the maximum number of diagnostics that TypeCobol have to return.", v =>  typeCobolConfig.RawMaximumDiagnostics = v},
-                { "f|outputFormat=", "Output format (default is Cobol 85). (Cobol85/0, PublicSignature/1, Cobol85Mixed/3)", v =>typeCobolConfig.RawOutputFormat = v},
+                { "f|outputFormat=", "Output format (default is Cobol 85). (Cobol85/0, PublicSignature/1, Cobol85Mixed/3, Documentation/4)", v =>typeCobolConfig.RawOutputFormat = v},
                 { "ec|expandingcopy=", "Generate a file with all COPY directives expanded in the source code. This option will be executed if the Preprocessor step is enabled.", v => typeCobolConfig.ExpandingCopyFilePath = v },
                 { "exc|extractusedcopy=", "Generate a file with all COPIES detected by the parser", v => typeCobolConfig.ExtractedCopiesFilePath = v },
                 { "antlrp|antlrprogparse", "Use ANTLR to parse a program", v => typeCobolConfig.UseAntlrProgramParsing = true},