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.

Author: natikgadzhi

CodeGeneration/Sources/SyntaxSupport/Child.swift

@@ -93,17 +93,34 @@ public class Child {
   public let documentationSummary: SwiftSyntax.Trivia
 
   /// A docc comment describing the child, including the trivia provided when
-  /// initializing the Child, and the list of possible token choices inferred automatically.
+  /// initializing the ``Child``, and the list of possible token choices inferred automatically.
   public var documentation: SwiftSyntax.Trivia {
     if case .token(let choices, _, _) = kind {
-      var tokenKindsComment =
+      let grammar = GrammarGenerator()
+
+      var tokensDocumentation = """
+        ### Tokens
+        For syntax trees generated by the parser, this is guaranteed to be the following
+        """
+
+      tokensDocumentation +=
         choices.count == 1
-        ? "For syntax trees generated by the parser, this is guaranteed to be the following kind:"
-        : "For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:\n"
-      tokenKindsComment += GrammarGenerator.childTokenChoices(for: self)
+        ? "kind: \(grammar.grammar(for: choices.first!))"
+        : """
+        kinds:
+        \(choices.map { " - \(grammar.grammar(for: $0))" }.joined(separator: "\n"))
+        """
 
-      let trivia = docCommentTrivia(from: tokenKindsComment)
-      return documentationSummary.appending(trivia)
+      // trivia's last piece does not end in \n.
+      // So if the existing documentation is not emtpy, we need to append an
+      // additional TriviaPiece.newlines(1) before appending the token choices.
+      if documentationSummary.isEmpty {
+        return docCommentTrivia(from: tokensDocumentation)
+      } else {
+        return documentationSummary
+          .appending(TriviaPiece.newlines(1))
+          .appending(docCommentTrivia(from: tokensDocumentation))
+      }
     }
 
     // If this child is not a token kind, return documentation summary without the choices list.

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -19,8 +19,7 @@ struct GrammarGenerator {
   ///
   /// - parameters:
   ///   - tokenChoice: ``TokenChoice`` to describe
-  ///   - backticks: Whether to wrap the token choice in backticks
-  private func grammar(for tokenChoice: TokenChoice) -> String {
+  public func grammar(for tokenChoice: TokenChoice) -> String {
     switch tokenChoice {
     case .keyword(let keyword):
       return "`'\(keyword.spec.name)'`"
@@ -66,20 +65,4 @@ struct GrammarGenerator {
       .map { " - `\($0.varOrCaseName)`: \(generator.grammar(for: $0))" }
       .joined(separator: "\n")
   }
-
-  /// Generates the list of possible token kinds for this particular ``Child``.
-  /// The child must be of kind ``ChildKind/token``. Otherwise, an empty string will be returned.
-  static func childTokenChoices(for child: Child) -> String {
-    let generator = GrammarGenerator()
-
-    if case .token(let choices, _, _) = child.kind {
-      if choices.count == 1 {
-        return " \(generator.grammar(for: choices.first!))"
-      } else {
-        return choices.map { " - \(generator.grammar(for: $0))" }.joined(separator: "\n")
-      }
-    } else {
-      return ""
-    }
-  }
 }

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -16,13 +16,15 @@
 
 
 public protocol BracedSyntax: SyntaxProtocol {
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '{'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `'{'`
   var leftBrace: TokenSyntax {
     get
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '}'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `'}'`
   var rightBrace: TokenSyntax {
     get
     set
@@ -123,9 +125,10 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:
-  ///  - 'async'
-  ///  - 'reasync'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkinds:
+  ///  - `'async'`
+  ///  - `'reasync'`
   var asyncSpecifier: TokenSyntax? {
     get
     set
@@ -136,9 +139,10 @@ public protocol EffectSpecifiersSyntax: SyntaxProtocol {
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be one of the following token kinds:
-  ///  - 'throws'
-  ///  - 'rethrows'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkinds:
+  ///  - `'throws'`
+  ///  - `'rethrows'`
   var throwsSpecifier: TokenSyntax? {
     get
     set
@@ -181,13 +185,15 @@ public extension SyntaxProtocol {
 
 
 public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '#'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `'#'`
   var pound: TokenSyntax {
     get
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `<identifier>`
   var macroName: TokenSyntax {
     get
     set
@@ -198,7 +204,8 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `'('`
   var leftParen: TokenSyntax? {
     get
     set
@@ -209,7 +216,8 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `')'`
   var rightParen: TokenSyntax? {
     get
     set
@@ -257,7 +265,8 @@ public extension SyntaxProtocol {
 
 
 public protocol NamedDeclSyntax: SyntaxProtocol {
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `<identifier>`
   var name: TokenSyntax {
     get
     set
@@ -297,7 +306,9 @@ public extension SyntaxProtocol {
 /// 
 /// See the types conforming to this protocol for examples of where missing nodes can occur.
 public protocol MissingNodeSyntax: SyntaxProtocol {
-  /// 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>
+  /// A placeholder, i.e. `<#placeholder#>`, that can be inserted into the source code to represent the missing node.
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `<identifier>`
   var placeholder: TokenSyntax {
     get
     set
@@ -335,13 +346,15 @@ public extension SyntaxProtocol {
 
 
 public protocol ParenthesizedSyntax: SyntaxProtocol {
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `'('`
   var leftParen: TokenSyntax {
     get
     set
   }
 
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `')'`
   var rightParen: TokenSyntax {
     get
     set
@@ -573,7 +586,8 @@ public extension SyntaxProtocol {
 
 
 public protocol WithTrailingCommaSyntax: SyntaxProtocol {
-  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ','
+  /// ### Tokens
+  /// For syntax trees generated by the parser, this is guaranteed to be the followingkind: `','`
   var trailingComma: TokenSyntax? {
     get
     set