Refactor Trivia.docCommentValue for readability and correctness

- Fix blank line stripping to only remove first/last line, not all blank lines
- Add regression test and convert test strings to multi-line format
- Move release notes entry from 602 to 604

Author: PhantomInTheWire

Release Notes/602.md

@@ -25,10 +25,6 @@
   - Pull request: https://github.com/swiftlang/swift-syntax/pull/3030
   - Migration stems: None required.
 
-- `Trivia` has a new `docCommentValue` property.
-  - Description: Extracts sanitized comment text from doc comment trivia pieces, omitting leading comment markers (`///`, `/**`).
-  - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2966
-
 ## API Behavior Changes
 
 ## Deprecations

Release Notes/604.md

@@ -0,0 +1,25 @@
+# Swift Syntax 604 Release Notes
+
+## New APIs
+
+- `Trivia` has a new `docCommentValue` property.
+  - Description: Extracts sanitized comment text from doc comment trivia pieces, omitting leading comment markers (`///`, `/**`).
+  - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2966
+
+
+## API Behavior Changes
+
+## Deprecations
+
+## API-Incompatible Changes
+
+## Template
+
+- *Affected API or two word description*
+  - Description: *A 1-2 sentence description of the new/modified API*
+  - Issue: *If an issue exists for this change, a link to the issue*
+  - Pull Request: *Link to the pull request(s) that introduces this change*
+  - Migration steps: Steps that adopters of swift-syntax should take to move to the new API (required for deprecations and API-incompatible changes).
+  - Notes: *In case of deprecations or API-incompatible changes, the reason why this change was made and the suggested alternative*
+
+*Insert entries in chronological order, with newer entries at the bottom*

Sources/SwiftSyntax/Trivia+commentValue.swift

@@ -14,7 +14,7 @@ extension Trivia {
   /// The contents of the last doc comment piece with any comment markers removed and indentation whitespace stripped.
   public var docCommentValue: String? {
     var comments: [Substring] = []
-    var currentLineComments: [Substring] = []
+    var currentLineComments: [String] = []  // Reset line comments when encountering a block comment
     var isInsideDocLineCommentSection = false
     var consecutiveNewlines = 0
 
@@ -28,22 +28,19 @@ extension Trivia {
         consecutiveNewlines = 0
       case .docLineComment(let text):
         if isInsideDocLineCommentSection {
-          currentLineComments.append(text[...])
+          currentLineComments.append(text)
         } else {
-          currentLineComments = [text[...]]
+          currentLineComments = [text]
           isInsideDocLineCommentSection = true
         }
         consecutiveNewlines = 0
 
       case .newlines(let n), .carriageReturns(let n), .carriageReturnLineFeeds(let n):
-        if n == 1 {
-          consecutiveNewlines += 1
-        } else {
-          consecutiveNewlines = 0
-        }
+        consecutiveNewlines += n
 
         if consecutiveNewlines != 1 {
           processSectionBreak()
+          consecutiveNewlines = 0
         }
       default:
         processSectionBreak()
@@ -56,45 +53,60 @@ extension Trivia {
       var lines = text.dropPrefix("/**").dropSuffix("*/")
         .split(omittingEmptySubsequences: false, whereSeparator: \.isNewline)
 
+      // If the comment content starts on the same line as the `/**` marker or ends on the same line as the `*/` marker,
+      // it is common to separate the marker and the actual comment using spaces. Strip those spaces if they exists.
+      // If there are non no-space characters on the first / last line, then the comment doesn't start / end on the line
+      // with the marker, so don't do the stripping.
       if let firstLine = lines.first, firstLine.contains(where: { $0 != " " }) {
         lines[0] = firstLine.drop { $0 == " " }
       }
       if let lastLine = lines.last, lastLine.contains(where: { $0 != " " }) {
         lines[lines.count - 1] = lastLine.dropLast { $0 == " " }
       }
 
+      // Find the lowest indentation that is common among all lines in the block comment. Do not consider the first line
+      // because it won't have any indentation since it starts with /**
       let indentation = lines.dropFirst()
         .map { $0.prefix(while: { $0 == " " || $0 == "\t" }) }
         .reduce(nil as Substring?) { (acc: Substring?, element: Substring.SubSequence) in
           acc.map { commonPrefix($0, element) } ?? element
         }
 
       guard let firstLine = lines.first else {
+        // We did not have any lines. This should never happen in practice because `split` never returns an empty array
+        // but be safe and return `nil` here anyway.
         return nil
       }
 
       var unindentedLines = [firstLine] + lines.dropFirst().map { $0.dropPrefix(indentation ?? "") }
 
-      while unindentedLines.first?.allSatisfy({ $0 == " " }) == true {
+      // If the first line only contained the comment marker, don't include it. We don't want to start the comment value
+      // with a newline if `/**` is on its own line. Same for the end marker.
+      if unindentedLines.first?.allSatisfy({ $0 == " " }) ?? false {
         unindentedLines.removeFirst()
       }
-      while unindentedLines.last?.allSatisfy({ $0 == " " }) == true {
+      if unindentedLines.last?.allSatisfy({ $0 == " " }) ?? false {
         unindentedLines.removeLast()
       }
 
+      // We canonicalize the line endings to `\n` here. This matches how we concatenate the different line comment
+      // pieces using \n as well.
       return Substring(unindentedLines.joined(separator: "\n"))
     }
 
+    /// Processes a section break, which is defined as a sequence of newlines or other trivia pieces that are not comments.
     func processSectionBreak() {
+      // If we have a section break, we reset the current line comments.
       if !currentLineComments.isEmpty {
-        comments = currentLineComments
+        comments = currentLineComments.map { $0[...] }
         currentLineComments = []
       }
       isInsideDocLineCommentSection = false
     }
 
+    // If there are remaining line comments, use them as the last doc comment block.
     if !currentLineComments.isEmpty {
-      comments = currentLineComments
+      comments = currentLineComments.map { $0[...] }
     }
 
     if comments.isEmpty { return nil }
@@ -125,6 +137,6 @@ fileprivate extension StringProtocol where SubSequence == Substring {
   }
 }
 
-fileprivate func commonPrefix(_ lhs: Substring, _ rhs: Substring) -> Substring {
+private func commonPrefix(_ lhs: Substring, _ rhs: Substring) -> Substring {
   return lhs[..<lhs.index(lhs.startIndex, offsetBy: zip(lhs, rhs).prefix { $0 == $1 }.count)]
 }

Tests/SwiftSyntaxTest/TriviaCommentValueTests.swift

@@ -24,7 +24,10 @@ class TriviaCommentValueTests: XCTestCase {
       /// Some doc line comment
       /// Another
       """,
-      docCommentValue: "Some doc line comment\nAnother"
+      docCommentValue: """
+        Some doc line comment
+        Another
+        """
     )
     assertCommentValue(
       """
@@ -87,7 +90,10 @@ class TriviaCommentValueTests: XCTestCase {
       /// included
       /// also included
       """,
-      docCommentValue: "included\nalso included"
+      docCommentValue: """
+        included
+        also included
+        """
     )
     assertCommentValue(
       """
@@ -96,7 +102,10 @@ class TriviaCommentValueTests: XCTestCase {
       /// included
       /// also included
       """,
-      docCommentValue: "included\nalso included"
+      docCommentValue: """
+        included
+        also included
+        """
     )
   }
 
@@ -123,7 +132,10 @@ class TriviaCommentValueTests: XCTestCase {
       * spread on many lines
       */
       """,
-      docCommentValue: "Some doc block comment\n* spread on many lines"
+      docCommentValue: """
+        Some doc block comment
+        * spread on many lines
+        """
     )
     assertCommentValue(
       """
@@ -222,6 +234,24 @@ class TriviaCommentValueTests: XCTestCase {
       """,
       docCommentValue: "abc"
     )
+    assertCommentValue(
+      """
+      /**
+
+      First paragraph.
+
+      Second paragraph.
+
+      */
+      """,
+      docCommentValue: """
+
+        First paragraph.
+
+        Second paragraph.
+
+        """
+    )
   }
 
   func testMixedStyleCommentValues() {
@@ -265,9 +295,11 @@ private func assertCommentValue(
 }
 
 private func parseTrivia(from input: String) -> Trivia {
+  // Wrap the input in valid Swift code so the parser can recognize it
   let wrappedSource = "let _ = 0\n\(input)\nlet _ = 1"
   let sourceFile = Parser.parse(source: wrappedSource)
 
+  // Find the token where the comment would appear (before `let _ = 1`)
   guard
     let commentToken = sourceFile.tokens(viewMode: .sourceAccurate).first(where: {
       $0.leadingTrivia.contains(where: { $0.isComment })