List the token kinds in child documentation

For children of syntax nodes that are TokenSyntax, list the kinds of
tokens it can contain. Fixes #1987.

Author: natikgadzhi

CodeGeneration/Sources/SyntaxSupport/Child.swift

@@ -87,8 +87,27 @@ public class Child {
   /// This is used to e.g. describe the child if all of its tokens are missing in the source file.
   public let nameForDiagnostics: String?
 
-  /// A doc comment describing the child.
-  public let documentation: SwiftSyntax.Trivia
+  /// A summary of a doc comment describing the child. Full docc comment for the
+  /// child is available in ``Child/documentation``, and includes detailed list
+  /// of possible choices for the child if it's a token kind.
+  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.
+  public var documentation: SwiftSyntax.Trivia {
+    if case .token(let choices, _, _) = kind {
+      var tokenKindsComment = 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)
+
+      let trivia = docCommentTrivia(from: tokenKindsComment)
+      return documentationSummary.appending(trivia)
+    }
+
+    // If this child is not a token kind, return documentation summary without the choices list.
+    return documentationSummary
+  }
 
   /// The first line of the child's documentation
   public let documentationAbstract: String
@@ -220,7 +239,7 @@ public class Child {
     self.deprecatedName = deprecatedName
     self.kind = kind
     self.nameForDiagnostics = nameForDiagnostics
-    self.documentation = docCommentTrivia(from: documentation)
+    self.documentationSummary = docCommentTrivia(from: documentation)
     self.documentationAbstract = String(documentation?.split(whereSeparator: \.isNewline).first ?? "")
     self.isOptional = isOptional
   }

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -14,18 +14,27 @@ import SwiftSyntax
 
 /// Generates grammar doc comments for syntax nodes.
 struct GrammarGenerator {
-  private func grammar(for tokenChoice: TokenChoice) -> String {
+
+  /// Returns grammar for a ``TokenChoice``.
+  ///
+  /// - parameters:
+  ///   - tokenChoice: ``TokenChoice`` to describe
+  ///   - backticks: Whether to wrap the token choice in backticks
+  private func grammar(for tokenChoice: TokenChoice, backticked: Bool = true) -> String {
+    var description: String
     switch tokenChoice {
     case .keyword(let keyword):
-      return "`'\(keyword.spec.name)'`"
+      description = "'\(keyword.spec.name)'"
     case .token(let token):
       let tokenSpec = token.spec
       if let tokenText = tokenSpec.text {
-        return "`'\(tokenText)'`"
+        description = "'\(tokenText)'"
       } else {
-        return "`<\(tokenSpec.varOrCaseName)>`"
+        description = "<\(tokenSpec.varOrCaseName)>"
       }
     }
+
+    return backticked ? "`\(description)`" : description
   }
 
   private func grammar(for child: Child) -> String {
@@ -60,4 +69,20 @@ 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!, backticked: false))"
+      } else {
+        return choices.map { " - \(generator.grammar(for: $0, backticked: false))" }.joined(separator: "\n")
+      }
+    } else {
+      return ""
+    }
+  }
 }

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -16,11 +16,13 @@
 
 
 public protocol BracedSyntax: SyntaxProtocol {
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '{'
   var leftBrace: TokenSyntax {
     get
     set
   }
 
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '}'
   var rightBrace: TokenSyntax {
     get
     set
@@ -121,6 +123,9 @@ 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'
   var asyncSpecifier: TokenSyntax? {
     get
     set
@@ -131,6 +136,9 @@ 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'
   var throwsSpecifier: TokenSyntax? {
     get
     set
@@ -173,11 +181,13 @@ public extension SyntaxProtocol {
 
 
 public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '#'
   var pound: TokenSyntax {
     get
     set
   }
 
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
   var macroName: TokenSyntax {
     get
     set
@@ -188,6 +198,7 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
     set
   }
 
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
   var leftParen: TokenSyntax? {
     get
     set
@@ -198,6 +209,7 @@ public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
     set
   }
 
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
   var rightParen: TokenSyntax? {
     get
     set
@@ -245,6 +257,7 @@ public extension SyntaxProtocol {
 
 
 public protocol NamedDeclSyntax: SyntaxProtocol {
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: <identifier>
   var name: TokenSyntax {
     get
     set
@@ -284,7 +297,7 @@ 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.
+  /// 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>
   var placeholder: TokenSyntax {
     get
     set
@@ -322,11 +335,13 @@ public extension SyntaxProtocol {
 
 
 public protocol ParenthesizedSyntax: SyntaxProtocol {
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: '('
   var leftParen: TokenSyntax {
     get
     set
   }
 
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ')'
   var rightParen: TokenSyntax {
     get
     set
@@ -558,6 +573,7 @@ public extension SyntaxProtocol {
 
 
 public protocol WithTrailingCommaSyntax: SyntaxProtocol {
+  /// For syntax trees generated by the parser, this is guaranteed to be the following kind: ','
   var trailingComma: TokenSyntax? {
     get
     set