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

Fixes #2452

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1612UnitTests.cs

@@ -18,6 +18,8 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
     /// </summary>
     public class SA1612UnitTests : DiagnosticVerifier
     {
+        private string currentTestSettings;
+
         public static IEnumerable<object[]> Declarations
         {
             get
@@ -81,6 +83,68 @@ public class ClassName
             await this.VerifyCSharpDiagnosticAsync(testCode.Replace("$$", declaration), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Theory]
+        [MemberData(nameof(Declarations))]
+        [WorkItem(2452, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2452")]
+        public async Task TestMemberWithMissingNotRequiredParamAsync(string declaration)
+        {
+            var testCode = @"
+/// <summary>
+/// Foo
+/// </summary>
+public class ClassName
+{
+    /// <summary>
+    /// Foo
+    /// </summary>
+    ///<param name=""foo"">Test</param>
+    ///<param name=""new"">Test</param>
+$$
+}";
+
+            this.currentTestSettings = @"
+{
+  ""settings"": {
+    ""documentationRules"": {
+      ""documentExposedElements"": false
+    }
+  }
+}
+";
+            await this.VerifyCSharpDiagnosticAsync(testCode.Replace("$$", declaration), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        [Theory]
+        [MemberData(nameof(Declarations))]
+        [WorkItem(2452, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2452")]
+        public async Task TestMemberWithMissingNotRequiredReorderedParamAsync(string declaration)
+        {
+            var testCode = @"
+/// <summary>
+/// Foo
+/// </summary>
+public class ClassName
+{
+    /// <summary>
+    /// Foo
+    /// </summary>
+    ///<param name=""new"">Test</param>
+    ///<param name=""foo"">Test</param>
+$$
+}";
+
+            var diagnostic = this.CSharpDiagnostic()
+                .WithMessageFormat("The parameter documentation for '{0}' should be at position {1}.");
+
+            var expected = new[]
+            {
+                diagnostic.WithLocation(10, 21).WithArguments("new", 3),
+                diagnostic.WithLocation(11, 21).WithArguments("foo", 1),
+            };
+
+            await this.VerifyCSharpDiagnosticAsync(testCode.Replace("$$", declaration), expected, CancellationToken.None).ConfigureAwait(false);
+        }
+
         [Theory]
         [MemberData(nameof(Declarations))]
         public async Task TestMemberWithInvalidParamsAsync(string declaration)
@@ -301,6 +365,27 @@ public class ClassName
             };
 
             await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
+
+            // This is even reported if the documentation is not required, except that no warning is reported for the
+            // first param element (which is actually the last parameter) since it would otherwise be allowed to skip
+            // the documentation for the first two parameters.
+            this.currentTestSettings = @"
+{
+  ""settings"": {
+    ""documentationRules"": {
+      ""documentExposedElements"": false
+    }
+  }
+}
+";
+
+            expected = new[]
+            {
+                diagnostic.WithLocation(8, 22).WithArguments("bar", 1),
+                diagnostic.WithLocation(8, 22).WithArguments("new", 2),
+            };
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
         }
 
         [Fact]
@@ -428,6 +513,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 SA1612ElementParameterDocumentationMustMatchElementParameters();

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1612ElementParameterDocumentationMustMatchElementParameters.cs

@@ -97,14 +97,27 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool
                 {
                     context.ReportDiagnostic(Diagnostic.Create(MissingParameterDescriptor, location ?? identifierLocation, nameAttributeText));
                 }
-                else if (parentParameters.Length <= index || parentParameters[index] != parentParameter)
+                else
                 {
-                    context.ReportDiagnostic(
-                        Diagnostic.Create(
-                            OrderDescriptor,
-                            location ?? identifierLocation,
-                            nameAttributeText,
-                            parentParameters.IndexOf(parentParameter) + 1));
+                    if (!needsComment)
+                    {
+                        // Parameter documentation is allowed to be omitted, so skip parameters for which there is no
+                        // documentation.
+                        while (index < parentParameters.Length && parentParameters[index] != parentParameter)
+                        {
+                            index++;
+                        }
+                    }
+
+                    if (parentParameters.Length <= index || parentParameters[index] != parentParameter)
+                    {
+                        context.ReportDiagnostic(
+                            Diagnostic.Create(
+                                OrderDescriptor,
+                                location ?? identifierLocation,
+                                nameAttributeText,
+                                parentParameters.IndexOf(parentParameter) + 1));
+                    }
                 }
 
                 index++;
@@ -155,14 +168,27 @@ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext co
                 {
                     context.ReportDiagnostic(Diagnostic.Create(MissingParameterDescriptor, identifierLocation, nameAttributeText));
                 }
-                else if (parentParameters.Length <= index || parentParameters[index] != parentParameter)
+                else
                 {
-                    context.ReportDiagnostic(
-                        Diagnostic.Create(
-                            OrderDescriptor,
-                            identifierLocation,
-                            nameAttributeText,
-                            parentParameters.IndexOf(parentParameter) + 1));
+                    if (!needsComment)
+                    {
+                        // Parameter documentation is allowed to be omitted, so skip parameters for which there is no
+                        // documentation.
+                        while (index < parentParameters.Length && parentParameters[index] != parentParameter)
+                        {
+                            index++;
+                        }
+                    }
+
+                    if (parentParameters.Length <= index || parentParameters[index] != parentParameter)
+                    {
+                        context.ReportDiagnostic(
+                            Diagnostic.Create(
+                                OrderDescriptor,
+                                identifierLocation,
+                                nameAttributeText,
+                                parentParameters.IndexOf(parentParameter) + 1));
+                    }
                 }
 
                 index++;