DRAFT - Add Trivia.commentValues for sanitised comments

Sources/SwiftSyntax/Trivia.swift

@@ -42,6 +42,68 @@ public struct Trivia: Sendable {
     pieces.isEmpty
   }
 
+  /// The string contents of all the comment pieces with any comments tokens trimmed.
+  ///
+  /// Each element in the array is the trimmed contents of a line comment, or, in the case of a multi-line comment a trimmed, concatenated single string.
+  public var commentValues: [String] {
+    var comments = [String]()
+    var partialComments = [String]()
+
+    var foundStartOfCodeBlock = false
+    var foundEndOfCodeBlock = false
+    var isInCodeBlock: Bool { foundStartOfCodeBlock && !foundEndOfCodeBlock }
+
+    for piece in pieces {
+      switch piece {
+      case .blockComment(let text), .docBlockComment(let text):
+        let text = text.trimmingCharacters(in: "\n")
+
+        foundStartOfCodeBlock = text.hasPrefix("/*")
+        foundEndOfCodeBlock = text.hasSuffix("*/")
+
+        let sanitized =
+          text
+          .split(separator: "\n")
+          .map { $0.trimmingAnyCharacters(in: "/*").trimmingAnyCharacters(in: " ") }
+          .filter { !$0.isEmpty }
+          .joined(separator: " ")
+
+        appendPartialCommentIfPossible(sanitized)
+
+      case .lineComment(let text), .docLineComment(let text):
+        if isInCodeBlock {
+          appendPartialCommentIfPossible(text)
+        } else {
+          comments.append(String(text.trimmingPrefix("/ ")))
+        }
+
+      default:
+        break
+      }
+
+      if foundEndOfCodeBlock, !partialComments.isEmpty {
+        appendSubstringsToLines()
+        partialComments.removeAll()
+      }
+    }
+
+    if !partialComments.isEmpty {
+      appendSubstringsToLines()
+    }
+
+    func appendPartialCommentIfPossible(_ text: String) {
+      guard partialComments.isEmpty || !text.isEmpty else { return }
+
+      partialComments.append(text)
+    }
+
+    func appendSubstringsToLines() {
+      comments.append(partialComments.joined(separator: " "))
+    }
+
+    return comments
+  }
+
   /// The length of all the pieces in this ``Trivia``.
   public var sourceLength: SourceLength {
     return pieces.map({ $0.sourceLength }).reduce(.zero, +)

Sources/SwiftSyntax/Utils.swift

@@ -120,3 +120,49 @@ extension RawUnexpectedNodesSyntax {
     self.init(raw: raw)
   }
 }
+
+extension String {
+  func trimmingCharacters(in charactersToTrim: any BidirectionalCollection<Character>) -> Substring {
+    // TODO: adammcarter - this feels a bit dirty
+    self[startIndex...].trimmingAnyCharacters(in: charactersToTrim)
+  }
+
+  func trimmingPrefix(_ charactersToTrim: any BidirectionalCollection<Character>) -> Substring {
+    self[startIndex...].trimmingAnyCharactersFromPrefix(in: charactersToTrim)
+  }
+
+  func trimmingSuffix(_ charactersToTrim: any BidirectionalCollection<Character>) -> Substring {
+    self[startIndex...].trimmingAnyCharactersFromSuffix(in: charactersToTrim)
+  }
+}
+
+extension Substring {
+  func trimmingAnyCharacters(in charactersToTrim: any BidirectionalCollection<Character>) -> Substring {
+    trimmingAnyCharactersFromPrefix(in: charactersToTrim).trimmingAnyCharactersFromSuffix(in: charactersToTrim)
+  }
+
+  func trimmingAnyCharactersFromPrefix(in charactersToTrim: any BidirectionalCollection<Character>) -> Self {
+    dropFirst(countOfSequentialCharacters(charactersToTrim, in: self))
+  }
+
+  func trimmingAnyCharactersFromSuffix(in charactersToTrim: any BidirectionalCollection<Character>) -> Self {
+    dropLast(countOfSequentialCharacters(charactersToTrim, in: reversed()))
+  }
+}
+
+private func countOfSequentialCharacters(
+  _ charactersToCount: any BidirectionalCollection<Character>,
+  in characters: any BidirectionalCollection<Character>
+) -> Int {
+  var count = 0
+
+  for character in characters {
+    if charactersToCount.contains(character) {
+      count += 1
+    } else {
+      break
+    }
+  }
+
+  return count
+}