BRO1606: Constructor summary documentation should begin with standard text¶

A constructor's summary begins with Initializes a new instance of the <see cref="T"/> class. (or struct), and a static constructor's with Initializes static members of the <see cref="T"/> class.. Replaces StyleCop SA1642. Only summaries that say nothing else are reported: an empty one, filler (Default constructor.) and the standard sentence written differently. A summary with text of its own (Opens a connection to the server.) is left alone.

Example¶

Before¶

public class Connection
{
    /// <summary>Default constructor.</summary>
    /// <param name="host">The server's host name.</param>
    public Connection(string host)
    {
        Host = host;
    }

    /// <summary>Gets the host name.</summary>
    public string Host { get; }
}

After¶

public class Connection
{
    /// <summary>Initializes a new instance of the <see cref="Connection"/> class.</summary>
    /// <param name="host">The server's host name.</param>
    public Connection(string host)
    {
        Host = host;
    }

    /// <summary>Gets the host name.</summary>
    public string Host { get; }
}

Why¶

The standard sentence is what the .NET documentation uses, and it links to the type, so every constructor's documentation starts the same recognizable way.

How the fix works¶

Only the beginning counts, like in StyleCop: Initializes a new instance of the <see cref="T"/> class representing ... is fine. A sentence that is the standard one with the type named differently (Initializes a new instance of the Connection class., without the link) is replaced; a sentence that says more (Initializes a new instance of Connection with a timeout.) isn't reported (see Not reported). Filler is replaced too: a first sentence that only says it is a constructor (Default constructor., Constructor., Ctor., Constructor for X., Creates a new instance., Creates a new instance of X., Creates an instance of the X class., also with Constructs or Instantiates). Any text after it stays, after the standard sentence: Default constructor. Starts the timer. becomes Initializes a new instance of the <see cref="T"/> class. Starts the timer. (found in Stateless: ... class. Default constructor.). The list is short on purpose; a sentence that says anything more is kept. For a generic type the link is <see cref="Cache{TKey, TValue}"/>. A private constructor may also start with Prevents a default instance of the <see cref="T"/> class from being created. A summary that starts with <para> is judged by that paragraph's text, and the fix puts the standard sentence inside it. An empty or whitespace-only summary gets the standard sentence; when it spans lines, on a line of its own.

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

Not reported¶

Constructors without a summary or with <inheritdoc/>: missing documentation isn't reported.
Records.
A whitespace-only summary whose </summary> line holds more than ///: the fix couldn't write the new line.
A constructor summary with text of its own (Opens a connection to the server., Creates a words object.): it already says what the constructor does, and the standard sentence in front of it made two sentences doing one job (owner's decision 2026-10-12, issue #132: about 100 public summaries in a trial). A finalizer's summary still gets the standard sentence in front (BRO1607).
Text left after replaced filler that can't follow the standard sentence: text that starts in lower case (construct a dynamic parameter bag) or with a condition (If, When, Whenever, Unless, While, Whether, True, False). Initializes a new instance of the <see cref="T"/> class. construct a dynamic parameter bag isn't English; rephrase these by hand.
A finalizer summary that is a sentence of its own (it starts with Finalizes and says more than the standard sentence): replacing it would lose what it says.

Compared with StyleCop¶

Same results as StyleCop, except a summary that starts with <para>: StyleCop 1.2.0-beta.556 reports it even when the paragraph starts with the standard sentence, and its fix puts a second one in front of <para>. StyleCop's master (unreleased, 29514d23) accepts any summary that starts with <para> without checking its text; StyleBro still checks the paragraph's text (the owner's decision, see decisions). A whitespace-only summary is reported like in StyleCop (parity set documentation-tags). StyleCop's fix puts the standard sentence directly before the old text, without a space (class.Opens a connection), and also reports the summaries StyleBro leaves alone: a constructor summary with text of its own (StyleBro reports only empty, filler and near-miss summaries), and text after filler that starts in lower case or with a condition.