Merge pull request #1902 from ahoppen/ahoppen/children-of-collections

Add `Children` section to `SyntaxCollection` nodes

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -270,4 +270,21 @@ public struct CollectionNode {
       return choices
     }
   }
+
+  public var grammar: SwiftSyntax.Trivia {
+    let grammar: String
+    if let onlyElement = elementChoices.only {
+      grammar = "``\(onlyElement.syntaxType)`` `*`"
+    } else {
+      grammar = "(\(elementChoices.map { "``\($0.syntaxType)``" }.joined(separator: " | "))) `*`"
+    }
+
+    return docCommentTrivia(
+      from: """
+        ### Children
+
+        \(grammar)
+        """
+    )
+  }
 }

CodeGeneration/Sources/SyntaxSupport/Utils.swift

@@ -54,3 +54,14 @@ public func docCommentTrivia(from string: String?) -> SwiftSyntax.Trivia {
   }
   return SwiftSyntax.Trivia(pieces: pieces)
 }
+
+public extension Collection {
+  /// If the collection contains a single element, return it, otherwise `nil`.
+  var only: Element? {
+    if !isEmpty && index(after: startIndex) == endIndex {
+      return self.first!
+    } else {
+      return nil
+    }
+  }
+}

CodeGeneration/Sources/Utils/Utils.swift

@@ -10,39 +10,21 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Trims leading and trailing whitespace from each line.
-public func dedented<Lines: Sequence>(lines: Lines) -> [String] where Lines.Element: StringProtocol {
-  lines.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
-}
-
-/// Trims leading and trailing whitespace from each line.
-public func dedented(string: String) -> String {
-  dedented(lines: string.split(separator: "\n"))
-    .joined(separator: "\n")
-}
-
-/// Creates a single-line documentation string from indented
-/// documentation as written in `CodeGeneration`.
-public func flattened(indentedDocumentation: String) -> String {
-  dedented(string: indentedDocumentation)
-    .replacingOccurrences(of: "\n", with: "")
-    .trimmingCharacters(in: .whitespacesAndNewlines)
-}
-
-/// Removes all empty lines from a multi-line string.
-public func removedEmptyLines(string: String) -> String {
-  string.split(whereSeparator: \.isNewline)
-    .filter { !$0.allSatisfy(\.isWhitespace) }
-    .joined(separator: "\n")
-}
+extension String {
+  /// Creates a single-line documentation string from indented
+  /// documentation as written in `CodeGeneration`.
+  public var flattened: String {
+    self
+      .replacingOccurrences(of: "\n", with: "")
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+  }
 
-public extension Collection {
-  /// If the collection contains a single element, return it, otherwise `nil`.
-  var only: Element? {
-    if !isEmpty && index(after: startIndex) == endIndex {
-      return self.first!
-    } else {
-      return nil
-    }
+  /// Removes all empty lines from a multi-line string.
+  public var removingEmptyLines: String {
+    return
+      self
+      .split(whereSeparator: \.isNewline)
+      .filter { !$0.allSatisfy(\.isWhitespace) }
+      .joined(separator: "\n")
   }
 }

CodeGeneration/Sources/generate-swiftsyntax/LayoutNode+Extensions.swift

@@ -86,16 +86,14 @@ extension LayoutNode {
       return "  - \(child.varName): \(firstLine)"
     }
 
-    let formattedParams = removedEmptyLines(
-      string: """
-        - Parameters:
-          - leadingTrivia: Trivia to be prepended to the leading trivia of the node’s first token. \
-        If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
-        \(children.compactMap(generateParamDocComment).joined(separator: "\n"))
-          - trailingTrivia: Trivia to be appended to the trailing trivia of the node’s last token. \
-        If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
-        """
-    )
+    let formattedParams = """
+      - Parameters:
+        - leadingTrivia: Trivia to be prepended to the leading trivia of the node’s first token. \
+      If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
+      \(children.compactMap(generateParamDocComment).joined(separator: "\n"))
+        - trailingTrivia: Trivia to be appended to the trailing trivia of the node’s last token. \
+      If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
+      """.removingEmptyLines
 
     return docCommentTrivia(from: formattedParams)
   }

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

@@ -17,10 +17,16 @@ import Utils
 
 let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
   for node in SYNTAX_NODES.compactMap(\.collectionNode) {
+    let documentation = """
+      \(node.documentation)
+      \(node.documentation.isEmpty ? "" : "///")
+      \(node.grammar)
+      """.removingEmptyLines
+
     try! StructDeclSyntax(
       """
-      \(raw: node.documentation)
-      public struct \(raw: node.kind.syntaxType): SyntaxCollection, SyntaxHashable
+      \(raw: documentation)
+      public struct \(node.kind.syntaxType): SyntaxCollection, SyntaxHashable
       """
     ) {
       if let onlyElement = node.elementChoices.only {

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

@@ -20,8 +20,7 @@ extension Child {
     guard let description = documentation else {
       return []
     }
-    let dedented = dedented(string: description)
-    let lines = dedented.split(separator: "\n", omittingEmptySubsequences: false)
+    let lines = description.split(separator: "\n", omittingEmptySubsequences: false)
     let pieces = lines.map { SwiftSyntax.TriviaPiece.docLineComment("/// \($0)") }
     return Trivia(pieces: pieces)
   }
@@ -34,14 +33,18 @@ extension Child {
 func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
   SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES.compactMap(\.layoutNode) where node.base == emitKind {
+      let documentation = """
+        \(node.documentation)
+        \(node.documentation.isEmpty ? "" : "///")
+        \(node.grammar)
+        """.removingEmptyLines
+
       // We are actually handling this node now
       try! StructDeclSyntax(
         """
         // MARK: - \(raw: node.kind.syntaxType)
 
-        \(raw: node.documentation)
-        \(raw: node.documentation.isEmpty ? "" : "///")
-        \(raw: node.grammar)
+        \(raw: documentation)
         public struct \(raw: node.kind.syntaxType): \(raw: node.baseType.syntaxBaseName)Protocol, SyntaxHashable
         """
       ) {