Refactor child token choices comment generator

- Improves readability by omitting single quotes inside backticks
  (@kimdv)
- Cleans up the language on possible token choices (@ahoppen)
- Moves token choices generation into `GrammarGenerator`, but leaves the
  documentation property in `Child` so it's consistent with how `Node`
  works.

Author: natikgadzhi

CodeGeneration/Sources/SyntaxSupport/Child.swift

@@ -96,22 +96,8 @@ public class Child {
   /// initializing the ``Child``, and the list of possible token choices inferred automatically.
   public var documentation: SwiftSyntax.Trivia {
     if case .token(let choices, _, _) = kind {
-      let grammar = GrammarGenerator()
-
-      let choices =
-        choices.count == 1
-        ? "kind: \(grammar.grammar(for: choices.first!))"
-        : """
-        kinds:
-        \(choices.map { " - \(grammar.grammar(for: $0))" }.joined(separator: "\n"))
-        """
-
       let tokenChoicesTrivia = SwiftSyntax.Trivia.docCommentTrivia(
-        from: """
-          ### Tokens
-
-          For syntax trees generated by the parser, this is guaranteed to be one of the following \(choices)
-          """
+        from: GrammarGenerator.childTokenChoices(for: choices)
       )
 
       return SwiftSyntax.Trivia(joining: [documentationSummary, tokenChoicesTrivia])

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -19,14 +19,14 @@ struct GrammarGenerator {
   ///
   /// - parameters:
   ///   - tokenChoice: ``TokenChoice`` to describe
-  public func grammar(for tokenChoice: TokenChoice) -> String {
+  private func grammar(for tokenChoice: TokenChoice) -> String {
     switch tokenChoice {
     case .keyword(let keyword):
-      return "`'\(keyword.spec.name)'`"
+      return "`\(keyword.spec.name)`"
     case .token(let token):
       let tokenSpec = token.spec
       if let tokenText = tokenSpec.text {
-        return "`'\(tokenText)'`"
+        return "`\(tokenText)`"
       } else {
         return "`<\(tokenSpec.varOrCaseName)>`"
       }
@@ -65,4 +65,25 @@ struct GrammarGenerator {
       .map { " - `\($0.varOrCaseName)`: \(generator.grammar(for: $0))" }
       .joined(separator: "\n")
   }
+
+  /// Generates a markdown string describing possible choices for the given child
+  /// token.
+  static func childTokenChoices(for choices: [TokenChoice]) -> String {
+    let grammar = GrammarGenerator()
+    
+    if choices.count == 1 {
+      return """
+        ### Tokens
+
+        For syntax trees generated by the parser, this is guaranteed to be \(grammar.grammar(for: choices.first!)) 
+        """
+    } else {
+      return """
+        ### Tokens
+
+        For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
+        \(choices.map { " - \(grammar.grammar(for: $0))" }.joined(separator: "\n"))
+        """
+    }
+  }
 }

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -18,15 +18,15 @@
 public protocol BracedSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `'{'`
+  /// For syntax trees generated by the parser, this is guaranteed to be `{` 
   var leftBrace: TokenSyntax {
     get
     set
   }
 
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `'}'`
+  /// For syntax trees generated by the parser, this is guaranteed to be `}` 
   var rightBrace: TokenSyntax {
     get
     set
@@ -130,8 +130,8 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
   /// For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
-  ///  - `'async'`
-  ///  - `'reasync'`
+  ///  - `async`
+  ///  - `reasync`
   var asyncSpecifier: TokenSyntax? {
     get
     set
@@ -145,8 +145,8 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
   /// For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
-  ///  - `'throws'`
-  ///  - `'rethrows'`
+  ///  - `throws`
+  ///  - `rethrows`
   var throwsSpecifier: TokenSyntax? {
     get
     set
@@ -191,15 +191,15 @@ public extension SyntaxProtocol {
 public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `'#'`
+  /// For syntax trees generated by the parser, this is guaranteed to be `#` 
   var pound: TokenSyntax {
     get
     set
   }
 
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `<identifier>`
+  /// For syntax trees generated by the parser, this is guaranteed to be `<identifier>` 
   var macroName: TokenSyntax {
     get
     set
@@ -212,7 +212,7 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
 
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `'('`
+  /// For syntax trees generated by the parser, this is guaranteed to be `(` 
   var leftParen: TokenSyntax? {
     get
     set
@@ -225,7 +225,7 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
 
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `')'`
+  /// For syntax trees generated by the parser, this is guaranteed to be `)` 
   var rightParen: TokenSyntax? {
     get
     set
@@ -275,7 +275,7 @@ public extension SyntaxProtocol {
 public protocol NamedDeclSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `<identifier>`
+  /// For syntax trees generated by the parser, this is guaranteed to be `<identifier>` 
   var name: TokenSyntax {
     get
     set
@@ -319,7 +319,7 @@ public protocol MissingNodeSyntax: SyntaxProtocol {
   ///
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `<identifier>`
+  /// For syntax trees generated by the parser, this is guaranteed to be `<identifier>` 
   var placeholder: TokenSyntax {
     get
     set
@@ -359,15 +359,15 @@ public extension SyntaxProtocol {
 public protocol ParenthesizedSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `'('`
+  /// For syntax trees generated by the parser, this is guaranteed to be `(` 
   var leftParen: TokenSyntax {
     get
     set
   }
 
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `')'`
+  /// For syntax trees generated by the parser, this is guaranteed to be `)` 
   var rightParen: TokenSyntax {
     get
     set
@@ -601,7 +601,7 @@ public extension SyntaxProtocol {
 public protocol WithTrailingCommaSyntax: SyntaxProtocol {
   /// ### Tokens
   /// 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following kind: `','`
+  /// For syntax trees generated by the parser, this is guaranteed to be `,` 
   var trailingComma: TokenSyntax? {
     get
     set