Fetch full documentation in code completion

Sources/Csourcekitd/include/CodeCompletionSwiftInterop.h

@@ -324,6 +324,12 @@ typedef struct {
     void (^_Null_unspecified handler)(const char *_Null_unspecified)
   );
 
+  void (*_Nonnull completion_item_get_doc_full_copy)(
+    _Null_unspecified swiftide_api_completion_response_t,
+    _Null_unspecified swiftide_api_completion_item_t,
+    void (^_Null_unspecified handler)(char *_Null_unspecified)
+  );
+
   void (*_Nonnull completion_item_get_associated_usrs)(
     _Null_unspecified swiftide_api_completion_response_t,
     _Null_unspecified swiftide_api_completion_item_t,

Sources/SourceKitD/sourcekitd_functions.swift

@@ -146,6 +146,7 @@ extension sourcekitd_ide_api_functions_t {
       completion_item_get_source_text: try loadRequired("swiftide_completion_item_get_source_text"),
       completion_item_get_type_name: try loadRequired("swiftide_completion_item_get_type_name"),
       completion_item_get_doc_brief: try loadRequired("swiftide_completion_item_get_doc_brief"),
+      completion_item_get_doc_full_copy: try loadRequired("swiftide_completion_item_get_doc_full_copy"),
       completion_item_get_associated_usrs: try loadRequired("swiftide_completion_item_get_associated_usrs"),
       completion_item_get_kind: try loadRequired("swiftide_completion_item_get_kind"),
       completion_item_get_associated_kind: try loadRequired("swiftide_completion_item_get_associated_kind"),

Sources/SourceKitLSP/Swift/CodeCompletionSession.swift

@@ -574,13 +574,23 @@ class CodeCompletionSession {
           fileContents: nil
         )
       }
-      if let docString: String = documentationResponse?[sourcekitd.keys.docBrief] {
+
+      if let response = documentationResponse,
+         let docString = documentationString(from: response, sourcekitd: sourcekitd) {
         item.documentation = .markupContent(MarkupContent(kind: .markdown, value: docString))
       }
     }
     return item
   }
 
+  private static func documentationString(from response: SKDResponseDictionary, sourcekitd: SourceKitD) -> String? {
+    if let docFullAsXML: String = response[sourcekitd.keys.docFullAsXML] {
+      return try? xmlDocumentationToMarkdown(docFullAsXML)
+    }
+
+    return response[sourcekitd.keys.docBrief]
+  }
+
   private func computeCompletionTextEdit(
     completionPos: Position,
     requestPosition: Position,

Sources/SwiftSourceKitPlugin/ASTCompletion/CompletionSession.swift

@@ -241,6 +241,17 @@ struct ExtendedCompletionInfo {
     return result
   }
 
+  var fullDocumentation: String? {
+    var result: String? = nil
+    session.sourcekitd.ideApi.completion_item_get_doc_full_copy(session.response, rawItem) {
+      if let cstr = $0 {
+        result = String(cString: cstr)
+        free(cstr)
+      }
+    }
+    return result
+  }
+
   var associatedUSRs: [String] {
     var result: [String] = []
     session.sourcekitd.ideApi.completion_item_get_associated_usrs(session.response, rawItem) { ptr, len in

Sources/SwiftSourceKitPlugin/CompletionProvider.swift

@@ -262,10 +262,17 @@ actor CompletionProvider {
   func handleCompletionDocumentation(_ request: SKDRequestDictionaryReader) throws -> SKDResponseDictionaryBuilder {
     let info = try handleExtendedCompletionRequest(request)
 
-    return request.sourcekitd.responseDictionary([
-      request.sourcekitd.keys.docBrief: info.briefDocumentation,
-      request.sourcekitd.keys.associatedUSRs: info.associatedUSRs as [SKDResponseValue]?,
+    var response = request.sourcekitd.responseDictionary([
+      request.sourcekitd.keys.associatedUSRs: info.associatedUSRs as [SKDResponseValue]?
     ])
+
+    if let fullDocumentation = info.fullDocumentation {
+      response.set(request.sourcekitd.keys.docFullAsXML, to: fullDocumentation)
+    } else {
+      response.set(request.sourcekitd.keys.docBrief, to: info.briefDocumentation)
+    }
+
+    return response
   }
 
   func handleCompletionDiagnostic(_ dict: SKDRequestDictionaryReader) throws -> SKDResponseDictionaryBuilder {

Tests/SourceKitLSPTests/SwiftCompletionTests.swift

@@ -67,7 +67,15 @@ final class SwiftCompletionTests: XCTestCase {
     if let abc = abc {
       XCTAssertEqual(abc.kind, .property)
       XCTAssertEqual(abc.detail, "Int")
-      XCTAssertEqual(abc.documentation, .markupContent(MarkupContent(kind: .markdown, value: "Documentation for abc.")))
+      assertMarkdown(
+        documentation: abc.documentation,
+        expected: """
+          ```swift
+          var abc: Int
+          ```
+          Documentation for `abc`.
+          """
+      )
       XCTAssertEqual(abc.filterText, "abc")
       XCTAssertEqual(abc.textEdit, .textEdit(TextEdit(range: Range(positions["1️⃣"]), newText: "abc")))
       XCTAssertEqual(abc.insertText, "abc")
@@ -87,7 +95,15 @@ final class SwiftCompletionTests: XCTestCase {
       // If we switch to server-side filtering this will change.
       XCTAssertEqual(abc.kind, .property)
       XCTAssertEqual(abc.detail, "Int")
-      XCTAssertEqual(abc.documentation, .markupContent(MarkupContent(kind: .markdown, value: "Documentation for abc.")))
+      assertMarkdown(
+        documentation: abc.documentation,
+        expected: """
+          ```swift
+          var abc: Int
+          ```
+          Documentation for `abc`.
+          """
+      )
       XCTAssertEqual(abc.filterText, "abc")
       XCTAssertEqual(abc.textEdit, .textEdit(TextEdit(range: positions["1️⃣"]..<offsetPosition, newText: "abc")))
       XCTAssertEqual(abc.insertText, "abc")
@@ -1187,9 +1203,41 @@ final class SwiftCompletionTests: XCTestCase {
     let item = try XCTUnwrap(completions.items.only)
     XCTAssertNil(item.documentation)
     let resolvedItem = try await testClient.send(CompletionItemResolveRequest(item: item))
-    XCTAssertEqual(
-      resolvedItem.documentation,
-      .markupContent(MarkupContent(kind: .markdown, value: "Creates a true value"))
+    assertMarkdown(
+      documentation: resolvedItem.documentation,
+      expected: """
+        ```swift
+        func makeBool() -> Bool
+        ```
+        Creates a true value
+        """
+    )
+  }
+
+  func testCompletionBriefDocumentationFallback() async throws {
+    try await SkipUnless.sourcekitdSupportsPlugin()
+
+    let testClient = try await TestSourceKitLSPClient()
+    let uri = DocumentURI(for: .swift)
+
+    // We test completion for result builder build functions since they don't have full documentation
+    // but still have brief documentation.
+    let positions = testClient.openDocument(
+      """
+      @resultBuilder
+      struct AnyBuilder {
+        static func 1️⃣
+      }
+      """,
+      uri: uri
+    )
+    let completions = try await testClient.send(
+      CompletionRequest(textDocument: TextDocumentIdentifier(uri), position: positions["1️⃣"])
+    )
+    let item = try XCTUnwrap(completions.items.filter { $0.label.contains("buildBlock") }.only)
+    assertMarkdown(
+      documentation: item.documentation,
+      expected: "Required by every result builder to build combined results from statement blocks"
     )
   }
 
@@ -1253,6 +1301,15 @@ private func countFs(_ response: CompletionList) -> Int {
   return response.items.filter { $0.label.hasPrefix("f") }.count
 }
 
+private func assertMarkdown(
+  documentation: StringOrMarkupContent?,
+  expected: String,
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  XCTAssertEqual(documentation, .markupContent(MarkupContent(kind: .markdown, value: expected)))
+}
+
 fileprivate extension Position {
   func adding(columns: Int) -> Position {
     return Position(line: line, utf16index: utf16index + columns)

Tests/SwiftSourceKitPluginTests/SwiftSourceKitPluginTests.swift

@@ -203,7 +203,7 @@ final class SwiftSourceKitPluginTests: XCTestCase {
     XCTAssertEqual(result2.items.count, 1)
     XCTAssertEqual(result2.items[0].name, "")
     let doc = try await sourcekitd.completeDocumentation(id: result2.items[0].id)
-    XCTAssertEqual(doc.docBrief, nil)
+    XCTAssertEqual(doc.docFullAsXML, nil)
   }
 
   func testMultipleFiles() async throws {
@@ -436,15 +436,34 @@ final class SwiftSourceKitPluginTests: XCTestCase {
     let sym3 = try unwrap(result.items.first(where: { $0.name == "foo3()" }), "did not find foo3; got \(result.items)")
 
     let sym1Doc = try await sourcekitd.completeDocumentation(id: sym1.id)
-    XCTAssertEqual(sym1Doc.docBrief, "Protocol P foo1")
+    XCTAssertEqual(sym1Doc.docFullAsXML,
+                   "<Function file=\"\(path)\" line=\"3\" column=\"8\">"
+                   + "<Name>foo1()</Name>"
+                   + "<USR>s:1a1PP4foo1yyF</USR>"
+                   + "<Declaration>func foo1()</Declaration>"
+                   + "<CommentParts>"
+                   + "<Abstract><Para>Protocol P foo1</Para></Abstract>"
+                   + "<Discussion><Note>"
+                   + "<Para>This documentation comment was inherited from <codeVoice>P</codeVoice>.</Para>"
+                   + "</Note></Discussion>"
+                   + "</CommentParts>"
+                   + "</Function>")
     XCTAssertEqual(sym1Doc.associatedUSRs, ["s:1a1SV4foo1yyF", "s:1a1PP4foo1yyF"])
 
     let sym2Doc = try await sourcekitd.completeDocumentation(id: sym2.id)
-    XCTAssertEqual(sym2Doc.docBrief, "Struct S foo2")
+    XCTAssertEqual(sym2Doc.docFullAsXML,
+                   "<Function file=\"\(path)\" line=\"8\" column=\"8\">"
+                   + "<Name>foo2()</Name>"
+                   + "<USR>s:1a1SV4foo2yyF</USR>"
+                   + "<Declaration>func foo2()</Declaration>"
+                   + "<CommentParts>"
+                   + "<Abstract><Para>Struct S foo2</Para></Abstract>"
+                   + "</CommentParts>"
+                   + "</Function>")
     XCTAssertEqual(sym2Doc.associatedUSRs, ["s:1a1SV4foo2yyF"])
 
     let sym3Doc = try await sourcekitd.completeDocumentation(id: sym3.id)
-    XCTAssertNil(sym3Doc.docBrief)
+    XCTAssertNil(sym3Doc.docFullAsXML)
     XCTAssertEqual(sym3Doc.associatedUSRs, ["s:1a1SV4foo3yyF"])
   }
 
@@ -1766,12 +1785,12 @@ fileprivate struct CompletionResult: Equatable, Sendable {
 }
 
 fileprivate struct CompletionDocumentation {
-  var docBrief: String? = nil
+  var docFullAsXML: String? = nil
   var associatedUSRs: [String] = []
 
   init(_ dict: SKDResponseDictionary) {
     let keys = dict.sourcekitd.keys
-    self.docBrief = dict[keys.docBrief]
+    self.docFullAsXML = dict[keys.docFullAsXML]
     self.associatedUSRs = dict[keys.associatedUSRs]?.asStringArray ?? []
   }
 }