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
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021 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 Swift project authors
*/
import Foundation
import Markdown
extension Semantic.Analyses {
/**
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.
*/
public struct HasAtLeastOne<Parent: Semantic & DirectiveConvertible, Child: Semantic & DirectiveConvertible>: SemanticAnalysis {
let severityIfNotFound: DiagnosticSeverity?
public init(severityIfNotFound: DiagnosticSeverity?) {
self.severityIfNotFound = severityIfNotFound
}
public func analyze(
_ directive: BlockDirective,
children: some Sequence<Markup>,
source: URL?,
for bundle: DocumentationBundle,
in context: DocumentationContext,
problems: inout [Problem]
) -> ([Child], remainder: MarkupContainer) {
Semantic.Analyses.extractAtLeastOne(
childType: Child.self,
parentDirective: directive,
children: children,
source: source,
for: bundle,
in: context,
severityIfNotFound: severityIfNotFound,
problems: &problems
) as! ([Child], MarkupContainer)
}
}
static func extractAtLeastOne(
childType: DirectiveConvertible.Type,
parentDirective: BlockDirective,
children: some Sequence<Markup>,
source: URL?,
for bundle: DocumentationBundle,
in context: DocumentationContext,
severityIfNotFound: DiagnosticSeverity? = .warning,
problems: inout [Problem]
) -> ([DirectiveConvertible], remainder: MarkupContainer) {
let (matches, remainder) = children.categorize { child -> BlockDirective? in
guard let childDirective = child as? BlockDirective,
childType.canConvertDirective(childDirective)
else {
return nil
}
return childDirective
}
if matches.isEmpty, let severityIfNotFound {
let diagnostic = Diagnostic(
source: source,
severity: severityIfNotFound,
range: parentDirective.range,
identifier: "org.swift.docc.HasAtLeastOne<\(parentDirective.name), \(childType)>",
summary: "Missing required \(childType.directiveName.singleQuoted) child directive",
explanation:
"""
The \(parentDirective.name.singleQuoted) directive requires at least one \
\(childType.directiveName.singleQuoted) child directive
"""
)
problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
}
let converted = matches.compactMap { childDirective -> DirectiveConvertible? in
return childType.init(
from: childDirective,
source: source,
for: bundle,
in: context,
problems: &problems
)
}
return (converted, remainder: MarkupContainer(remainder))
}
}
|
