Merge pull request DotNetAnalyzers#3861 from MattFromRVA/SA1642_Fix

SA1642: Allow <para> Tags in Constructor Documentation

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs

@@ -1061,6 +1061,36 @@ public ClassName()
             await VerifyCSharpFixAsync(testCode, expected, fixedCode, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Fact]
+        [WorkItem(3575, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3575")]
+        public async Task TestConstructorSummaryWithParaTagsAsync()
+        {
+            var testCode = @"
+using System;
+/// <summary>
+/// Does a thing.
+/// </summary>
+public class B
+{
+    /// <summary>
+    /// <para>
+    /// Initializes a new instance of the <see cref=""B""/> class.
+    /// </para>
+    /// <para>
+    /// Some more info about B.
+    /// </para>
+    /// </summary>
+    public B()
+    {
+    }
+}
+";
+
+            var expectedDiagnostics = DiagnosticResult.EmptyDiagnosticResults;
+
+            await VerifyCSharpFixAsync(testCode, expectedDiagnostics, testCode, CancellationToken.None).ConfigureAwait(false);
+        }
+
         private static async Task TestEmptyConstructorAsync(string typeKind, string modifiers)
         {
             var testCode = @"namespace FooNamespace

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/StandardTextDiagnosticBase.cs

@@ -122,6 +122,26 @@ protected static MatchResult HandleDeclaration(SyntaxNodeAnalysisContext context
                 diagnosticLocation = summaryElement.GetLocation();
                 diagnosticProperties = ImmutableDictionary.Create<string, string>();
 
+                // Handle empty or whitespace-only summary content
+                var firstElementWithContent = XmlCommentHelper.TryGetFirstTextElementWithContent(summaryElement);
+                if (firstElementWithContent == null)
+                {
+                    // Report the diagnostic for empty or whitespace-only summaries
+                    if (diagnosticDescriptor != null)
+                    {
+                        context.ReportDiagnostic(Diagnostic.Create(diagnosticDescriptor, diagnosticLocation, diagnosticProperties));
+                    }
+
+                    return MatchResult.None;
+                }
+
+                // Check if the summary content starts with a <para> tag
+                if (firstElementWithContent != null && firstElementWithContent.Parent is XmlElementSyntax firstElement && firstElement.StartTag.Name.ToString() == "para")
+                {
+                    // We found a correct standard text
+                    return MatchResult.FoundMatch;
+                }
+
                 // Check if the summary content could be a correct standard text
                 if (summaryElement.Content.Count >= 3)
                 {

documentation/SA1642.md

@@ -96,6 +96,23 @@ private Customer()
 }
 ```
 
+The `<para>` tag can be used within the `<summary>` tag to structure the text. 
+For example:
+
+```csharp
+/// <summary>
+/// <para>
+/// Initializes a new instance of the <see cref="Customer"/> class.
+/// </para>
+/// <para>
+/// Additional information can be included in subsequent paragraphs.
+/// </para>
+/// </summary>
+public Customer()
+{
+}
+```
+
 ## How to fix violations
 
 To fix a violation of this rule, edit the summary text for the constructor as described above.