Update SA1608 to handle included documentation (fixes #1900)

Author: nbarbettini

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1608UnitTests.cs

@@ -7,6 +7,8 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
     using System.Threading;
     using System.Threading.Tasks;
     using Analyzers.DocumentationRules;
+    using Helpers;
+    using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.Diagnostics;
     using TestHelper;
     using Xunit;
@@ -142,7 +144,78 @@ public class ClassName
             await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
         }
 
-        protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
+        [Fact]
+        public async Task TestClassWithIncludedEmptyDocumentationAsync()
+        {
+            var testCode = @"
+/// <include file='ClassWithoutSummary.xml' path='/ClassName/*' />
+public class ClassName
+{
+}";
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        [Fact]
+        public async Task TestClassWithIncludedSummaryDocumentationAsync()
+        {
+            var testCode = @"
+/// <include file='ClassWithSummary.xml' path='/ClassName/*' />
+public class ClassName
+{
+}";
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        [Fact]
+        public async Task TestClassWithIncludedDefaultSummaryDocumentationAsync()
+        {
+            var testCode = @"
+/// <include file='ClassWithDefaultSummary.xml' path='/ClassName/*' />
+public class ClassName
+{
+}";
+
+            DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(3, 14);
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        /// <inheritdoc/>
+        protected override Project CreateProject(string[] sources, string language = "C#", string[] filenames = null)
+        {
+            var resolver = new TestXmlReferenceResolver();
+
+            string contentWithoutSummary = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+</ClassName>
+";
+            resolver.XmlReferences.Add("ClassWithoutSummary.xml", contentWithoutSummary);
+
+            string contentWithSummary = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+  <summary>
+    Foo
+  </summary>
+</ClassName>
+";
+            resolver.XmlReferences.Add("ClassWithSummary.xml", contentWithSummary);
+
+            string contentWithDefaultSummary = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+  <summary>
+    Summary description for the ClassName class.
+  </summary>
+</ClassName>
+";
+            resolver.XmlReferences.Add("ClassWithDefaultSummary.xml", contentWithDefaultSummary);
+
+            Project project = base.CreateProject(sources, language, filenames);
+            project = project.WithCompilationOptions(project.CompilationOptions.WithXmlReferenceResolver(resolver));
+            return project;
+        }
+
+    /// <inheritdoc/>
+    protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
         {
             yield return new SA1608ElementDocumentationMustNotHaveDefaultSummary();
         }

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1608ElementDocumentationMustNotHaveDefaultSummary.cs

@@ -5,6 +5,8 @@ namespace StyleCop.Analyzers.DocumentationRules
 {
     using System;
     using System.Collections.Immutable;
+    using System.Linq;
+    using System.Xml.Linq;
     using Helpers;
     using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.CSharp;
@@ -30,7 +32,7 @@ namespace StyleCop.Analyzers.DocumentationRules
     /// default documentation text generated by Visual Studio.</para>
     /// </remarks>
     [DiagnosticAnalyzer(LanguageNames.CSharp)]
-    internal class SA1608ElementDocumentationMustNotHaveDefaultSummary : DiagnosticAnalyzer
+    internal class SA1608ElementDocumentationMustNotHaveDefaultSummary : ElementDocumentationSummaryBase
     {
         /// <summary>
         /// The ID for diagnostics produced by the <see cref="SA1608ElementDocumentationMustNotHaveDefaultSummary"/>
@@ -47,50 +49,57 @@ internal class SA1608ElementDocumentationMustNotHaveDefaultSummary : DiagnosticA
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
 
-        private static readonly Action<CompilationStartAnalysisContext> CompilationStartAction = HandleCompilationStart;
-        private static readonly Action<SyntaxNodeAnalysisContext> DocumentationAction = HandleDocumentation;
+        private static readonly ImmutableArray<SyntaxKind> DocumentationCommentKinds =
+            ImmutableArray.Create(SyntaxKind.SingleLineDocumentationCommentTrivia, SyntaxKind.MultiLineDocumentationCommentTrivia);
 
         /// <inheritdoc/>
         public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } =
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        public override void Initialize(AnalysisContext context)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
-            context.RegisterCompilationStartAction(CompilationStartAction);
-        }
-
-        private static void HandleCompilationStart(CompilationStartAnalysisContext context)
+            if (completeDocumentation != null)
         {
-            context.RegisterSyntaxNodeActionHonorExclusions(DocumentationAction, SyntaxKinds.DocumentationComment);
-        }
-
-        private static void HandleDocumentation(SyntaxNodeAnalysisContext context)
+                // We are working with an <include> element
+                var includedSummaryElement = completeDocumentation.Nodes().OfType<XElement>().FirstOrDefault(element => element.Name == XmlCommentHelper.SummaryXmlTag);
+                if (includedSummaryElement != null)
         {
-            var documentationTrivia = context.Node as DocumentationCommentTriviaSyntax;
+                    string text = includedSummaryElement.Value;
 
-            if (documentationTrivia != null)
+                    if (IsDefaultText(text))
             {
-                var summaryElement = documentationTrivia.Content.GetFirstXmlElement(XmlCommentHelper.SummaryXmlTag) as XmlElementSyntax;
-
-                if (summaryElement != null)
-                {
-                    var textElement = summaryElement.Content.FirstOrDefault() as XmlTextSyntax;
+                        context.ReportDiagnostic(Diagnostic.Create(Descriptor, diagnosticLocations.First()));
+                        return;
+                    }
+                }
+            }
 
+            var summaryElement = syntax as XmlElementSyntax;
+            var textElement = summaryElement?.Content.FirstOrDefault() as XmlTextSyntax;
                     if (textElement != null)
                     {
                         string text = XmlCommentHelper.GetText(textElement, true);
 
-                        if (!string.IsNullOrEmpty(text))
-                        {
-                            if (text.TrimStart().StartsWith(DefaultText, StringComparison.Ordinal))
+                if (IsDefaultText(text))
                             {
                                 context.ReportDiagnostic(Diagnostic.Create(Descriptor, summaryElement.GetLocation()));
+                    return;
                             }
                         }
                     }
+
+        private static bool IsDefaultText(string text)
+        {
+            if (!string.IsNullOrEmpty(text))
+            {
+                if (text.TrimStart().StartsWith(DefaultText, StringComparison.Ordinal))
+                {
+                    return true;
                 }
             }
+
+            return false;
         }
     }
 }