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 the 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 the ASP Documentation Tool, can create comprehensive technical documentation from any 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.

Thankfully, with the introduction of the .NET Framework, Microsoft included some form of code documentation standards. Sadly, with the 1.0 and 1.1 releases of the .NET Framework, the standards were only supported in the new C# programming language. Not including the standards officially in Visual Basic's replacement, VB.NET was a curious omission. Thankfully though, the 2.0 release of the .NET Framework includes the documentation standards that C# .NET developers had been enjoying for several years.

C# has supported the XML comments system since version 1.0 of the .NET Framework.

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.

Figure 1

/// <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>&lt;</description></item>
/// <item><term>^g</term><description>&gt;</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 the entire XML comment standard markup supported by the .NET Framework. It is also possible to use your own XML tags within the comments.

If that all looks like hard work, then it is possible to use an application, such as the GhostDoc add-in for Visual Studio, that makes an attempt at writing your XML comments for you!

The following XML comment tags are officially supported in the .NET Framework: c,code, example, exception, include, list, para, param, paramref, permission, remarks, returns, see, seealso, summary and typeparam. Note that typeparam is supported from version 2.0 of the .NET Framework; all of the other tags are supported from .NET 1.0. In version 2.0 of the .NET Framework, both C# and VB.NET support the same XML comment tags.

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>Dim MyObject As MyType</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 and ensure the 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>

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 or do not want to figure out the complex XSL syntax, there are a few other products of interest. The open source NDOC was a popular open source utility for generating documentation from XML commented source code. It extended the usage of XML comments through the introduction of a few additional tags, such as a tag for adding hyperlinks to the comments. Unfortunately, the main developer left the project and the source code has not been updated for several years. It also has no support for version 2.0 of the .NET Framework.

Alternatively, a product I have been working on since 2002, the .NET Documentation Tool creates documentation from .NET source code. It supports XML comments in either C# or VB.NET source code. Most types of .NET project are supported and it has been updated for version 2.0 of the .NET Framework. For ease of reference it also includes the application's source code within the documentation.

Hopefully, this article will encourage you to add XML comments to your .NET source code. Whether you are working for a company or for yourself, properly commented code always looks professional and can help give you the competitive edge over your competitors.