Documenting C# source code with XML Comments

What are code documentation standards?

Many programming languages have well defined standards for documenting source code. These standards are useful in that they allow developers to add comments to code in a uniform format. Furthermore, it is possible to use tools to extract the documentation from an entire application's source code and use it to automatically produce project technical documentation in a fraction of the time it would take to manually produce the documentation.

Programming languages such as Java have had code documentation standards for many years. The Java system is called JavaDoc, and allows developers to easily create HTML format documentation from project source code.

Since classic Active Server Pages (ASP) has no defined standards of source code documentation, ASP web application documentation of source code can vary enormously from project to project. While applications such as our ASP Documentation Tool can create technical documentation from ASP source code, lack of a defined documentation standard is a major limitation of ASP. Visual Basic 6.0 is similarly affected by a lack of documentation standards (although our VB Documentation Tool resolves this).

Thankfully with the introduction of the .NET Framework and the new C# programming language, Microsoft included some form of code documentation standards - XML Comments. These were further enhanced with the 2.0 release of the .NET Framework (which also allowed XML comments to be used with VB.NET.

Commenting C# source code

XML comments are added to source code by prefixing the XML comment lines with three forward slashes. Visual Studio will automatically insert a documentation template whenever three forward slashes are typed within a C# source code file. Visual Studio's intellisense system also works within XML comments, using the comments to enhance the information presented about a class, constructor or other member.

Although these comments can potentially be added to the source code at any point, it is usual to ensure that documentation is inserted immediately before the definition of classes, functions, subroutines and properties, thereby allowing these members to be documented. An example of a function documented with XML comments is shown below:

/// <summary>  
///<para>Non-HTML files like Adobe Acrobat PDF files and Word  
///documents are stored with their original URLs partially  
///encoded in their filenames. This function will return the  
///original URL of the file.</para>  
///<para>The encoding done by the Index Server Companion removes  
///characters that cannot be present in Windows filenames  
///(these are: \/:*?"<>|). The decoding performed is:</para>  
/// <list type="table">  
/// <listheader><term>Find</term><description>Replace</description></listheader>  
/// <item><term>^f</term><description>\</description></item>  
/// <item><term>^b</term><description>/</description></item>  
/// <item><term>^c</term><description>:</description></item>  
/// <item><term>^s</term><description>*</description></item>  
/// <item><term>^q</term><description>?</description></item>  
/// <item><term>^d</term><description>\</description></item>  
/// <item><term>^l</term><description><</description></item>  
/// <item><term>^g</term><description>></description></item>  
/// <item><term>^p</term><description>|</description></item>  
/// </list>  
/// </summary>  
/// <param name="FileName">The document's original filename.</param>  
/// <returns>Decoded filename</returns>  
/// <exception cref="System.Exception">Throws an exception when something goes wrong.</exception>  
private string CreateURLFromFileName(string FileName)  
{

    try  
    {
        //Remove o_ prefix from URL  
        FileName = FileName.Substring(2, FileName.Length - 2);

        //Remove other encoded characters  
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^b", "/");
        FileName = FileName.Replace("^c", ":");
        FileName = FileName.Replace("^s", "*");
        FileName = FileName.Replace("^q", "?");
        FileName = FileName.Replace("^d", "\"");
        FileName = FileName.Replace("^l", "<");
        FileName = FileName.Replace("^g", ">");
        FileName = FileName.Replace("^p", "|");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
    }  
    catch  
    {

    }

    return FileName;

}

This example shows that as well as a general description of the function's purpose, the function's arguments and return values can also be documented using standard syntax. There are also clearly defined standards for cross-referencing the documentation, adding hyperlinks, lists, tables and code samples. The MSDN documentation for the .NET Framework describes all of the XML comment standard markup supported by the .NET Framework. It is also possible to use your own XML tags within the comments.

The "official" XML comment tags

The following XML comment tags are officially supported in C#: c,code, example, exception, include, list, para, param, paramref, permission, remarks, returns, see, seealso, summary and typeparam.

c: This tag is used to denote code, so it can be used to identify sample code associated with a particular entity within the source code. Note that the tag can only be used to represent a single line of code or to denote that some of the text on a line should be marked up as code. Example: <c>double SalesTotal = 12</c>

code: This tag is used to denote more than one line of code, so it can be used to identify longer areas of sample code.

example: This tag may be used to describe an example of using a particular method or class. It is possible to include code samples within the example tag by making use of either the c or code tags.

exception: The exception tag allows a method's exception handling to be documented. The cref attribute allows the namespace of the exception handler to be included. Example: <exception cref="System.Exception" >Throws an exception if the customer is not found.</exception>

include: This tag allows documentation to be imported from an external XML file rather than being stored within the source code itself. As such it may be useful if the documentation is written by people other than the software developers (e.g. technical writers).

list: This tag allows bulleted or numbered lists or tables to be added to XML comments.

para: This tag indicates that the text within the tags should be formatted within a paragraph. As such it can be used to format text within other tags such as summary or returns. Example: <para>This is a paragraph</para>

param: The param tag is used to document a method's arguments. The tag's name attribute specifies the name of the argument to which the tag refers. The tag is also used by Visual Studio's Intellisense system to show a description of a method's arguments. It is also used by the Visual Studio Object Browser. Example: <param name="FileName" >The filename of the file to be loaded.</param>

paramref: This tag can be used to refer to a method's argument elsewhere within the method's XML comments. The tag's name attribute specifies the name of the argument to which the tag refers. Note that the param tag is actually used to describe the parameter. Example: Use the <paramref name="FileName"/> argument to specify which filename is loaded.

permission: The permission tag can be used to describe any special permissions a specific object needs. The object to which the permission refers is included as the cref attribute. Example: Class needs to write to the file system, ensure user has appropriate access.

summary: The summary tag describes a method or class, so it is the most important tag. As well as being used in a project's documentation, the tag is also used by Visual Studio's Intellisense system to show a description of the method or class being referenced. It is also used by the Visual Studio Object Browser.

remarks: The remarks tag can be used to supply additional information about a method or class, supplementing the details given in the summary tag. As with the summary tag, this tag is also used by Visual Studio's Intellisense system and the Visual Studio Object Browser.

returns: Describes the return value of a method. Example: <returns>True if user has permission to access the resource, otherwise False.</returns>

see: The see tag is used to reference other entities (such as classes) in the project. The see tag is intended for use within other tags such as the summary tag. Example: <seealso cref="System.Configuration"/>

seealso: The seealso tag resembles the see tag and has identical syntax, except that the text is intended to be used to create a separate seealso section for the entity's documentation.

typeparam: Typeparam is used in an identical way to param, except that it is used to document a type associated with a generic class or function.

value: Value is only used when documenting a property, and is used to describe the value assigned to that. The comment is not required for properties that are marked as read only. Example: <value>Sets the employee's salary</value>

What to do with the documented code

Once the XML comments have been added to the code, it is useful to be able to do something with them. Although code documented in a standard format is an obvious benefit, XML comments allow much more to be done with the source code.

Visual Studio allows the comments to be compiled to an XML file. Although this is a useful feature, the XML file should be considered an intermediate documentation format rather than finished project documentation. Simple documentation can be created by applying an XSL stylesheet to the XML file in order to produce a more easily readable HTML version of the documentation. Here is a simple example of how to implement a suitable XSL stylesheet: Simple XSLT stylesheet for Visual Studio .NET XML documentation.

If you want more comprehensive documentation, our .NET Documentation Tool product creates documentation from C# source code (VB.NET is also supported).

Summary & Conclusions

Hopefully this article will encourage you to add XML comments to your C# source code. Whether you are working for a company or for yourself, well commented code always looks professional, and can help give you the competitive edge over other developers and businesses.