BRO1619: Put the documentation elements in the standard order¶

The top-level elements of a documentation comment come in this order: <summary>, <typeparam>, <param>, <returns>, <value>, <exception>, <remarks>, <example>, <seealso>. Elements of one kind keep their order among themselves. Not a StyleCop rule.

Example¶

Before¶

public class Calculator
{
    /// <returns>The sum.</returns>
    /// <param name="a">The first number.</param>
    /// <param name="b">The second number.</param>
    /// <summary>Adds two numbers.</summary>
    /// <remarks>Overflows silently.</remarks>
    /// <exception cref="System.InvalidOperationException">Never, in practice.</exception>
    public int Add(int a, int b) => a + b;
}

After¶

public class Calculator
{
    /// <summary>Adds two numbers.</summary>
    /// <param name="a">The first number.</param>
    /// <param name="b">The second number.</param>
    /// <returns>The sum.</returns>
    /// <exception cref="System.InvalidOperationException">Never, in practice.</exception>
    /// <remarks>Overflows silently.</remarks>
    public int Add(int a, int b) => a + b;
}

Why¶

Readers look for the summary first and the parameters next; a fixed order puts every member's documentation in the same place. C# itself prescribes no order, so the order is the one most code already follows:

<summary>, <typeparam>, <param>, <returns>: the stub Visual Studio inserts when you type ///.
<value>, then <exception>: the order of the sections on Microsoft Learn's API pages (parameters, returns or property value, exceptions).
<remarks>, <example>, <seealso> last: the supplementary material, with the "see also" links at the end, where documentation pages show them.

Survey #15 in beyond-stylecop.md listed this as Roslynator's RCS1232, but RCS1232 only orders <param> tags, which BRO1611 already does.

How the fix works¶

Like BRO1611's reorder: each element's lines are a slot, and every slot gets the lines of the element that belongs there. Lines between the elements (an empty ///) stay where they are. The order within one kind is kept, so <param> tags in the wrong order are BRO1611's and <typeparam> tags BRO1613's; dotnet format fixes both in one run, in either order.

This rule reads documentation as XML, which the compiler only does when the project generates documentation (<GenerateDocumentationFile>true</GenerateDocumentationFile>), like the other documentation rules.

Not reported¶

An element that shares a line with another element or text: only whole lines are moved.
Any other top-level element (<inheritdoc/>, <include/>, <permission>, a custom tag): where it belongs isn't clear, so the comment is left as it is.
Text outside the elements (a loose sentence between two tags).
/** */ comments.