Document Your Types, Members, and Namespaces with Comments in the Code

You can use XML documentation comments, a feature of Visual Studio, in your .NET COBOL code. The XML comments enable you to include definitions of your namespaces, types, and members in the code. The definitions are used as follows:

When IntelliSense shows the namespaces, types, and members you can use, the definitions are provided in tool-tips.
If you compile with the ILDOC Compiler directive, the build produces an XML file with the definitions inserted in the code. You can then convert this XML file into a documentation file (CHM, Visual Studio Help, or other) with a suitable tool such as Sandcastle Help File Builder.

In order to generate an XML file with documentation comments for your code:

Insert documentation comments in your .NET COBOL code as specified below.
Enable the XML documentation file property for your .NET COBOL project. This is equivalent to setting the ILDOC Compiler directive.
Build your application.

Start each line of the XML documentation comments with *>>. The comments need to have an XML formatted body - the minimum requirement is to use the <summary> tag on the first line, and a closing </summary> tag on the last line. For more supported tags, check the information on XML documentation comments available on the MSDN.

Documentation comments must be added immediately before the declaration of the namespace, type, or member, for which they provide a definition:

      *>> <summary>
      *>> A namespace, class, or a method decscription
      *>> </summary>
       class-id ClassName public inherits type MyNamespace.MyType...

Examples

If you want to document a specific namespace, you need to specify it directly in your code, with $set, and not from the project's properties XML documentation file property. For example:

      *>> <summary>
      *>> This namespace includes all the types dealing with MFUNIT
      *>> </summary>
        $set ilnamespace"MicroFocus.COBOL.MFUNIT.Framework"

The following example shows the documentation comments for a class, and its two methods:

      *>> <summary>
      *>> SuccessException - Exception thrown if the test case ends with a sucess condition
      *>> </summary>
       class-id SuccessException  public inherits type Exception
           attribute Serializable
           .

           *>> <summary>
           *>> SuccessException - constructor with no assert message
           *>> </summary>
           method-id New.
           procedure division.
               invoke super::New("")
           end method.

           *>> <summary>
           *>> SuccessException - constructor with assert message
           *>> </summary>
           *>> <param name="msg">message</param>
           method-id New.
           procedure division using by value msg as string.
               invoke super::New(msg)
           end method.
       end class.