Skip to content

BRO1616: Write the summary's tags consistently on their own lines or on the text's line

A <summary> has its tags on lines of their own (the default), or, with stylebro_summary_layout = single_line_when_fits, is written on one line when its text is one line and the result fits within max_line_length. Not a StyleCop rule; Roslynator's RCS1253 and Meziantou's MA0177/MA0211 check the same.

Example

Before

/// <summary>A shape on the screen.</summary>
public class Shape
{
    /// <summary>Draws the shape
    /// at its position.</summary>
    public void Draw()
    {
    }
}

After

/// <summary>
/// A shape on the screen.
/// </summary>
public class Shape
{
    /// <summary>
    /// Draws the shape
    /// at its position.
    /// </summary>
    public void Draw()
    {
    }
}

Why

A codebase that mixes /// <summary>Gets the name.</summary> with the three-line form reads as two styles. The three-line form is what Visual Studio inserts when you type ///, and the eight repositories StyleBro is tested on use it for 99% of their one-sentence summaries (14,329 to 148, see decisions.md), so it's the default. A team that prefers the short form picks single_line_when_fits.

How the fix works

Only the gap between a tag and the text next to it changes: it becomes a line break and /// (indented like the <summary> line), or, when joining, nothing. The text itself, any lines in between, inline elements (<see cref>, <c>) and the tags stay as they are, so a missing period is still BRO1603's and the /// spacing BRO1005's.

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

Configuration

[*.cs]
# multi_line (default): the tags on lines of their own.
# single_line_when_fits: one line when the text is one line, has no <para>, <code> or <list>, and the joined line
# fits within max_line_length (no limit when it isn't set); any other summary has its tags on lines of their own.
stylebro_summary_layout = multi_line
max_line_length = 120

With single_line_when_fits:

/// <summary>A shape on the screen.</summary>
public class Shape
{
    /// <summary>
    /// Draws the shape
    /// at its position.
    /// </summary>
    public void Draw()
    {
    }
}

Not reported

  • Empty summaries (<summary></summary>, <summary/>, only blank /// lines).
  • A tag that shares its line with something else (/// <summary>Draws.</summary> <remarks>...): the layout of the other element isn't this rule's.
  • /** ... */ documentation comments.
  • Summaries with XML errors (a missing or misspelled end tag).
  • With single_line_when_fits: a summary already on one line, even when it's longer than max_line_length (this isn't a line-length rule), and text on several lines or with <para>, <code> or <list>, which keeps (or gets) its tags on their own lines.
  • Only <summary>: <remarks>, <returns>, <param> and the other elements are left as they are.

Compared with StyleCop

StyleCop has no such rule. Roslynator's RCS1253 (off by default, roslynator_doc_comment_summary_style = single_line | multi_line) and Meziantou's MA0211 (multi-line) and MA0177 (single line when the content is one line and fits within max_line_length; for every top-level element, not only the summary) do the same, off by default. Unlike them, the multi-line layout here also moves the tags of a summary whose text starts on the <summary> line or ends on the </summary> line. stylebro-migrate turns this rule off, so migrating doesn't change a StyleCop-clean repository.