C# XML documentation

C# supports structured API documentation with /// comments. IDEs such as Rider can display the summary and parameters in completion and quick documentation. The build can also generate an XML documentation file, which other documentation tools can consume.

Document behavior rather than restating a signature

using System;

public static class InventoryRules
{
    /// <summary>Validates whether a slot index may be used.</summary>
    /// <param name="slot">Zero-based slot index to check.</param>
    /// <param name="capacity">Number of slots, which must be non-negative.</param>
    /// <returns>True only when slot is within the current capacity.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Thrown if capacity is negative.
    /// </exception>
    public static bool IsValidSlot(int slot, int capacity)
    {
        ArgumentOutOfRangeException.ThrowIfNegative(capacity);
        return slot >= 0 && slot < capacity;
    }
}

The summary communicates the purpose. The parameter documentation specifies units and bounds, and the exception is justified by actual implementation behavior.

Common XML tags

Tag	Meaning
<summary>	Brief purpose visible in IDE hints
<param name="...">	Caller-visible input contract
<returns>	The meaning of a return value
<exception cref="...">	Relevant conditions for an exception
<remarks>	Important additional constraints
<typeparam name="...">	A generic type parameter
<see cref="..." />	A compiler-aware reference
<example>	A small caller example

Build and review

Enable <GenerateDocumentationFile>true</GenerateDocumentationFile> in the project file if you want emitted XML documentation. Check warnings for missing or invalid references. XML comments do not enforce the contract by themselves; tests and implementation must agree. Comments can become outdated, so public API changes need documentation review.

Exercise: Document a method that returns -1 when an array search misses a value. Include the meaning of -1, null-input behavior and any exceptions the implementation can actually throw.

References: Microsoft XML documentation and Rider.