move SwiftDocC related functionality into its own module

Author: matthewbastien

Package.swift

@@ -214,6 +214,24 @@ var targets: [Target] = [
     swiftSettings: globalSwiftSettings
   ),
 
+  // MARK: DocCDocumentation
+
+  .target(
+    name: "DocCDocumentation",
+    dependencies: [
+      "BuildServerProtocol",
+      "BuildSystemIntegration",
+      "LanguageServerProtocol",
+      "SemanticIndex",
+      "SKLogging",
+      "SKUtilities",
+      "SwiftExtensions",
+      .product(name: "SwiftDocC", package: "swift-docc"),
+    ],
+    exclude: ["CMakeLists.txt"],
+    swiftSettings: globalSwiftSettings
+  ),
+
   // MARK: InProcessClient
 
   .target(
@@ -474,6 +492,7 @@ var targets: [Target] = [
     dependencies: [
       "BuildServerProtocol",
       "BuildSystemIntegration",
+      "DocCDocumentation",
       "LanguageServerProtocol",
       "LanguageServerProtocolExtensions",
       "LanguageServerProtocolJSONRPC",
@@ -485,12 +504,11 @@ var targets: [Target] = [
       "SwiftExtensions",
       "ToolchainRegistry",
       "TSCExtensions",
-      .product(name: "SwiftDocC", package: "swift-docc"),
-      .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
-      .product(name: "Markdown", package: "swift-markdown"),
       .product(name: "IndexStoreDB", package: "indexstore-db"),
       .product(name: "Crypto", package: "swift-crypto"),
+      .product(name: "Markdown", package: "swift-markdown"),
       .product(name: "SwiftToolsSupport-auto", package: "swift-tools-support-core"),
+      .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
     ]
       + swiftPMDependency([
         .product(name: "SwiftPM-auto", package: "swift-package-manager")

Sources/SourceKitLSP/Documentation/DocCWorkspaceExtensions.swift renamed to Sources/DocCDocumentation/BuildSystemIntegrationExtensions.swift

@@ -10,49 +10,39 @@
 //
 //===----------------------------------------------------------------------===//
 
-#if canImport(SwiftDocC)
 import BuildServerProtocol
-import BuildSystemIntegration
-import Foundation
-import LanguageServerProtocol
+package import BuildSystemIntegration
+package import Foundation
+package import LanguageServerProtocol
 
-extension Workspace {
-  private var documentationManager: DocumentationManager {
-    get throws {
-      guard let sourceKitLSPServer else {
-        throw ResponseError.unknown("Connection to the editor closed")
-      }
-      return sourceKitLSPServer.documentationManager
-    }
-  }
-
-  func findModuleName(for document: DocumentURI) async -> String? {
-    guard let target = await buildSystemManager.canonicalTarget(for: document) else {
+package extension BuildSystemManager {
+  func moduleName(for document: DocumentURI) async -> String? {
+    guard let target = await canonicalTarget(for: document) else {
       return nil
     }
-    let sourceFiles = (try? await buildSystemManager.sourceFiles(in: [target]).flatMap(\.sources)) ?? []
+    let sourceFiles = (try? await sourceFiles(in: [target]).flatMap(\.sources)) ?? []
     for sourceFile in sourceFiles {
-      let language = await buildSystemManager.defaultLanguage(for: sourceFile.uri, in: target)
+      let language = await defaultLanguage(for: sourceFile.uri, in: target)
       guard language == .swift else {
         continue
       }
-      if let moduleName = await buildSystemManager.moduleName(for: sourceFile.uri, in: target) {
+      if let moduleName = await moduleName(for: sourceFile.uri, in: target) {
         return moduleName
       }
     }
     return nil
   }
 
-  func findDocCCatalog(for document: DocumentURI) async -> URL? {
-    guard let target = await buildSystemManager.canonicalTarget(for: document) else {
+  func doccCatalog(for document: DocumentURI) async -> URL? {
+    guard let target = await canonicalTarget(for: document) else {
       return nil
     }
-    let sourceFiles = (try? await buildSystemManager.sourceFiles(in: [target]).flatMap(\.sources)) ?? []
+    let sourceFiles = (try? await sourceFiles(in: [target]).flatMap(\.sources)) ?? []
     return sourceFiles.compactMap(\.uri.fileURL?.doccCatalogURL).first
   }
 }
 
-extension URL {
+package extension URL {
   var doccCatalogURL: URL? {
     var pathComponents = self.pathComponents
     var result = self
@@ -66,4 +56,3 @@ extension URL {
     return nil
   }
 }
-#endif

Sources/SourceKitLSP/Documentation/DocCCatalogIndexManager.swift renamed to Sources/DocCDocumentation/DocCCatalogIndexManager.swift

@@ -10,14 +10,19 @@
 //
 //===----------------------------------------------------------------------===//
 
+package import Foundation
+
+package protocol DocCCatalogIndex: Sendable {
+  func documentationExtension(for symbolLink: any DocCSymbolLink) -> URL?
+}
+
 #if canImport(SwiftDocC)
-import Foundation
 @preconcurrency import SwiftDocC
 import SwiftExtensions
 
 final actor DocCCatalogIndexManager {
   private let server: DocCServer
-  private var catalogToIndexMap = [URL: Result<DocCCatalogIndex, DocCIndexError>]()
+  private var catalogToIndexMap = [URL: Result<DocCCatalogIndexImpl, DocCIndexError>]()
 
   init(server: DocCServer) {
     self.server = server
@@ -32,11 +37,11 @@ final actor DocCCatalogIndexManager {
     }
   }
 
-  func index(for catalogURL: URL) async throws(DocCIndexError) -> DocCCatalogIndex {
+  func index(for catalogURL: URL) async throws(DocCIndexError) -> DocCCatalogIndexImpl {
     if let existingCatalog = catalogToIndexMap[catalogURL] {
       return try existingCatalog.get()
     }
-    let catalogIndexResult: Result<DocCCatalogIndex, DocCIndexError>
+    let catalogIndexResult: Result<DocCCatalogIndexImpl, DocCIndexError>
     do {
       let convertResponse = try await server.convert(
         externalIDsToConvert: [],
@@ -62,37 +67,37 @@ final actor DocCCatalogIndexManager {
           Result { try JSONDecoder().decode(RenderReferenceStore.self, from: renderReferenceStoreData) }
             .flatMapError { .failure(.decodingFailure($0)) }
         }
-        .map { DocCCatalogIndex(from: $0) }
+        .map { DocCCatalogIndexImpl(from: $0) }
     } catch {
-      catalogIndexResult = .failure(.serverError(error))
+      catalogIndexResult = .failure(.internalError(error))
     }
     catalogToIndexMap[catalogURL] = catalogIndexResult
     return try catalogIndexResult.get()
   }
 }
 
 /// Represents a potential error that the ``DocCCatalogIndexManager`` could encounter while indexing
-enum DocCIndexError: LocalizedError {
+package enum DocCIndexError: LocalizedError {
   case decodingFailure(Error)
-  case serverError(DocCServerError)
+  case internalError(LocalizedError)
   case unexpectedlyNilRenderReferenceStore
 
-  var errorDescription: String? {
+  package var errorDescription: String? {
     switch self {
     case .decodingFailure(let decodingError):
       return "Failed to decode a received message: \(decodingError.localizedDescription)"
-    case .serverError(let serverError):
-      return "DocC server failed to convert the catalog: \(serverError.localizedDescription)"
+    case .internalError(let internalError):
+      return "An internal error occurred: \(internalError.localizedDescription)"
     case .unexpectedlyNilRenderReferenceStore:
       return "Did not receive a RenderReferenceStore from the DocC server"
     }
   }
 }
 
-struct DocCCatalogIndex: Sendable {
+package struct DocCCatalogIndexImpl: DocCCatalogIndex {
   private let assetReferenceToDataAsset: [String: DataAsset]
   private let fuzzyAssetReferenceToDataAsset: [String: DataAsset]
-  private let documentationExtensionToSourceURL: [DocCSymbolLink: URL]
+  private let documentationExtensionToSourceURL: [DocCSymbolLinkImpl: URL]
   let articlePathToSourceURLAndReference: [String: (URL, TopicRenderReference)]
   let tutorialPathToSourceURLAndReference: [String: (URL, TopicRenderReference)]
   let tutorialOverviewPathToSourceURLAndReference: [String: (URL, TopicRenderReference)]
@@ -101,8 +106,11 @@ struct DocCCatalogIndex: Sendable {
     assetReferenceToDataAsset[assetReference.assetName] ?? fuzzyAssetReferenceToDataAsset[assetReference.assetName]
   }
 
-  func documentationExtension(for symbolLink: DocCSymbolLink) -> URL? {
-    documentationExtensionToSourceURL[symbolLink]
+  package func documentationExtension(for symbolLink: any DocCSymbolLink) -> URL? {
+    guard let symbolLink = symbolLink as? DocCSymbolLinkImpl else {
+      return nil
+    }
+    return documentationExtensionToSourceURL[symbolLink]
   }
 
   init(from renderReferenceStore: RenderReferenceStore) {
@@ -121,7 +129,7 @@ struct DocCCatalogIndex: Sendable {
     self.assetReferenceToDataAsset = assetReferenceToDataAsset
     self.fuzzyAssetReferenceToDataAsset = fuzzyAssetReferenceToDataAsset
     // Markdown and Tutorial content
-    var documentationExtensionToSourceURL = [DocCSymbolLink: URL]()
+    var documentationExtensionToSourceURL = [DocCSymbolLinkImpl: URL]()
     var articlePathToSourceURLAndReference = [String: (URL, TopicRenderReference)]()
     var tutorialPathToSourceURLAndReference = [String: (URL, TopicRenderReference)]()
     var tutorialOverviewPathToSourceURLAndReference = [String: (URL, TopicRenderReference)]()
@@ -138,7 +146,7 @@ struct DocCCatalogIndex: Sendable {
         else {
           continue
         }
-        let doccSymbolLink = DocCSymbolLink(absoluteSymbolLink: absoluteSymbolLink)
+        let doccSymbolLink = DocCSymbolLinkImpl(absoluteSymbolLink: absoluteSymbolLink)
         documentationExtensionToSourceURL[doccSymbolLink] = topicContentValue.source
       } else if topicRenderReference.kind == .article {
         articlePathToSourceURLAndReference[renderReferenceKey.url.lastPathComponent] = (

Sources/DocCDocumentation/DocCDocumentationManager.swift

@@ -0,0 +1,76 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+package import Foundation
+@preconcurrency package import IndexStoreDB
+package import LanguageServerProtocol
+package import SemanticIndex
+
+/// An actor that can be used to interface with SwiftDocC
+package protocol DocCDocumentationManager: Actor {
+  func getRenderingSupport() -> DocCDocumentationManagerWithRendering?
+}
+
+/// An actor that can be used to render SwiftDocC documentation
+package protocol DocCDocumentationManagerWithRendering: DocCDocumentationManager {
+  func filesDidChange(_: [FileEvent]) async
+
+  func catalogIndex(for: URL) async throws -> DocCCatalogIndex
+
+  func symbolLink(string: String) -> DocCSymbolLink?
+
+  func symbolLink(forUSR: String, in: CheckedIndex) -> DocCSymbolLink?
+
+  func primaryDefinitionOrDeclarationOccurrence(
+    ofDocCSymbolLink: DocCSymbolLink,
+    in: CheckedIndex
+  ) -> SymbolOccurrence?
+
+  func renderDocCDocumentation(
+    symbolUSR: String?,
+    symbolGraph: String?,
+    overrideDocComments: [String]?,
+    markupFile: String?,
+    tutorialFile: String?,
+    moduleName: String?,
+    catalogURL: URL?
+  ) async throws -> DoccDocumentationResponse
+}
+
+extension DocCDocumentationManagerWithRendering {
+  package func renderDocCDocumentation(
+    symbolUSR: String? = nil,
+    symbolGraph: String? = nil,
+    overrideDocComments: [String]? = nil,
+    markupFile: String? = nil,
+    tutorialFile: String? = nil,
+    moduleName: String?,
+    catalogURL: URL?
+  ) async throws -> DoccDocumentationResponse {
+    try await renderDocCDocumentation(
+      symbolUSR: symbolUSR,
+      symbolGraph: symbolGraph,
+      overrideDocComments: overrideDocComments,
+      markupFile: markupFile,
+      tutorialFile: tutorialFile,
+      moduleName: moduleName,
+      catalogURL: catalogURL
+    )
+  }
+}
+
+/// Creates a new ``DocCDocumentationManager`` that can be used to interface with SwiftDocC.
+///
+/// - Returns: An instance of ``DocCDocumentationManager``
+package func createDocCDocumentationManager() -> any DocCDocumentationManager {
+  DocCDocumentationManagerImpl()
+}