BRO1612: Element parameter documentation should declare parameter name¶

Every <param> tag says which parameter it documents. Replaces StyleCop SA1613.

Example¶

Before¶

public class Ruler
{
    /// <summary>Measures a distance.</summary>
    /// <param name="from">The start.</param>
    /// <param>The end.</param>
    /// <returns>The distance.</returns>
    public double Measure(double from, double to) => to - from;
}

After¶

public class Ruler
{
    /// <summary>Measures a distance.</summary>
    /// <param name="from">The start.</param>
    /// <param name="to">The end.</param>
    /// <returns>The distance.</returns>
    public double Measure(double from, double to) => to - from;
}

Why¶

A <param> without a name doesn't show up in IntelliSense or the generated documentation; the text is lost.

How the fix works¶

The fix adds name="..." (or fills in an empty one) when the parameter is certain: the tag is the only unnamed one and exactly one parameter has no tag, or every tag is unnamed and there is one per parameter, which are then named in order. The tag's problems are fixed together with BRO1611's, so both fixes give the same result.

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

Not reported¶

When the parameter isn't certain, for example two unnamed tags for three parameters, or an unnamed tag next to a tag naming a parameter that doesn't exist: the fix would have to guess.
Constructors and operators, like BRO1611.

Compared with StyleCop¶

StyleCop reports every unnamed tag and has no fix; StyleBro reports the ones it can name.