Implement Trivia.docCommentValue to process doc comments

Author: zyadtaha

Release Notes/602.md

@@ -25,8 +25,8 @@
   - Pull request: https://github.com/swiftlang/swift-syntax/pull/3030
   - Migration stems: None required.
 
-- `Trivia` has a new `commentValue` property.
-  - Description: Extracts sanitized comment text from comment trivia pieces, omitting leading comment markers (`//`, `///`, `/*`, `*/`).
+- `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

Sources/SwiftSyntax/Trivia+commentValue.swift

@@ -11,31 +11,27 @@
 //===----------------------------------------------------------------------===//
 
 extension Trivia {
-  /// The contents of all the comment pieces with any comments markers removed and indentation whitespace stripped.
-  public var commentValue: String? {
+  /// The contents of the last doc comment piece with any comment markers removed and indentation whitespace stripped.
+  public var docCommentValue: String? {
     var comments: [Substring] = []
 
-    /// Keep track of whether we have seen a line or block comment trivia piece. If this `Trivia` contains both a block
-    /// and a line comment, we don't know how to concatenate them to form the comment value and thus default to
-    /// returning `nil`.
+    /// Keep track of whether we have seen a line or block comment trivia piece.
     var hasBlockComment = false
-    var hasLineComment = false
 
-    // Determine if all line comments have a space separating the `//` or `///` comment marker and the actual comment.
+    // Determine if all line comments have a space separating the `///` comment marker and the actual comment.
     lazy var allLineCommentsHaveSpace: Bool = pieces.allSatisfy { piece in
       switch piece {
-      case .lineComment(let text): return text.hasPrefix("// ")
       case .docLineComment(let text): return text.hasPrefix("/// ")
       default: return true
       }
     }
 
-    // Strips /* */ markers and remove any common indentation between the lines in the block comment.
-    func processBlockComment(_ text: String, isDocComment: Bool) -> String? {
-      var lines = text.dropPrefix(isDocComment ? "/**" : "/*").dropSuffix("*/")
+    // Strips /** */ markers and removes any common indentation between the lines in the block comment.
+    func processBlockComment(_ text: String) -> Substring? {
+      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,
+      // 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.
@@ -48,7 +44,7 @@ extension Trivia {
 
       var indentation: Substring? = nil
       // 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 /*
+      // because it won't have any indentation since it starts with /**
       for line in lines.dropFirst() {
         let lineIndentation = line.prefix(while: { $0 == " " || $0 == "\t" })
         guard let previousIndentation = indentation else {
@@ -67,7 +63,7 @@ extension Trivia {
       var unindentedLines = [firstLine] + lines.dropFirst().map { $0.dropPrefix(indentation ?? "") }
 
       // 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.
+      // with a newline if `/**` is on its own line. Same for the end marker.
       if unindentedLines.first?.allSatisfy({ $0 == " " }) ?? false {
         unindentedLines.removeFirst()
       }
@@ -76,34 +72,48 @@ extension Trivia {
       }
       // We canonicalize the line endings to `\n` here. This matches how we concatenate the different line comment
       // pieces using \n as well.
-      return unindentedLines.joined(separator: "\n")
+      return unindentedLines.joined(separator: "\n")[...]
     }
 
+    var currentLineComments: [Substring] = []
+    var foundStop = false
     for piece in pieces {
       switch piece {
-      case .blockComment(let text), .docBlockComment(let text):
-        if hasBlockComment || hasLineComment {
-          return nil
+      case .docBlockComment(let text):
+        if let processedComment = processBlockComment(text) {
+          if hasBlockComment {
+            comments.append(processedComment)
+          } else {
+            hasBlockComment = true
+            comments = [processedComment]
+          }
         }
-        hasBlockComment = true
-        guard let processedText = processBlockComment(text, isDocComment: piece.isDocComment) else {
-          return nil
+        currentLineComments = [] // Reset line comments when encountering a block comment
+      case .docLineComment(let text):
+        let prefixToDrop = ("///") + (allLineCommentsHaveSpace ? " " : "")
+        if foundStop {
+          currentLineComments = [text.dropPrefix(prefixToDrop)]
+          foundStop = false
+        } else {
+          currentLineComments.append(text.dropPrefix(prefixToDrop))
         }
-        comments.append(processedText[...])
-      case .lineComment(let text), .docLineComment(let text):
-        if hasBlockComment {
-          return nil
-        }
-        hasLineComment = true
-        let prefixToDrop = (piece.isDocComment ? "///" : "//") + (allLineCommentsHaveSpace ? " " : "")
-        comments.append(text.dropPrefix(prefixToDrop))
+      case .newlines(let count) where count == 1:
+        continue
       default:
-        break
+        if !currentLineComments.isEmpty {
+          comments = currentLineComments
+        }
+        currentLineComments = []
+        foundStop = true
       }
     }
 
-    if comments.isEmpty { return nil }
+    // If there are remaining line comments, use them as the last doc comment block.
+    if !currentLineComments.isEmpty {
+      comments = currentLineComments
+    }
 
+    if comments.isEmpty { return nil }
     return comments.joined(separator: "\n")
   }
 }
@@ -132,12 +142,3 @@ fileprivate extension StringProtocol where SubSequence == Substring {
 fileprivate func commonPrefix(_ lhs: Substring, _ rhs: Substring) -> Substring {
   return lhs[..<lhs.index(lhs.startIndex, offsetBy: zip(lhs, rhs).prefix { $0 == $1 }.count)]
 }
-
-fileprivate extension TriviaPiece {
-  var isDocComment: Bool {
-    switch self {
-    case .docBlockComment, .docLineComment: return true
-    default: return false
-    }
-  }
-}