BRO1613: Generic type parameter documentation should match type parameters¶

<typeparam> tags document the type parameters that exist, in their order. Replaces StyleCop SA1620.

Example¶

Before¶

/// <summary>A cache.</summary>
/// <typeparam name="TValue">The value type.</typeparam>
/// <typeparam name="TKey">The key type.</typeparam>
public class Cache<TKey, TValue>
{
    /// <summary>Gets an item.</summary>
    /// <typeparam name="TResult">The result type.</typeparam>
    /// <returns>The item.</returns>
    public TItem Get<TItem>() => default(TItem);
}

After¶

/// <summary>A cache.</summary>
/// <typeparam name="TKey">The key type.</typeparam>
/// <typeparam name="TValue">The value type.</typeparam>
public class Cache<TKey, TValue>
{
    /// <summary>Gets an item.</summary>
    /// <typeparam name="TItem">The result type.</typeparam>
    /// <returns>The item.</returns>
    public TItem Get<TItem>() => default(TItem);
}

Why¶

Type parameters get renamed and reordered like parameters, and stale tags describe something that no longer exists.

How the fix works¶

Like BRO1611 for <param>: a tag for a type parameter that doesn't exist is renamed when it's the only such tag and exactly one type parameter has no tag (it was most likely renamed), and removed otherwise. Tags out of order are put in type parameter order when each has its own /// lines. Checked on methods, delegates, classes, structs, interfaces and records.

This rule reads documentation as XML, which needs <GenerateDocumentationFile>true</GenerateDocumentationFile>.

Not reported¶

Duplicate tags, and tags out of order that share a line with other documentation.
Members whose documentation has a top-level <inheritdoc>, like StyleCop's SA1620.

Compared with StyleCop¶

Same positions as StyleCop. StyleCop has no fix for SA1620.