Documentation in C#

Introduction

Documentation has been always a neglected task in the software development life cycle. While developing applications, most of the software developing professionals including senior professionals tend to forget about documentation although everyone is aware about the difficulties that are faced during code maintenance application. Documentation is a very important aspect specially when developing large and very big applications involving a number of modules.

When developing an application with C#, we can minimize the effort of making and maintaining the application documentation. As a C# application developer, it is common to give inline comments, these inline comments can be the source to generate a strong and more accurate documentation. Inline comments are the most important part of any code as they provide valuable information about the part of the code that is written. And most importantly it is written when the system is constructed. One of the wonderful features of the C# compiler is that it supports automatic creation of documentation using comments written in the code, the only distinction being that the documentation is produced in XML. Unlike other automated documentation provided by various programming languages, that generates HTML based documentation, C# produces in XML but there are tools available that take XML files as the input and produce HTML based documentation. As the C# stores all the comments in an XML file, users have the flexibility to develop excellent documentation from C#. Code comments, user manuals, developer manuals, test plans, and many other documents can be generated from a single source using XML tags.

The process of generating an XML based documentation is done by adding comments to various parts of the code. The process can be described in the following manner:

Source file  (.cs) -> C# Compiler (csc.exe) -> XML Documentation (doc.xml) 
                -> HTML/ Visual Studio Based Documentation

In-depth of C# Documentation

Before we proceed in depth about the automated documentation part, let's see some of the important aspects that are required to be known when developing the XML based documentation. The main point is that the comments needs to start with "///" as this is the way in which the compiler identifies tags for XML based documentation. "//" way of comments are also supported in C# but in general, the compiler ignores anything that is put after this, but when the compiler encounters another "/" then this indicates that this is an XML comment and needs to be handled properly. Usually the three slashes are followed by the XML tag, this contains the property and value along with it as needed.
For example:

/// <Summary>
/// this is a place where something is done
/// </Summary>

There are various predefined tags that are available for the purpose of generating the document. The developer has the freedom to use any type of XML tags to document the code, only thing is that these tags need to adhere to the XML syntax. The predefined tag indicates the type of documentary information that is being given, and the compiler validates these tags against certain aspects of these and produces the output. Other elements are used for the layout and/or formatting purpose. The C# compiler takes these comments embedded inside the XML tags and builds the XML based documentation. It generates errors when a false reference is encountered.

The following lists describe the main documentation elements provided and are available for usage. The important thing to remember is that each element should be written between its opening and closing tags, Also, some of the tags take some further mandatory attributes. For example, the 'cref' attribute can be used in any element, but it should be used only when it is advisable.

Tag	Description
<summary>	This tag is used to hold the overview information of any documenting element.
<remarks>	This helps to expand the comments that are given in the summary and usually follows it.
<param name="name">	Describes a parameter passed to a method. The compiler checks that the 'name' value matches an actual parameter in the code. Also, if you give documentation for one parameter value, the compiler will expect you to give documentation for them all.
<paramref name="name">	Identifies the mention of a parameter name within some other descriptive element, for instance within 'summary' tags. The idea is that this mentioned name can be styled differently from the surrounding text. The compiler checks that the 'name' value matches an actual parameter in the code.
<param name="name">	Describes a parameter passed to a method. The compiler checks that the 'name' value matches an actual parameter in the code. Also, if you give documentation for one parameter value, the compiler will expect you to give documentation for them all.
<returns>	Describes the return value for a method. As the descriptive field is just free text there is no compiler checking.
<exceptions cref="type">	Describes an exception that may be thrown by a method. The 'cref' attribute refers to a type or field (such as System.Exception), and the compiler checks that this reference is available from the current compilation environment.
<permission cref="type">	Describes a permission requirement for a type or member. The cref attribute refers to a type or field (such as System.Security.PermissionSet), and the compiler checks that this reference is available from the current compilation environment.
<value>	Describes a class property.
<example>	Gives an example of the use of the referenced object (for example a class method). The 'example' element is often used with the following two elements.
<c>	Marks up a single phrase or line as a code example. Generally used in conjunction with the 'example' element.
<code>	Marks up multiple lines as code examples. Generally used in conjunction with the 'example' element.
<see cref ="type">	Used to identify a crossreference in the documentation; designed to be used inline within a description element. The cref attribute refers to a type or field, and the compiler checks that this reference is available from the current compilation environment. and the see also tag is used in a separate section. This allows the documentation to create crossreferences.
<seealso cref ="type">	Used to identify a crossreference in the documentation; different from 'see' in that it is designed to stand alone. The cref attribute refers to a type or field, and the compiler checks that this reference is available from the current compilation environment.

Some of the formatting tags are as follows:

<list type=""table"">
<listheader>
<term>Employee</term>
<description>Employee Type</description>
</listheader>
<item>
<term>XXXX</term>
<description>Administrator</description>
</item>
<item>
<term>YYYY</term>
<description>User</description>
</item>
</list>"

C# Documentation Example

Let's take an example and then try to use the above information to get an automated documentation file.

The above is a typical example of an application during the construction phase and then we struggle at the time of maintenance as to what the function or the class was supposed to do! Let's give some comments and do the needful.

using System; 
using System.Data; 

namespace ExampleDocumentation
{ 
/// <summary>

///  DocumentationClass: Is the class that will be used for explaining the 

///  example of automated documentation

/// </summary> 


    public class DocumentationClass
    { 
    /// <summary>

    /// public DocumentationClass () : 

    ///     Is the constructor used for DocumentationClass class

    /// </summary> 


    public DocumentationClass () 
    { 
    } 

    /// <summary>

    /// public void DocumentationClassMethod: Is a void method 

    /// that does not return anything and takes no parameters.

    /// It does the functionality of some addition and subtraction to 

    /// get the result

    /// </summary> 

    public void DocumentationClassMethod () 
    { 
    } 
   } 
}

As you can see above, now we have added some valuable comments that tend to have lots of value. Now to generate the documentation we can have the following command

<Directory>\Microsoft.NET\Framework\v1.1.4322>

In the above, command /doc instructs the compiler to produce the documentation named doc.xml. And this will produce the following output:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name> DocumentationClass</name>
    </assembly>
    <members>
        <member name="T:ExampleDocumentation.DocumentationClass">
            <summary>
             DocumentationClass: Is the class that will be used 
             for explaining the example of automated documentation
            </summary> 
        </member>
        <member name="M:ExampleDocumentation.DocumentationClass.#ctor">
            <summary>
            public DocumentationClass () : 
            Is the constructor used for DocumentationClass class
            </summary> 
        </member>
        <member name=
    "M:ExampleDocumentation.DocumentationClass.DocumentationClassMethod">
            <summary>
            public void DocumentationClassMethod: 
            Is a void method that does not return anything 
    /// and takes no parameters. 
    ///It does the functionality of some addition and substation to 
            get the result
            </summary> 
        </member>
    </members>
</doc>

Some points

Some of the constants are attached usually with the commented object, these are the ID's that are used to identify the type code and part. Usually these are categorised in the following manner:

• N denotes the Namespace
• T denotes Type, and includes class, Interface, struct, enum or delegates
• F denotes the fields of class
• P denotes the Property indexer or indexed property
• M denotes the Methods special methods constructor and operator(overloaded)
• E denotes Events
• ! denotes an error string that C# was unable to resolve some references

Generation of C# documentation with Visual Studio NET 2000 IDE

The documentation can be generated in the following way from the Visual Studio NET 2000 IDE:

• Open the property page for the project, usually by right-clicking on the project in the Solution Explorer, and click Properties.
• Click the Configuration Properties folder.
• Click the Build option.
• In the right pane, there will be a property field called XML Documentation File. Enter the required information like the path and name of the file.

Generating HTML based Documentation with Visual Studio .NET

The XML based on the C# compiler can be used to generate the HTML based documentation. Visual Studio takes the doc.xml file generated by the C# compiler and produces whole documentation of HTML pages. To do this we need to follow the same process and then go to the Tools menu in Visual Studio .NET and select Build Comment Web Pages, there will be a dialog box that will appear. In this, select the projects to create the documentation. There is also the possibility to choose the specific part of the solution to generate the documentation.

Problems with the C# Documenter

The automated documentation in C# has some flaws; following are some of them that need to be taken into consideration:

1. If in any case if you have forgotten to mention any comments for any method, it will just be ignored
2. Even if the comments are written and you have written "//" instead of "///" then again the documentation will not have any reference of these comments
3. While generating C# documentation whenever there is any kind of return type explicitly this has to be specified