From a1909e063e77c9644ad6131b2073b362ed261a16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Hellander?= <bjorn.hellander@gmail.com>
Date: Sat, 11 May 2024 10:16:21 +0200
Subject: [PATCH] Update SA1004 to allow doc comments to start with the in, out
 and ref keywords #3817

---
 .../SpacingRules/SA1004UnitTests.cs           | 47 ++++++++++++++++++-
 ...umentationLinesMustBeginWithSingleSpace.cs |  5 +-
 2 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1004UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1004UnitTests.cs
index 8f90dfcab..d88d3e66d 100644
--- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1004UnitTests.cs
+++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1004UnitTests.cs
@@ -1,13 +1,14 @@
 // 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.SpacingRules
 {
+    using System.Collections.Generic;
     using System.Threading;
     using System.Threading.Tasks;
+    using Microsoft.CodeAnalysis.CSharp;
     using Microsoft.CodeAnalysis.Testing;
+    using StyleCop.Analyzers.Lightup;
     using StyleCop.Analyzers.SpacingRules;
     using Xunit;
     using static StyleCop.Analyzers.Test.Verifiers.StyleCopCodeFixVerifier<
@@ -19,6 +20,20 @@ namespace StyleCop.Analyzers.Test.SpacingRules
     /// </summary>
     public class SA1004UnitTests
     {
+        public static IEnumerable<object[]> ParameterModifiers
+        {
+            get
+            {
+                yield return new[] { "out" };
+                yield return new[] { "ref" };
+
+                if (LightupHelpers.SupportsCSharp72)
+                {
+                    yield return new[] { "in" };
+                }
+            }
+        }
+
         [Fact]
         public async Task TestFixedExampleAsync()
         {
@@ -213,5 +228,33 @@ private void Method1(int x, int y)
 
             await VerifyCSharpFixAsync(testCode, expected, fixedCode, CancellationToken.None).ConfigureAwait(false);
         }
+
+        [Theory]
+        [MemberData(nameof(ParameterModifiers))]
+        [WorkItem(3817, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/3817")]
+        public async Task TestParameterModifierFirstOnLineAsync(string keyword)
+        {
+            string testCode = $@"
+/// <summary>
+/// Description of some remarks that refer to a method: <see cref=""SomeMethod(int, int,
+/// {keyword} string)""/>.
+/// </summary>
+public class TypeName
+{{
+    public void SomeMethod(int x, int y, {keyword} string z)
+    {{
+        throw new System.Exception();
+    }}
+}}";
+
+            var languageVersion = (LightupHelpers.SupportsCSharp8, LightupHelpers.SupportsCSharp72) switch
+            {
+                // Make sure to use C# 7.2 if supported, unless we are going to default to something greater
+                (false, true) => LanguageVersionEx.CSharp7_2,
+                _ => (LanguageVersion?)null,
+            };
+
+            await VerifyCSharpDiagnosticAsync(languageVersion, testCode, DiagnosticResult.EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
     }
 }
diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1004DocumentationLinesMustBeginWithSingleSpace.cs b/StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1004DocumentationLinesMustBeginWithSingleSpace.cs
index 0521e9277..49787987e 100644
--- a/StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1004DocumentationLinesMustBeginWithSingleSpace.cs
+++ b/StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1004DocumentationLinesMustBeginWithSingleSpace.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.SpacingRules
 {
     using System;
@@ -112,6 +110,9 @@ private static void HandleDocumentationCommentExteriorTrivia(SyntaxTreeAnalysisC
             case SyntaxKind.XmlCommentEndToken:
             case SyntaxKind.XmlCDataStartToken:
             case SyntaxKind.XmlCDataEndToken:
+            case SyntaxKind.InKeyword:
+            case SyntaxKind.OutKeyword:
+            case SyntaxKind.RefKeyword:
                 if (!token.HasLeadingTrivia)
                 {
                     break;