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+

Adding Code Examples to Documentation Comments

Documentation for code libraries is generally improved with the addition of sample code that shows how those libraries are used. When using XML documentation comments, three tags can be used to incorporate examples within the compiled help file.

Code Samples

One of the most important things you can do when documenting code libraries is to add sample code. Many programmers read the samples before they look at the rest of the documentation and some will only read the other information if they are unable to understand the provided source code. Luckily, the XML documentation comments system includes several XML tags that can be incorporated within your code to decorate sample code. In this short article I'll introduce three tags, which are:

  • c. The c tag allows you to insert a small code fragment directly into your documentation. The fragment may not include line breaks and is inserted into the flow of the surrounding text. When the XML is compiled into a help file, using a tool such as Sandcastle Help File Builder, it is presented in a different font. This tag is ideal when adding the names of classes, structures and members to summary descriptions.
  • code. The code tag is used to include larger code samples in your documentation. The compiled help file includes the code, with line breaks, in a shaded rectangle. The code is formatted in a similar manner as it would appear in Visual Studio, with type names, variables and values appearing in different colours. The samples also include "Copy" links, making it easy to copy and paste into other source code files.
  • example. Usually when you add example code to your documentation you will usually place it within example tags. Each example tag is added to the "Examples" section of the appropriate help page. This is a collapsible section. Example tags may also contain text outside of code elements. This is formatted using the standard text style.

The following code shows documentation comments including all of the above tags. The c tag is used in the summary to compare the rather simple method with the multiplication operator. A larger sample is included within an example tag that also includes a description. Note that the source code within the code tag starts on a new line. If you start the sample code on the same line as the opening tag, you may find that the alignment of the code is incorrect in the final help file. Adding the code on a new line prevents this.

/// <summary>
/// Multiplies two numbers. Provides the same result as <c>int result = x * y</c>.
/// </summary>
/// <param name="x">A number to multiply.</param>
/// <param name="y">A number to multiply.</param>
/// <returns>The product of x and y.</returns>
/// <example>This example multiplies 10 and 12 to get 120.
/// <code>
/// int x = 10;
/// int y = 12;
/// int result = x * y; // result = 120
/// </code>
/// </example>
public int Multiply(int x, int y)
{
    return x * y;
}

Once a help file is created for the above documentation, the Examples section appears as follows. Note that the code sample appears, along with its description, in the Examples section. Note also the Copy link for the code.

Example code in documentation

31 May 2012