BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Documentation
.NET 1.1+

XML Documentation Comments

Documentation is important to ensure that developers can quickly learn and use code libraries. With XML documentation comments, the documentation can be embedded within source code using special mark-up that is recognised by Visual Studio's Intellisense.

Documenting Libraries

If you are developing code libraries that will be reused, particularly if they will be referenced by other developers, it is a good idea to document those libraries. As a minimum, it is good practice to document the public classes and structures and their members to describe their basic operation, inputs and outputs. Some developers like to provide further documentation, such as example code, details of the exceptions that methods can throw and further notes that describe these items in greater detail.

Documentation is ideally created during the development process, when the usage of a library is fresh in the mind. However, the documentation process is often delayed until the end of development, when it may be more difficult to remember the required detail. In some cases the postponed documentation stage never happens and the library is left without any usage notes. The information may be sorely missed when the library is used in the future.

To enabled you to quickly create documentation as you develop your code, to keep the documentation in a standard format and to gain benefit from the information as you code, you can use XML documentation comments. These are specially formatted comments that decorate elements of your code. When you build your project with the correct option enabled, the comments are extracted and combined in an XML file that resides in the same folder as the compiled DLL.

The documentation XML file is not particularly readable for users. However, Visual Studio will use the file to generate Intellisense information for your classes and methods in the same manner as you see for the standard .NET framework libraries. You can also view the documentation within the code definition window, ensuring that the information is always at hand when you are writing code. If you wish to read the information in a web site, help file or printable format, there are tools available that will automatically create these items using the XML files as their data sources. Such tools are beyond the scope of this article.

Adding Documentation Comments

In this article we will create some documentation comments for a class and a structure. We'll look at how to create the XML file containing the description of the source code and how to utilise the comments via Intellisense. The code will perform no function other than providing items to which we can anchor comments. We will consider only the basic XML documentation comments here. Further options are available and will be discussed in future articles.

To begin, create a new console application.

Documenting Classes

You can add a summary description to classes. This can contain simple textual information that describes the purpose of the class. To try it out, we need a class to work with. Add a new class file to the project and name it, "Calculator". Adjust the declaration of the new class so that it matches that shown below:

public class Calculator
{
}

Documentation comments must always appear directly before the element that they describe. To make room for the comment, add a blank line above the class declaration. Documentation comments are distinguished by their use of three forward slashes (///). Type "///" onto the blank line above the class. If Visual Studio is configured with its default options, the three slashes will be expanded into an empty documentation comment, as shown below. If you have disabled this feature in Visual Studio, you will need to enter the comment structure manually.

/// <summary>
/// 
/// </summary>
public class Calculator
{
}

You can see that the information within the comments is a very simple XML fragment containing a single summary element. To add the text that you wish to use to describe the class, you simply insert it within the element. For example:

/// <summary>
/// Performs mathematical calculations.
/// </summary>
public class Calculator
{
}

Even though we have not yet created a documentation XML file, we can already use the summary within the same solution. To see this, switch to the Program class and modify the Main method as shown below:

static void Main(string[] args)
{
    Calculator calc;
}

If you point at the Calculator symbol in the code, the Intellisense pop-up should appear. In addition to showing the class' fully qualified name, you will also see the summary entered in the comment. The image below is captured from the Visual Studio 2003 version of Intellisense. The display will be slightly different in other versions.

Documentation comment visible in Intellisense

Documenting Structures

Structures can be given a summary description in the same manner as classes. Try creating the structure below. As before, start by adding the declaration before moving to the preceding line and typing "///". You can then fill in the summary.

/// <summary>
/// Holds the calculator memory value.
/// </summary>
public struct CalculatorMemory
{
}
3 January 2012