File: ConvertRequest.swift

package info (click to toggle)
swiftlang 6.0.3-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 2,519,992 kB
  • sloc: cpp: 9,107,863; ansic: 2,040,022; asm: 1,135,751; python: 296,500; objc: 82,456; f90: 60,502; lisp: 34,951; pascal: 19,946; sh: 18,133; perl: 7,482; ml: 4,937; javascript: 4,117; makefile: 3,840; awk: 3,535; xml: 914; fortran: 619; cs: 573; ruby: 573
file content (226 lines) | stat: -rw-r--r-- 10,889 bytes parent folder | download
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
/*
 This source file is part of the Swift.org open source project

 Copyright (c) 2021-2024 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 SymbolKit
import Foundation

/// A request to convert in-memory documentation.
public struct ConvertRequest: Codable {
    /// Information about the documentation bundle to convert.
    ///
    /// ## See Also
    /// - ``DocumentationBundle/Info``
    public var bundleInfo: DocumentationBundle.Info
    
    /// Feature flags to enable when performing this convert request.
    public var featureFlags: FeatureFlags
    
    /// The external IDs of the symbols to convert.
    ///
    /// Use this property to indicate what symbol documentation nodes should be converted. When ``externalIDsToConvert``
    /// and ``documentPathsToConvert`` are both set, the documentation nodes that are in either arrays will be
    /// converted.
    ///
    /// If you want all the symbol render nodes to be returned as part of the conversion's response, set this property to `nil`.
    /// For Swift, the external ID of the symbol is its USR.
    public var externalIDsToConvert: [String]?
    
    /// The mapping of external symbol identifiers to known disambiguated symbol path components.
    ///
    /// Use this property to provide accurately disambiguated symbol path components for symbols
    /// in the given ``symbolGraphs`` that collide with other symbols that exist in the module but
    /// are not included in the given partial symbol graphs.
    public var knownDisambiguatedSymbolPathComponents: [String: [String]]?
    
    /// The paths of the documentation nodes to convert.
    ///
    /// Use this property to indicate what documentation nodes should be converted. When ``externalIDsToConvert``
    /// and ``documentPathsToConvert`` are both set, the documentation nodes that are in either arrays will be
    /// converted.
    ///
    /// If you want all the render nodes to be returned as part of the conversion's response, set this property to `nil`.
    public var documentPathsToConvert: [String]?
    
    /// Whether the conversion's render reference store should be included in the response.
    ///
    /// The ``RenderReferenceStore`` contains compiled information for documentation nodes registered in a context. This
    /// information can be used as a lightweight index of the available documentation content in the bundle that's been converted.
    public var includeRenderReferenceStore: Bool?
    
    /// The file location of the bundle to convert, if any.
    public var bundleLocation: URL?
    
    /// The symbols graph data included in the documentation bundle to convert.
    ///
    /// ## See Also
    /// - ``DocumentationBundle/symbolGraphURLs``
    public var symbolGraphs: [Data]
    
    /// The mapping of external symbol identifiers to lines of a documentation comment that overrides the value in the symbol graph.
    ///
    /// Use this property to override the `docComment` mixin of a symbol entry in a symbol graph. This allows
    /// the client to pass a more up-to-date value than is available in the symbol graph.
    public var overridingDocumentationComments: [String: [Line]]? = nil
    
    /// Whether the conversion's rendered documentation should include source file location metadata.
    public var emitSymbolSourceFileURIs: Bool
    
    /// The article and documentation extension file data included in the documentation bundle to convert.
    ///
    /// ## See Also
    /// - ``DocumentationBundle/markupURLs``
    public var markupFiles: [Data]
    
    
    /// The tutorial file data included in the documentation bundle to convert.
    public var tutorialFiles: [Data]
    
    /// The on-disk resources in the documentation bundle to convert.
    ///
    /// ## See Also
    /// - ``DocumentationBundle/miscResourceURLs``
    public var miscResourceURLs: [URL]
    
    /// The symbol identifiers that have an expanded documentation page available if they meet the associated access level requirement.
    ///
    /// For each of these symbols DocC sets the ``RenderMetadata/hasNoExpandedDocumentation`` property to `true`
    /// if the symbol fails to meet its provided requirements. This information in the page's ``RenderMetadata`` can be used to display
    /// a "View More" link that navigates the user to the full version of the documentation page.
    public var symbolIdentifiersWithExpandedDocumentation: [String: ExpandedDocumentationRequirements]?
    
    /// Creates a request to convert in-memory documentation.
    /// - Parameters:
    ///   - bundleInfo: Information about the bundle to convert.
    ///   - featureFlags: Feature flags to enable when performing this convert request.
    ///   - externalIDsToConvert: The external IDs of the symbols to convert.
    ///   - documentPathsToConvert: The paths of the documentation nodes to convert.
    ///   - includeRenderReferenceStore: Whether the conversion's render reference store should be included in the
    ///   response.
    ///   - bundleLocation: The file location of the documentation bundle to convert, if any.
    ///   - symbolGraphs: The symbols graph data included in the documentation bundle to convert.
    ///   - overridingDocumentationComments: The mapping of external symbol identifiers to lines of a
    ///   documentation comment that overrides the value in the symbol graph.
    ///   - emitSymbolSourceFileURIs: Whether the conversion's rendered documentation should include source file location metadata.
    ///   - knownDisambiguatedSymbolPathComponents: The mapping of external symbol identifiers to
    ///   known disambiguated symbol path components.
    ///   - markupFiles: The article and documentation extension file data included in the documentation bundle to convert.
    ///   - tutorialFiles: The tutorial file data included in the documentation bundle to convert.
    ///   - miscResourceURLs: The on-disk resources in the documentation bundle to convert.
    ///   - symbolIdentifiersWithExpandedDocumentation: A dictionary of identifiers to requirements for these symbols to have expanded
    ///   documentation available.
    public init(
        bundleInfo: DocumentationBundle.Info,
        featureFlags: FeatureFlags = FeatureFlags(),
        externalIDsToConvert: [String]?,
        documentPathsToConvert: [String]? = nil,
        includeRenderReferenceStore: Bool? = nil,
        bundleLocation: URL? = nil,
        symbolGraphs: [Data],
        overridingDocumentationComments: [String: [Line]]? = nil,
        knownDisambiguatedSymbolPathComponents: [String: [String]]? = nil,
        emitSymbolSourceFileURIs: Bool = true,
        markupFiles: [Data],
        tutorialFiles: [Data] = [],
        miscResourceURLs: [URL],
        symbolIdentifiersWithExpandedDocumentation: [String: ExpandedDocumentationRequirements]? = nil
    ) {
        self.externalIDsToConvert = externalIDsToConvert
        self.documentPathsToConvert = documentPathsToConvert
        self.includeRenderReferenceStore = includeRenderReferenceStore
        self.bundleLocation = bundleLocation
        self.symbolGraphs = symbolGraphs
        self.overridingDocumentationComments = overridingDocumentationComments
        self.knownDisambiguatedSymbolPathComponents = knownDisambiguatedSymbolPathComponents
        
        // The default value for this is `true` to enable the inclusion of symbol declaration file paths
        // in the produced render json by default.
        // This default to true, because the render nodes created by `ConvertService` are intended for
        // local uses of documentation where this information could be relevant and we don't have the
        // privacy concerns that come with including this information in public releases of docs.
        self.emitSymbolSourceFileURIs = emitSymbolSourceFileURIs
        self.markupFiles = markupFiles
        self.tutorialFiles = tutorialFiles
        self.miscResourceURLs = miscResourceURLs
        self.bundleInfo = bundleInfo
        self.featureFlags = featureFlags
        self.symbolIdentifiersWithExpandedDocumentation = symbolIdentifiersWithExpandedDocumentation
    }
}

extension ConvertRequest {
    /// A line of text in source code.
    public struct Line: Codable {
        /// The string contents of a line.
        ///
        /// Do not include newline characters in this property.
        public var text: String
        
        /// The line's range in a document if available.
        public var sourceRange: SourceRange?
        
        /// Creates a line of text from source code.
        /// - Parameters:
        ///   - text: The strings contents of a line. Do not include newline characters.
        ///   - sourceRange: The line's range in a document if available.
        public init(
            text: String,
            sourceRange: SourceRange? = nil
        ) {
            self.text = text
            self.sourceRange = sourceRange
        }
    }
    
    /// Represents a selection in text.
    public struct SourceRange: Codable {
        /// The range's start position.
        public var start: Position
        
        /// The range's end position.
        public var end: Position
        
        /// Creates a new source range with the given start and end positions.
        public init(
            start: Position,
            end: Position
        ) {
            self.start = start
            self.end = end
        }
    }
    
    /// Represents a cursor position in text.
    public struct Position: Codable {
        /// The zero-based line number in a document.
        public var line: Int
        
        /// The zero-based byte offset into a line.
        public var character: Int
        
        /// Creates a new cursor position with the given line number and character offset.
        public init(line: Int, character: Int) {
            self.line = line
            self.character = character
        }
    }
    
    /// Represents any requirements needed for a symbol to have additional documentation available in the client.
    public struct ExpandedDocumentationRequirements: Codable {
        /// Access control levels required for the symbol to have additional documentation available.
        public let accessControlLevels: [String]
        /// Whether the client provides additional documentation for the symbol despite it being prefixed with an underscore.
        public let canBeUnderscored: Bool
        
        public init(accessControlLevels: [String], canBeUnderscored: Bool = false) {
            self.accessControlLevels = accessControlLevels
            self.canBeUnderscored = canBeUnderscored
        }
    }
}