XML Documentation

A documentation comment is a piece of embedded XML that documents a type or member. A documentation comment comes immediately before a type or member declaration, and starts with three slashes:

/// <summary>Cancels a running query.</summary>
public void Cancel() { ... }

Multiline comments can be done either like this:

/// <summary>
/// Cancels a running query
/// </summary>
public void Cancel() { ... }

or like this (notice the extra star at the start):

/**
    <summary> Cancels a running query. </summary>
*/
public void Cancel() { ... }

If you compile with the /doc directive, the compiler extracts and collates documentation comments into a single XML file. This has two main uses:

  • If placed in the same folder as the compiled assembly, Visual Studio automatically reads the XML file and uses the information to provide IntelliSense member listings to consumers of the assembly of the same name.

  • Third-party tools (such as Sandcastle and NDoc) can transform an XML file into an HTML help file.

Standard XML Documentation Tags

Here are the standard XML tags that Visual Studio and documentation generators recognize:

<summary>
<summary>...</summary>

Indicates the tool tip that IntelliSense should display for the type or member. Typically a single phrase or sentence.

<remarks>
<remarks>...</remarks>

Additional text that describes the type or member. Documentation generators pick this up and merge it into the bulk of a type or member’s description.

<param>
<param name="name">...</param>

Explains a ...

Get C# 5.0 Pocket Reference now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.