Skip to content

Commit 18c027e

Browse files
d-ronnqvistd-ronnqvist
authored
Deprecate the context parameter for MarkupConvertible and DirectiveConvertible (#1175)
Also, remove or deprecate `context` parameters that were only passed for directives or markup initialization. rdar://147478428
1 parent 75fa7d6 commit 18c027e

File tree

77 files changed

+604
-595
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+604
-595
lines changed

‎Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

Lines changed: 5 additions & 6 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-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2025 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
@@ -407,7 +407,7 @@ public class DocumentationContext {
407407
/// - problems: A mutable collection of problems to update with any problem encountered during the semantic analysis.
408408
/// - Returns: The result of the semantic analysis.
409409
private func analyze(_ document: Document, at source: URL, in bundle: DocumentationBundle, engine: DiagnosticEngine) -> Semantic? {
410-
var analyzer = SemanticAnalyzer(source: source, context: self, bundle: bundle)
410+
var analyzer = SemanticAnalyzer(source: source, bundle: bundle)
411411
let result = analyzer.visit(document)
412412
engine.emit(analyzer.problems)
413413
return result
@@ -1074,8 +1074,7 @@ public class DocumentationContext {
10741074
updatedNode.initializeSymbolContent(
10751075
documentationExtension: foundDocumentationExtension?.value,
10761076
engine: diagnosticEngine,
1077-
bundle: bundle,
1078-
context: self
1077+
bundle: bundle
10791078
)
10801079

10811080
// After merging the documentation extension into the symbol, warn about deprecation summary for non-deprecated symbols.
@@ -2010,7 +2009,7 @@ public class DocumentationContext {
20102009
}
20112010
let article = Article(
20122011
markup: articleResult.value.markup,
2013-
metadata: Metadata(from: metadataMarkup, for: bundle, in: self),
2012+
metadata: Metadata(from: metadataMarkup, for: bundle),
20142013
redirects: articleResult.value.redirects,
20152014
options: articleResult.value.options
20162015
)
@@ -2043,7 +2042,7 @@ public class DocumentationContext {
20432042
Heading(level: 1, Text(title)),
20442043
metadataDirectiveMarkup
20452044
)
2046-
let metadata = Metadata(from: metadataDirectiveMarkup, for: bundle, in: self)
2045+
let metadata = Metadata(from: metadataDirectiveMarkup, for: bundle)
20472046
let article = Article(markup: markup, metadata: metadata, redirects: nil, options: [:])
20482047
let documentationNode = DocumentationNode(
20492048
reference: reference,

‎Sources/SwiftDocC/Model/DocumentationNode.swift

Lines changed: 3 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-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2025 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
@@ -332,16 +332,14 @@ public struct DocumentationNode {
332332
mutating func initializeSymbolContent(
333333
documentationExtension: Article?,
334334
engine: DiagnosticEngine,
335-
bundle: DocumentationBundle,
336-
context: DocumentationContext
335+
bundle: DocumentationBundle
337336
) {
338337
precondition(unifiedSymbol != nil && symbol != nil, "You can only call initializeSymbolContent() on a symbol node.")
339338

340339
let (markup, docChunks, metadataFromDocumentationComment) = Self.contentFrom(
341340
documentedSymbol: unifiedSymbol?.documentedSymbol,
342341
documentationExtension: documentationExtension,
343342
bundle: bundle,
344-
context: context,
345343
engine: engine
346344
)
347345

@@ -503,7 +501,6 @@ public struct DocumentationNode {
503501
documentedSymbol: SymbolGraph.Symbol?,
504502
documentationExtension: Article?,
505503
bundle: DocumentationBundle? = nil,
506-
context: DocumentationContext? = nil,
507504
engine: DiagnosticEngine
508505
) -> (
509506
markup: any Markup,
@@ -543,15 +540,14 @@ public struct DocumentationNode {
543540

544541
var problems = [Problem]()
545542

546-
if let bundle, let context {
543+
if let bundle {
547544
metadata = DirectiveParser()
548545
.parseSingleDirective(
549546
Metadata.self,
550547
from: &docCommentMarkupElements,
551548
parentType: Symbol.self,
552549
source: docCommentLocation?.url,
553550
bundle: bundle,
554-
context: context,
555551
problems: &problems
556552
)
557553

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

Lines changed: 2 additions & 2 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-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2025 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
@@ -517,7 +517,7 @@ public class DocumentationContentRenderer {
517517
}
518518

519519
let supportedLanguages = group.directives[SupportedLanguage.directiveName]?.compactMap {
520-
SupportedLanguage(from: $0, source: nil, for: bundle, in: documentationContext)?.language
520+
SupportedLanguage(from: $0, source: nil, for: bundle)?.language
521521
}
522522

523523
return ReferenceGroup(

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

Lines changed: 3 additions & 3 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-2025 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
@@ -33,11 +33,11 @@ struct LinkTitleResolver {
3333
var problems = [Problem]()
3434
switch directive.name {
3535
case Tutorial.directiveName:
36-
if let tutorial = Tutorial(from: directive, source: source, for: bundle, in: context, problems: &problems) {
36+
if let tutorial = Tutorial(from: directive, source: source, for: bundle, problems: &problems) {
3737
return .init(defaultVariantValue: tutorial.intro.title)
3838
}
3939
case TutorialTableOfContents.directiveName:
40-
if let overview = TutorialTableOfContents(from: directive, source: source, for: bundle, in: context, problems: &problems) {
40+
if let overview = TutorialTableOfContents(from: directive, source: source, for: bundle, problems: &problems) {
4141
return .init(defaultVariantValue: overview.name)
4242
}
4343
default: break

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

Lines changed: 2 additions & 6 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) 2022 Apple Inc. and the Swift project authors
4+
Copyright (c) 2022-2025 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
@@ -24,11 +24,7 @@ extension RenderableDirectiveConvertible {
2424
_ blockDirective: BlockDirective,
2525
with contentCompiler: inout RenderContentCompiler
2626
) -> [any RenderContent] {
27-
guard let directive = Self.init(
28-
from: blockDirective,
29-
for: contentCompiler.bundle,
30-
in: contentCompiler.context
31-
) else {
27+
guard let directive = Self.init(from: blockDirective, for: contentCompiler.bundle) else {
3228
return []
3329
}
3430

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

Lines changed: 2 additions & 2 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-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2025 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
@@ -1029,7 +1029,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
10291029
) -> [TaskGroupRenderSection] {
10301030
return topics.taskGroups.compactMap { group in
10311031
let supportedLanguages = group.directives[SupportedLanguage.directiveName]?.compactMap {
1032-
SupportedLanguage(from: $0, source: nil, for: bundle, in: context)?.language
1032+
SupportedLanguage(from: $0, source: nil, for: bundle)?.language
10331033
}
10341034

10351035
// If the task group has a set of supported languages, see if it should render for the allowed traits.

‎Sources/SwiftDocC/Semantics/Article/Article.swift

Lines changed: 4 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-2024 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2025 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
@@ -94,10 +94,9 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
9494
/// - Parameters:
9595
/// - markup: The markup that makes up this article's content.
9696
/// - source: The location of the file that this article's content comes from.
97-
/// - bundle: The documentation bundle that the article belongs to.
98-
/// - context: The documentation context that the article belongs to.
97+
/// - bundle: The documentation bundle that the source file belongs to.
9998
/// - problems: A mutable collection of problems to update with any problem encountered while initializing the article.
100-
public convenience init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) {
99+
public convenience init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, problems: inout [Problem]) {
101100
guard let title = markup.child(at: 0) as? Heading, title.level == 1 else {
102101
let range = markup.child(at: 0)?.range ?? SourceLocation(line: 1, column: 1, source: nil)..<SourceLocation(line: 1, column: 1, source: nil)
103102
let diagnostic = Diagnostic(source: source, severity: .warning, range: range, identifier: "org.swift.docc.Article.Title.NotFound", summary: "An article is expected to start with a top-level heading title")
@@ -126,7 +125,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
126125
guard let childDirective = child as? BlockDirective, childDirective.name == Redirect.directiveName else {
127126
return nil
128127
}
129-
return Redirect(from: childDirective, source: source, for: bundle, in: context, problems: &problems)
128+
return Redirect(from: childDirective, source: source, for: bundle, problems: &problems)
130129
}
131130

132131
var optionalMetadata = DirectiveParser()
@@ -136,7 +135,6 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
136135
parentType: Article.self,
137136
source: source,
138137
bundle: bundle,
139-
context: context,
140138
problems: &problems
141139
)
142140

@@ -155,7 +153,6 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
155153
from: childDirective,
156154
source: source,
157155
for: bundle,
158-
in: context,
159156
problems: &problems
160157
)
161158
}

‎Sources/SwiftDocC/Semantics/Article/MarkupConvertible.swift

Lines changed: 18 additions & 4 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-2025 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
@@ -13,13 +13,27 @@ public import Markdown
1313

1414
/// A type that can be initialized from markup.
1515
public protocol MarkupConvertible {
16-
/// Initializes a new element with a given markup and source for a given documentation bundle and documentation context.
16+
/// Initializes a new element with a given markup and source that's part of a given documentation bundle.
1717
///
1818
/// - Parameters:
1919
/// - markup: The markup that makes up this element's content.
2020
/// - source: The location of the file that this element's content comes from.
21-
/// - bundle: The documentation bundle that the element belongs to.
22-
/// - context: The documentation context that the element belongs to.
21+
/// - bundle: The documentation bundle that the source file belongs to.
2322
/// - problems: A mutable collection of problems to update with any problem encountered while initializing the element.
23+
init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, problems: inout [Problem])
24+
25+
@available(*, deprecated, renamed: "init(from:source:for:problems:)", message: "Use 'init(from:source:for:problems:)' instead. This deprecated API will be removed after 6.2 is released")
2426
init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem])
2527
}
28+
29+
public extension MarkupConvertible {
30+
// Default implementation to avoid source breaking changes. Remove this after 6.2 is released.
31+
init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, problems: inout [Problem]) {
32+
fatalError("Markup convertible type doesn't implement either 'init(from:source:for:problems:)' or 'init(from:source:for:in:problems:)'")
33+
}
34+
35+
// Default implementation to new types don't need to implement a deprecated initializer. Remove this after 6.2 is released.
36+
init?(from markup: any Markup, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) {
37+
self.init(from: markup, source: source, for: bundle, problems: &problems)
38+
}
39+
}

‎Sources/SwiftDocC/Semantics/Comment.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ public final class Comment: Semantic, DirectiveConvertible {
3333
self.content = content
3434
}
3535

36-
public convenience init?(from directive: BlockDirective, source: URL?, for _: DocumentationBundle, in _: DocumentationContext, problems: inout [Problem]) {
36+
public convenience init?(from directive: BlockDirective, source: URL?, for _: DocumentationBundle, problems: inout [Problem]) {
3737
precondition(directive.name == Comment.directiveName)
3838
self.init(originalMarkup: directive, content: MarkupContainer(directive.children))
3939
}

‎Sources/SwiftDocC/Semantics/ContentAndMedia.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ public final class ContentAndMedia: Semantic, DirectiveConvertible {
7575
self.mediaPosition = mediaPosition
7676
}
7777

78-
public convenience init?(from directive: BlockDirective, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) {
78+
public convenience init?(from directive: BlockDirective, source: URL?, for bundle: DocumentationBundle, problems: inout [Problem]) {
7979
let arguments = Semantic.Analyses.HasOnlyKnownArguments<ContentAndMedia>(severityIfFound: .warning, allowedArguments: [Semantics.Title.argumentName, Semantics.Layout.argumentName, Semantics.Eyebrow.argumentName]).analyze(directive, children: directive.children, source: source, problems: &problems)
8080

8181
Semantic.Analyses.HasOnlyKnownDirectives<ContentAndMedia>(severityIfFound: .warning, allowedDirectives: [ImageMedia.directiveName, VideoMedia.directiveName]).analyze(directive, children: directive.children, source: source, problems: &problems)
@@ -85,7 +85,7 @@ public final class ContentAndMedia: Semantic, DirectiveConvertible {
8585

8686
let layout = Semantic.Analyses.DeprecatedArgument<ContentAndMedia, Semantics.Layout>.unused(severityIfFound: .warning).analyze(directive, arguments: arguments, problems: &problems)
8787

88-
let (media, remainder) = Semantic.Analyses.HasExactlyOneMedia<ContentAndMedia>(severityIfNotFound: nil).analyze(directive, children: directive.children, source: source, for: bundle, in: context, problems: &problems)
88+
let (media, remainder) = Semantic.Analyses.HasExactlyOneMedia<ContentAndMedia>(severityIfNotFound: nil).analyze(directive, children: directive.children, source: source, for: bundle, problems: &problems)
8989

9090
let mediaPosition: MediaPosition
9191
if let firstChildDirective = directive.child(at: 0) as? BlockDirective,

0 commit comments

Comments
 (0)