Refine ParametersDocumentationExtractor to avoid mutations

Author: a7medev

Sources/SwiftLanguageService/ParametersDocumentationExtractor.swift

@@ -1,25 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
 import Foundation
 import Markdown
 
+/// Extracts parameter documentation from a markdown string.
+///
+/// The parameter extraction implementation is almost ported from the implementation in the Swift compiler codebase.
+///
+/// The problem with doing that in the Swift compiler codebase is that once you parse a the comment as markdown into
+/// a `Document` you cannot easily convert it back into markdown (we'd need to write our own markdown formatter).
+/// Besides, `cmark` doesn't handle Doxygen commands.
+///
+/// We considered using `swift-docc` but we faced some problems with it:
+///
+/// 1. We would need to refactor existing use of `swift-docc` in SourceKit-LSP to reuse some of that logic here besides
+///    providing the required arguments.
+/// 2. The result returned by DocC can't be directly converted to markdown, we'd need to provide our own DocC markdown renderer.
+///
+/// Implementing this using `swift-markdown` allows us to easily parse the comment, process it, convert it back to markdown.
+/// It also provides minimal parsing for Doxygen commands (we're only interested in `\param`) allowing us to use the same
+/// implementation for Clang-based declarations.
+///
+/// Although this approach involves code duplication, it's simple enough for the initial implementation. We should consider
+/// `swift-docc` in the future.
 private struct ParametersDocumentationExtractor {
-  private var parameters = [String: String]()
+  struct Parameter {
+    let name: String
+    let documentation: String
+  }
 
   /// Extracts parameter documentation from a markdown string.
   ///
   /// - Returns: A tuple containing the extracted parameters and the remaining markdown.
-  mutating func extract(from markdown: String) -> (parameters: [String: String], remaining: String) {
+  func extract(from markdown: String) -> (parameters: [String: String], remaining: String) {
     let document = Document(parsing: markdown, options: [.parseBlockDirectives, .parseMinimalDoxygen])
 
-    var remainingBlocks = [any BlockMarkup]()
+    var parameters: [String: String] = [:]
+    var remainingBlocks: [any BlockMarkup] = []
 
     for block in document.blockChildren {
       switch block {
       case let unorderedList as UnorderedList:
-        if let newUnorderedList = extract(from: unorderedList) {
+        let (newUnorderedList, params) = extract(from: unorderedList)
+        if let newUnorderedList {
           remainingBlocks.append(newUnorderedList)
         }
+
+        for param in params {
+          parameters[param.name] = param.documentation
+        }
+
       case let doxygenParameter as DoxygenParameter:
-        extract(from: doxygenParameter)
+        let param = extract(from: doxygenParameter)
+        parameters[param.name] = param.documentation
+
       default:
         remainingBlocks.append(block)
       }
@@ -31,29 +75,35 @@ private struct ParametersDocumentationExtractor {
   }
 
   /// Extracts parameter documentation from a Doxygen parameter command.
-  private mutating func extract(from doxygenParameter: DoxygenParameter) {
-    parameters[doxygenParameter.name] = Document(doxygenParameter.blockChildren).format()
+  private func extract(from doxygenParameter: DoxygenParameter) -> Parameter {
+    return Parameter(
+      name: doxygenParameter.name,
+      documentation: Document(doxygenParameter.blockChildren).format(),
+    )
   }
 
   /// Extracts parameter documentation from an unordered list.
   ///
   /// - Returns: A new UnorderedList with the items that were not added to the parameters if any.
-  private mutating func extract(from unorderedList: UnorderedList) -> UnorderedList? {
-    var newItems = [ListItem]()
+  private func extract(from unorderedList: UnorderedList) -> (remaining: UnorderedList?, parameters: [Parameter]) {
+    var parameters: [Parameter] = []
+    var newItems: [ListItem] = []
 
     for item in unorderedList.listItems {
-      if extractSingle(from: item) || extractOutline(from: item) {
-        continue
+      if let param = extractSingle(from: item) {
+        parameters.append(param)
+      } else if let params = extractOutline(from: item) {
+        parameters.append(contentsOf: params)
+      } else {
+        newItems.append(item)
       }
-
-      newItems.append(item)
     }
 
     if newItems.isEmpty {
-      return nil
+      return (remaining: nil, parameters: parameters)
     }
 
-    return UnorderedList(newItems)
+    return (remaining: UnorderedList(newItems), parameters: parameters)
   }
 
   /// Parameter documentation from a `Parameters:` outline.
@@ -65,33 +115,24 @@ private struct ParametersDocumentationExtractor {
   /// ```
   ///
   /// - Returns: True if the list item has parameter outline documentation, false otherwise.
-  private mutating func extractOutline(from listItem: ListItem) -> Bool {
+  private func extractOutline(from listItem: ListItem) -> [Parameter]? {
     guard let firstChild = listItem.child(at: 0) as? Paragraph,
       let headingText = firstChild.child(at: 0) as? Text
     else {
-      return false
+      return nil
     }
 
-    let parametersPrefix = "parameters:"
-    let headingContent = headingText.string.trimmingCharacters(in: .whitespaces)
-
-    guard headingContent.lowercased().hasPrefix(parametersPrefix) else {
-      return false
+    guard headingText.string.trimmingCharacters(in: .whitespaces).lowercased().hasPrefix("parameters:") else {
+      return nil
     }
 
-    for child in listItem.children {
+    return listItem.children.flatMap { child in
       guard let nestedList = child as? UnorderedList else {
-        continue
+        return [] as [Parameter]
       }
 
-      for nestedItem in nestedList.listItems {
-        if let parameter = extractOutlineItem(from: nestedItem) {
-          parameters[parameter.name] = parameter.documentation
-        }
-      }
+      return nestedList.listItems.compactMap(extractOutlineItem)
     }
-
-    return true
   }
 
   /// Extracts parameter documentation from a single parameter.
@@ -102,40 +143,34 @@ private struct ParametersDocumentationExtractor {
   /// ```
   ///
   /// - Returns: True if the list item has single parameter documentation, false otherwise.
-  private mutating func extractSingle(from listItem: ListItem) -> Bool {
+  private func extractSingle(from listItem: ListItem) -> Parameter? {
     guard let paragraph = listItem.child(at: 0) as? Paragraph,
       let paragraphText = paragraph.child(at: 0) as? Text
     else {
-      return false
+      return nil
     }
 
     let parameterPrefix = "parameter "
     let paragraphContent = paragraphText.string
 
     guard paragraphContent.count >= parameterPrefix.count else {
-      return false
+      return nil
     }
 
     let prefixEnd = paragraphContent.index(paragraphContent.startIndex, offsetBy: parameterPrefix.count)
     let potentialMatch = paragraphContent[..<prefixEnd].lowercased()
 
     guard potentialMatch == parameterPrefix else {
-      return false
+      return nil
     }
 
     let remainingContent = String(paragraphContent[prefixEnd...]).trimmingCharacters(in: .whitespaces)
 
-    guard let parameter = extractParam(firstTextContent: remainingContent, listItem: listItem) else {
-      return false
-    }
-
-    parameters[parameter.name] = parameter.documentation
-
-    return true
+    return extractParam(firstTextContent: remainingContent, listItem: listItem)
   }
 
   /// Extracts a parameter field from a list item (used for parameter outline items)
-  private func extractOutlineItem(from listItem: ListItem) -> (name: String, documentation: String)? {
+  private func extractOutlineItem(from listItem: ListItem) -> Parameter? {
     guard let paragraph = listItem.child(at: 0) as? Paragraph else {
       return nil
     }
@@ -157,7 +192,7 @@ private struct ParametersDocumentationExtractor {
   private func extractParam(
     firstTextContent: String,
     listItem: ListItem
-  ) -> (name: String, documentation: String)? {
+  ) -> Parameter? {
     guard let paragraph = listItem.child(at: 0) as? Paragraph else {
       return nil
     }
@@ -178,7 +213,7 @@ private struct ParametersDocumentationExtractor {
     let remainingChildren = [Paragraph(remainingParagraphChildren)] + listItem.blockChildren.dropFirst()
     let documentation = Document(remainingChildren).format()
 
-    return (name, documentation)
+    return Parameter(name: name, documentation: documentation)
   }
 }
 
@@ -187,6 +222,6 @@ private struct ParametersDocumentationExtractor {
 /// - Parameter markdown: The markdown text to extract parameters from
 /// - Returns: A tuple containing the extracted parameters dictionary and the remaining markdown text
 package func extractParametersDocumentation(from markdown: String) -> ([String: String], String) {
-  var extractor = ParametersDocumentationExtractor()
+  let extractor = ParametersDocumentationExtractor()
   return extractor.extract(from: markdown)
 }