How to Use XML Documentation Comments in C# 4.0

In the following excerpt, the author of Programming C# 4.0, Sixth Edition shows how to add XML documentation comments to your code and why they are useful.

---

If you structure your comments in a certain way, Visual Studio is able to present the information in those comments in tool tips whenever developers use your code. As Example 2-4 shows, documentation comments are denoted with three slashes, and they contain XML elements describing the target of the comment—in this case, there’s a description of a method, its parameters, and the information it returns.

Example 2-4. XML documentation comments

/// <summary>
/// Returns the square of the specified number.
/// </summary>
/// <param name="x">The number to square.</param>
/// <returns>The squared value.</returns>
static double Square(double x)
{
    return x * x;
}

If a developer starts writing code to invoke this method, Visual Studio will show a pop up listing all available members matching what she’s typed so far, and also adds a tool tip showing the information from the <summary> element of the selected method in the list, as Figure 2-4 shows. You’ll see similar information when using classes from the .NET Framework—documentation from its class libraries is provided as part of the .NET Framework SDK included with Visual Studio. (The C# compiler can extract this information from your source files and put it in a separate XML file, enabling you to provide the documentation for a library without necessarily having to ship the source code.)




The <param> information shows up as you start to type arguments, as Figure 2-5 shows. The <returns> information doesn’t appear here, but there are tools that can build documentation from this information into HTML files or help files. For example, Microsoft provides a tool called Sandcastle, available from http://www.codeplex.com/Sandcastle, which can generate documentation with a similar structure to the documentation for Microsoft’s own class libraries.





We’re moving on from “Hello, world” now, so this is a good time to create a new project if you’re following along in Visual Studio as you read. (Select File→New Project or press Ctrl-Shift-N. Note that, by default, this will create a new solution for your new project. There’s an option in the New Project dialog to add the new project to the existing solution, but in this case, let it create a new one.) Create another console application and call it RaceInfo—the code is going to perform various jobs to analyze the performance of a race car. Let Visual Studio create the project for you, and you’ll end up with much the same code as we had in Example 2-1, but with the Program class in a namespace called RaceInfo instead of HelloWorld. The first task will be to calculate the average speed and fuel consumption of the car, so we need to introduce the C# mechanism for holding and working with data.