Change type of Child.documentation to Trivia

This also fixes a bug that caused multi-line documentation of children to be rendered incorrectly

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/Child.swift

@@ -58,15 +58,41 @@ public enum ChildKind {
 /// A child of a node, that may be declared optional or a token with a
 /// restricted subset of acceptable kinds or texts.
 public class Child {
+  /// The name of the child.
+  ///
+  /// The first character of the name is always uppercase.
   public let name: String
+
+  /// If the child has been renamed, its old, now deprecated, name.
+  ///
+  /// This is used to generate deprecated compatibility layers.
   public let deprecatedName: String?
+
+  /// The kind of the child (node, token, collection, ...)
   public let kind: ChildKind
+
+  /// Whether this child is optional and can be `nil`.
+  public let isOptional: Bool
+
+  /// A name of this child that can be shown in diagnostics.
+  ///
+  /// This is used to e.g. describe the child if all of its tokens are missing in the source file.
   public let nameForDiagnostics: String?
-  public let documentation: String?
+
+  /// A doc comment describing the child.
+  public let documentation: SwiftSyntax.Trivia
+
+  /// The first line of the child's documentation
+  public let documentationAbstract: String
+
+  /// If not `nil`, identifiers within this child will be syntax highlighted with this classification.
+  public let classification: SyntaxClassification?
+
+  /// When `true`, `classification` not only applies to identifiers but also overrides the classifcation of keywords.
   public let forceClassification: Bool
+
+  /// Whether the elements in this child should be indented by another indentation level.
   public let isIndented: Bool
-  public let isOptional: Bool
-  public let classification: SyntaxClassification?
 
   public var syntaxNodeKind: SyntaxNodeKind {
     switch kind {
@@ -151,12 +177,6 @@ public class Child {
     }
   }
 
-  /// Returns `true` if this child's type is one of the base syntax kinds and
-  /// it's optional.
-  public var hasOptionalBaseType: Bool {
-    return hasBaseType && isOptional
-  }
-
   /// If a classification is passed, it specifies the color identifiers in
   /// that subtree should inherit for syntax coloring. Must be a member of
   /// ``SyntaxClassification``.
@@ -180,7 +200,8 @@ public class Child {
     self.deprecatedName = deprecatedName
     self.kind = kind
     self.nameForDiagnostics = nameForDiagnostics
-    self.documentation = documentation
+    self.documentation = docCommentTrivia(from: documentation)
+    self.documentationAbstract = String(documentation?.split(whereSeparator: \.isNewline).first ?? "")
     self.classification = classificationByName(classification)
     self.forceClassification = forceClassification
     self.isIndented = isIndented

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -182,6 +182,7 @@ public let COMMON_NODES: [Node] = [
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
           A placeholder, i.e. `<#decl#>`, that can be inserted into the source code to represent the missing declaration.
+
           This token should always have `presence = .missing`.
           """
       ),
@@ -202,6 +203,7 @@ public let COMMON_NODES: [Node] = [
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
           A placeholder, i.e. `<#expression#>`, that can be inserted into the source code to represent the missing expression.
+
           This token should always have `presence = .missing`.
           """
       )
@@ -222,6 +224,7 @@ public let COMMON_NODES: [Node] = [
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
           A placeholder, i.e. `<#pattern#>`, that can be inserted into the source code to represent the missing pattern.
+
           This token should always have `presence = .missing`.
           """
       )
@@ -242,6 +245,7 @@ public let COMMON_NODES: [Node] = [
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
           A placeholder, i.e. `<#statement#>`, that can be inserted into the source code to represent the missing pattern.
+
           This token should always have `presence = .missing`.
           """
       )
@@ -262,6 +266,7 @@ public let COMMON_NODES: [Node] = [
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
           A placeholder, i.e. `<#syntax#>`, that can be inserted into the source code to represent the missing pattern.
+
           This token should always have `presence = .missing`
           """
       )
@@ -281,7 +286,9 @@ public let COMMON_NODES: [Node] = [
         name: "Placeholder",
         kind: .token(choices: [.token(tokenKind: "IdentifierToken")], requiresLeadingSpace: false, requiresTrailingSpace: false),
         documentation: """
-          A placeholder, i.e. `<#type#>`, that can be inserted into the source code to represent the missing type. This token should always have `presence = .missing`.
+          A placeholder, i.e. `<#type#>`, that can be inserted into the source code to represent the missing type.
+
+          This token should always have `presence = .missing`.
           """
       )
     ]

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

@@ -77,13 +77,10 @@ extension LayoutNode {
 
   func generateInitializerDocComment() -> SwiftSyntax.Trivia {
     func generateParamDocComment(for child: Child) -> String? {
-      guard let documentation = child.documentation,
-        let firstLine = documentation.split(whereSeparator: \.isNewline).first
-      else {
+      if child.documentationAbstract.isEmpty {
         return nil
       }
-
-      return "  - \(child.varOrCaseName): \(firstLine)"
+      return "  - \(child.varOrCaseName): \(child.documentationAbstract)"
     }
 
     let formattedParams = """

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

@@ -15,17 +15,6 @@ import SwiftSyntaxBuilder
 import SyntaxSupport
 import Utils
 
-extension Child {
-  public var docComment: SwiftSyntax.Trivia {
-    guard let description = documentation else {
-      return []
-    }
-    let lines = description.split(separator: "\n", omittingEmptySubsequences: false)
-    let pieces = lines.map { SwiftSyntax.TriviaPiece.docLineComment("/// \($0)") }
-    return Trivia(pieces: pieces)
-  }
-}
-
 /// This file generates the syntax nodes for SwiftSyntax. To keep the generated
 /// files at a manageable file size, it is to be invoked multiple times with the
 /// variable `emitKind` set to a base kind listed in
@@ -168,7 +157,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
 
           try! VariableDeclSyntax(
             """
-            \(raw: child.docComment)
+            \(raw: child.documentation)
             public var \(child.varOrCaseName.backtickedIfNeeded): \(type)
             """
           ) {

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

@@ -28,7 +28,7 @@ let syntaxTraitsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       for child in trait.children {
         DeclSyntax(
           """
-          \(raw: child.docComment)
+          \(raw: child.documentation)
           var \(child.varOrCaseName): \(child.syntaxNodeKind.syntaxType)\(raw: child.isOptional ? "?" : "") { get set }
           """
         )

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxDeclNodes.swift

@@ -4803,7 +4803,9 @@ public struct MissingDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// A placeholder, i.e. `<#decl#>`, that can be inserted into the source code to represent the missing declaration./// This token should always have `presence = .missing`.
+  /// A placeholder, i.e. `<#decl#>`, that can be inserted into the source code to represent the missing declaration.
+  /// 
+  /// This token should always have `presence = .missing`.
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 5, parent: Syntax(self))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxExprNodes.swift

@@ -4171,7 +4171,9 @@ public struct MissingExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// A placeholder, i.e. `<#expression#>`, that can be inserted into the source code to represent the missing expression./// This token should always have `presence = .missing`.
+  /// A placeholder, i.e. `<#expression#>`, that can be inserted into the source code to represent the missing expression.
+  /// 
+  /// This token should always have `presence = .missing`.
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 1, parent: Syntax(self))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodes.swift

@@ -13475,7 +13475,9 @@ public struct MissingSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// A placeholder, i.e. `<#syntax#>`, that can be inserted into the source code to represent the missing pattern./// This token should always have `presence = .missing`
+  /// A placeholder, i.e. `<#syntax#>`, that can be inserted into the source code to represent the missing pattern.
+  /// 
+  /// This token should always have `presence = .missing`
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 1, parent: Syntax(self))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxPatternNodes.swift

@@ -363,7 +363,9 @@ public struct MissingPatternSyntax: PatternSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// A placeholder, i.e. `<#pattern#>`, that can be inserted into the source code to represent the missing pattern./// This token should always have `presence = .missing`.
+  /// A placeholder, i.e. `<#pattern#>`, that can be inserted into the source code to represent the missing pattern.
+  /// 
+  /// This token should always have `presence = .missing`.
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 1, parent: Syntax(self))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxStmtNodes.swift

@@ -1589,7 +1589,9 @@ public struct MissingStmtSyntax: StmtSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// A placeholder, i.e. `<#statement#>`, that can be inserted into the source code to represent the missing pattern./// This token should always have `presence = .missing`.
+  /// A placeholder, i.e. `<#statement#>`, that can be inserted into the source code to represent the missing pattern.
+  /// 
+  /// This token should always have `presence = .missing`.
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 1, parent: Syntax(self))!)