Documentation Comment

C# documentation comments are specially formatted comments containing XML elements, placed immediately preceding user-defined types (classes, interfaces, structs, records, delegates) or members (methods, properties, fields, events). The C# compiler parses these comments during compilation to extract the XML elements and generate a structured XML file representing the API surface.

Syntax

Documentation comments are denoted by either triple forward slashes (///) for single-line constructs or a forward slash followed by two asterisks (/** ... */) for multi-line block constructs.

/// <summary>
/// Single-line documentation comment syntax.
/// </summary>

/**
 * <summary>
 * Multi-line block documentation comment syntax.
 * </summary>
 */

Core XML Elements

The compiler recognizes specific XML tags to categorize the metadata of the documented code element.

• <summary>: Provides a concise, high-level description of the type or member.
• <remarks>: Specifies supplementary, detailed information that expands upon the <summary>.
• <param name="parameterName">: Describes a specific method or delegate parameter. The name attribute must match the parameter signature exactly.
• <typeparam name="parameterName">: Describes a generic type parameter.
• <returns>: Describes the return value of a method.
• <value>: Describes the value represented by a property.
• <exception cref="ExceptionType">: Identifies an exception that the method or property can throw. The cref attribute creates a compiler-verified cross-reference to the exception type.
• <see cref="member"/>: Creates an inline hyperlink to another code element within the documentation text.
• <seealso cref="member"/>: Creates a cross-reference link, typically placed in a “See Also” section at the end of the documentation.
• <example>: Contains a code example demonstrating the element. Often used in conjunction with the <code> tag.

Structural Example

The following code block demonstrates the application of documentation comments to a generic method, utilizing multiple XML elements to map the method’s signature and behavior.

/// <summary>
/// Parses a string representation of a value into its generic type equivalent.
/// </summary>
/// <typeparam name="T">The target type to parse the string into. Must implement <see cref="IParsable{T}"/>.</typeparam>
/// <param name="input">The string containing the data to parse.</param>
/// <returns>An instance of <typeparamref name="T"/> representing the parsed value.</returns>
/// <exception cref="ArgumentNullException">Thrown when <paramref name="input"/> is null.</exception>
/// <exception cref="FormatException">Thrown when <paramref name="input"/> is not in the correct format.</exception>
public T ParseValue<T>(string input) where T : IParsable<T>
{
    if (input == null)
    {
        throw new ArgumentNullException(nameof(input));
    }
    
    return T.Parse(input, CultureInfo.InvariantCulture);
}

Compiler Configuration

To instruct the C# compiler to extract these comments and emit the XML file, the GenerateDocumentationFile property must be enabled in the project’s .csproj file.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

When enabled, the compiler validates the XML syntax and verifies all cref (code reference) and name attributes against the actual code elements. If a referenced parameter or type does not exist, the compiler generates a warning (e.g., CS1572 or CS1574).

Master C# with Deep Grasping Methodology!

Learn More