Generate grammar doc comments for layout nodes

Generate a `Grammar` and a `Children` section as doc-comments for layout nodes.

The `Grammar` section is particularly useful for fairly simple syntax nodes to convey their structure. The `Children` section allows you to see the children of the syntax node at a glance in the source order.

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -0,0 +1,82 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 {
+  let lookThroughCollections: Bool
+
+  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, _):
+      if lookThroughCollections {
+        let collectionElementTypes = SYNTAX_NODE_MAP[kind]!.collectionNode!.elementChoices
+        if collectionElementTypes.count == 1 {
+          return "``\(collectionElementTypes.first!.syntaxType)`` `*`"
+        } else {
+          let choicesDescriptions = collectionElementTypes.map { "``\($0.syntaxType)``" }
+          return "(\(choicesDescriptions.joined(separator: " | "))) `*`"
+        }
+      } else {
+        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 single line grammar for a syntax node.
+  static func grammar(for children: [Child]) -> String {
+    let generator = GrammarGenerator(lookThroughCollections: true)
+    return
+      children
+      .filter { !$0.isUnexpectedNodes }
+      .map { generator.grammar(for: $0) }
+      .joined(separator: "\n")
+  }
+
+  /// Generates a
+  static func childrenList(for children: [Child]) -> String {
+    let generator = GrammarGenerator(lookThroughCollections: false)
+    return
+      children
+      .filter { !$0.isUnexpectedNodes }
+      .map { " - `\($0.varName)`: \(generator.grammar(for: $0))" }
+      .joined(separator: "\n")
+  }
+}

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -208,6 +208,24 @@ 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: """
+        ### Grammar
+
+        \(GrammarGenerator.grammar(for: children))
+
+        ### 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
         """
       ) {