Merge pull request #3174 from angelobreuer/fix-3173

#3173 - SA1611 ignores included documentation

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs

@@ -313,6 +313,55 @@ public void TestMethod(string param1, string param2, string param3)
             await VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Verifies that included documentation with missing elements documented produces the expected diagnostics.
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task VerifyIncludedPartialDocumentationMissingElementsAsync()
+        {
+            var testCode = @"
+/// <summary>
+/// Foo
+/// </summary>
+public class ClassName
+{
+    /// <include file='WithPartialElementDocumentation.xml' path='/TestClass/TestMethod/*' />
+    public void TestMethod(string param1, string param2, string param3)
+    {
+    }
+}";
+            DiagnosticResult[] expected =
+            {
+                Diagnostic().WithLocation(8, 35).WithArguments("param1"),
+            };
+
+            await VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Verifies that included documentation with missing elements documented produces the expected diagnostics.
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task VerifyIncludedPartialDocumentationElementsAsync()
+        {
+            var testCode = @"
+/// <summary>
+/// Foo
+/// </summary>
+public class ClassName
+{
+    /// <param name=""param1"">Param 1</param>
+    /// <include file='WithPartialElementDocumentation.xml' path='/TestClass/TestMethod/*' />
+    public void TestMethod(string param1, string param2, string param3)
+    {
+    }
+}";
+
+            await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Verifies that included documentation with an <c>&lt;inheritdoc&gt;</c> tag is ignored.
         /// </summary>
@@ -356,6 +405,17 @@ private static Task VerifyCSharpDiagnosticAsync(string source, DiagnosticResult[
         <param name=""param3"">Param 3</param>
     </TestMethod>
 </TestClass>
+";
+            string contentWithPartialElementDocumentation = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<TestClass>
+    <TestMethod>
+        <summary>
+            Foo
+        </summary>
+        <param name=""param2"">Param 2</param>
+        <param name=""param3"">Param 3</param>
+    </TestMethod>
+</TestClass>
 ";
             string contentWithInheritedDocumentation = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
  <TestClass>
@@ -372,6 +432,7 @@ private static Task VerifyCSharpDiagnosticAsync(string source, DiagnosticResult[
                 {
                     { "MissingElementDocumentation.xml", contentWithoutElementDocumentation },
                     { "WithElementDocumentation.xml", contentWithElementDocumentation },
+                    { "WithPartialElementDocumentation.xml", contentWithPartialElementDocumentation },
                     { "InheritedDocumentation.xml", contentWithInheritedDocumentation },
                 },
             };

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/ElementDocumentationBase.cs

@@ -229,34 +229,34 @@ private void HandleDeclaration(SyntaxNodeAnalysisContext context, StyleCopSettin
                 return;
             }
 
-            IEnumerable<XmlNodeSyntax> matchingXmlElements = string.IsNullOrEmpty(this.matchElementName)
-                ? documentation.Content
-                    .Where(x => x is XmlElementSyntax || x is XmlEmptyElementSyntax)
-                    .Where(x => !string.Equals(x.GetName()?.ToString(), XmlCommentHelper.IncludeXmlTag, StringComparison.Ordinal))
-                : documentation.Content.GetXmlElements(this.matchElementName);
+            var hasIncludedDocumentation =
+                documentation.Content.GetFirstXmlElement(XmlCommentHelper.IncludeXmlTag) is object;
 
-            if (!matchingXmlElements.Any())
+            if (hasIncludedDocumentation)
             {
-                var includedDocumentation = documentation.Content.GetFirstXmlElement(XmlCommentHelper.IncludeXmlTag);
-                if (includedDocumentation != null)
+                var declaration = context.SemanticModel.GetDeclaredSymbol(node, context.CancellationToken);
+                var rawDocumentation = declaration?.GetDocumentationCommentXml(expandIncludes: true, cancellationToken: context.CancellationToken);
+                var completeDocumentation = XElement.Parse(rawDocumentation, LoadOptions.None);
+
+                if (this.inheritDocSuppressesWarnings &&
+                    completeDocumentation.Nodes().OfType<XElement>().Any(element => element.Name == XmlCommentHelper.InheritdocXmlTag))
                 {
-                    var declaration = context.SemanticModel.GetDeclaredSymbol(node, context.CancellationToken);
-                    var rawDocumentation = declaration?.GetDocumentationCommentXml(expandIncludes: true, cancellationToken: context.CancellationToken);
-                    var completeDocumentation = XElement.Parse(rawDocumentation, LoadOptions.None);
-
-                    if (this.inheritDocSuppressesWarnings &&
-                        completeDocumentation.Nodes().OfType<XElement>().Any(element => element.Name == XmlCommentHelper.InheritdocXmlTag))
-                    {
-                        // Ignore nodes with an <inheritdoc/> tag in the included XML.
-                        return;
-                    }
-
-                    this.HandleCompleteDocumentation(context, needsComment, completeDocumentation, locations);
-                    return; // done
+                    // Ignore nodes with an <inheritdoc/> tag in the included XML.
+                    return;
                 }
+
+                this.HandleCompleteDocumentation(context, needsComment, completeDocumentation, locations);
             }
+            else
+            {
+                IEnumerable<XmlNodeSyntax> matchingXmlElements = string.IsNullOrEmpty(this.matchElementName)
+                    ? documentation.Content
+                        .Where(x => x is XmlElementSyntax || x is XmlEmptyElementSyntax)
+                        .Where(x => !string.Equals(x.GetName()?.ToString(), XmlCommentHelper.IncludeXmlTag, StringComparison.Ordinal))
+                    : documentation.Content.GetXmlElements(this.matchElementName);
 
-            this.HandleXmlElement(context, settings, needsComment, matchingXmlElements, locations);
+                this.HandleXmlElement(context, settings, needsComment, matchingXmlElements, locations);
+            }
         }
     }
 }