Merge pull request #2864 from sharwell/allow-para

Allow property standard summary text to use paragraph elements

Author: vweijsters

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/PropertySummaryDocumentationCodeFixProvider.cs

@@ -62,7 +62,7 @@ private static async Task<Document> GetTransformedDocumentAsync(Document documen
             var documentation = node.GetDocumentationCommentTriviaSyntax();
 
             var summaryElement = (XmlElementSyntax)documentation.Content.GetFirstXmlElement(XmlCommentHelper.SummaryXmlTag);
-            var textElement = (XmlTextSyntax)summaryElement.Content.FirstOrDefault();
+            var textElement = XmlCommentHelper.TryGetFirstTextElementWithContent(summaryElement);
             if (textElement == null)
             {
                 return document;

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs

@@ -168,6 +168,106 @@ public int Property
             await VerifyCSharpFixAsync(testCode, expected, testCode, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Fact]
+        [WorkItem(1934, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1934")]
+        public async Task SummaryInParagraphIsAllowedAsync()
+        {
+            var testCode = @"public class ClassName
+{
+    /// <summary><para>Gets the first test value.</para></summary>
+    public int Property1
+    {
+        get;
+    }
+
+    /// <summary>
+    /// <para>Gets the second test value.</para>
+    /// </summary>
+    public int Property2
+    {
+        get;
+    }
+
+    /// <summary>
+    /// <para>
+    /// Gets the third test value.
+    /// </para>
+    /// </summary>
+    public int Property3
+    {
+        get;
+    }
+}";
+
+            await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        [Fact]
+        [WorkItem(1934, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1934")]
+        public async Task SummaryInParagraphCanBeFixedAsync()
+        {
+            var testCode = @"public class ClassName
+{
+    /// <summary><para>Gets the first test value.</para></summary>
+    public int Property1
+    {
+        set { }
+    }
+
+    /// <summary>
+    /// <para>Gets the second test value.</para>
+    /// </summary>
+    public int Property2
+    {
+        set { }
+    }
+
+    /// <summary>
+    /// <para>
+    /// Gets the third test value.
+    /// </para>
+    /// </summary>
+    public int Property3
+    {
+        set { }
+    }
+}";
+            var fixedTestCode = @"public class ClassName
+{
+    /// <summary><para>Sets the first test value.</para></summary>
+    public int Property1
+    {
+        set { }
+    }
+
+    /// <summary>
+    /// <para>Sets the second test value.</para>
+    /// </summary>
+    public int Property2
+    {
+        set { }
+    }
+
+    /// <summary>
+    /// <para>
+    /// Sets the third test value.
+    /// </para>
+    /// </summary>
+    public int Property3
+    {
+        set { }
+    }
+}";
+
+            DiagnosticResult[] expected =
+            {
+                Diagnostic(PropertySummaryDocumentationAnalyzer.SA1623Descriptor).WithLocation(4, 16).WithArguments("Sets"),
+                Diagnostic(PropertySummaryDocumentationAnalyzer.SA1623Descriptor).WithLocation(12, 16).WithArguments("Sets"),
+                Diagnostic(PropertySummaryDocumentationAnalyzer.SA1623Descriptor).WithLocation(22, 16).WithArguments("Sets"),
+            };
+            await VerifyCSharpFixAsync(testCode, expected, fixedTestCode, CancellationToken.None).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Verifies that an incorrect summary tag with a known prefix will be fixed correctly.
         /// </summary>

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs

@@ -126,7 +126,8 @@ private static void AnalyzeSummaryElement(SyntaxNodeAnalysisContext context, Xml
                 diagnosticProperties.Add(NoCodeFixKey, string.Empty);
             }
 
-            var text = !(summaryElement.Content.FirstOrDefault() is XmlTextSyntax textElement) ? string.Empty : XmlCommentHelper.GetText(textElement, true).TrimStart();
+            var textElement = XmlCommentHelper.TryGetFirstTextElementWithContent(summaryElement);
+            string text = textElement is null ? string.Empty : XmlCommentHelper.GetText(textElement, normalizeWhitespace: true).TrimStart();
 
             bool prefixIsGetsOrSets = text.StartsWith(startingTextGetsOrSets, StringComparison.OrdinalIgnoreCase);
             bool prefixIsGets = !prefixIsGetsOrSets && text.StartsWith(startingTextGets, StringComparison.OrdinalIgnoreCase);

StyleCop.Analyzers/StyleCop.Analyzers/Helpers/XmlCommentHelper.cs

@@ -170,6 +170,37 @@ internal static bool IsConsideredEmpty(XNode node)
             return true;
         }
 
+        /// <summary>
+        /// Returns the first <see cref="XmlTextSyntax"/> which is not simply empty or whitespace.
+        /// </summary>
+        /// <param name="node">The XML content to search.</param>
+        /// <returns>The first <see cref="XmlTextSyntax"/> which is not simply empty or whitespace, or
+        /// <see langword="null"/> if no such element exists.</returns>
+        internal static XmlTextSyntax TryGetFirstTextElementWithContent(XmlNodeSyntax node)
+        {
+            if (node is XmlEmptyElementSyntax)
+            {
+                return null;
+            }
+            else if (node is XmlTextSyntax xmlText)
+            {
+                return !IsConsideredEmpty(node) ? xmlText : null;
+            }
+            else if (node is XmlElementSyntax xmlElement)
+            {
+                foreach (var child in xmlElement.Content)
+                {
+                    var nestedContent = TryGetFirstTextElementWithContent(child);
+                    if (nestedContent != null)
+                    {
+                        return nestedContent;
+                    }
+                }
+            }
+
+            return null;
+        }
+
         /// <summary>
         /// Checks if a <see cref="SyntaxTrivia"/> contains a <see cref="DocumentationCommentTriviaSyntax"/> and returns
         /// <see langword="true"/> if it is considered empty.