Merge pull request swiftlang#2198 from matthewbastien/docc-swift-symbols

Always try to render some documentation for Swift files

Author: matthewbastien

Sources/DocCDocumentation/DoccDocumentationError.swift

@@ -14,14 +14,17 @@ import Foundation
 package import LanguageServerProtocol
 
 package enum DocCDocumentationError: LocalizedError {
-  case noDocumentation
+  case unsupportedLanguage(Language)
+  case noDocumentableSymbols
   case indexNotAvailable
   case symbolNotFound(String)
 
   var errorDescription: String? {
     switch self {
-    case .noDocumentation:
-      return "No documentation could be rendered for the position in this document"
+    case .unsupportedLanguage(let language):
+      return "Documentation preview is not available for \(language.description) files"
+    case .noDocumentableSymbols:
+      return "No documentable symbols were found in this Swift file"
     case .indexNotAvailable:
       return "The index is not availble to complete the request"
     case .symbolNotFound(let symbolName):

Sources/SourceKitLSP/Clang/ClangLanguageService.swift

@@ -488,7 +488,12 @@ extension ClangLanguageService {
 
   #if canImport(DocCDocumentation)
   func doccDocumentation(_ req: DoccDocumentationRequest) async throws -> DoccDocumentationResponse {
-    throw ResponseError.requestFailed(doccDocumentationError: .noDocumentation)
+    guard let sourceKitLSPServer else {
+      throw ResponseError.unknown("Connection to the editor closed")
+    }
+
+    let snapshot = try sourceKitLSPServer.documentManager.latestSnapshot(req.textDocument.uri)
+    throw ResponseError.requestFailed(doccDocumentationError: .unsupportedLanguage(snapshot.language))
   }
   #endif
 

Sources/SourceKitLSP/Documentation/DoccDocumentationHandler.swift

@@ -105,7 +105,7 @@ extension DocumentationLanguageService {
         catalogURL: catalogURL
       )
     default:
-      throw ResponseError.requestFailed(doccDocumentationError: .noDocumentation)
+      throw ResponseError.requestFailed(doccDocumentationError: .unsupportedLanguage(snapshot.language))
     }
   }
 }

Sources/SourceKitLSP/Swift/DoccDocumentation.swift

@@ -48,7 +48,7 @@ extension SwiftLanguageService {
         position: snapshot.absolutePosition(of: position)
       )
     else {
-      throw ResponseError.requestFailed(doccDocumentationError: .noDocumentation)
+      throw ResponseError.requestFailed(doccDocumentationError: .noDocumentableSymbols)
     }
     // Retrieve the symbol graph as well as information about the symbol
     let symbolPosition = await adjustPositionToStartOfIdentifier(
@@ -130,30 +130,67 @@ fileprivate struct DocumentableSymbol {
     }
   }
 
+  init?(node: any SyntaxProtocol) {
+    if let namedDecl = node.asProtocol(NamedDeclSyntax.self) {
+      self = DocumentableSymbol(node: namedDecl, position: namedDecl.name.positionAfterSkippingLeadingTrivia)
+    } else if let initDecl = node.as(InitializerDeclSyntax.self) {
+      self = DocumentableSymbol(node: initDecl, position: initDecl.initKeyword.positionAfterSkippingLeadingTrivia)
+    } else if let deinitDecl = node.as(DeinitializerDeclSyntax.self) {
+      self = DocumentableSymbol(node: deinitDecl, position: deinitDecl.deinitKeyword.positionAfterSkippingLeadingTrivia)
+    } else if let functionDecl = node.as(FunctionDeclSyntax.self) {
+      self = DocumentableSymbol(node: functionDecl, position: functionDecl.name.positionAfterSkippingLeadingTrivia)
+    } else if let subscriptDecl = node.as(SubscriptDeclSyntax.self) {
+      self = DocumentableSymbol(node: subscriptDecl, position: subscriptDecl.positionAfterSkippingLeadingTrivia)
+    } else if let variableDecl = node.as(VariableDeclSyntax.self) {
+      guard let identifier = variableDecl.bindings.only?.pattern.as(IdentifierPatternSyntax.self) else {
+        return nil
+      }
+      self = DocumentableSymbol(node: variableDecl, position: identifier.positionAfterSkippingLeadingTrivia)
+    } else if let enumCaseDecl = node.as(EnumCaseDeclSyntax.self) {
+      guard let name = enumCaseDecl.elements.only?.name else {
+        return nil
+      }
+      self = DocumentableSymbol(node: enumCaseDecl, position: name.positionAfterSkippingLeadingTrivia)
+    } else {
+      return nil
+    }
+  }
+
   static func findNearestSymbol(syntaxTree: SourceFileSyntax, position: AbsolutePosition) -> DocumentableSymbol? {
-    guard let token = syntaxTree.token(at: position) else {
+    let token: TokenSyntax
+    if let tokenAtPosition = syntaxTree.token(at: position) {
+      token = tokenAtPosition
+    } else if position >= syntaxTree.endPosition, let lastToken = syntaxTree.lastToken(viewMode: .sourceAccurate) {
+      // token(at:) returns nil if position is at the end of the document.
+      token = lastToken
+    } else if position < syntaxTree.position, let firstToken = syntaxTree.firstToken(viewMode: .sourceAccurate) {
+      // No case in practice where this happens but good to cover anyway
+      token = firstToken
+    } else {
       return nil
     }
-    return token.ancestorOrSelf { node in
-      if let namedDecl = node.asProtocol(NamedDeclSyntax.self) {
-        return DocumentableSymbol(node: namedDecl, position: namedDecl.name.positionAfterSkippingLeadingTrivia)
-      } else if let initDecl = node.as(InitializerDeclSyntax.self) {
-        return DocumentableSymbol(node: initDecl, position: initDecl.initKeyword.positionAfterSkippingLeadingTrivia)
-      } else if let functionDecl = node.as(FunctionDeclSyntax.self) {
-        return DocumentableSymbol(node: functionDecl, position: functionDecl.name.positionAfterSkippingLeadingTrivia)
-      } else if let variableDecl = node.as(VariableDeclSyntax.self) {
-        guard let identifier = variableDecl.bindings.only?.pattern.as(IdentifierPatternSyntax.self) else {
-          return nil
-        }
-        return DocumentableSymbol(node: variableDecl, position: identifier.positionAfterSkippingLeadingTrivia)
-      } else if let enumCaseDecl = node.as(EnumCaseDeclSyntax.self) {
-        guard let name = enumCaseDecl.elements.only?.name else {
-          return nil
-        }
-        return DocumentableSymbol(node: enumCaseDecl, position: name.positionAfterSkippingLeadingTrivia)
+    // Check if the current token is within a valid documentable symbol
+    if let symbol = token.ancestorOrSelf(mapping: { DocumentableSymbol(node: $0) }) {
+      return symbol
+    }
+    // Walk forward through the tokens until we find a documentable symbol
+    var previousToken: TokenSyntax? = token
+    while let nextToken = previousToken?.nextToken(viewMode: .sourceAccurate) {
+      if let symbol = nextToken.ancestorOrSelf(mapping: { DocumentableSymbol(node: $0) }) {
+        return symbol
       }
-      return nil
+      previousToken = nextToken
+    }
+    // Walk backwards through the tokens until we find a documentable symbol
+    previousToken = token
+    while let nextToken = previousToken?.previousToken(viewMode: .sourceAccurate) {
+      if let symbol = nextToken.ancestorOrSelf(mapping: { DocumentableSymbol(node: $0) }) {
+        return symbol
+      }
+      previousToken = nextToken
     }
+    // We couldn't find anything
+    return nil
   }
 }
 #endif