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

Fixes #2451

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1609UnitTests.cs

@@ -354,6 +354,31 @@ public int Property
             await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Fact]
+        [WorkItem(2451, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2451")]
+        public async Task TestPropertyWithoutDocumentationRequirementAsync()
+        {
+            var testCode = @"
+/// <summary>
+/// 
+/// </summary>
+public class ClassName
+{
+    /// <include file='PropertyWithoutValue.xml' path='/ClassName/Property/*'/>
+    private int Property
+    {
+        get;
+    }
+
+    /// <summary>
+    /// 
+    /// </summary>
+    private ClassName PropertyWithSummary { get; set; }
+}";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
         protected override Project ApplyCompilationOptions(Project project)
         {
             var resolver = new TestXmlReferenceResolver();

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertyDocumentationBase.cs

@@ -11,6 +11,7 @@ namespace StyleCop.Analyzers.DocumentationRules
     using Microsoft.CodeAnalysis.CSharp.Syntax;
     using Microsoft.CodeAnalysis.Diagnostics;
     using StyleCop.Analyzers.Helpers;
+    using StyleCop.Analyzers.Settings.ObjectModel;
 
     /// <summary>
     /// This is the base class for analyzers which examine the <c>&lt;value&gt;</c> text of a documentation comment on a property declaration.
@@ -22,7 +23,7 @@ internal abstract class PropertyDocumentationBase : DiagnosticAnalyzer
         /// </summary>
         internal const string NoCodeFixKey = "NoCodeFix";
 
-        private readonly Action<SyntaxNodeAnalysisContext> propertyDeclarationAction;
+        private readonly Action<SyntaxNodeAnalysisContext, StyleCopSettings> propertyDeclarationAction;
 
         protected PropertyDocumentationBase()
         {
@@ -48,27 +49,32 @@ public override void Initialize(AnalysisContext context)
         /// Analyzes the top-level <c>&lt;summary&gt;</c> element of a documentation comment.
         /// </summary>
         /// <param name="context">The current analysis context.</param>
+        /// <param name="needsComment"><see langword="true"/> if the current documentation settings indicate that the
+        /// element should be documented; otherwise, <see langword="false"/>.</param>
         /// <param name="syntax">The <see cref="XmlElementSyntax"/> or <see cref="XmlEmptyElementSyntax"/> of the node
         /// to examine.</param>
         /// <param name="completeDocumentation">The complete documentation for the declared symbol, with any
         /// <c>&lt;include&gt;</c> elements expanded. If the XML documentation comment included a <c>&lt;summary&gt;</c>
         /// element, this value will be <see langword="null"/>, even if the XML documentation comment also included an
         /// <c>&lt;include&gt;</c> element.</param>
         /// <param name="diagnosticLocation">The location where diagnostics, if any, should be reported.</param>
-        protected abstract void HandleXmlElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation);
+        protected abstract void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation);
 
-        private void HandlePropertyDeclaration(SyntaxNodeAnalysisContext context)
+        private void HandlePropertyDeclaration(SyntaxNodeAnalysisContext context, StyleCopSettings settings)
         {
             var node = (PropertyDeclarationSyntax)context.Node;
             if (node.Identifier.IsMissing)
             {
                 return;
             }
 
-            this.HandleDeclaration(context, node, node.Identifier.GetLocation());
+            Accessibility declaredAccessibility = node.GetDeclaredAccessibility(context.SemanticModel, context.CancellationToken);
+            Accessibility effectiveAccessibility = node.GetEffectiveAccessibility(context.SemanticModel, context.CancellationToken);
+            bool needsComment = SA1600ElementsMustBeDocumented.NeedsComment(settings.DocumentationRules, node.Kind(), node.Parent.Kind(), declaredAccessibility, effectiveAccessibility);
+            this.HandleDeclaration(context, needsComment, node, node.Identifier.GetLocation());
         }
 
-        private void HandleDeclaration(SyntaxNodeAnalysisContext context, SyntaxNode node, Location location)
+        private void HandleDeclaration(SyntaxNodeAnalysisContext context, bool needsComment, SyntaxNode node, Location location)
         {
             var documentation = node.GetDocumentationCommentTriviaSyntax();
             if (documentation == null)
@@ -102,7 +108,7 @@ private void HandleDeclaration(SyntaxNodeAnalysisContext context, SyntaxNode nod
                 }
             }
 
-            this.HandleXmlElement(context, relevantXmlElement, completeDocumentation, location);
+            this.HandleXmlElement(context, needsComment, relevantXmlElement, completeDocumentation, location);
         }
     }
 }

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs

@@ -57,7 +57,7 @@ internal class PropertySummaryDocumentationAnalyzer : PropertyDocumentationBase
         protected override string XmlTagToHandle => XmlCommentHelper.SummaryXmlTag;
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
         {
             var propertyDeclaration = (PropertyDeclarationSyntax)context.Node;
             var propertyType = context.SemanticModel.GetTypeInfo(propertyDeclaration.Type);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1609PropertyDocumentationMustHaveValue.cs

@@ -49,8 +49,14 @@ internal class SA1609PropertyDocumentationMustHaveValue : PropertyDocumentationB
         protected override string XmlTagToHandle => XmlCommentHelper.ValueXmlTag;
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
         {
+            if (!needsComment)
+            {
+                // A missing 'value' documentation is allowed for this element.
+                return;
+            }
+
             var properties = ImmutableDictionary.Create<string, string>();
 
             if (completeDocumentation != null)

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1610PropertyDocumentationMustHaveValueText.cs

@@ -49,7 +49,7 @@ internal class SA1610PropertyDocumentationMustHaveValueText : PropertyDocumentat
         protected override string XmlTagToHandle => XmlCommentHelper.ValueXmlTag;
 
         /// <inheritdoc/>
-        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
+        protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, bool needsComment, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation)
         {
             var properties = ImmutableDictionary.Create<string, string>();