Created On:  10 December 2010

Problem:

What do you do when you need to create documentation for the user-defined classes and methods declared in your .NET COBOL applications?

Resolution:

It is a good practice to provide descriptions of the classes and methods declared in your managed COBOL applications files by adding XML documentation comments in the source files. For example, the descriptions are used by the Visual Studio IntelliSense Quick Info feature that shows tool-tips about the classes and methods you can use.

You can configure your project to generate an XML file with the comments at build time. From this file you can create documentation in CHM, Help 2 or MS Help Viewer format using a third party utility such as Sandcastle.

To add XML documentation comments do the following:

1. Open your solution in Visual Studio.

2. Open a source file which is part of a managed COBOL project.

3. Position the cursor on a line preceding a method or a class declaration.

4. Type *>> starting in column seven. This automatically inserts the construct of the documentation comment with XML tags for a summary and for descriptions of the parameters that the class or the method uses.

Note: For variable and fixed source code formats you need to start the documentation comment in column seven. For free source code format you can start typing the documentation comment anywhere on a line preceding the class or method declaration.

5. Inside the tag type a meaningful description of what the class or the method does.

6. Type descriptions inside any other tags that might be added. For example:

      
*>>
       *>> Returns the computed stock value of the book.
       *>>
       *>> The computed stock value of the book
       method-id get property StockValue.
       procedure division returning stockvalue as float-short.
           compute stockvalue = book-retail * book-onhand
 
       end method.

7. Display the project properties and select the COBOL tab.

8. Check XML documentation file in the Output section.

Note: Ensure the XML documentation file is generated in the same folder as the project output files (.dll or .exe).

9. Save your changes.

10. Repeat for all the other managed projects that are part of your solution.

11. Build the solution.

Create a documentation file for the classes and methods in your managed COBOL project as follows:

1. Install Sandcastle and Sandcastle Help File Builder.

2. Create a new project in Sandcastle Help File Builder. Tip: Add the XML documentation file and the build output build file (.DLL or .EXE) of your project as documentation sources to the project.

3. Check the Sandcastle Help File Builder documentation for instructions on how to create a documentation file.

Please be sure to see the Related Links at the bottom of this article for Sandcastle.