Assert appropriate completion doc based on full doc support in sourcekitd

Author: a7medev

Tests/SourceKitLSPTests/SwiftCompletionTests.swift

@@ -10,10 +10,13 @@
 //
 //===----------------------------------------------------------------------===//
 
+import Csourcekitd
 import LanguageServerProtocol
 import SKTestSupport
+import SourceKitD
 import SourceKitLSP
 import SwiftExtensions
+import ToolchainRegistry
 import XCTest
 
 final class SwiftCompletionTests: XCTestCase {
@@ -67,9 +70,10 @@ final class SwiftCompletionTests: XCTestCase {
     if let abc = abc {
       XCTAssertEqual(abc.kind, .property)
       XCTAssertEqual(abc.detail, "Int")
-      assertMarkdown(
+      try await assertDocumentation(
         documentation: abc.documentation,
-        expected: """
+        expectedBrief: "Documentation for abc.",
+        expectedFull: """
           ```swift
           var abc: Int
           ```
@@ -95,9 +99,10 @@ final class SwiftCompletionTests: XCTestCase {
       // If we switch to server-side filtering this will change.
       XCTAssertEqual(abc.kind, .property)
       XCTAssertEqual(abc.detail, "Int")
-      assertMarkdown(
+      try await assertDocumentation(
         documentation: abc.documentation,
-        expected: """
+        expectedBrief: "Documentation for abc.",
+        expectedFull: """
           ```swift
           var abc: Int
           ```
@@ -1203,9 +1208,10 @@ final class SwiftCompletionTests: XCTestCase {
     let item = try XCTUnwrap(completions.items.only)
     XCTAssertNil(item.documentation)
     let resolvedItem = try await testClient.send(CompletionItemResolveRequest(item: item))
-    assertMarkdown(
+    try await assertDocumentation(
       documentation: resolvedItem.documentation,
-      expected: """
+      expectedBrief: "Creates a true value",
+      expectedFull: """
         ```swift
         func makeBool() -> Bool
         ```
@@ -1217,6 +1223,9 @@ final class SwiftCompletionTests: XCTestCase {
   func testCompletionBriefDocumentationFallback() async throws {
     try await SkipUnless.sourcekitdSupportsPlugin()
 
+    let fullDocumentationSupported = try await sourcekitdSupportsFullDocumentation()
+    try XCTSkipUnless(fullDocumentationSupported)
+
     let testClient = try await TestSourceKitLSPClient()
     let uri = DocumentURI(for: .swift)
 
@@ -1310,6 +1319,30 @@ private func assertMarkdown(
   XCTAssertEqual(documentation, .markupContent(MarkupContent(kind: .markdown, value: expected)))
 }
 
+/// Asserts that documentation matches the expected values based on whether full documentation is supported in sourcekitd or not.
+private func assertDocumentation(
+  documentation: StringOrMarkupContent?,
+  expectedBrief: String,
+  expectedFull: String,
+  file: StaticString = #filePath,
+  line: UInt = #line
+) async throws {
+  let supportsFullDocumentation = try await sourcekitdSupportsFullDocumentation()
+  let expected = supportsFullDocumentation ? expectedFull : expectedBrief
+
+  assertMarkdown(documentation: documentation, expected: expected, file: file, line: line)
+}
+
+private func sourcekitdSupportsFullDocumentation() async throws -> Bool {
+  let sourcekitdPath = await ToolchainRegistry.forTesting.default!.sourcekitd!
+  let sourcekitd = try await SourceKitD.getOrCreate(
+    dylibPath: sourcekitdPath,
+    pluginPaths: sourceKitPluginPaths
+  )
+
+  return sourcekitd.ideApi.completion_item_get_doc_full_copy != nil
+}
+
 fileprivate extension Position {
   func adding(columns: Int) -> Position {
     return Position(line: line, utf16index: utf16index + columns)

Tests/SwiftSourceKitPluginTests/SwiftSourceKitPluginTests.swift

@@ -203,7 +203,8 @@ 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.docFullAsXML, nil)
+    XCTAssertNil(doc.docFullAsXML)
+    XCTAssertNil(doc.docBrief)
   }
 
   func testMultipleFiles() async throws {
@@ -436,38 +437,47 @@ 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.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>
-                   """)
+    assertDocumentation(
+      full: sourcekitd.supportsFullDocumentationInCompletion,
+      documentation: sym1Doc,
+      expectedBrief: "Protocol P foo1",
+      expectedFull: """
+        <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.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>
-                   """)
+    assertDocumentation(
+      full: sourcekitd.supportsFullDocumentationInCompletion,
+      documentation: sym2Doc,
+      expectedBrief: "Struct S foo2",
+      expectedFull: """
+        <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.docFullAsXML)
+    XCTAssertNil(sym3Doc.docBrief)
     XCTAssertEqual(sym3Doc.associatedUSRs, ["s:1a1SV4foo3yyF"])
   }
 
@@ -1789,11 +1799,13 @@ 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 ?? []
   }
@@ -2072,6 +2084,10 @@ fileprivate extension SourceKitD {
     try await openDocument(path, contents: textWithoutMarker, compilerArguments: [path])
     return (positions["1️⃣"], recent)
   }
+
+  nonisolated var supportsFullDocumentationInCompletion: Bool {
+    return ideApi.completion_item_get_doc_full_copy != nil
+  }
 }
 
 private struct ExpectationNotFulfilledError: Error {}
@@ -2094,3 +2110,21 @@ private func runAsync<T: Sendable>(_ body: @escaping @Sendable () async throws -
   }
   return try result.get()
 }
+
+/// Asserts that documentation matches the expected values based on whether full documentation is supported in sourcekitd or not.
+private func assertDocumentation(
+  full: Bool,
+  documentation: CompletionDocumentation,
+  expectedBrief: String,
+  expectedFull: String,
+  file: StaticString = #filePath,
+  line: UInt = #line
+) {
+  if full {
+    XCTAssertEqual(documentation.docFullAsXML, expectedFull, file: file, line: line)
+    XCTAssertNil(documentation.docBrief, "Expected brief documentation to not be available", file: file, line: line)
+  } else {
+    XCTAssertEqual(documentation.docBrief, expectedBrief, file: file, line: line)
+    XCTAssertNil(documentation.docFullAsXML, "Expected full documentation to not be available", file: file, line: line)
+  }
+}