From a61e80ba1ad96e54451195a20e2d10d56d46de3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Hellander?= Date: Fri, 2 Aug 2024 13:39:18 +0200 Subject: [PATCH 1/2] Update PropertySummaryDocumentationAnalyzer to bail out earlier if the current node is not an XmlElementSyntax --- .../PropertySummaryDocumentationAnalyzer.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs index 0580c4aad..19dffdd88 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs @@ -61,6 +61,12 @@ internal class PropertySummaryDocumentationAnalyzer : PropertyDocumentationBase /// protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, StyleCopSettings settings, bool needsComment, XmlNodeSyntax syntax, XElement completeDocumentation, Location diagnosticLocation) { + if (!(syntax is XmlElementSyntax summaryElement)) + { + // This is reported by SA1604 or SA1606. + return; + } + var propertyDeclaration = (PropertyDeclarationSyntax)context.Node; var propertyType = context.SemanticModel.GetTypeInfo(propertyDeclaration.Type.StripRefFromType()); var culture = settings.DocumentationRules.DocumentationCultureInfo; @@ -70,7 +76,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, Styl { AnalyzeSummaryElement( context, - syntax, + summaryElement, diagnosticLocation, propertyDeclaration, resourceManager.GetString(nameof(DocumentationResources.StartingTextGetsWhether), culture), @@ -82,7 +88,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, Styl { AnalyzeSummaryElement( context, - syntax, + summaryElement, diagnosticLocation, propertyDeclaration, resourceManager.GetString(nameof(DocumentationResources.StartingTextGets), culture), @@ -92,7 +98,7 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, Styl } } - private static void AnalyzeSummaryElement(SyntaxNodeAnalysisContext context, XmlNodeSyntax syntax, Location diagnosticLocation, PropertyDeclarationSyntax propertyDeclaration, string startingTextGets, string startingTextSets, string startingTextGetsOrSets, string startingTextReturns) + private static void AnalyzeSummaryElement(SyntaxNodeAnalysisContext context, XmlElementSyntax summaryElement, Location diagnosticLocation, PropertyDeclarationSyntax propertyDeclaration, string startingTextGets, string startingTextSets, string startingTextGetsOrSets, string startingTextReturns) { var diagnosticProperties = ImmutableDictionary.CreateBuilder(); ArrowExpressionClauseSyntax expressionBody = propertyDeclaration.ExpressionBody; @@ -116,12 +122,6 @@ private static void AnalyzeSummaryElement(SyntaxNodeAnalysisContext context, Xml } } - if (!(syntax is XmlElementSyntax summaryElement)) - { - // This is reported by SA1604 or SA1606. - return; - } - // Add a no code fix tag when the summary element is empty. // This will only impact SA1623, because SA1624 cannot trigger with an empty summary. if (summaryElement.Content.Count == 0) From e6b6efc946f75eae60bb17b248a513c0d12dbc2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Hellander?= Date: Fri, 2 Aug 2024 14:15:01 +0200 Subject: [PATCH 2/2] Update PropertySummaryDocumentationAnalyzer (SA1623 and SA1624) to ignore summary tags containing an inheritdoc tag #3465 --- .../DocumentationRules/SA1623UnitTests.cs | 20 +++++++++++++++++++ .../DocumentationRules/SA1624UnitTests.cs | 20 +++++++++++++++++++ .../PropertySummaryDocumentationAnalyzer.cs | 6 ++++++ 3 files changed, 46 insertions(+) diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs index 0e6503f58..948328aaf 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs @@ -341,6 +341,26 @@ public class TestClass /// public int TestProperty { get; set; } } +"; + + await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false); + } + + [Theory] + [InlineData("")] + [InlineData("XYZ ")] + [InlineData(" XYZ")] + [WorkItem(3465, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3465")] + public async Task VerifyInheritdocInSummaryTagIsAllowedAsync(string summary) + { + var testCode = $@" +public class TestClass +{{ + /// + /// {summary} + /// + public int TestProperty {{ get; set; }} +}} "; await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false); diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1624UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1624UnitTests.cs index fb9ce294e..ad524a756 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1624UnitTests.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1624UnitTests.cs @@ -152,6 +152,26 @@ public class TestClass /// public int TestProperty { get; set; } } +"; + + await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false); + } + + [Theory] + [InlineData("")] + [InlineData("XYZ ")] + [InlineData(" XYZ")] + [WorkItem(3465, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3465")] + public async Task VerifyInheritdocInSummaryTagIsAllowedAsync(string summary) + { + var testCode = $@" +public class TestClass +{{ + /// + /// {summary} + /// + public int TestProperty {{ get; private set; }} +}} "; await VerifyCSharpDiagnosticAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false); diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs index 19dffdd88..c3087b145 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs @@ -67,6 +67,12 @@ protected override void HandleXmlElement(SyntaxNodeAnalysisContext context, Styl return; } + if (summaryElement.Content.GetFirstXmlElement(XmlCommentHelper.InheritdocXmlTag) != null) + { + // Ignore nodes with an tag. + return; + } + var propertyDeclaration = (PropertyDeclarationSyntax)context.Node; var propertyType = context.SemanticModel.GetTypeInfo(propertyDeclaration.Type.StripRefFromType()); var culture = settings.DocumentationRules.DocumentationCultureInfo;