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))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxTypeNodes.swift

@@ -1550,7 +1550,7 @@ public struct MissingTypeSyntax: TypeSyntaxProtocol, SyntaxHashable {
 
   /// - 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.
-  ///   - placeholder: 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`.
+  ///   - placeholder: A placeholder, i.e. `<#type#>`, that can be inserted into the source code to represent the missing type.
   ///   - 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.
   public init(
       leadingTrivia: Trivia? = nil,
@@ -1586,7 +1586,9 @@ public struct MissingTypeSyntax: TypeSyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// 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`.
   public var placeholder: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 1, parent: Syntax(self))!)