Update SA1619 to suppress messages when documentation for an element is optional

Fixes #2453

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1619UnitTests.cs

@@ -6,9 +6,9 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
     using System.Collections.Generic;
     using System.Threading;
     using System.Threading.Tasks;
-    using Analyzers.DocumentationRules;
     using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.Diagnostics;
+    using StyleCop.Analyzers.DocumentationRules;
     using StyleCop.Analyzers.Test.Helpers;
     using TestHelper;
     using Xunit;
@@ -18,6 +18,8 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
     /// </summary>
     public class SA1619UnitTests : DiagnosticVerifier
     {
+        private string currentTestSettings;
+
         public static IEnumerable<object[]> Types
         {
             get
@@ -122,6 +124,32 @@ public async Task TestPartialTypesWithMissingDocumentationAsync(string p)
             await this.VerifyCSharpDiagnosticAsync(testCode.Replace("##", p), expected, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Theory]
+        [MemberData(nameof(Types))]
+        [WorkItem(2453, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2453")]
+        public async Task TestPartialTypesWithMissingButNotRequiredDocumentationAsync(string p)
+        {
+            var testCode = @"
+/// <summary>
+/// Foo
+/// </summary>
+public partial ##";
+
+            // This situation is allowed if 'documentExposedElements' and 'documentInterfaces' is false
+            string interfaceSettingName = p.StartsWith("interface ") ? "documentInterfaces" : "ignoredProperty";
+            this.currentTestSettings = $@"
+{{
+  ""settings"": {{
+    ""documentationRules"": {{
+      ""documentExposedElements"": false,
+      ""{interfaceSettingName}"": false
+    }}
+  }}
+}}
+";
+            await this.VerifyCSharpDiagnosticAsync(testCode.Replace("##", p), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
         [Theory]
         [MemberData(nameof(Types))]
         public async Task TestNonPartialTypesWithMissingDocumentationAsync(string p)
@@ -200,6 +228,31 @@ public partial class TestClass<T>
             await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Fact]
+        [WorkItem(2453, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2453")]
+        public async Task TestGenericPartialTypeWithoutTypeparamInIncludedButNotRequiredDocumentationAsync()
+        {
+            var testCode = @"
+/// <include file='ClassWithoutTypeparamDoc.xml' path='/TestClass/*'/>
+public partial class TestClass<T>
+{
+}
+";
+
+            // The situation is allowed if 'documentExposedElements' false
+            this.currentTestSettings = @"
+{
+  ""settings"": {
+    ""documentationRules"": {
+      ""documentExposedElements"": false
+    }
+  }
+}
+";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Verifies that a generic partial type with &lt;inheritdoc&gt; in included documentation will work.
         /// </summary>
@@ -254,6 +307,11 @@ protected override Project ApplyCompilationOptions(Project project)
             return project;
         }
 
+        protected override string GetSettings()
+        {
+            return this.currentTestSettings ?? base.GetSettings();
+        }
+
         protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
         {
             yield return new SA1619GenericTypeParametersMustBeDocumentedPartialClass();

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1619GenericTypeParametersMustBeDocumentedPartialClass.cs

@@ -12,6 +12,7 @@ namespace StyleCop.Analyzers.DocumentationRules
     using Microsoft.CodeAnalysis.CSharp.Syntax;
     using Microsoft.CodeAnalysis.Diagnostics;
     using StyleCop.Analyzers.Helpers;
+    using StyleCop.Analyzers.Settings.ObjectModel;
 
     /// <summary>
     /// A generic, partial C# element is missing documentation for one or more of its generic type parameters, and the
@@ -91,7 +92,7 @@ internal class SA1619GenericTypeParametersMustBeDocumentedPartialClass : Diagnos
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
 
-        private static readonly Action<SyntaxNodeAnalysisContext> TypeDeclarationAction = HandleTypeDeclaration;
+        private static readonly Action<SyntaxNodeAnalysisContext, StyleCopSettings> TypeDeclarationAction = HandleTypeDeclaration;
 
         /// <inheritdoc/>
         public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } =
@@ -106,7 +107,7 @@ public override void Initialize(AnalysisContext context)
             context.RegisterSyntaxNodeAction(TypeDeclarationAction, SyntaxKinds.TypeDeclaration);
         }
 
-        private static void HandleTypeDeclaration(SyntaxNodeAnalysisContext context)
+        private static void HandleTypeDeclaration(SyntaxNodeAnalysisContext context, StyleCopSettings settings)
         {
             TypeDeclarationSyntax typeDeclaration = (TypeDeclarationSyntax)context.Node;
 
@@ -129,6 +130,15 @@ private static void HandleTypeDeclaration(SyntaxNodeAnalysisContext context)
                 return;
             }
 
+            Accessibility declaredAccessibility = typeDeclaration.GetDeclaredAccessibility(context.SemanticModel, context.CancellationToken);
+            Accessibility effectiveAccessibility = typeDeclaration.GetEffectiveAccessibility(context.SemanticModel, context.CancellationToken);
+            bool needsComment = SA1600ElementsMustBeDocumented.NeedsComment(settings.DocumentationRules, typeDeclaration.Kind(), typeDeclaration.Parent.Kind(), declaredAccessibility, effectiveAccessibility);
+            if (!needsComment)
+            {
+                // Omitting documentation is allowed for this element.
+                return;
+            }
+
             var includeElement = documentation.Content.GetFirstXmlElement(XmlCommentHelper.IncludeXmlTag);
             if (includeElement != null)
             {