Update SA1611 to suppress messages when documentation for an element …

…is optional Fixes DotNetAnalyzers#2444
sharwell · Jun 20, 2017 · b99dd6e · b99dd6e
1 parent 5400cf3
commit b99dd6e
Show file tree

Hide file tree

Showing 9 changed files with 120 additions and 52 deletions.
diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs
@@ -154,6 +154,25 @@ public class ClassName
             await this.VerifyCSharpDiagnosticAsync(testCode.Replace("##", p), expected, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Fact]
+        [WorkItem(2444, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2444")]
+        public async Task TestPrivateMethodMissingParametersAsync()
+        {
+            var testCode = @"
+internal class ClassName
+{
+    ///
+    private void Test1(int arg) { }
+
+    /**
+     *
+     */
+    private void Test2(int arg) { }
+}";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Verifies that valid operator declarations will not produce diagnostics.
         /// </summary>

diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/ElementDocumentationBase.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/ElementDocumentationBase.cs
diff --git a/...leCop.Analyzers/DocumentationRules/SA1608ElementDocumentationMustNotHaveDefaultSummary.cs b/...leCop.Analyzers/DocumentationRules/SA1608ElementDocumentationMustNotHaveDefaultSummary.cs
@@ -59,7 +59,7 @@ public SA1608ElementDocumentationMustNotHaveDefaultSummary()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             foreach (var syntax in syntaxList)
             {
@@ -79,7 +79,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             // We are working with an <include> element
             var includedSummaryElement = completeDocumentation.Nodes().OfType<XElement>().FirstOrDefault(element => element.Name == XmlCommentHelper.SummaryXmlTag);

diff --git a/...nalyzers/StyleCop.Analyzers/DocumentationRules/SA1611ElementParametersMustBeDocumented.cs b/...nalyzers/StyleCop.Analyzers/DocumentationRules/SA1611ElementParametersMustBeDocumented.cs
@@ -51,8 +51,14 @@ public SA1611ElementParametersMustBeDocumented()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
+            if (!needsComment)
+            {
+                // Omitting documentation for a parameter is allowed for this element.
+                return;
+            }
+
             var node = context.Node;
             var parameterList = GetParameters(node);
             if (parameterList == null)
@@ -69,8 +75,13 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
+            if (!needsComment)
+            {
+                // Omitting documentation for a parameter is allowed for this element.
+            }
+
             var node = context.Node;
             var parameterList = GetParameters(node);
             if (parameterList == null)

diff --git a/...yzers/DocumentationRules/SA1612ElementParameterDocumentationMustMatchElementParameters.cs b/...yzers/DocumentationRules/SA1612ElementParameterDocumentationMustMatchElementParameters.cs
@@ -57,7 +57,7 @@ public SA1612ElementParameterDocumentationMustMatchElementParameters()
             ImmutableArray.Create(MissingParameterDescriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             var node = context.Node;
             var identifier = GetIdentifier(node);
@@ -112,7 +112,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             var node = context.Node;
             var identifier = GetIdentifier(node);

diff --git a/...alyzers/DocumentationRules/SA1613ElementParameterDocumentationMustDeclareParameterName.cs b/...alyzers/DocumentationRules/SA1613ElementParameterDocumentationMustDeclareParameterName.cs
@@ -56,7 +56,7 @@ public SA1613ElementParameterDocumentationMustDeclareParameterName()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             foreach (var syntax in syntaxList)
             {
@@ -71,7 +71,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             var xmlParamTags = completeDocumentation.Nodes()
                 .OfType<XElement>()

diff --git a/.../StyleCop.Analyzers/DocumentationRules/SA1614ElementParameterDocumentationMustHaveText.cs b/.../StyleCop.Analyzers/DocumentationRules/SA1614ElementParameterDocumentationMustHaveText.cs
@@ -52,7 +52,7 @@ public SA1614ElementParameterDocumentationMustHaveText()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             foreach (var syntax in syntaxList)
             {
@@ -66,7 +66,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             var xmlParamTags = completeDocumentation.Nodes()
                 .OfType<XElement>()

diff --git a/...tyleCop.Analyzers/DocumentationRules/SA1616ElementReturnValueDocumentationMustHaveText.cs b/...tyleCop.Analyzers/DocumentationRules/SA1616ElementReturnValueDocumentationMustHaveText.cs
@@ -51,7 +51,7 @@ public SA1616ElementReturnValueDocumentationMustHaveText()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             foreach (var syntax in syntaxList)
             {
@@ -64,7 +64,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             var returnsNodes = completeDocumentation.Nodes()
                 .OfType<XElement>()

diff --git a/...yleCop.Analyzers/DocumentationRules/SA1625ElementDocumentationMustNotBeCopiedAndPasted.cs b/...yleCop.Analyzers/DocumentationRules/SA1625ElementDocumentationMustNotBeCopiedAndPasted.cs
@@ -87,7 +87,7 @@ public SA1625ElementDocumentationMustNotBeCopiedAndPasted()
             ImmutableArray.Create(Descriptor);
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)
         {
             var objectPool = SharedPools.Default<HashSet<string>>();
             HashSet<string> documentationTexts = objectPool.Allocate();
@@ -119,7 +119,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu
         }
 
         /// <inheritdoc/>
-        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)
+        protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)
         {
             var objectPool = SharedPools.Default<HashSet<string>>();
             HashSet<string> documentationTexts = objectPool.Allocate();