Skip to content

Commit f53b6e0

Browse files
d-ronnqvistanferbui
d-ronnqvist
and
anferbui
authored
Deprecate the unused AttributedCodeListing type (#956)
* Deprecate the unused CodeListing type * Correct reference to renamed initializer Co-authored-by: Andrea Fernandez Buitrago <[email protected]> * Remove deprecated case now to avoid a 2nd breaking change in the future --------- Co-authored-by: Andrea Fernandez Buitrago <[email protected]>
1 parent 9942d5c commit f53b6e0

24 files changed

+118
-127
lines changed

‎Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,8 @@ public struct DocumentationBundle {
6868
}
6969

7070
/// Code listings extracted from the documented modules' source, indexed by their identifier.
71-
public var attributedCodeListings: [String: AttributedCodeListing]
71+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
72+
public var attributedCodeListings: [String: AttributedCodeListing] = [:]
7273

7374
/// Symbol Graph JSON files for the modules documented by this bundle.
7475
public let symbolGraphURLs: [URL]
@@ -100,7 +101,6 @@ public struct DocumentationBundle {
100101
/// - Parameters:
101102
/// - info: Information about the bundle.
102103
/// - baseURL: A URL prefix to be appended to the relative presentation URL.
103-
/// - attributedCodeListings: Code listings extracted from the documented modules' source, indexed by their identifier.
104104
/// - symbolGraphURLs: Symbol Graph JSON files for the modules documented by the bundle.
105105
/// - markupURLs: DocC Markup files of the bundle.
106106
/// - miscResourceURLs: Miscellaneous resources of the bundle.
@@ -110,7 +110,6 @@ public struct DocumentationBundle {
110110
public init(
111111
info: Info,
112112
baseURL: URL = URL(string: "/")!,
113-
attributedCodeListings: [String: AttributedCodeListing] = [:],
114113
symbolGraphURLs: [URL],
115114
markupURLs: [URL],
116115
miscResourceURLs: [URL],
@@ -120,7 +119,6 @@ public struct DocumentationBundle {
120119
) {
121120
self.info = info
122121
self.baseURL = baseURL
123-
self.attributedCodeListings = attributedCodeListings
124122
self.symbolGraphURLs = symbolGraphURLs
125123
self.markupURLs = markupURLs
126124
self.miscResourceURLs = miscResourceURLs
@@ -134,6 +132,22 @@ public struct DocumentationBundle {
134132
self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName))
135133
}
136134

135+
@available(*, deprecated, renamed: "init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)", message: "Use 'init(info:baseURL:symbolGraphURLs:markupURLs:miscResourceURLs:customHeader:customFooter:themeSettings:)' instead. This deprecated API will be removed after 6.1 is released")
136+
public init(
137+
info: Info,
138+
baseURL: URL = URL(string: "/")!,
139+
attributedCodeListings: [String: AttributedCodeListing] = [:],
140+
symbolGraphURLs: [URL],
141+
markupURLs: [URL],
142+
miscResourceURLs: [URL],
143+
customHeader: URL? = nil,
144+
customFooter: URL? = nil,
145+
themeSettings: URL? = nil
146+
) {
147+
self.init(info: info, baseURL: baseURL, symbolGraphURLs: symbolGraphURLs, markupURLs: markupURLs, miscResourceURLs: miscResourceURLs, customHeader: customHeader, customFooter: customFooter, themeSettings: themeSettings)
148+
self.attributedCodeListings = attributedCodeListings
149+
}
150+
137151
public private(set) var rootReference: ResolvedTopicReference
138152

139153
/// Default path to resolve symbol links.

‎Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -413,16 +413,9 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
413413
func preResolveModuleNames() {
414414
for reference in rootModules {
415415
if let node = try? entity(with: reference) {
416-
let displayName: String
417-
switch node.name {
418-
case .conceptual(let title):
419-
displayName = title
420-
case .symbol(let declaration):
421-
displayName = declaration.tokens.map { $0.description }.joined()
422-
}
423416
// A module node should always have a symbol.
424417
// Remove the fallback value and force unwrap `node.symbol` on the main branch: https://github.com/apple/swift-docc/issues/249
425-
moduleNameCache[reference] = (displayName, node.symbol?.names.title ?? reference.lastPathComponent)
418+
moduleNameCache[reference] = (node.name.plainText, node.symbol?.names.title ?? reference.lastPathComponent)
426419
}
427420
}
428421
}
@@ -2877,6 +2870,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
28772870
/// - Parameters:
28782871
/// - unresolvedCodeListingReference: The code listing reference to resolve.
28792872
/// - parent: The topic the code listing reference appears in.
2873+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
28802874
public func resolveCodeListing(_ unresolvedCodeListingReference: UnresolvedCodeListingReference, in parent: ResolvedTopicReference) -> AttributedCodeListing? {
28812875
return dataProvider.bundles[parent.bundleIdentifier]?.attributedCodeListings[unresolvedCodeListingReference.identifier]
28822876
}

‎Sources/SwiftDocC/Infrastructure/Workspace/GeneratedDataProvider.swift

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,6 @@ public class GeneratedDataProvider: DocumentationWorkspaceDataProvider {
7676
return [
7777
DocumentationBundle(
7878
info: info,
79-
attributedCodeListings: [:],
8079
symbolGraphURLs: options.additionalSymbolGraphFiles,
8180
markupURLs: topLevelPages,
8281
miscResourceURLs: []

‎Sources/SwiftDocC/Model/Content/AttributedCodeListing.swift

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
/// A code block represented as lines of lexical tokens.
1212
///
1313
/// Use attributed code listings to represent code written in a specific programming language.
14+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
1415
public struct AttributedCodeListing: Hashable {
1516
/// The source-code language for this code listing.
1617
public let sourceLanguage: SourceLanguage?
@@ -30,6 +31,7 @@ public struct AttributedCodeListing: Hashable {
3031
}
3132
}
3233

34+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
3335
extension AttributedCodeListing {
3436
/// A single line of tokenized code in an attributed code listing.
3537
public struct Line: Hashable {
@@ -66,6 +68,7 @@ extension AttributedCodeListing {
6668
}
6769
}
6870

71+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
6972
extension AttributedCodeListing.Line {
7073
/// An element in a line of code.
7174
public enum Token: Hashable, CustomStringConvertible {

‎Sources/SwiftDocC/Model/DocumentationNode.swift

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ public struct DocumentationNode {
207207

208208
self.kind = Self.kind(for: defaultSymbol)
209209
self.sourceLanguage = reference.sourceLanguage
210-
self.name = .symbol(declaration: .init([.plain(defaultSymbol.names.title)]))
210+
self.name = .symbol(name: defaultSymbol.names.title)
211211
self.symbol = defaultSymbol
212212
self.unifiedSymbol = unifiedSymbol
213213
self.isVirtual = moduleData.isVirtual
@@ -364,7 +364,7 @@ public struct DocumentationNode {
364364
case .conceptual:
365365
self.name = .conceptual(title: displayName.name)
366366
case .symbol:
367-
self.name = .symbol(declaration: .init([.plain(displayName.name)]))
367+
self.name = .symbol(name: displayName.name)
368368
}
369369
semantic.titleVariants = semantic.titleVariants.map { _ in
370370
displayName.name
@@ -610,10 +610,10 @@ public struct DocumentationNode {
610610
case .conceptual:
611611
self.name = .conceptual(title: displayName.name)
612612
case .symbol:
613-
self.name = .symbol(declaration: .init([.plain(displayName.name)]))
613+
self.name = .symbol(name: displayName.name)
614614
}
615615
} else {
616-
self.name = .symbol(declaration: .init([.plain(symbol.names.title)]))
616+
self.name = .symbol(name: symbol.names.title)
617617
}
618618
self.symbol = symbol
619619

‎Sources/SwiftDocC/Model/Name.swift

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
This source file is part of the Swift.org open source project
33

4-
Copyright (c) 2021 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
55
Licensed under Apache License v2.0 with Runtime Library Exception
66

77
See https://swift.org/LICENSE.txt for license information
@@ -19,25 +19,36 @@ extension DocumentationNode {
1919
public enum Name: Hashable, CustomStringConvertible {
2020
/// The name of a conceptual document is its title.
2121
case conceptual(title: String)
22-
/// The name of the symbol is derived from its declaration.
23-
case symbol(declaration: AttributedCodeListing.Line)
22+
/// The name of the symbol.
23+
case symbol(name: String)
2424

2525
public func hash(into hasher: inout Hasher) {
2626
switch self {
2727
case .conceptual(let text):
2828
hasher.combine(text)
29-
case .symbol(let declaration):
30-
hasher.combine(declaration)
29+
case .symbol(let name):
30+
hasher.combine(name)
3131
}
3232
}
3333

3434
public var description: String {
3535
switch self {
3636
case .conceptual(let title):
3737
return title
38-
case .symbol(let declaration):
39-
return declaration.tokens.map { $0.description }.joined(separator: " ")
38+
case .symbol(let name):
39+
return name
4040
}
4141
}
42+
43+
var plainText: String {
44+
description
45+
}
46+
47+
@available(*, deprecated, message: "This deprecated API will be removed after 6.1 is released")
48+
static func symbol(declaration: AttributedCodeListing.Line) -> Name {
49+
// This static function exists so that `Name.symbol(declaration:)` is available while
50+
// still allowing switching over the two "symbol" name cases.
51+
Name.symbol(name: declaration.tokens.first?.description ?? "")
52+
}
4253
}
4354
}

‎Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -613,12 +613,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
613613

614614
let moduleNames = modules.compactMap { reference -> String? in
615615
guard let node = try? context.entity(with: reference) else { return nil }
616-
switch node.name {
617-
case .conceptual(let title):
618-
return title
619-
case .symbol(let declaration):
620-
return declaration.tokens.map { $0.description }.joined(separator: " ")
621-
}
616+
return node.name.plainText
622617
}
623618
if !moduleNames.isEmpty {
624619
node.metadata.modules = moduleNames.map({

‎Sources/SwiftDocC/Semantics/ReferenceResolver.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -408,8 +408,8 @@ struct ReferenceResolver: SemanticVisitor {
408408
switch node.name {
409409
case .conceptual(let documentTitle):
410410
return documentTitle
411-
case .symbol(let declaration):
412-
return node.symbol?.names.title ?? declaration.tokens.map { $0.description }.joined(separator: " ")
411+
case .symbol(let name):
412+
return node.symbol?.names.title ?? name
413413
}
414414
}
415415

‎Tests/SwiftDocCTests/Checker/Checkers/NonInclusiveLanguageCheckerTests.swift

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -178,12 +178,12 @@ func aBlackListedFunc() {
178178

179179
func testDisabledByDefault() throws {
180180
// Create a test bundle with some non-inclusive content.
181-
let (bundleURL, _, _) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], codeListings: [:], externalResolvers: [:], externalSymbolResolver: nil, configureBundle: { url in
181+
let (bundleURL, _, _) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], externalResolvers: [:], externalSymbolResolver: nil, configureBundle: { url in
182182
try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
183183
})
184184

185185
// Load the bundle
186-
let (_, _, context) = try loadBundle(from: bundleURL, codeListings: [:], externalResolvers: [:], externalSymbolResolver: nil, diagnosticFilterLevel: .error, configureContext: nil)
186+
let (_, _, context) = try loadBundle(from: bundleURL, externalResolvers: [:], externalSymbolResolver: nil, diagnosticFilterLevel: .error, configureContext: nil)
187187
XCTAssertEqual(context.problems.count, 0)
188188
}
189189

@@ -198,15 +198,15 @@ func aBlackListedFunc() {
198198
]
199199

200200
// Create a test bundle with some non-inclusive content.
201-
let (bundleURL, _, _) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], codeListings: [:], externalResolvers: [:], externalSymbolResolver: nil, configureBundle: { url in
201+
let (bundleURL, _, _) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], externalResolvers: [:], externalSymbolResolver: nil, configureBundle: { url in
202202
try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
203203
})
204204

205205
for expectation in expectations {
206206
let (severity, enabled) = expectation
207207

208208
// Load the bundle
209-
let (_, _, context) = try loadBundle(from: bundleURL, codeListings: [:], externalResolvers: [:], externalSymbolResolver: nil, diagnosticFilterLevel: severity, configureContext: nil)
209+
let (_, _, context) = try loadBundle(from: bundleURL, externalResolvers: [:], externalSymbolResolver: nil, diagnosticFilterLevel: severity, configureContext: nil)
210210
// Verify that checker diagnostics were emitted or not, depending on the diagnostic level set.
211211
XCTAssertEqual(context.problems.contains(where: { $0.diagnostic.identifier == "org.swift.docc.NonInclusiveLanguage" }), enabled)
212212
}

‎Tests/SwiftDocCTests/Infrastructure/AutomaticCurationTests.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ class AutomaticCurationTests: XCTestCase {
115115
}
116116

117117
func testAutomaticTopicsSkippingCustomCuratedSymbols() throws {
118-
let (_, bundle, context) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], codeListings: [:], configureBundle: { url in
118+
let (_, bundle, context) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], configureBundle: { url in
119119
// Curate some of `SideClass`'s children under SideKit.
120120
let sideKit = """
121121
# ``SideKit``
@@ -413,7 +413,7 @@ class AutomaticCurationTests: XCTestCase {
413413
forResource: "TopLevelCuration.symbols", withExtension: "json", subdirectory: "Test Resources")!
414414

415415
// Create a test bundle copy with the symbol graph from above
416-
let (bundleURL, bundle, context) = try testBundleAndContext(copying: "TestBundle", excludingPaths: [], codeListings: [:]) { url in
416+
let (bundleURL, bundle, context) = try testBundleAndContext(copying: "TestBundle", excludingPaths: []) { url in
417417
try? FileManager.default.copyItem(at: topLevelCurationSGFURL, to: url.appendingPathComponent("TopLevelCuration.symbols.json"))
418418
}
419419
defer {

0 commit comments

Comments
 (0)