1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2025 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
//
//===----------------------------------------------------------------------===//
#if canImport(DocCDocumentation)
import BuildSystemIntegration
import DocCDocumentation
import Foundation
@preconcurrency import IndexStoreDB
package import LanguageServerProtocol
import Markdown
import SKUtilities
import SemanticIndex
extension DocumentationLanguageService {
package func doccDocumentation(_ req: DoccDocumentationRequest) async throws -> DoccDocumentationResponse {
guard let sourceKitLSPServer else {
throw ResponseError.internalError("SourceKit-LSP is shutting down")
}
guard let workspace = await sourceKitLSPServer.workspaceForDocument(uri: req.textDocument.uri) else {
throw ResponseError.workspaceNotOpen(req.textDocument.uri)
}
let documentationManager = workspace.doccDocumentationManager
let snapshot = try documentManager.latestSnapshot(req.textDocument.uri)
var moduleName: String? = nil
var catalogURL: URL? = nil
if let target = await workspace.buildSystemManager.canonicalTarget(for: req.textDocument.uri) {
moduleName = await workspace.buildSystemManager.moduleName(for: target)
catalogURL = await workspace.buildSystemManager.doccCatalog(for: target)
}
switch snapshot.language {
case .tutorial:
return try await documentationManager.renderDocCDocumentation(
tutorialFile: snapshot.text,
moduleName: moduleName,
catalogURL: catalogURL
)
case .markdown:
guard case .symbol(let symbolName) = MarkdownTitleFinder.find(parsing: snapshot.text) else {
// This is an article that can be rendered on its own
return try await documentationManager.renderDocCDocumentation(
markupFile: snapshot.text,
moduleName: moduleName,
catalogURL: catalogURL
)
}
guard let moduleName, symbolName == moduleName else {
// This is a symbol extension page. Find the symbol so that we can include it in the request.
guard let index = workspace.index(checkedFor: .deletedFiles) else {
throw ResponseError.requestFailed(doccDocumentationError: .indexNotAvailable)
}
guard let symbolLink = DocCSymbolLink(linkString: symbolName),
let symbolOccurrence = index.primaryDefinitionOrDeclarationOccurrence(ofDocCSymbolLink: symbolLink)
else {
throw ResponseError.requestFailed(doccDocumentationError: .symbolNotFound(symbolName))
}
let symbolDocumentUri = symbolOccurrence.location.documentUri
guard
let symbolWorkspace = try await workspaceForDocument(uri: symbolDocumentUri),
let languageService = try await languageService(for: symbolDocumentUri, .swift, in: symbolWorkspace)
as? SwiftLanguageService
else {
throw ResponseError.internalError("Unable to find Swift language service for \(symbolDocumentUri)")
}
let symbolGraph = try await languageService.withSnapshotFromDiskOpenedInSourcekitd(
uri: symbolDocumentUri,
fallbackSettingsAfterTimeout: false
) { snapshot, compileCommand in
try await languageService.cursorInfo(
snapshot,
compileCommand: compileCommand,
Range(snapshot.position(of: symbolOccurrence.location)),
includeSymbolGraph: true
).symbolGraph
}
guard let symbolGraph else {
throw ResponseError.internalError("Unable to retrieve symbol graph for \(symbolOccurrence.symbol.name)")
}
return try await documentationManager.renderDocCDocumentation(
symbolUSR: symbolOccurrence.symbol.usr,
symbolGraph: symbolGraph,
markupFile: snapshot.text,
moduleName: moduleName,
catalogURL: catalogURL
)
}
// This is a page representing the module itself.
// Create a dummy symbol graph and tell SwiftDocC to convert the module name.
// The version information isn't really all that important since we're creating
// what is essentially an empty symbol graph.
return try await documentationManager.renderDocCDocumentation(
symbolUSR: moduleName,
symbolGraph: emptySymbolGraph(forModule: moduleName),
markupFile: snapshot.text,
moduleName: moduleName,
catalogURL: catalogURL
)
default:
throw ResponseError.requestFailed(doccDocumentationError: .unsupportedLanguage(snapshot.language))
}
}
}
struct MarkdownTitleFinder: MarkupVisitor {
enum Title {
case plainText(String)
case symbol(String)
}
static func find(parsing text: String) -> Title? {
let document = Markdown.Document(parsing: text, options: [.parseSymbolLinks])
var visitor = MarkdownTitleFinder()
return visitor.visit(document)
}
mutating func defaultVisit(_ markup: any Markup) -> Title? {
for child in markup.children {
if let value = visit(child) {
return value
}
}
return nil
}
mutating func visitHeading(_ heading: Heading) -> Title? {
guard heading.level == 1 else {
return nil
}
if let symbolLink = heading.child(at: 0) as? SymbolLink {
// Remove the surrounding backticks to find the symbol name
let plainText = symbolLink.plainText
var startIndex = plainText.startIndex
if plainText.hasPrefix("``") {
startIndex = plainText.index(plainText.startIndex, offsetBy: 2)
}
var endIndex = plainText.endIndex
if plainText.hasSuffix("``") {
endIndex = plainText.index(plainText.endIndex, offsetBy: -2)
}
return .symbol(String(plainText[startIndex..<endIndex]))
}
return .plainText(heading.plainText)
}
}
#endif
|
