Updated SA1617

Author: vweijsters

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/SA1617CodeFixProvider.cs

@@ -39,12 +39,15 @@ public override Task RegisterCodeFixesAsync(CodeFixContext context)
         {
             foreach (Diagnostic diagnostic in context.Diagnostics)
             {
-                context.RegisterCodeFix(
-                    CodeAction.Create(
-                        DocumentationResources.SA1617CodeFix,
-                        cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
-                        nameof(SA1617CodeFixProvider)),
-                    diagnostic);
+                if (!diagnostic.Properties.ContainsKey(SA1617VoidReturnValueMustNotBeDocumented.NoCodeFixKey))
+                {
+                    context.RegisterCodeFix(
+                        CodeAction.Create(
+                            DocumentationResources.SA1617CodeFix,
+                            cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
+                            nameof(SA1617CodeFixProvider)),
+                        diagnostic);
+                }
             }
 
             return SpecializedTasks.CompletedTask;

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1617UnitTests.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.CodeFixes;
     using Microsoft.CodeAnalysis.Diagnostics;
     using TestHelper;
@@ -262,6 +264,105 @@ public void Method() { }
             await this.VerifyCSharpFixAsync(testCode, fixedCode).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Verifies that included method documentation without a returns tag will be accepted.
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task TestMethodWithValidIncludeAsync()
+        {
+            var testCode = @"
+public class ClassName
+{
+    /// <include file='MethodWithoutReturns.xml' path='/ClassName/Method/*'/>
+    public void Method() { }
+}";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Verifies that included method documentation with a returns tag will be flagged.
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task TestMethodWithReturnsInIncludeAsync()
+        {
+            var testCode = @"
+public class ClassName
+{
+    /// <include file='MethodWithReturns.xml' path='/ClassName/Method/*'/>
+    public void Method() { }
+}";
+
+            var expected = this.CSharpDiagnostic().WithLocation(4, 9);
+            await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
+            var offeredFixes = await this.GetOfferedCSharpFixesAsync(testCode).ConfigureAwait(false);
+            Assert.Empty(offeredFixes);
+        }
+
+        /// <summary>
+        /// Verifies that included method documentation containing &gt;inheritdoc/&lt; will be accepted.
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task TestMethodWithInheritdocInIncludeAsync()
+        {
+            var testCode = @"
+public interface ITestInterface
+{
+  /// <summary>
+  /// Foo bar.
+  /// </summary>
+  void Method();
+}
+
+public class ClassName : ITestInterface
+{
+    /// <include file='MethodWithInheritdoc.xml' path='/ClassName/Method/*'/>
+    public void Method() { }
+}";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        protected override Project ApplyCompilationOptions(Project project)
+        {
+            var resolver = new TestXmlReferenceResolver();
+
+            string contentWithoutReturns = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+  <Method>
+    <summary>Foo</summary>
+  </Method>
+</ClassName>
+";
+            resolver.XmlReferences.Add("MethodWithoutReturns.xml", contentWithoutReturns);
+
+            string contentWithReturns = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+  <Method>
+    <summary>Foo</summary>
+    <returns>Bar</returns>
+  </Method>
+</ClassName>
+";
+            resolver.XmlReferences.Add("MethodWithReturns.xml", contentWithReturns);
+
+            string contentWithInheritdocValue = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
+<ClassName>
+  <Method>
+    <inheritdoc/>
+  </Method>
+</ClassName>
+";
+            resolver.XmlReferences.Add("MethodWithInheritdoc.xml", contentWithInheritdocValue);
+
+            project = base.ApplyCompilationOptions(project);
+            project = project.WithCompilationOptions(project.CompilationOptions.WithXmlReferenceResolver(resolver));
+            return project;
+        }
+
         protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
         {
             yield return new SA1617VoidReturnValueMustNotBeDocumented();

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1617VoidReturnValueMustNotBeDocumented.cs

@@ -5,6 +5,8 @@ namespace StyleCop.Analyzers.DocumentationRules
 {
     using System;
     using System.Collections.Immutable;
+    using System.Linq;
+    using System.Xml.Linq;
     using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.CSharp;
     using Microsoft.CodeAnalysis.CSharp.Syntax;
@@ -32,6 +34,12 @@ internal class SA1617VoidReturnValueMustNotBeDocumented : DiagnosticAnalyzer
         /// The ID for diagnostics produced by the <see cref="SA1617VoidReturnValueMustNotBeDocumented"/> analyzer.
         /// </summary>
         public const string DiagnosticId = "SA1617";
+
+        /// <summary>
+        /// The key used for signalling that no codefix should be offered.
+        /// </summary>
+        internal const string NoCodeFixKey = "NoCodeFix";
+
         private const string Title = "Void return value must not be documented";
         private const string MessageFormat = "Void return value must not be documented";
         private const string Description = "A C# code element does not contain a return value, or returns void, but the documentation header for the element contains a <returns> tag.";
@@ -82,8 +90,32 @@ private static void HandleMember(SyntaxNodeAnalysisContext context, TypeSyntax r
                 {
                     // Check if the return value is documented
                     var returnsElement = documentation.Content.GetFirstXmlElement(XmlCommentHelper.ReturnsXmlTag);
+                    if (returnsElement == null)
+                    {
+                        var includeElement = documentation.Content.GetFirstXmlElement(XmlCommentHelper.IncludeXmlTag);
+                        if (includeElement != null)
+                        {
+                            string rawDocumentation;
+                            var declaration = context.SemanticModel.GetDeclaredSymbol(context.Node, context.CancellationToken);
+                            rawDocumentation = declaration?.GetDocumentationCommentXml(expandIncludes: true, cancellationToken: context.CancellationToken);
+                            var completeDocumentation = XElement.Parse(rawDocumentation, LoadOptions.None);
+                            if (completeDocumentation.Nodes().OfType<XElement>().Any(element => element.Name == XmlCommentHelper.InheritdocXmlTag))
+                            {
+                                // Ignore nodes with an <inheritdoc/> tag in the included XML.
+                                return;
+                            }
+
+                            var includedReturnsElement = completeDocumentation.Nodes().OfType<XElement>().FirstOrDefault(element => element.Name == XmlCommentHelper.ReturnsXmlTag);
+                            if (includedReturnsElement != null)
+                            {
+                                var properties = ImmutableDictionary.Create<string, string>()
+                                    .Add(NoCodeFixKey, string.Empty);
 
-                    if (returnsElement != null)
+                                context.ReportDiagnostic(Diagnostic.Create(Descriptor, includeElement.GetLocation(), properties));
+                            }
+                        }
+                    }
+                    else
                     {
                         context.ReportDiagnostic(Diagnostic.Create(Descriptor, returnsElement.GetLocation()));
                     }