From 29514d235601c117f0624061fc4636f6ae4ed91a Mon Sep 17 00:00:00 2001 From: Matt Chaulklin Date: Tue, 18 Jun 2024 08:52:52 -0400 Subject: [PATCH 1/3] Added changes to allow the tag in . Added Unit test for SA1642 --- .../DocumentationRules/SA1642UnitTests.cs | 51 +++++++++++++++++++ .../StandardTextDiagnosticBase.cs | 20 ++++++++ 2 files changed, 71 insertions(+) diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs index 4433b5044..7bc85b757 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs @@ -1061,6 +1061,57 @@ public ClassName() await VerifyCSharpFixAsync(testCode, expected, fixedCode, CancellationToken.None).ConfigureAwait(false); } + [Fact] + [WorkItem(3575, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3575")] + public async Task TestConstructorSummaryWithParaTagsAsync() + { + var testCode = @" +using System; +/// +/// Does a thing. +/// +public class B +{ + /// + /// + /// Initializes a new instance of the class. + /// + /// + /// Some more info about B. + /// + /// + public B() + { + } +} +"; + + var fixedCode = @" +using System; +/// +/// Does a thing. +/// +public class B +{ + /// + /// + /// Initializes a new instance of the class. + /// + /// + /// Some more info about B. + /// + /// + public B() + { + } +} +"; + + var expectedDiagnostics = DiagnosticResult.EmptyDiagnosticResults; + + await VerifyCSharpFixAsync(testCode, expectedDiagnostics, fixedCode, CancellationToken.None).ConfigureAwait(false); + } + private static async Task TestEmptyConstructorAsync(string typeKind, string modifiers) { var testCode = @"namespace FooNamespace diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/StandardTextDiagnosticBase.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/StandardTextDiagnosticBase.cs index 2b6c7263e..2af1351f2 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/StandardTextDiagnosticBase.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/StandardTextDiagnosticBase.cs @@ -122,6 +122,26 @@ protected static MatchResult HandleDeclaration(SyntaxNodeAnalysisContext context diagnosticLocation = summaryElement.GetLocation(); diagnosticProperties = ImmutableDictionary.Create(); + // Handle empty or whitespace-only summary content + var firstElementWithContent = XmlCommentHelper.TryGetFirstTextElementWithContent(summaryElement); + if (firstElementWithContent == null) + { + // Report the diagnostic for empty or whitespace-only summaries + if (diagnosticDescriptor != null) + { + context.ReportDiagnostic(Diagnostic.Create(diagnosticDescriptor, diagnosticLocation, diagnosticProperties)); + } + + return MatchResult.None; + } + + // Check if the summary content starts with a tag + if (firstElementWithContent != null && firstElementWithContent.Parent is XmlElementSyntax firstElement && firstElement.StartTag.Name.ToString() == "para") + { + // We found a correct standard text + return MatchResult.FoundMatch; + } + // Check if the summary content could be a correct standard text if (summaryElement.Content.Count >= 3) { From 400f970491370b00467536b413404ffb2fa149ed Mon Sep 17 00:00:00 2001 From: Matt Chaulklin Date: Tue, 18 Jun 2024 08:58:16 -0400 Subject: [PATCH 2/3] updated documentation --- documentation/SA1642.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/documentation/SA1642.md b/documentation/SA1642.md index f64ea96b4..f12da3238 100644 --- a/documentation/SA1642.md +++ b/documentation/SA1642.md @@ -96,6 +96,23 @@ private Customer() } ``` +The `` tag can be used within the `` tag to structure the text. +For example: + +```csharp +/// +/// +/// Initializes a new instance of the class. +/// +/// +/// Additional information can be included in subsequent paragraphs. +/// +/// +public Customer() +{ +} +``` + ## How to fix violations To fix a violation of this rule, edit the summary text for the constructor as described above. From df783118542278556516b40e41a5344c843cd7d9 Mon Sep 17 00:00:00 2001 From: Matt Chaulklin Date: Mon, 24 Jun 2024 08:43:01 -0400 Subject: [PATCH 3/3] Updated unit test --- .../DocumentationRules/SA1642UnitTests.cs | 23 +------------------ 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs index 7bc85b757..d6d81d7db 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1642UnitTests.cs @@ -1084,32 +1084,11 @@ public B() { } } -"; - - var fixedCode = @" -using System; -/// -/// Does a thing. -/// -public class B -{ - /// - /// - /// Initializes a new instance of the class. - /// - /// - /// Some more info about B. - /// - /// - public B() - { - } -} "; var expectedDiagnostics = DiagnosticResult.EmptyDiagnosticResults; - await VerifyCSharpFixAsync(testCode, expectedDiagnostics, fixedCode, CancellationToken.None).ConfigureAwait(false); + await VerifyCSharpFixAsync(testCode, expectedDiagnostics, testCode, CancellationToken.None).ConfigureAwait(false); } private static async Task TestEmptyConstructorAsync(string typeKind, string modifiers)