C# has a built-in XML documentation system that can help you create and maintain a reference document to the classes and methods used in your application. It isn't the only documentation you will need, but it's a good start.

C# has a built-in system that can turn special comments that you insert into the code into full documentation. It is a bit like the JavaDoc system but is used XML formatting and can be used with a variety of standard and custom tool. The good news is that the XML documentation facility is built into all Visual Studio versions, including Express, because it is actually provided by the compiler at the next level down from the IDE.

You could say that it’s core C# yet many programmers simply don’t know it exists and when they do find out about it they often fail to see its value and treat it as a more sophisticated form of code commenting.

Let’s begin by looking at the basic facilities and then move on to the interesting topic of using the generated XML documentation to create something more human friendly.

The triple slash means XML

The key to embedding XML within a program is to make use of the triple slash comment.

Whenever the compiler encounters the sequence “///” it assumes that the line contains valid XML.

Yes it really is this simple. If you start a new project, depending on the type of project, you might see some /// comments that have automatically been inserted by the template. If you have been wondering why triple slash comments were used – now you know.

If you type /// within the code of any project just before a method definition then the IDE will automatically generate a <summary> tag for you:

/// <summary>
///
/// </summary>
public void MyMethod()
{
}

Simply from the look of this, it is clear that you have just added a pair of XML tags and whatever you type between them will be converted into the tag’s value.

For example:

/// <summary>
///  MyMethod is designed to
///  demonstrate XML documentation
/// </summary>
public void MyMethod()
{
}

It is a little known fact but as well as the triple slash comment method you can also make use of a block comment similar to /*  */. In this case you write /** to start the block and /** to end it. However block comments are not automatically generated in C# so to enter the above as a block comment you would have to manually enter:

/**
* <summary>
* MyMethod is designed to
* demonstrate XML documentation
* </summary>
**/

Block comments are sometimes useful but the triple slash comments are much more common.

Converting from comments to XML

So far so good but how do we get the triple slash comments converted into the promised XML?

All you have to do is open the project properties, click on the Build tab and then select the box “XML documentation file” and provide a suitable file name. There is a corresponding command line parameter for the command line compiler and this is easy to look up in the documentation.

Selecting the XML document option is easy but often overlooked

If you now build or debug the program the triple slash comments are used to generate the XML file specified. You can find this either in the debug or release directory within the Bin directory.

If you try this out you might be surprised to see are so many tags that you didn’t specify.

The raw XML documentation

<ASIN: 0596002521>

<ASIN:0321658701>