Show full documentation without declaration in completion

Author: a7medev

Sources/SourceKitLSP/Swift/CodeCompletionSession.swift

@@ -587,7 +587,7 @@ 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)
+        try xmlDocumentationToMarkdown(docFullAsXML, includeDeclaration: false)
       }
     }
 

Sources/SourceKitLSP/Swift/CommentXML.swift

@@ -24,13 +24,17 @@ enum CommentXMLError: Error {
 /// Converts from sourcekit's XML documentation format to Markdown.
 ///
 /// This code should go away and sourcekitd should return the Markdown directly.
-package func xmlDocumentationToMarkdown(_ xmlString: String) throws -> String {
+///
+/// - Parameters:
+///   - xmlString: The XML string to convert.
+///   - includeDeclaration: If true, the declaration will be included at the top of the output markdown.
+package func xmlDocumentationToMarkdown(_ xmlString: String, includeDeclaration: Bool = true) throws -> String {
   let xml = try XMLDocument(xmlString: xmlString)
   guard let root = xml.rootElement() else {
     throw CommentXMLError.noRootElement
   }
 
-  var convert = XMLToMarkdown()
+  var convert = XMLToMarkdown(includeDeclaration: includeDeclaration)
   convert.out.reserveCapacity(xmlString.utf16.count)
   convert.toMarkdown(root)
   return convert.out
@@ -42,6 +46,11 @@ private struct XMLToMarkdown {
   let indentWidth: Int = 4
   var lineNumber: Int = 0
   var inParam: Bool = false
+  let includeDeclaration: Bool
+
+  init(includeDeclaration: Bool) {
+    self.includeDeclaration = includeDeclaration
+  }
 
   mutating func newlineIfNeeded(count: Int = 1) {
     if !out.isEmpty && out.last! != "\n" {
@@ -74,10 +83,12 @@ private struct XMLToMarkdown {
   mutating func toMarkdown(_ node: XMLElement) {
     switch node.name {
     case "Declaration":
-      newlineIfNeeded(count: 2)
-      out += "```swift\n"
-      toMarkdown(node.children)
-      out += "\n```\n"
+      if includeDeclaration {
+        newlineIfNeeded(count: 2)
+        out += "```swift\n"
+        toMarkdown(node.children)
+        out += "\n```\n"
+      }
 
     case "Name", "USR", "Direction":
       break

Tests/SourceKitLSPTests/LocalSwiftTests.swift

@@ -1149,6 +1149,32 @@ final class LocalSwiftTests: XCTestCase {
     )
   }
 
+  func testXMLToMarkdownCommentOmitDeclaration() {
+      XCTAssertEqual(
+        try xmlDocumentationToMarkdown(
+          """
+          <Function file="Pi.swift" line="3" column="14">\
+          <Declaration>func pi()</Declaration>\
+          <CommentParts>\
+          <Abstract><Para>Computes π with infinite precision.</Para></Abstract>\
+          <Discussion>\
+          <Para>This function doesn’t terminate.</Para>\
+          </Discussion>\
+          </CommentParts>\
+          </Function>
+          """,
+          includeDeclaration: false
+        ),
+        """
+        Computes π with infinite precision.
+
+        ### Discussion
+
+        This function doesn’t terminate.
+        """
+      )
+  }
+
   func testSymbolInfo() async throws {
     let testClient = try await TestSourceKitLSPClient()
     let url = URL(fileURLWithPath: "/\(UUID())/a.swift")

Tests/SourceKitLSPTests/SwiftCompletionTests.swift

@@ -40,6 +40,8 @@ final class SwiftCompletionTests: XCTestCase {
       """
       struct S {
         /// Documentation for `abc`.
+        ///
+        /// - Note: This is a note.
         var abc: Int
 
         func test(a: Int) {
@@ -71,10 +73,11 @@ final class SwiftCompletionTests: XCTestCase {
       assertMarkdown(
         documentation: abc.documentation,
         expected: """
-          ```swift
-          var abc: Int
-          ```
           Documentation for `abc`.
+
+          ### Discussion
+
+          This is a note.
           """
       )
       XCTAssertEqual(abc.filterText, "abc")
@@ -99,10 +102,11 @@ final class SwiftCompletionTests: XCTestCase {
       assertMarkdown(
         documentation: abc.documentation,
         expected: """
-          ```swift
-          var abc: Int
-          ```
           Documentation for `abc`.
+
+          ### Discussion
+
+          This is a note.
           """
       )
       XCTAssertEqual(abc.filterText, "abc")
@@ -126,6 +130,8 @@ final class SwiftCompletionTests: XCTestCase {
       """
       struct S {
         /// Documentation for `abc`.
+        ///
+        /// - Note: This is a note.
         var abc: Int
 
         func test(a: Int) {
@@ -182,6 +188,8 @@ final class SwiftCompletionTests: XCTestCase {
       """
       struct S {
         /// Documentation for `abc`.
+        ///
+        /// - Note: This is a note.
         var abc: Int
 
         func test(a: Int) {
@@ -1207,12 +1215,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 +1313,7 @@ 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 {