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

sharwell · sharwell · commit c8137022d6bb · 2017-06-20T07:37:51.000-05:00
Fixes #2444
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/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1608ElementDocumentationMustNotHaveDefaultSummary.cs b/StyleCop.Analyzers/StyleCop.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/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1611ElementParametersMustBeDocumented.cs b/StyleCop.Analyzers/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,14 @@ 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.
+                return;
+            }
+
             var node = context.Node;
             var parameterList = GetParameters(node);
             if (parameterList == null)
diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1612ElementParameterDocumentationMustMatchElementParameters.cs b/StyleCop.Analyzers/StyleCop.Analyzers/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/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1613ElementParameterDocumentationMustDeclareParameterName.cs b/StyleCop.Analyzers/StyleCop.Analyzers/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/StyleCop.Analyzers/DocumentationRules/SA1614ElementParameterDocumentationMustHaveText.cs b/StyleCop.Analyzers/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/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1616ElementReturnValueDocumentationMustHaveText.cs b/StyleCop.Analyzers/StyleCop.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/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1625ElementDocumentationMustNotBeCopiedAndPasted.cs b/StyleCop.Analyzers/StyleCop.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();

Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@ public SA1608ElementDocumentationMustNotHaveDefaultSummary()`
`59`	`59`	`ImmutableArray.Create(Descriptor);`
`60`	`60`
`61`	`61`	`/// <inheritdoc/>`
`62`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`62`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`63`	`63`	`{`
`64`	`64`	`foreach (var syntax in syntaxList)`
`65`	`65`	`{`
`@@ -79,7 +79,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`79`	`79`	`}`
`80`	`80`
`81`	`81`	`/// <inheritdoc/>`
`82`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`82`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`83`	`83`	`{`
`84`	`84`	`// We are working with an <include> element`
`85`	`85`	`var includedSummaryElement = completeDocumentation.Nodes().OfType<XElement>().FirstOrDefault(element => element.Name == XmlCommentHelper.SummaryXmlTag);`
Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ public SA1612ElementParameterDocumentationMustMatchElementParameters()`
`57`	`57`	`ImmutableArray.Create(MissingParameterDescriptor);`
`58`	`58`
`59`	`59`	`/// <inheritdoc/>`
`60`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`60`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`61`	`61`	`{`
`62`	`62`	`var node = context.Node;`
`63`	`63`	`var identifier = GetIdentifier(node);`
`@@ -112,7 +112,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`112`	`112`	`}`
`113`	`113`
`114`	`114`	`/// <inheritdoc/>`
`115`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`115`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`116`	`116`	`{`
`117`	`117`	`var node = context.Node;`
`118`	`118`	`var identifier = GetIdentifier(node);`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ public SA1613ElementParameterDocumentationMustDeclareParameterName()`
`56`	`56`	`ImmutableArray.Create(Descriptor);`
`57`	`57`
`58`	`58`	`/// <inheritdoc/>`
`59`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`59`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`60`	`60`	`{`
`61`	`61`	`foreach (var syntax in syntaxList)`
`62`	`62`	`{`
`@@ -71,7 +71,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`/// <inheritdoc/>`
`74`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`74`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`75`	`75`	`{`
`76`	`76`	`var xmlParamTags = completeDocumentation.Nodes()`
`77`	`77`	`.OfType<XElement>()`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ public SA1614ElementParameterDocumentationMustHaveText()`
`52`	`52`	`ImmutableArray.Create(Descriptor);`
`53`	`53`
`54`	`54`	`/// <inheritdoc/>`
`55`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`55`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`56`	`56`	`{`
`57`	`57`	`foreach (var syntax in syntaxList)`
`58`	`58`	`{`
`@@ -66,7 +66,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`/// <inheritdoc/>`
`69`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`69`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`70`	`70`	`{`
`71`	`71`	`var xmlParamTags = completeDocumentation.Nodes()`
`72`	`72`	`.OfType<XElement>()`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ public SA1616ElementReturnValueDocumentationMustHaveText()`
`51`	`51`	`ImmutableArray.Create(Descriptor);`
`52`	`52`
`53`	`53`	`/// <inheritdoc/>`
`54`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`54`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`55`	`55`	`{`
`56`	`56`	`foreach (var syntax in syntaxList)`
`57`	`57`	`{`
`@@ -64,7 +64,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`64`	`64`	`}`
`65`	`65`
`66`	`66`	`/// <inheritdoc/>`
`67`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`67`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`68`	`68`	`{`
`69`	`69`	`var returnsNodes = completeDocumentation.Nodes()`
`70`	`70`	`.OfType<XElement>()`
Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ public SA1625ElementDocumentationMustNotBeCopiedAndPasted()`
`87`	`87`	`ImmutableArray.Create(Descriptor);`
`88`	`88`
`89`	`89`	`/// <inheritdoc/>`
`90`		`- protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
	`90`	`+ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, IEnumerable<XmlNodeSyntax> syntaxList, params Location[] diagnosticLocations)`
`91`	`91`	`{`
`92`	`92`	`var objectPool = SharedPools.Default<HashSet<string>>();`
`93`	`93`	`HashSet<string> documentationTexts = objectPool.Allocate();`
`@@ -119,7 +119,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, IEnu`
`119`	`119`	`}`
`120`	`120`
`121`	`121`	`/// <inheritdoc/>`
`122`		`- protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, XElement completeDocumentation, params Location[] diagnosticLocations)`
	`122`	`+ protected override void HandleCompleteDocumentation(SyntaxNodeAnalysisContext context, bool needsComment, XElement completeDocumentation, params Location[] diagnosticLocations)`
`123`	`123`	`{`
`124`	`124`	`var objectPool = SharedPools.Default<HashSet<string>>();`
`125`	`125`	`HashSet<string> documentationTexts = objectPool.Allocate();`