.NET 1.1+

Adding Remarks to XML Documentation

by Richard Carr, published at http://www.blackwasp.co.uk/DocumentationRemarks.aspx

Some information that is added to XML documentation is important but secondary to the summary text and the technical details of the code library's class and member usage. This information should be included as remarks.

Remarks

When you create XML documentation to describe your types and their members, you will almost always include a summary for each. This provides the primary description for the item. Sometimes you will wish to add further details that are of lower importance than the summary and the technical details of a class, method or property. You can include such information using remarks.

To add remarks to a set of XML documentation comments, surround the additional text with a remarks tag. For long remarks you can include para tags to add paragraph breaks and better organise the information. Information included as remarks will be compiled into the final HTML Help files, as well as appearing within Visual Studio windows, such as the Object Browser.

The following code shows a class with a summary and some remarks:

/// <summary>
/// Utility class containing static methods that perform simple
/// but handy mathematical operations.
/// </summary>
/// <remarks>All of the methods work with decimal values and
/// return decimal values. This gives the greatest accuracy as
/// single and double-precision floating-point numbers are prone
/// to rounding errors.</remarks>
public static class SimpleMathsUtilities
{
    /// <summary>
    /// Increases a value by a given percentage.
    /// The percentage can be negative.
    /// </summary>
    /// <param name="value">The value to increase.</param>
    /// <param name="percentage">The percentage.</param>
    /// <returns>The new value</returns>
    public static decimal AddPercentage(decimal value, decimal percentage)
    {
        return value * ((percentage / 100) + 1);
    }
}

When the above documentation comments are compiled into a HTML Help file using Sandcastle Help File Builder, the remarks appear in their own collapsible section, secondary to the summary and the syntax options.