From cc18acf9cc0b3288369a60e44262bae7b91b904f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Hellander?= <bjorn.hellander@gmail.com>
Date: Thu, 6 Jun 2024 09:17:55 +0200
Subject: [PATCH] Correct SA1629 to add a period if the documentation ends in
 an xml entity. Previously replaced the semicolon in the xml entity. #3802

---
 .../DocumentationRules/SA1629UnitTests.cs     | 28 ++++++++++++++++---
 ...1629DocumentationTextMustEndWithAPeriod.cs |  8 ++++--
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1629UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1629UnitTests.cs
index f86afd24e..f31c5ffad 100644
--- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1629UnitTests.cs
+++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1629UnitTests.cs
@@ -1,8 +1,6 @@
 // Copyright (c) Tunnel Vision Laboratories, LLC. All Rights Reserved.
 // Licensed under the MIT License. See LICENSE in the project root for license information.
 
-#nullable disable
-
 namespace StyleCop.Analyzers.Test.DocumentationRules
 {
     using System.Threading;
@@ -962,10 +960,32 @@ public interface ITest
             await VerifyCSharpDiagnosticAsync(testCode, testSettings, expectedResult, CancellationToken.None).ConfigureAwait(false);
         }
 
+        [Theory]
+        [InlineData("&lt;")]
+        [InlineData("&amp;")]
+        [InlineData("&quot;")]
+        [WorkItem(3802, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3802")]
+        public async Task TestSentenceEndingWithXmlEntityAsync(string xmlEntity)
+        {
+            var testCode = $@"
+/// <summary>Something {xmlEntity}[|<|]/summary>
+public class TestClass
+{{
+}}";
+
+            var fixedTestCode = $@"
+/// <summary>Something {xmlEntity}.</summary>
+public class TestClass
+{{
+}}";
+
+            await VerifyCSharpFixAsync(testCode, DiagnosticResult.EmptyDiagnosticResults, fixedTestCode, CancellationToken.None).ConfigureAwait(false);
+        }
+
         private static Task VerifyCSharpDiagnosticAsync(string source, DiagnosticResult[] expected, CancellationToken cancellationToken)
             => VerifyCSharpDiagnosticAsync(source, testSettings: null, expected, cancellationToken);
 
-        private static Task VerifyCSharpDiagnosticAsync(string source, string testSettings, DiagnosticResult[] expected, CancellationToken cancellationToken)
+        private static Task VerifyCSharpDiagnosticAsync(string source, string? testSettings, DiagnosticResult[] expected, CancellationToken cancellationToken)
         {
             var test = CreateTest(testSettings, expected);
             test.TestCode = source;
@@ -985,7 +1005,7 @@ private static Task VerifyCSharpFixAsync(string source, DiagnosticResult[] expec
             return test.RunAsync(cancellationToken);
         }
 
-        private static StyleCopCodeFixVerifier<SA1629DocumentationTextMustEndWithAPeriod, SA1629CodeFixProvider>.CSharpTest CreateTest(string testSettings, DiagnosticResult[] expected)
+        private static StyleCopCodeFixVerifier<SA1629DocumentationTextMustEndWithAPeriod, SA1629CodeFixProvider>.CSharpTest CreateTest(string? testSettings, DiagnosticResult[] expected)
         {
             string contentClassInheritDoc = @"<?xml version=""1.0"" encoding=""utf-8"" ?>
 <TestClass>
diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1629DocumentationTextMustEndWithAPeriod.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1629DocumentationTextMustEndWithAPeriod.cs
index 6f16360cf..c989fb472 100644
--- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1629DocumentationTextMustEndWithAPeriod.cs
+++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1629DocumentationTextMustEndWithAPeriod.cs
@@ -9,6 +9,7 @@ namespace StyleCop.Analyzers.DocumentationRules
     using System.Collections.Generic;
     using System.Collections.Immutable;
     using System.Linq;
+    using System.Text.RegularExpressions;
     using System.Xml.Linq;
     using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.CSharp.Syntax;
@@ -66,6 +67,8 @@ internal class SA1629DocumentationTextMustEndWithAPeriod : ElementDocumentationB
 
         private static readonly ImmutableDictionary<string, string> NoCodeFixProperties = ImmutableDictionary.Create<string, string>().Add(NoCodeFixKey, string.Empty);
 
+        private static readonly Regex XmlEntityRegex = new Regex("&[a-z]+;$");
+
         /// <summary>
         /// Initializes a new instance of the <see cref="SA1629DocumentationTextMustEndWithAPeriod"/> class.
         /// </summary>
@@ -131,8 +134,9 @@ private static void HandleSectionOrBlockXmlElement(SyntaxNodeAnalysisContext con
                             {
                                 int spanStart = textToken.SpanStart + textWithoutTrailingWhitespace.Length;
                                 ImmutableDictionary<string, string> properties = null;
-                                if (textWithoutTrailingWhitespace.EndsWith(",", StringComparison.Ordinal)
-                                    || textWithoutTrailingWhitespace.EndsWith(";", StringComparison.Ordinal))
+                                if (textWithoutTrailingWhitespace.EndsWith(",", StringComparison.Ordinal) ||
+                                    (textWithoutTrailingWhitespace.EndsWith(";", StringComparison.Ordinal) &&
+                                     !XmlEntityRegex.IsMatch(textWithoutTrailingWhitespace)))
                                 {
                                     spanStart -= 1;
                                     SetReplaceChar();