fix: narrow MA0211 to summary comments

Copilot · meziantou · web-flow · commit ef91285fc524 · 2026-07-08T00:19:01.000Z
Co-authored-by: meziantou &lt;509220+meziantou@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -229,7 +229,7 @@ If you are already using other analyzers, you can check [which rules are duplica
 |[MA0208](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0208.md)|Usage|\[FixedAddressValueType\] fields must be value types|⚠️|✔️|❌|
 |[MA0209](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0209.md)|Performance|Use in keyword for in parameter|ℹ️|❌|✔️|
 |[MA0210](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0210.md)|Performance|Use in keyword to call the in overload|ℹ️|❌|✔️|
-|[MA0211](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0211.md)|Style|Use multi-line XML comment syntax|ℹ️|❌|✔️|
+|[MA0211](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0211.md)|Style|Use multi-line syntax for XML summary comments|ℹ️|❌|✔️|
 
 <!-- rules -->
 
diff --git a/docs/README.md b/docs/README.md
@@ -209,7 +209,7 @@
 |[MA0208](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0208.md)|Usage|\[FixedAddressValueType\] fields must be value types|<span title='Warning'>⚠️</span>|✔️|❌|
 |[MA0209](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0209.md)|Performance|Use in keyword for in parameter|<span title='Info'>ℹ️</span>|❌|✔️|
 |[MA0210](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0210.md)|Performance|Use in keyword to call the in overload|<span title='Info'>ℹ️</span>|❌|✔️|
-|[MA0211](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0211.md)|Style|Use multi-line XML comment syntax|<span title='Info'>ℹ️</span>|❌|✔️|
+|[MA0211](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0211.md)|Style|Use multi-line syntax for XML summary comments|<span title='Info'>ℹ️</span>|❌|✔️|
 
 |Id|Suppressed rule|Justification|
 |--|---------------|-------------|
diff --git a/docs/Rules/MA0211.md b/docs/Rules/MA0211.md
@@ -1,9 +1,9 @@
-# MA0211 - Use multi-line XML comment syntax
+# MA0211 - Use multi-line syntax for XML summary comments
 <!-- sources -->
 Sources: [UseMultiLineXmlCommentSyntaxAnalyzer.cs](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer/Rules/UseMultiLineXmlCommentSyntaxAnalyzer.cs), [UseMultiLineXmlCommentSyntaxFixer.cs](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.CodeFixers/Rules/UseMultiLineXmlCommentSyntaxFixer.cs)
 <!-- sources -->
 
-This rule reports XML documentation comments written on a single line when they can be expanded to the standard multi-line XML comment form.
+This rule reports single-line `<summary>` XML documentation comments when they contain non-empty content and can be expanded to the standard multi-line XML comment form.
 
 ````csharp
 /// <summary>Description</summary>
@@ -18,16 +18,15 @@ public class Sample { }
 
 ## When to use multi-line format
 
-Use this rule when you want XML documentation comments to consistently use the multi-line form, even when the content fits on a single line.
+Use this rule when you want `<summary>` XML documentation comments to consistently use the multi-line form, even when the content fits on a single line.
 
 ## When NOT to use multi-line format
 
 The analyzer will NOT suggest converting when:
 
-- The XML element already spans multiple lines
-- The element contains multiple lines of source content
-- The element contains CDATA sections
-- The element contains nested XML elements (like `<c>`, `<see>`, etc.)
+- The `<summary>` element already spans multiple lines
+- The `<summary>` element is empty or contains only whitespace
+- The XML documentation element is not a `<summary>` element
 
 ## Examples
 
@@ -42,10 +41,11 @@ public int Add(int a, int b) => a + b;
 /// </summary>
 public int Add(int a, int b) => a + b;
 
-// Compliant: Multiple lines of source content
-/// <summary>
-/// Returns the sum of two numbers.
-/// This method handles integer overflow.
-/// </summary>
+// Compliant: Empty summary
+/// <summary></summary>
 public int Add(int a, int b) => a + b;
+
+// Compliant: Other XML documentation elements are ignored
+/// <param name="value">The value</param>
+public void SetValue(int value) { }
 ````
diff --git a/src/Meziantou.Analyzer.CodeFixers/Rules/UseMultiLineXmlCommentSyntaxFixer.cs b/src/Meziantou.Analyzer.CodeFixers/Rules/UseMultiLineXmlCommentSyntaxFixer.cs
@@ -1,10 +1,8 @@
 using System.Collections.Immutable;
 using System.Composition;
-using System.Text;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CodeActions;
 using Microsoft.CodeAnalysis.CodeFixes;
-using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Microsoft.CodeAnalysis.Text;
 
@@ -24,11 +22,14 @@ public override async Task RegisterCodeFixesAsync(CodeFixContext context)
         if (nodeToFix is not XmlElementSyntax elementSyntax)
             return;
 
+        if (!string.Equals(elementSyntax.StartTag.Name.LocalName.ValueText, "summary", StringComparison.Ordinal))
+            return;
+
         var sourceText = await context.Document.GetTextAsync(context.CancellationToken).ConfigureAwait(false);
         if (!TryCreateReplacementText(sourceText, elementSyntax, out var replacementText))
             return;
 
-        var title = "Use multi-line XML comment syntax";
+        var title = "Use multi-line syntax for XML summary comments";
         var codeAction = CodeAction.Create(
             title,
             cancellationToken => FixAsync(context.Document, elementSyntax.Span, replacementText, cancellationToken),
@@ -53,32 +54,13 @@ private static bool TryCreateReplacementText(SourceText sourceText, XmlElementSy
             lineBreak = "\n";
         }
 
-        var contentText = new StringBuilder();
-        foreach (var content in elementSyntax.Content)
-        {
-            if (content is not XmlTextSyntax textSyntax)
-                continue;
-
-            foreach (var token in textSyntax.TextTokens)
-            {
-                var text = token.Text.Trim();
-                if (string.IsNullOrWhiteSpace(text))
-                    continue;
-
-                if (contentText.Length > 0)
-                {
-                    contentText.Append(' ');
-                }
-
-                contentText.Append(text);
-            }
-        }
+        var contentText = string.Concat(elementSyntax.Content.Select(static content => content.ToFullString())).Trim();
+        if (contentText.Length == 0)
+            return false;
 
         var startTagText = elementSyntax.StartTag.ToString();
         var endTagText = elementSyntax.EndTag.ToString();
-        replacementText = contentText.Length == 0
-            ? startTagText + lineBreak + commentPrefix + endTagText
-            : startTagText + lineBreak + commentPrefix + contentText + lineBreak + commentPrefix + endTagText;
+        replacementText = startTagText + lineBreak + commentPrefix + contentText + lineBreak + commentPrefix + endTagText;
         return true;
     }
 
diff --git a/src/Meziantou.Analyzer.Pack/configuration/all-errors.editorconfig b/src/Meziantou.Analyzer.Pack/configuration/all-errors.editorconfig
@@ -626,5 +626,5 @@ dotnet_diagnostic.MA0209.severity = error
 # MA0210: Use in keyword to call the in overload
 dotnet_diagnostic.MA0210.severity = error
 
-# MA0211: Use multi-line XML comment syntax
+# MA0211: Use multi-line syntax for XML summary comments
 dotnet_diagnostic.MA0211.severity = error
diff --git a/src/Meziantou.Analyzer.Pack/configuration/all-suggestions.editorconfig b/src/Meziantou.Analyzer.Pack/configuration/all-suggestions.editorconfig
@@ -626,5 +626,5 @@ dotnet_diagnostic.MA0209.severity = suggestion
 # MA0210: Use in keyword to call the in overload
 dotnet_diagnostic.MA0210.severity = suggestion
 
-# MA0211: Use multi-line XML comment syntax
+# MA0211: Use multi-line syntax for XML summary comments
 dotnet_diagnostic.MA0211.severity = suggestion
diff --git a/src/Meziantou.Analyzer.Pack/configuration/all-warnings.editorconfig b/src/Meziantou.Analyzer.Pack/configuration/all-warnings.editorconfig
@@ -626,5 +626,5 @@ dotnet_diagnostic.MA0209.severity = warning
 # MA0210: Use in keyword to call the in overload
 dotnet_diagnostic.MA0210.severity = warning
 
-# MA0211: Use multi-line XML comment syntax
+# MA0211: Use multi-line syntax for XML summary comments
 dotnet_diagnostic.MA0211.severity = warning
diff --git a/src/Meziantou.Analyzer.Pack/configuration/default.editorconfig b/src/Meziantou.Analyzer.Pack/configuration/default.editorconfig
@@ -626,5 +626,5 @@ dotnet_diagnostic.MA0209.severity = none
 # MA0210: Use in keyword to call the in overload
 dotnet_diagnostic.MA0210.severity = none
 
-# MA0211: Use multi-line XML comment syntax
+# MA0211: Use multi-line syntax for XML summary comments
 dotnet_diagnostic.MA0211.severity = none
diff --git a/src/Meziantou.Analyzer.Pack/configuration/none.editorconfig b/src/Meziantou.Analyzer.Pack/configuration/none.editorconfig
@@ -626,5 +626,5 @@ dotnet_diagnostic.MA0209.severity = none
 # MA0210: Use in keyword to call the in overload
 dotnet_diagnostic.MA0210.severity = none
 
-# MA0211: Use multi-line XML comment syntax
+# MA0211: Use multi-line syntax for XML summary comments
 dotnet_diagnostic.MA0211.severity = none
diff --git a/src/Meziantou.Analyzer/Rules/UseMultiLineXmlCommentSyntaxAnalyzer.cs b/src/Meziantou.Analyzer/Rules/UseMultiLineXmlCommentSyntaxAnalyzer.cs
@@ -1,6 +1,5 @@
 using System.Collections.Immutable;
 using Microsoft.CodeAnalysis;
-using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Microsoft.CodeAnalysis.Diagnostics;
 
@@ -11,12 +10,12 @@ public sealed class UseMultiLineXmlCommentSyntaxAnalyzer : DiagnosticAnalyzer
 {
     private static readonly DiagnosticDescriptor Rule = new(
         RuleIdentifiers.UseMultiLineXmlCommentSyntax,
-        title: "Use multi-line XML comment syntax",
-        messageFormat: "Use multi-line XML comment syntax",
+        title: "Use multi-line syntax for XML summary comments",
+        messageFormat: "Use multi-line syntax for XML summary comments",
         RuleCategories.Style,
         DiagnosticSeverity.Info,
         isEnabledByDefault: false,
-        description: "Enforce multi-line XML documentation comment syntax for consistency.",
+        description: "Enforce multi-line XML documentation comment syntax for <summary> elements.",
         helpLinkUri: RuleIdentifiers.GetHelpUri(RuleIdentifiers.UseMultiLineXmlCommentSyntax));
 
     public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(Rule);
@@ -55,40 +54,16 @@ private static void AnalyzeSymbol(SymbolAnalysisContext context)
                     if (childNode is not XmlElementSyntax elementSyntax)
                         continue;
 
+                    if (!string.Equals(elementSyntax.StartTag.Name.LocalName.ValueText, "summary", StringComparison.Ordinal))
+                        continue;
+
                     var startLine = elementSyntax.StartTag.GetLocation().GetLineSpan().StartLinePosition.Line;
                     var endLine = elementSyntax.EndTag.GetLocation().GetLineSpan().EndLinePosition.Line;
                     if (endLine != startLine)
                         continue;
 
-                    var hasCDataOrOtherElements = false;
-                    var meaningfulTextTokenCount = 0;
-                    foreach (var content in elementSyntax.Content)
-                    {
-                        if (content is XmlTextSyntax textSyntax)
-                        {
-                            foreach (var token in textSyntax.TextTokens)
-                            {
-                                if (token.IsKind(SyntaxKind.XmlTextLiteralNewLineToken))
-                                    continue;
-
-                                var text = token.Text.Trim();
-                                if (!string.IsNullOrWhiteSpace(text))
-                                {
-                                    meaningfulTextTokenCount++;
-                                }
-                            }
-                        }
-                        else if (content is XmlCDataSectionSyntax || content is XmlElementSyntax)
-                        {
-                            hasCDataOrOtherElements = true;
-                            break;
-                        }
-                    }
-
-                    if (!hasCDataOrOtherElements && meaningfulTextTokenCount <= 1)
-                    {
+                    if (!string.IsNullOrWhiteSpace(string.Concat(elementSyntax.Content.Select(static content => content.ToFullString()))))
                         context.ReportDiagnostic(Diagnostic.Create(Rule, elementSyntax.GetLocation()));
-                    }
                 }
             }
         }
diff --git a/tests/Meziantou.Analyzer.Test/Rules/UseMultiLineXmlCommentSyntaxAnalyzerTests.cs b/tests/Meziantou.Analyzer.Test/Rules/UseMultiLineXmlCommentSyntaxAnalyzerTests.cs
@@ -32,74 +32,96 @@ class Sample { }
     }
 
     [Fact]
-    public async Task ParamSingleLine_ShouldReportDiagnostic()
+    public async Task SingleLineSummaryWithNestedElement_ShouldReportDiagnostic()
     {
         await CreateProjectBuilder()
               .WithSourceCode("""
-                  class Sample
-                  {
-                      /// {|MA0211:<param name="value">The value</param>|}
-                      public void Method(int value) { }
-                  }
+                  /// {|MA0211:<summary>This has <c>code</c> inside</summary>|}
+                  class Sample { }
                   """)
               .ShouldFixCodeWith("""
-                  class Sample
-                  {
-                      /// <param name="value">
-                      /// The value
-                      /// </param>
-                      public void Method(int value) { }
-                  }
+                  /// <summary>
+                  /// This has <c>code</c> inside
+                  /// </summary>
+                  class Sample { }
                   """)
               .ValidateAsync();
     }
 
     [Fact]
-    public async Task EmptyContent_ShouldReportDiagnostic()
+    public async Task SingleLineSummaryWithCData_ShouldReportDiagnostic()
     {
         await CreateProjectBuilder()
               .WithSourceCode("""
-                  /// {|MA0211:<summary></summary>|}
+                  /// {|MA0211:<summary><![CDATA[Sample]]></summary>|}
                   class Sample { }
                   """)
               .ShouldFixCodeWith("""
                   /// <summary>
+                  /// <![CDATA[Sample]]>
                   /// </summary>
                   class Sample { }
                   """)
               .ValidateAsync();
     }
 
     [Fact]
-    public async Task MultiLineDescription_ShouldNotReportDiagnostic()
+    public async Task EmptyContent_ShouldNotReportDiagnostic()
     {
         await CreateProjectBuilder()
               .WithSourceCode("""
-                  /// <summary>
-                  /// description
-                  /// </summary>
+                  /// <summary></summary>
                   class Sample { }
                   """)
               .ValidateAsync();
     }
 
     [Fact]
-    public async Task InnerXmlElements_ShouldNotReportDiagnostic()
+    public async Task ParamSingleLine_ShouldNotReportDiagnostic()
     {
         await CreateProjectBuilder()
               .WithSourceCode("""
-                  /// <summary>This has <c>code</c> inside</summary>
+                  class Sample
+                  {
+                      /// <param name="value">The value</param>
+                      public void Method(int value) { }
+                  }
+                  """)
+              .ValidateAsync();
+    }
+
+    [Fact]
+    public async Task SummaryContainingOnlyWhitespace_ShouldNotReportDiagnostic()
+    {
+        await CreateProjectBuilder()
+              .WithSourceCode("""
+                  /// <summary>   </summary>
                   class Sample { }
                   """)
               .ValidateAsync();
     }
 
     [Fact]
-    public async Task CDataSection_ShouldNotReportDiagnostic()
+    public async Task MultiLineDescription_ShouldNotReportDiagnostic()
     {
         await CreateProjectBuilder()
               .WithSourceCode("""
-                  /// <summary><![CDATA[Sample]]></summary>
+                  /// <summary>
+                  /// description
+                  /// </summary>
+                  class Sample { }
+                  """)
+              .ValidateAsync();
+    }
+
+    [Fact]
+    public async Task MultiLineSummaryWithNestedElement_ShouldNotReportDiagnostic()
+    {
+        await CreateProjectBuilder()
+              .WithSourceCode("""
+                  /// <summary>
+                  /// This has <c>code</c> inside
+                  /// </summary>
                   class Sample { }
                   """)
               .ValidateAsync();
