Skip to content

Commit 926d85b

Browse files
d-ronnqvistd-ronnqvist
authored
Avoid passing context and bundle parameters to directives that don't use them. (#1168)
* Avoid passing the context and bundle to directive methods that don't use it rdar://147405751 * Remove unused context and bundle parameters from internal protocol * Deprecate protocol that is never used as an existential
1 parent da20498 commit 926d85b

31 files changed

+141
-131
lines changed

‎Sources/SwiftDocC/Semantics/Comment.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-2023 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,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 bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) {
36+
public convenience init?(from directive: BlockDirective, source: URL?, for _: DocumentationBundle, in _: DocumentationContext, 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: 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-2023 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
@@ -76,9 +76,9 @@ public final class ContentAndMedia: Semantic, DirectiveConvertible {
7676
}
7777

7878
public convenience init?(from directive: BlockDirective, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) {
79-
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, for: bundle, in: context, problems: &problems)
79+
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

81-
Semantic.Analyses.HasOnlyKnownDirectives<ContentAndMedia>(severityIfFound: .warning, allowedDirectives: [ImageMedia.directiveName, VideoMedia.directiveName]).analyze(directive, children: directive.children, source: source, for: bundle, in: context, problems: &problems)
81+
Semantic.Analyses.HasOnlyKnownDirectives<ContentAndMedia>(severityIfFound: .warning, allowedDirectives: [ImageMedia.directiveName, VideoMedia.directiveName]).analyze(directive, children: directive.children, source: source, problems: &problems)
8282

8383
let optionalEyebrow = Semantic.Analyses.DeprecatedArgument<ContentAndMedia, Semantics.Eyebrow>.unused(severityIfFound: .warning).analyze(directive, arguments: arguments, problems: &problems)
8484
let optionalTitle = Semantic.Analyses.DeprecatedArgument<ContentAndMedia, Semantics.Title>.unused(severityIfFound: .warning).analyze(directive, arguments: arguments, problems: &problems)

‎Sources/SwiftDocC/Semantics/DirectiveInfrastructure/AutomaticDirectiveConvertible.swift‎

Lines changed: 4 additions & 20 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-2023 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
@@ -26,12 +26,7 @@ protocol AutomaticDirectiveConvertible: DirectiveConvertible, Semantic {
2626
///
2727
/// Return false if a serious enough error is encountered such that the directive
2828
/// should not be initialized.
29-
func validate(
30-
source: URL?,
31-
for bundle: DocumentationBundle,
32-
in context: DocumentationContext,
33-
problems: inout [Problem]
34-
) -> Bool
29+
func validate(source: URL?, problems: inout [Problem]) -> Bool
3530

3631
/// The key paths to any property wrapped directive arguments, child directives,
3732
/// or child markup properties.
@@ -80,12 +75,7 @@ extension AutomaticDirectiveConvertible {
8075
String(describing: self)
8176
}
8277

83-
func validate(
84-
source: URL?,
85-
for bundle: DocumentationBundle,
86-
in context: DocumentationContext,
87-
problems: inout [Problem]
88-
) -> Bool {
78+
func validate(source: URL?, problems: inout [Problem]) -> Bool {
8979
return true
9080
}
9181

@@ -143,8 +133,6 @@ extension AutomaticDirectiveConvertible {
143133
directive,
144134
children: directive.children,
145135
source: source,
146-
for: bundle,
147-
in: context,
148136
problems: &problems
149137
)
150138

@@ -181,8 +169,6 @@ extension AutomaticDirectiveConvertible {
181169
directive,
182170
children: directive.children,
183171
source: source,
184-
for: bundle,
185-
in: context,
186172
problems: &problems
187173
)
188174

@@ -301,8 +287,6 @@ extension AutomaticDirectiveConvertible {
301287
directive,
302288
children: remainder,
303289
source: source,
304-
for: bundle,
305-
in: context,
306290
problems: &problems
307291
)
308292
} else if !remainder.isEmpty {
@@ -367,7 +351,7 @@ extension AutomaticDirectiveConvertible {
367351
return nil
368352
}
369353

370-
guard validate(source: source, for: bundle, in: context, problems: &problems) else {
354+
guard validate(source: source, problems: &problems) else {
371355
return nil
372356
}
373357
}

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/Extract.swift‎

Lines changed: 9 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
@@ -15,7 +15,7 @@ extension Semantic.Analyses {
1515
/**
1616
Separates `children` into directives whose names match `Child.directiveName` and those remaining, attempting to convert extracted children to the semantic `Child` type.
1717
*/
18-
public struct ExtractAll<Child: Semantic & DirectiveConvertible>: SemanticAnalysis {
18+
public struct ExtractAll<Child: Semantic & DirectiveConvertible> {
1919
public init() {}
2020

2121
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> ([Child], remainder: MarkupContainer) {
@@ -54,15 +54,20 @@ extension Semantic.Analyses {
5454
/**
5555
Separates `children` into markup elements that are of a specific type without performing any further analysis.
5656
*/
57-
public struct ExtractAllMarkup<Child: Markup>: SemanticAnalysis {
57+
public struct ExtractAllMarkup<Child: Markup> {
5858
public init() {}
5959

60-
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> ([Child], remainder: MarkupContainer) {
60+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, problems: inout [Problem]) -> ([Child], remainder: MarkupContainer) {
6161
let (matches, remainder) = children.categorize {
6262
$0 as? Child
6363
}
6464
return (matches, remainder: MarkupContainer(remainder))
6565
}
66+
67+
@available(*, deprecated, renamed: "analyze(_:children:source:problems:)", message: "Use 'analyze(_:children:source:problems:)' instead. This deprecated API will be removed after 6.2 is released")
68+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for _: DocumentationBundle, in _: DocumentationContext, problems: inout [Problem]) -> ([Child], remainder: MarkupContainer) {
69+
analyze(directive, children: children, source: source, problems: &problems)
70+
}
6671
}
6772
}
6873

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/HasAtLeastOne.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 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
@@ -15,7 +15,7 @@ extension Semantic.Analyses {
1515
/**
1616
Checks to see if a parent directive has at least one child directive of a specified type. If so, return those that match and those that don't.
1717
*/
18-
public struct HasAtLeastOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible>: SemanticAnalysis {
18+
public struct HasAtLeastOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible> {
1919
let severityIfNotFound: DiagnosticSeverity?
2020
public init(severityIfNotFound: DiagnosticSeverity?) {
2121
self.severityIfNotFound = severityIfNotFound

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/HasAtMostOne.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 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
@@ -15,7 +15,7 @@ extension Semantic.Analyses {
1515
/**
1616
Checks to see if a parent directive has at most one child directive of a specified type. If so, return that child and the remainder.
1717
*/
18-
public struct HasAtMostOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible>: SemanticAnalysis {
18+
public struct HasAtMostOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible> {
1919

2020
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> (Child?, remainder: MarkupContainer) {
2121
return Semantic.Analyses.extractAtMostOne(

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/HasContent.swift‎

Lines changed: 8 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
@@ -15,7 +15,7 @@ extension Semantic.Analyses {
1515
/**
1616
Checks to see if a directive has child markup content.
1717
*/
18-
public struct HasContent<Parent: Semantic & DirectiveConvertible>: SemanticAnalysis {
18+
public struct HasContent<Parent: Semantic & DirectiveConvertible> {
1919
let additionalContext: String
2020
public init(additionalContext: String? = nil) {
2121
if let additionalContext,
@@ -26,7 +26,7 @@ extension Semantic.Analyses {
2626
}
2727
}
2828

29-
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> MarkupContainer {
29+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, problems: inout [Problem]) -> MarkupContainer {
3030
let children = Array(children)
3131
guard children.isEmpty else {
3232
return MarkupContainer(children)
@@ -36,5 +36,10 @@ extension Semantic.Analyses {
3636
problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
3737
return MarkupContainer()
3838
}
39+
40+
@available(*, deprecated, renamed: "analyze(_:children:source:problems:)", message: "Use 'analyze(_:children:source:problems:)' instead. This deprecated API will be removed after 6.2 is released")
41+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> MarkupContainer {
42+
analyze(directive, children: children, source: source, problems: &problems)
43+
}
3944
}
4045
}

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/HasExactlyOne.swift‎

Lines changed: 12 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-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
@@ -15,7 +15,7 @@ extension Semantic.Analyses {
1515
/**
1616
Checks a parent directive for the presence of exactly one child directive to be converted to a type ``SemanticAnalysis/Result``. If so, return that child and the remainder.
1717
*/
18-
public struct HasExactlyOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible>: SemanticAnalysis {
18+
public struct HasExactlyOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible> {
1919
let severityIfNotFound: DiagnosticSeverity?
2020
public init(severityIfNotFound: DiagnosticSeverity?) {
2121
self.severityIfNotFound = severityIfNotFound
@@ -95,7 +95,7 @@ extension Semantic.Analyses {
9595
}
9696

9797
/// Checks a parent directive for the presence of exactly one of two child directives---but not both---to be converted to a type ``SemanticAnalysis/Result``. If so, return that child and the remainder.
98-
public struct HasExactlyOneOf<Parent: Semantic & DirectiveConvertible, Child1: Semantic & DirectiveConvertible, Child2: Semantic & DirectiveConvertible>: SemanticAnalysis {
98+
public struct HasExactlyOneOf<Parent: Semantic & DirectiveConvertible, Child1: Semantic & DirectiveConvertible, Child2: Semantic & DirectiveConvertible> {
9999
let severityIfNotFound: DiagnosticSeverity?
100100
public init(severityIfNotFound: DiagnosticSeverity?) {
101101
self.severityIfNotFound = severityIfNotFound
@@ -145,7 +145,7 @@ extension Semantic.Analyses {
145145
}
146146
}
147147

148-
public struct HasExactlyOneImageOrVideoMedia<Parent: Semantic & DirectiveConvertible>: SemanticAnalysis {
148+
public struct HasExactlyOneImageOrVideoMedia<Parent: Semantic & DirectiveConvertible> {
149149
let severityIfNotFound: DiagnosticSeverity?
150150
public init(severityIfNotFound: DiagnosticSeverity?) {
151151
self.severityIfNotFound = severityIfNotFound
@@ -157,7 +157,7 @@ extension Semantic.Analyses {
157157
}
158158
}
159159

160-
public struct HasExactlyOneMedia<Parent: Semantic & DirectiveConvertible>: SemanticAnalysis {
160+
public struct HasExactlyOneMedia<Parent: Semantic & DirectiveConvertible> {
161161
let severityIfNotFound: DiagnosticSeverity?
162162

163163
init(severityIfNotFound: DiagnosticSeverity?) {
@@ -217,14 +217,14 @@ extension Semantic.Analyses {
217217
}
218218
}
219219

220-
public struct HasExactlyOneUnorderedList<Parent: Semantic & DirectiveConvertible, ListElement>: SemanticAnalysis {
220+
public struct HasExactlyOneUnorderedList<Parent: Semantic & DirectiveConvertible, ListElement> {
221221
let severityIfNotFound: DiagnosticSeverity?
222222

223223
init(severityIfNotFound: DiagnosticSeverity?) {
224224
self.severityIfNotFound = severityIfNotFound
225225
}
226226

227-
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> [ListElement]? {
227+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, problems: inout [Problem]) -> [ListElement]? {
228228
var validElements: [ListElement] = []
229229

230230
var (lists, notLists) = directive.children.categorize { $0 as? UnorderedList }
@@ -260,6 +260,11 @@ extension Semantic.Analyses {
260260

261261
return validElements
262262
}
263+
264+
@available(*, deprecated, renamed: "analyze(_:children:source:problems:)", message: "Use 'analyze(_:children:source:problems:)' instead. This deprecated API will be removed after 6.2 is released")
265+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for _: DocumentationBundle, in _: DocumentationContext, problems: inout [Problem]) -> [ListElement]? {
266+
analyze(directive, children: children, source: source, problems: &problems)
267+
}
263268

264269
func firstChildElement(in markup: Markup) -> ListElement? {
265270
return markup // ListItem

‎Sources/SwiftDocC/Semantics/General Purpose Analyses/HasOnlyKnownArguments.swift‎

Lines changed: 8 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
@@ -12,15 +12,15 @@ import Foundation
1212
import Markdown
1313

1414
extension Semantic.Analyses {
15-
public struct HasOnlyKnownArguments<Parent: Semantic & DirectiveConvertible>: SemanticAnalysis {
15+
public struct HasOnlyKnownArguments<Parent: Semantic & DirectiveConvertible> {
1616
let severityIfFound: DiagnosticSeverity?
1717
let allowedArguments: [String]
1818
public init(severityIfFound: DiagnosticSeverity?, allowedArguments: [String]) {
1919
self.severityIfFound = severityIfFound
2020
self.allowedArguments = allowedArguments
2121
}
2222

23-
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> [String: Markdown.DirectiveArgument] {
23+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, problems: inout [Problem]) -> [String: Markdown.DirectiveArgument] {
2424
let arguments = directive.arguments(problems: &problems)
2525
if let severity = severityIfFound {
2626
let unknownKeys = Set(arguments.keys).subtracting(allowedArguments)
@@ -42,6 +42,11 @@ extension Semantic.Analyses {
4242
}
4343
return arguments
4444
}
45+
46+
@available(*, deprecated, renamed: "analyze(_:children:source:problems:)", message: "Use 'analyze(_:children:source:problems:)' instead. This deprecated API will be removed after 6.2 is released")
47+
public func analyze(_ directive: BlockDirective, children: some Sequence<Markup>, source: URL?, for _: DocumentationBundle, in _: DocumentationContext, problems: inout [Problem]) -> [String: Markdown.DirectiveArgument] {
48+
analyze(directive, children: children, source: source, problems: &problems)
49+
}
4550
}
4651
}
4752

0 commit comments

Comments
 (0)