From 90aa435d355652d6005bb0f5e097083d9a4c9076 Mon Sep 17 00:00:00 2001
From: Adam Ward <award999@apple.com>
Date: Wed, 25 Jun 2025 13:35:56 -0400
Subject: [PATCH 1/3] Make sure newline starts with /// when splitting doc
 comment

The existing behaviour where splitting a /// line results in the next
line starting with // is a vscode issue. Other examples follow a similar
approach as this PR to accomplish the desired behaviour.

Issue: #1648
---
 src/editor/CommentCompletion.ts | 42 +++++++++++++++++++--------------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/src/editor/CommentCompletion.ts b/src/editor/CommentCompletion.ts
index 799fb12c5..df3fed335 100644
--- a/src/editor/CommentCompletion.ts
+++ b/src/editor/CommentCompletion.ts
@@ -15,6 +15,14 @@
 import * as vscode from "vscode";
 import { DocumentParser } from "./DocumentParser";
 
+function isLineComment(document: vscode.TextDocument, line: number): boolean {
+    // test if line consists of just '///'
+    if (/^\s*\/\/\//.test(document.lineAt(line).text)) {
+        return true;
+    }
+    return false;
+}
+
 /** CompletionItem for Swift Comments */
 class CommentCompletion extends vscode.CompletionItem {
     constructor(
@@ -40,20 +48,26 @@ class CommentCompletionProvider implements vscode.CompletionItemProvider {
         position: vscode.Position
     ): Promise<vscode.CompletionItem[] | undefined> {
         // Is line a '///' comment
-        if (position.line === 0 || this.isLineComment(document, position.line - 1) === false) {
+        if (position.line === 0 || isLineComment(document, position.line - 1) === false) {
+            return undefined;
+        }
+        // Fixes https://github.com/swiftlang/vscode-swift/issues/1648
+        const match = /^(\s*)\/\/\s(.+)/.exec(document.lineAt(position.line).text);
+        if (match) {
+            void vscode.window.activeTextEditor?.edit(
+                edit => {
+                    void edit.replace(
+                        new vscode.Range(position.line, 0, position.line, match[0].length),
+                        `${match[1]}///${match[2]}`
+                    );
+                },
+                { undoStopBefore: false, undoStopAfter: true }
+            );
             return undefined;
         }
         const completion = new CommentCompletion("/// ", "///", "Documentation comment");
         return [completion];
     }
-
-    private isLineComment(document: vscode.TextDocument, line: number): boolean {
-        // test if line starts with '///'
-        if (/^\s*\/\/\//.test(document.lineAt(line).text)) {
-            return true;
-        }
-        return false;
-    }
 }
 
 interface FunctionDetails {
@@ -73,7 +87,7 @@ class FunctionDocumentationCompletionProvider implements vscode.CompletionItemPr
         position: vscode.Position
     ): Promise<vscode.CompletionItem[] | undefined> {
         // Is line a '///' comment
-        const isComment = this.isLineComment(document, position.line);
+        const isComment = isLineComment(document, position.line);
         if (isComment === false) {
             return undefined;
         }
@@ -117,14 +131,6 @@ class FunctionDocumentationCompletionProvider implements vscode.CompletionItemPr
         }
     }
 
-    private isLineComment(document: vscode.TextDocument, line: number): boolean {
-        // test if line consists of just '///'
-        if (/^\s*\/\/\/\s*$/.test(document.lineAt(line).text)) {
-            return true;
-        }
-        return false;
-    }
-
     /**
      * Extract function details from line below. Inspiration for this code can be found
      * here https://github.com/fappelman/swift-add-documentation

From cee6e18099df4eb831665d1eca9a665e361a22ce Mon Sep 17 00:00:00 2001
From: Adam Ward <award999@apple.com>
Date: Thu, 26 Jun 2025 10:31:22 -0400
Subject: [PATCH 2/3] Fix review comment

---
 src/editor/CommentCompletion.ts | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/editor/CommentCompletion.ts b/src/editor/CommentCompletion.ts
index df3fed335..ffd2157d5 100644
--- a/src/editor/CommentCompletion.ts
+++ b/src/editor/CommentCompletion.ts
@@ -17,10 +17,7 @@ import { DocumentParser } from "./DocumentParser";
 
 function isLineComment(document: vscode.TextDocument, line: number): boolean {
     // test if line consists of just '///'
-    if (/^\s*\/\/\//.test(document.lineAt(line).text)) {
-        return true;
-    }
-    return false;
+    return /^\s*\/\/\//.test(document.lineAt(line).text);
 }
 
 /** CompletionItem for Swift Comments */

From 29308d6f8de6f974cb274b6d727089a0f9c8f897 Mon Sep 17 00:00:00 2001
From: Adam Ward <award999@apple.com>
Date: Thu, 26 Jun 2025 12:49:01 -0400
Subject: [PATCH 3/3] Add changelog entry

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 00eda4a8f..e9d598cdb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### Fixed
 
 - Cleanup Swift diagnostics when the source file is moved or deleted ([#1653](https://github.com/swiftlang/vscode-swift/pull/1653))
+- Make sure newline starts with /// when splitting doc comment ([#1651](https://github.com/swiftlang/vscode-swift/pull/1651))
 
 ## 2.6.0 - 2025-06-26