Use raw documentation for full documentation in completion

Author: a7medev

Sources/Csourcekitd/include/CodeCompletionSwiftInterop.h

@@ -324,11 +324,15 @@ typedef struct {
     void (^_Null_unspecified handler)(const char *_Null_unspecified)
   );
 
-  void (*_Nullable completion_item_get_doc_full)(
-    _Nonnull swiftide_api_completion_response_t,
-    _Nonnull swiftide_api_completion_item_t,
-    void (^_Nonnull handler)(const char *_Nullable)
-  );
+  void (*_Nullable completion_item_get_doc_full_as_xml)(
+      _Nonnull swiftide_api_completion_response_t,
+      _Nonnull swiftide_api_completion_item_t,
+      void (^_Nonnull handler)(const char *_Nullable));
+
+  void (*_Nullable completion_item_get_doc_raw)(
+      _Nonnull swiftide_api_completion_response_t,
+      _Nonnull swiftide_api_completion_item_t,
+      void (^_Nonnull handler)(const char *_Nullable));
 
   void (*_Nonnull completion_item_get_associated_usrs)(
     _Null_unspecified swiftide_api_completion_response_t,

Sources/SKTestSupport/SkipUnless.swift

@@ -278,7 +278,7 @@ package actor SkipUnless {
     return try await shared.skipUnlessSupportedByToolchain(swiftVersion: SwiftVersion(6, 2), file: file, line: line) {
       let sourcekitd = try await getSourceKitD()
 
-      return sourcekitd.ideApi.completion_item_get_doc_full != nil
+      return sourcekitd.ideApi.completion_item_get_doc_raw != nil
     }
   }
 

Sources/SourceKitD/sourcekitd_functions.swift

@@ -146,7 +146,8 @@ 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: loadOptional("swiftide_completion_item_get_doc_full"),
+      completion_item_get_doc_full_as_xml: loadOptional("swiftide_completion_item_get_doc_full_as_xml"),
+      completion_item_get_doc_raw: loadOptional("swiftide_completion_item_get_doc_raw"),
       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/SwiftLanguageService/CodeCompletionSession.swift

@@ -586,10 +586,8 @@ class CodeCompletionSession {
   }
 
   private static func documentationString(from response: SKDResponseDictionary, sourcekitd: SourceKitD) -> String? {
-    if let docFullAsXML: String = response[sourcekitd.keys.docFullAsXML] {
-      return orLog("Converting XML documentation to markdown") {
-        try xmlDocumentationToMarkdown(docFullAsXML)
-      }
+    if let docComment: String = response[sourcekitd.keys.docComment] {
+      return docComment
     }
 
     return response[sourcekitd.keys.docBrief]

Sources/SwiftSourceKitPlugin/ASTCompletion/CompletionSession.swift

@@ -241,9 +241,19 @@ struct ExtendedCompletionInfo {
     return result
   }
 
-  var fullDocumentation: String? {
+  var fullDocumentationAsXML: String? {
     var result: String? = nil
-    session.sourcekitd.ideApi.completion_item_get_doc_full?(session.response, rawItem) {
+    session.sourcekitd.ideApi.completion_item_get_doc_full_as_xml?(session.response, rawItem) {
+      if let cstr = $0 {
+        result = String(cString: cstr)
+      }
+    }
+    return result
+  }
+
+  var rawDocumentation: String? {
+    var result: String? = nil
+    session.sourcekitd.ideApi.completion_item_get_doc_raw?(session.response, rawItem) {
       if let cstr = $0 {
         result = String(cString: cstr)
       }

Sources/SwiftSourceKitPlugin/CompletionProvider.swift

@@ -266,7 +266,8 @@ actor CompletionProvider {
 
     return request.sourcekitd.responseDictionary([
       request.sourcekitd.keys.docBrief: info.briefDocumentation,
-      request.sourcekitd.keys.docFullAsXML: info.fullDocumentation,
+      request.sourcekitd.keys.docFullAsXML: info.fullDocumentationAsXML,
+      request.sourcekitd.keys.docComment: info.rawDocumentation,
       request.sourcekitd.keys.associatedUSRs: info.associatedUSRs as [SKDResponseValue]?,
     ])
   }

Tests/SourceKitLSPTests/SwiftCompletionTests.swift

@@ -40,6 +40,13 @@ final class SwiftCompletionTests: XCTestCase {
       """
       struct S {
         /// Documentation for `abc`.
+        ///
+        /// _More_ documentation for `abc`.
+        ///
+        /// Usage:
+        /// ```swift
+        /// S().abc
+        /// ```
         var abc: Int
 
         func test(a: Int) {
@@ -71,10 +78,14 @@ final class SwiftCompletionTests: XCTestCase {
       assertMarkdown(
         documentation: abc.documentation,
         expected: """
+          Documentation for `abc`.
+
+          _More_ documentation for `abc`.
+
+          Usage:
           ```swift
-          var abc: Int
+          S().abc
           ```
-          Documentation for `abc`.
           """
       )
       XCTAssertEqual(abc.filterText, "abc")
@@ -99,10 +110,14 @@ final class SwiftCompletionTests: XCTestCase {
       assertMarkdown(
         documentation: abc.documentation,
         expected: """
+          Documentation for `abc`.
+
+          _More_ documentation for `abc`.
+
+          Usage:
           ```swift
-          var abc: Int
+          S().abc
           ```
-          Documentation for `abc`.
           """
       )
       XCTAssertEqual(abc.filterText, "abc")
@@ -1207,12 +1222,7 @@ final class SwiftCompletionTests: XCTestCase {
     let resolvedItem = try await testClient.send(CompletionItemResolveRequest(item: item))
     assertMarkdown(
       documentation: resolvedItem.documentation,
-      expected: """
-        ```swift
-        func makeBool() -> Bool
-        ```
-        Creates a true value
-        """
+      expected: "Creates a true value"
     )
   }
 
@@ -1310,7 +1320,12 @@ private func assertMarkdown(
   file: StaticString = #filePath,
   line: UInt = #line
 ) {
-  XCTAssertEqual(documentation, .markupContent(MarkupContent(kind: .markdown, value: expected)))
+  XCTAssertEqual(
+    documentation,
+    .markupContent(MarkupContent(kind: .markdown, value: expected)),
+    file: file,
+    line: line
+  )
 }
 
 fileprivate extension Position {

Tests/SwiftSourceKitPluginTests/SwiftSourceKitPluginTests.swift

@@ -205,6 +205,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)
+    XCTAssertNil(doc.docComment)
     XCTAssertNil(doc.docFullAsXML)
     XCTAssertNil(doc.docBrief)
   }
@@ -441,6 +442,7 @@ 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.docComment, "Protocol P foo1")
     XCTAssertEqual(
       sym1Doc.docFullAsXML,
       """
@@ -461,6 +463,7 @@ final class SwiftSourceKitPluginTests: XCTestCase {
     XCTAssertEqual(sym1Doc.associatedUSRs, ["s:1a1SV4foo1yyF", "s:1a1PP4foo1yyF"])
 
     let sym2Doc = try await sourcekitd.completeDocumentation(id: sym2.id)
+    XCTAssertEqual(sym2Doc.docComment, "Struct S foo2")
     XCTAssertEqual(
       sym2Doc.docFullAsXML,
       """
@@ -478,6 +481,7 @@ final class SwiftSourceKitPluginTests: XCTestCase {
     XCTAssertEqual(sym2Doc.associatedUSRs, ["s:1a1SV4foo2yyF"])
 
     let sym3Doc = try await sourcekitd.completeDocumentation(id: sym3.id)
+    XCTAssertNil(sym3Doc.docComment)
     XCTAssertNil(sym3Doc.docFullAsXML)
     XCTAssertNil(sym3Doc.docBrief)
     XCTAssertEqual(sym3Doc.associatedUSRs, ["s:1a1SV4foo3yyF"])
@@ -1801,12 +1805,14 @@ private struct CompletionResult: Equatable, Sendable {
 }
 
 private struct CompletionDocumentation {
+  var docComment: String? = nil
   var docFullAsXML: String? = nil
   var docBrief: String? = nil
   var associatedUSRs: [String] = []
 
   init(_ dict: SKDResponseDictionary) {
     let keys = dict.sourcekitd.keys
+    self.docComment = dict[keys.docComment]
     self.docFullAsXML = dict[keys.docFullAsXML]
     self.docBrief = dict[keys.docBrief]
     self.associatedUSRs = dict[keys.associatedUSRs]?.asStringArray ?? []