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
|
/*
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
/**
A `Document` may only have one level-2 "Topics" heading at the top level, since it serves as structured data for a documentation bundle's hierarchy.
*/
public struct DuplicateTopicsSections: Checker {
/// The list of level-2 headings with the text "Topics" found in the document.
public var foundTopicsHeadings = [Heading]()
private var sourceFile: URL?
/// Creates a new checker that detects documents with multiple "Topics" sections.
///
/// - Parameter sourceFile: The URL to the documentation file that the checker checks.
public init(sourceFile: URL?) {
self.sourceFile = sourceFile
}
public var problems: [Problem] {
guard foundTopicsHeadings.count > 1 else {
return []
}
let first = foundTopicsHeadings[0]
let duplicates = foundTopicsHeadings[1...]
return duplicates.map { duplicateHeading -> Problem in
let range = duplicateHeading.range!
let notes: [DiagnosticNote]
if let sourceFile, let range = first.range {
notes = [DiagnosticNote(source: sourceFile, range: range, message: "First Topics Section starts here.")]
} else {
notes = []
}
let explanation = """
A second-level heading with the name "Topics" is a reserved heading name you use to begin a section to organize topics into task groups. To resolve this issue, change the name of this heading or merge the contents of both topics sections under a single Topics heading.
"""
let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: range, identifier: "org.swift.docc.MultipleTopicsSections", summary: "The Topics section may only appear once in a document", explanation: explanation, notes: notes)
return Problem(diagnostic: diagnostic, possibleSolutions: [])
}
}
public mutating func visitHeading(_ heading: Heading) {
guard heading.isTopicsSection,
heading.parent is Document? else {
return
}
foundTopicsHeadings.append(heading)
}
}
|
