Test parameter extraction edge cases and match swift-docc

Author: a7medev

Sources/SwiftLanguageService/ParametersDocumentationExtractor.swift

@@ -57,12 +57,14 @@ private struct ParametersDocumentationExtractor {
         }
 
         for param in params {
-          parameters[param.name] = param.documentation
+          // If duplicate parameter documentation is found, keep the first one following swift-docc's behavior
+          parameters[param.name] = parameters[param.name] ?? param.documentation
         }
 
       case let doxygenParameter as DoxygenParameter:
         let param = extract(from: doxygenParameter)
-        parameters[param.name] = param.documentation
+        // If duplicate parameter documentation is found, keep the first one following swift-docc's behavior
+        parameters[param.name] = parameters[param.name] ?? param.documentation
 
       default:
         remainingBlocks.append(block)

Sources/SwiftLanguageService/SignatureHelp.swift

@@ -36,6 +36,7 @@ fileprivate extension String {
 }
 
 fileprivate extension ParameterInformation {
+  /// - Parameter parameterDocumentation: A dictionary with the parameter name as the key and its documentation as the value.
   init?(
     _ parameter: SKDResponseDictionary,
     _ signatureLabel: String,

Tests/SourceKitLSPTests/ParametersDocumentationExtractorTests.swift

@@ -249,4 +249,79 @@ final class ParametersDocumentationExtractorTests: XCTestCase {
       """
     )
   }
+
+  /// Tests that we drop non-parameter items in the parameter outline. Aligns with swift-docc.
+  func testDropsNonParameterItemsInParameterOutline() {
+    let comment = """
+      - Parameters:
+        - number: The number to do stuff with
+        - TODO Improve this documentation
+      """
+
+    let (parameters, remaining) = extractParametersDocumentation(from: comment)
+
+    XCTAssertEqual(parameters, ["number": "The number to do stuff with"])
+    XCTAssertTrue(remaining.isEmpty)
+  }
+
+  /// Tests that we drop duplicate parameter documentation and keep thefirst one. Aligns with swift-docc.
+  func testDropsDuplicateParameterDocumentation() {
+    let comment = """
+      - Parameters:
+        - number: The number to do stuff with
+        - number: The number to do amazing stuff with
+      """
+
+    let (parameters, remaining) = extractParametersDocumentation(from: comment)
+
+    XCTAssertEqual(parameters, ["number": "The number to do stuff with"])
+    XCTAssertTrue(remaining.isEmpty)
+  }
+
+  /// Tests that we drop text after the colon in the parameter outline. Aligns with swift-docc.
+  func testDropsTextAfterColonInParameterOutline() {
+    let comment = """
+      - Parameters: listing parameter documentation below
+        - number: The number to do stuff
+      """
+
+    let (parameters, remaining) = extractParametersDocumentation(from: comment)
+
+    XCTAssertEqual(parameters, ["number": "The number to do stuff"])
+    XCTAssertTrue(remaining.isEmpty)
+  }
+
+  /// Tests that we support mixed parameter documentation styles in a single comment. Aligns with swift-docc.
+  func testMixedParameterDocumentationStyles() {
+    let comment = #"""
+      Function documentation.
+
+      - Parameters:
+        - first: First parameter from Parameters section
+      - Parameter second: Second parameter from separate Parameter
+      \param third Third parameter from Doxygen style
+
+      Additional documentation.
+      """#
+
+    let (parameters, remaining) = extractParametersDocumentation(from: comment)
+
+    XCTAssertEqual(
+      parameters,
+      [
+        "first": "First parameter from Parameters section",
+        "second": "Second parameter from separate Parameter",
+        "third": "Third parameter from Doxygen style",
+      ]
+    )
+
+    XCTAssertEqual(
+      remaining,
+      """
+      Function documentation.
+
+      Additional documentation.
+      """
+    )
+  }
 }

Tests/SourceKitLSPTests/SwiftSignatureHelpTests.swift

@@ -668,4 +668,77 @@ final class SwiftSignatureHelpTests: XCTestCase {
       ]
     )
   }
+
+  func testSignatureHelpMatchesParametersWithInternalNames() async throws {
+    try await SkipUnless.sourcekitdSupportsSignatureHelp()
+
+    let testClient = try await TestSourceKitLSPClient()
+    let uri = DocumentURI(for: .swift)
+
+    let positions = testClient.openDocument(
+      """
+      /// - Parameter number: The number to add 1 to
+      func addOne(to number: Int) -> Int { number + 1 }
+
+      func main() {
+        addOne(1️⃣)
+      }
+      """,
+      uri: uri
+    )
+
+    let result = try await testClient.send(
+      SignatureHelpRequest(
+        textDocument: TextDocumentIdentifier(uri),
+        position: positions["1️⃣"]
+      )
+    )
+
+    let signatureHelp = try XCTUnwrap(result)
+    let signature = try XCTUnwrap(signatureHelp.signatures.only)
+    let signatureDocumentation = try XCTUnwrap(signature.documentation)
+    let parameter = try XCTUnwrap(signature.parameters?.only)
+
+    XCTAssertEqual(signatureDocumentation, .markupContent(MarkupContent(kind: .markdown, value: "")))
+    XCTAssertEqual(
+      parameter.documentation,
+      .markupContent(MarkupContent(kind: .markdown, value: "The number to add 1 to"))
+    )
+  }
+
+  /// Tests that we drop parameter documentation for parameters that don't exist aligning with swift-docc.
+  func testSignatureHelpDropsNonExistentParameterDocumentation() async throws {
+    try await SkipUnless.sourcekitdSupportsSignatureHelp()
+
+    let testClient = try await TestSourceKitLSPClient()
+    let uri = DocumentURI(for: .swift)
+
+    let positions = testClient.openDocument(
+      """
+      /// - Parameters:
+      ///   - numberWithTypo: The number to do stuff with
+      func compute(number: Int) {}
+
+      func main() {
+        compute(1️⃣)
+      }
+      """,
+      uri: uri
+    )
+
+    let result = try await testClient.send(
+      SignatureHelpRequest(
+        textDocument: TextDocumentIdentifier(uri),
+        position: positions["1️⃣"]
+      )
+    )
+
+    let signatureHelp = try XCTUnwrap(result)
+    let signature = try XCTUnwrap(signatureHelp.signatures.only)
+    let parameter = try XCTUnwrap(signature.parameters?.only)
+    let signatureDocumentation = try XCTUnwrap(signature.documentation)
+
+    XCTAssertEqual(signatureDocumentation, .markupContent(MarkupContent(kind: .markdown, value: "")))
+    XCTAssertNil(parameter.documentation)
+  }
 }