BRO1611: Element parameter documentation should match element parameters¶

<param> tags document the parameters that exist, in their order. Replaces StyleCop SA1612.

Example¶

Before¶

public class Mailer
{
    /// <summary>Sends a message.</summary>
    /// <param name="subject">The subject.</param>
    /// <param name="recipient">Who receives it.</param>
    public void Send(string to, string subject)
    {
    }

    /// <summary>Queues a message.</summary>
    /// <param name="to">Who receives it.</param>
    /// <param name="retries">How often to retry.</param>
    public void Queue(string to)
    {
    }
}

After¶

public class Mailer
{
    /// <summary>Sends a message.</summary>
    /// <param name="to">Who receives it.</param>
    /// <param name="subject">The subject.</param>
    public void Send(string to, string subject)
    {
    }

    /// <summary>Queues a message.</summary>
    /// <param name="to">Who receives it.</param>
    public void Queue(string to)
    {
    }
}

Why¶

Parameters get renamed, removed and reordered, and their documentation is easily forgotten. Stale tags describe parameters that don't exist, and IntelliSense shows the documentation in the wrong place.

How the fix works¶

A tag for a parameter that doesn't exist is renamed when it's the only such tag and exactly one parameter has no tag: the parameter was most likely renamed (recipient becomes to above). Otherwise the tag is removed, since its parameter is gone (retries above).
Tags out of order are put in parameter order, when each tag has its own /// lines.

A renamed tag's text isn't changed; read it when you review the fix.

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

Not reported¶

Tags without a name, or two tags for the same parameter.
Out-of-order tags that share a line with other documentation.
Members whose documentation has a top-level <inheritdoc> (/// <inheritdoc cref="Other"/> next to <param> tags), like StyleCop's SA1612. An <inheritdoc> inside a tag (<param name="x"><inheritdoc/></param>) doesn't count.
Constructors and operators, like StyleCop, whose SA1612 doesn't check them. Primary constructors are checked: the <param> tags of a class, struct or record with a parameter list.

Compared with StyleCop¶

Same results as StyleCop's master (unreleased): methods, indexers, delegates, and the primary constructor parameters of classes, structs and records; StyleCop leaves constructors and operators out, and so does StyleBro, so switching doesn't flag code StyleCop accepted. StyleCop 1.2.0-beta.556 doesn't check primary constructors. StyleCop has no fix for SA1612.