Skip to content

Commit 6bc0968

Browse files
natikgadzhinatikgadzhi
committed
Improve token choices doc comment
- Moves complexity of generating the comment into `Child.swift` and uses `grammar.grammar()` directly. - Appends a `TriviaPiece.newlines(1)` between trivia pieces when merging with the original comment. - Uses approach similar to `SyntaxNodesFile.swift` to concatenating documentation pieces.
1 parent 5625a8c commit 6bc0968

File tree

12 files changed

+1653
-654
lines changed

12 files changed

+1653
-654
lines changed

‎CodeGeneration/Sources/SyntaxSupport/Child.swift

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -93,17 +93,35 @@ public class Child {
9393
public let documentationSummary: SwiftSyntax.Trivia
9494

9595
/// A docc comment describing the child, including the trivia provided when
96-
/// initializing the Child, and the list of possible token choices inferred automatically.
96+
/// initializing the ``Child``, and the list of possible token choices inferred automatically.
9797
public var documentation: SwiftSyntax.Trivia {
9898
if case .token(let choices, _, _) = kind {
99-
var tokenKindsComment =
99+
let grammar = GrammarGenerator()
100+
101+
let choices =
100102
choices.count == 1
101-
? "For syntax trees generated by the parser, this is guaranteed to be the following kind:"
102-
: "For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:\n"
103-
tokenKindsComment += GrammarGenerator.childTokenChoices(for: self)
103+
? "kind: \(grammar.grammar(for: choices.first!))"
104+
: """
105+
kinds:
106+
\(choices.map { " - \(grammar.grammar(for: $0))" }.joined(separator: "\n"))
107+
"""
108+
109+
let tokenChoicesTrivia = docCommentTrivia(
110+
from:"""
111+
### Tokens
112+
113+
For syntax trees generated by the parser, this is guaranteed to be the following \(choices)
114+
"""
115+
)
116+
117+
let separator = SwiftSyntax.Trivia(pieces: [TriviaPiece.newlines(1), TriviaPiece.docLineComment("///"), TriviaPiece.newlines(1)])
104118

105-
let trivia = docCommentTrivia(from: tokenKindsComment)
106-
return documentationSummary.appending(trivia)
119+
// Grab the documentation secions, filter out empty ones, and join them
120+
// with an empty documentation line inbetween.
121+
return [documentationSummary, tokenChoicesTrivia]
122+
.filter { !$0.isEmpty }
123+
.joined(separator: separator)
124+
.reduce(SwiftSyntax.Trivia(), { $0.appending($1) })
107125
}
108126

109127
// If this child is not a token kind, return documentation summary without the choices list.

‎CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,7 @@ struct GrammarGenerator {
1919
///
2020
/// - parameters:
2121
/// - tokenChoice: ``TokenChoice`` to describe
22-
/// - backticks: Whether to wrap the token choice in backticks
23-
private func grammar(for tokenChoice: TokenChoice) -> String {
22+
public func grammar(for tokenChoice: TokenChoice) -> String {
2423
switch tokenChoice {
2524
case .keyword(let keyword):
2625
return "`'\(keyword.spec.name)'`"
@@ -66,20 +65,4 @@ struct GrammarGenerator {
6665
.map { " - `\($0.varOrCaseName)`: \(generator.grammar(for: $0))" }
6766
.joined(separator: "\n")
6867
}
69-
70-
/// Generates the list of possible token kinds for this particular ``Child``.
71-
/// The child must be of kind ``ChildKind/token``. Otherwise, an empty string will be returned.
72-
static func childTokenChoices(for child: Child) -> String {
73-
let generator = GrammarGenerator()
74-
75-
if case .token(let choices, _, _) = child.kind {
76-
if choices.count == 1 {
77-
return " \(generator.grammar(for: choices.first!))"
78-
} else {
79-
return choices.map { " - \(generator.grammar(for: $0))" }.joined(separator: "\n")
80-
}
81-
} else {
82-
return ""
83-
}
84-
}
8568
}

‎Sources/SwiftSyntax/generated/SyntaxTraits.swift

Lines changed: 45 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,17 @@
1616

1717

1818
public protocol BracedSyntax: SyntaxProtocol {
19-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: '{'
19+
/// ### Tokens
20+
///
21+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `'{'`
2022
var leftBrace: TokenSyntax {
2123
get
2224
set
2325
}
2426

25-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: '}'
27+
/// ### Tokens
28+
///
29+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `'}'`
2630
var rightBrace: TokenSyntax {
2731
get
2832
set
@@ -123,9 +127,11 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
123127
set
124128
}
125129

126-
/// For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:
127-
/// - 'async'
128-
/// - 'reasync'
130+
/// ### Tokens
131+
///
132+
/// For syntax trees generated by the parser, this is guaranteed to be the following kinds:
133+
/// - `'async'`
134+
/// - `'reasync'`
129135
var asyncSpecifier: TokenSyntax? {
130136
get
131137
set
@@ -136,9 +142,11 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
136142
set
137143
}
138144

139-
/// For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:
140-
/// - 'throws'
141-
/// - 'rethrows'
145+
/// ### Tokens
146+
///
147+
/// For syntax trees generated by the parser, this is guaranteed to be the following kinds:
148+
/// - `'throws'`
149+
/// - `'rethrows'`
142150
var throwsSpecifier: TokenSyntax? {
143151
get
144152
set
@@ -181,13 +189,17 @@ public extension SyntaxProtocol {
181189

182190

183191
public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
184-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: '#'
192+
/// ### Tokens
193+
///
194+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `'#'`
185195
var pound: TokenSyntax {
186196
get
187197
set
188198
}
189199

190-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
200+
/// ### Tokens
201+
///
202+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `<identifier>`
191203
var macroName: TokenSyntax {
192204
get
193205
set
@@ -198,7 +210,9 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
198210
set
199211
}
200212

201-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
213+
/// ### Tokens
214+
///
215+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `'('`
202216
var leftParen: TokenSyntax? {
203217
get
204218
set
@@ -209,7 +223,9 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
209223
set
210224
}
211225

212-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
226+
/// ### Tokens
227+
///
228+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `')'`
213229
var rightParen: TokenSyntax? {
214230
get
215231
set
@@ -257,7 +273,9 @@ public extension SyntaxProtocol {
257273

258274

259275
public protocol NamedDeclSyntax: SyntaxProtocol {
260-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
276+
/// ### Tokens
277+
///
278+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `<identifier>`
261279
var name: TokenSyntax {
262280
get
263281
set
@@ -297,7 +315,11 @@ public extension SyntaxProtocol {
297315
///
298316
/// See the types conforming to this protocol for examples of where missing nodes can occur.
299317
public protocol MissingNodeSyntax: SyntaxProtocol {
300-
/// A placeholder, i.e. `<#placeholder#>`, that can be inserted into the source code to represent the missing node./// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
318+
/// A placeholder, i.e. `<#placeholder#>`, that can be inserted into the source code to represent the missing node.
319+
///
320+
/// ### Tokens
321+
///
322+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `<identifier>`
301323
var placeholder: TokenSyntax {
302324
get
303325
set
@@ -335,13 +357,17 @@ public extension SyntaxProtocol {
335357

336358

337359
public protocol ParenthesizedSyntax: SyntaxProtocol {
338-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
360+
/// ### Tokens
361+
///
362+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `'('`
339363
var leftParen: TokenSyntax {
340364
get
341365
set
342366
}
343367

344-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
368+
/// ### Tokens
369+
///
370+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `')'`
345371
var rightParen: TokenSyntax {
346372
get
347373
set
@@ -573,7 +599,9 @@ public extension SyntaxProtocol {
573599

574600

575601
public protocol WithTrailingCommaSyntax: SyntaxProtocol {
576-
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: ','
602+
/// ### Tokens
603+
///
604+
/// For syntax trees generated by the parser, this is guaranteed to be the following kind: `','`
577605
var trailingComma: TokenSyntax? {
578606
get
579607
set

0 commit comments

Comments
 (0)