C# XML documentation comments FAQ
Ever since we released the first version of C# 1.0 I’ve received a question or two a month about XML documentation comments. These are often referred to as ‘doc comments’ for short. The questions range from the use of doc comments in VS to the recommended schema of the XML. This post captures a few of the common questions that I’ve seen.
Why isn’t there a multi-line version of XML doc comments?
There are actually two forms of doc comments in C#, single and multi-line. However, the single-line version is by far the most commonly used; in fact, the multi-line version wasn’t supported until the 1.1 version of the compiler even though they were defined in the 1.0 version of the language spec. The single line version is likely to be familiar to any user of Visual Studio; it’s syntactically indicated on a line that starts with a triple slash (///):
/// <summary>
/// This is the single line version of the doc comment
/// </summary>
static void Example()
{
}
The multi-line version uses /**:
/** <summary>
* This is the multi-line version
* </summary> */
static void Example()
{
}
They are functionally identical, the only difference being that it’s possible to use the multi-line version “inline” within an expression. The multi-line version of the comments weren’t actually in the proposed version of the language specification submitted to ECMA; however, the ECMA committee decided that having both forms would be better.
The C# language service doesn’t support multi-line XML doc comments as well as the singe line comments (i.e. /** doesn’t auto-generate any tags); however, colorization for multi-line doc comments does work, and in VS 2005 it’s possible to get completion lists for the tags but you must first end the multi-line comment and then go back and enter in the tags.
How do I make VS show the XML doc comments of the types and methods of my components in completion lists and object browser?
This has been an extremely common question for a long time. The short and long of it is that you must deploy the XML file that is generated by the compiler with the component. They must be in the same directory, and the XML file must have the same name as the component except with an .xml extension. I wrote a whitepaper that contains a walkthrough, in VS 2003, which demonstrates this. It’s available here.
How do use XML doc comments to refer to generic types?
Several of the tags that are recommended in the C# language specification have an attribute named ‘cref’ on them. Cref refers to a code reference. This attribute can be used by tools to create links between different types and members (e.g. object browser uses crefs to create hyperlinks that allow quick navigation to the related type). The C# compiler actually understands the cref attribute to a limited extent. The compiler will try to bind the type or member listed in a cref attribute to a code element defined your source. Assuming that it can it will then fully qualify that member in the generated XML file. For example:
using System.Collections;
class Program
{
/// <summary>
/// DoSomething takes a <see cref="ArrayList"/>
/// </summary>
void DoSomething(ArrayList al) { }
}
This generates the following XML file:
<member name="M:Program.DoSomething(System.Collections.ArrayList)">
<summary>
DoSomething takes a <see cref="T:System.Collections.ArrayList"/>
</summary>
</member>
Notice that the compiler bound ArrayList and emitted System.Collections.ArrayList instead.
I’m sure you’re saying, wow, fascinating, um… but what does that have to do with generics? Good question. Generics complicate doc comments because C# uses angle brackets which would usually be associated with XML. It’s possible just to use the normal escaping mechanisms associated with angle brackets (> <) in XML. Unfortunately this turns out to look fairly ugly:
using System.Collections.Generic;
class Program
{
/// <summary>
/// DoSomething takes a <see cref="List<T>"/>
/// </summary>
void DoSomething(List<int> al) { }
}
This can become particularly onerous when the generic type has many type arguments. The compiler team decided to improve this by allowing an alternate syntax to refer to generic types and methods in doc comments. Specifically, instead of using the open and close angle-brackets it’s legal to use the open and close curly braces. The example above would then become:
using System.Collections.Generic;
class Program
{
/// <summary>
/// DoSomething takes a <see cref="List{T}"/>
/// </summary>
void DoSomething(List<int> al) { }
}
The compiler understands this syntax and will correctly bind List{T} to System.Collections.Generic.List<T>.
When the <example> tag is used and there are a number of generic types or methods in the example, an easier approach is to simply surround the example with a CDATA block. That way there is no need to escape less-than signs.
Which doc comment tags are understood and used by Visual Studio?
There are a number of tags that Visual Studio uses to process or present information:
|
Tag name |
Tools that make use of the tag |
|
summary |
Completion lists, quick info, class view, class designer, object browser, object test bench |
|
param |
Parameter help, quick info, object test bench, class designer, object browser |
|
exception |
Completion lists, quick info, object browser |
|
include |
C# Compiler |
|
returns |
Object browser |
|
see/seealso |
Object browser |
The ‘metadata as source’ feature, which is invoked when goto definition is performed on a type or member that is defined in metadata, processes a number of the tags documented in the C# language specification and tries to provide a reasonable view.
How do I generate HTML or .chm documentation from the XML file?
The generated XML file actually doesn’t contain enough information to fully generate good reference documentation. In fact, it was an explicit goal to make the XML file contain just enough information to map the comment back to the associated code element in metadata. Regardless, there are a number of tools that take the assembly and the generated XML file and produce a very nice looking, easy to browse output. NDoc has been a favorite of many developers that I’ve talked to for quite a while. I believe that development on NDoc has slowed somewhat; another option is SandCastle.
