Generate grammar doc comments for layout nodes

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -0,0 +1,63 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+/// Generates grammar doc comments for syntax nodes.
+struct GrammarGenerator {
+  private func grammar(for tokenChoice: TokenChoice) -> String {
+    switch tokenChoice {
+    case .keyword(text: let text):
+      return "`'\(text)'`"
+    case .token(tokenKind: let tokenKind):
+      let token = SYNTAX_TOKEN_MAP[tokenKind]!
+      if let tokenText = token.text {
+        return "`'\(tokenText)'`"
+      } else {
+        return "`<\(token.swiftKind)>`"
+      }
+    }
+  }
+
+  private func grammar(for child: Child) -> String {
+    let optionality = child.isOptional ? "?" : ""
+    switch child.kind {
+    case .node(let kind):
+      return "``\(kind.syntaxType)``\(optionality)"
+    case .nodeChoices(let choices):
+      let choicesDescriptions = choices.map { grammar(for: $0) }
+      return "(\(choicesDescriptions.joined(separator: " | ")))\(optionality)"
+    case .collection(let kind, _, _):
+      return "``\(kind.syntaxType)``"
+    case .token(let choices, _, _):
+      if choices.count == 1 {
+        return "\(grammar(for: choices.first!))\(optionality)"
+      } else {
+        let choicesDescriptions = choices.map { grammar(for: $0) }
+        return "(\(choicesDescriptions.joined(separator: " | ")))\(optionality)"
+      }
+    }
+  }
+
+  /// Generates a markdown list containing the children’s names and their
+  /// grammar.
+  ///
+  /// - Parameter children: The children to show in the list
+  static func childrenList(for children: [Child]) -> String {
+    let generator = GrammarGenerator()
+    return
+      children
+      .filter { !$0.isUnexpectedNodes }
+      .map { " - `\($0.varName)`: \(generator.grammar(for: $0))" }
+      .joined(separator: "\n")
+  }
+}

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -220,6 +220,20 @@ public struct LayoutNode {
       preconditionFailure("NodeLayoutView must wrap a Node with data `.layout`")
     }
   }
+
+  public var grammar: SwiftSyntax.Trivia {
+    guard !children.isEmpty else {
+      return []
+    }
+
+    return docCommentTrivia(
+      from: """
+        ### Children
+
+        \(GrammarGenerator.childrenList(for: children))
+        """
+    )
+  }
 }
 
 /// Provides a view into a collection node that offers access to the

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SyntaxNodesFile.swift

@@ -40,6 +40,8 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
         // MARK: - \(raw: node.kind.syntaxType)
 
         \(raw: node.documentation)
+        \(raw: node.documentation.isEmpty ? "" : "///")
+        \(raw: node.grammar)
         public struct \(raw: node.kind.syntaxType): \(raw: node.baseType.syntaxBaseName)Protocol, SyntaxHashable
         """
       ) {