Skip to content

Add MA0211 to enforce multi-line XML documentation comments#1218

Merged
meziantou merged 6 commits into
mainfrom
copilot/add-multi-line-syntax-rule
Jul 8, 2026
Merged

Add MA0211 to enforce multi-line XML documentation comments#1218
meziantou merged 6 commits into
mainfrom
copilot/add-multi-line-syntax-rule

Conversation

Copilot AI commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

This adds a complementary rule to MA0177 for teams that want XML documentation comments to always use multi-line formatting, even when the content fits on a single line. The new rule is disabled by default so it can be enabled selectively.

  • New analyzer rule

    • Added MA0211 to report single-line XML documentation elements such as <summary> and <param> when they can be rewritten in multi-line form
    • Scoped the rule to simple text-only XML elements and intentionally skips nested XML content and CDATA, matching the existing MA0177 boundaries
  • Code fix

    • Added a fixer that expands inline XML documentation into standard multi-line /// form
    • Preserves indentation, comment prefixing, and tag attributes while rewriting the element
  • Tests

    • Added focused coverage for:
      • single-line <summary> and <param> elements
      • empty XML elements
      • non-diagnostic cases for already multi-line comments, nested XML content, and CDATA
  • Rule metadata and docs

    • Added docs/Rules/MA0211.md
    • Regenerated rule listings and packaged editorconfig entries so MA0211 appears alongside the existing analyzer set

Example:

/// <summary>description</summary>
class Sample { }

// becomes

/// <summary>
/// description
/// </summary>
class Sample { }

Copilot AI and others added 3 commits July 7, 2026 14:34
Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com>
Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com>
Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com>
Copilot AI changed the title [WIP] Add analyser rule for enforcing multi-line XML summaries Add MA0211 to enforce multi-line XML documentation comments Jul 7, 2026
Copilot AI requested a review from meziantou July 7, 2026 14:47
{
await CreateProjectBuilder()
.WithSourceCode("""
/// <summary>This has <c>code</c> inside</summary>

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot This should be reported. Skip the logic to find nested elements. Report all non-empty summary element that are single line.

Also, do not report other elements, only summary. Make sure to also update the rule title, description and documentation page

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in ef91285 and feaad1a. MA0211 now only reports single-line, non-empty <summary> elements, no longer skips nested XML/CDATA inside <summary>, and the rule title/description/docs were updated accordingly.

Copilot AI and others added 2 commits July 8, 2026 00:19
Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com>
Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com>
This was referenced Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Compliment MA0177 with rule that enforces multi-line syntax.

2 participants