Merge pull request swiftlang#1527 from ahoppen/ahoppen/documentation-for-initializer

Add documentation for `InitializerDeclSyntax` and all its children

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -1024,6 +1024,16 @@ public let DECL_NODES: [Node] = [
   Node(
     name: "InitializerDecl",
     nameForDiagnostics: "initializer",
+    description: """
+      An initializer declaration like the following.
+
+      ```swift
+      init(someParameter: Int) {
+      }
+      ```
+
+      The body is optional because this node also represents initializer requirements inside protocols.
+      """,
     kind: "Decl",
     traits: [
       "Attributed"
@@ -1033,43 +1043,51 @@ public let DECL_NODES: [Node] = [
         name: "Attributes",
         kind: .collection(kind: "AttributeList", collectionElementName: "Attribute"),
         nameForDiagnostics: "attributes",
+        description: "Attributes that are attached to the initializer.",
         isOptional: true
       ),
       Child(
         name: "Modifiers",
         kind: .collection(kind: "ModifierList", collectionElementName: "Modifier"),
         nameForDiagnostics: "modifiers",
+        description: "Modifiers attached to the initializer",
         isOptional: true
       ),
       Child(
         name: "InitKeyword",
-        kind: .token(choices: [.keyword(text: "init")])
+        kind: .token(choices: [.keyword(text: "init")]),
+        description: "The init keyword"
       ),
       Child(
         name: "OptionalMark",
         kind: .token(choices: [.token(tokenKind: "PostfixQuestionMarkToken"), .token(tokenKind: "InfixQuestionMarkToken"), .token(tokenKind: "ExclamationMarkToken")]),
+        description: "If the initializer is failable, a question mark to indicate that.",
         isOptional: true
       ),
       Child(
         name: "GenericParameterClause",
         kind: .node(kind: "GenericParameterClause"),
         nameForDiagnostics: "generic parameter clause",
+        description: "Generic parameters of the initializer.",
         isOptional: true
       ),
       Child(
         name: "Signature",
         kind: .node(kind: "FunctionSignature"),
-        nameForDiagnostics: "function signature"
+        nameForDiagnostics: "function signature",
+        description: "The arguments of the initializer. While the function signature allows specifying an return clause, doing so is not semantically valid."
       ),
       Child(
         name: "GenericWhereClause",
         kind: .node(kind: "GenericWhereClause"),
         nameForDiagnostics: "generic where clause",
+        description: "If the initializer had generic parameters, a where clause that can restrict those",
         isOptional: true
       ),
       Child(
         name: "Body",
         kind: .node(kind: "CodeBlock"),
+        description: "The initializer’s body. Missing if the initialier is a requirement of a protocol declaration.",
         isOptional: true
       ),
     ]

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

@@ -23,7 +23,7 @@ func syntaxNode(emitKind: String) -> SourceFileSyntax {
   SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where !node.isBase && node.collectionElement.isEmpty && node.baseKind == emitKind {
       // We are actually handling this node now
-      let nodeDoc = node.description.map { "/// \($0)" }
+      let nodeDoc = node.description?.split(separator: "\n", omittingEmptySubsequences: false).map { "/// \($0)" }.joined(separator: "\n")
       try! StructDeclSyntax(
         """
         // MARK: - \(raw: node.name)

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntaxbuilder/BuildableNodesFile.swift

@@ -22,9 +22,9 @@ let buildableNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     let type = node.type
 
     if let convenienceInit = try! createConvenienceInitializer(node: node) {
-      let docComment: SwiftSyntax.Trivia = node.documentation.isEmpty ? [] : .docLineComment("/// \(node.documentation)") + .newline
+      let docComment = node.description?.split(separator: "\n", omittingEmptySubsequences: false).map { "/// \($0)" }.joined(separator: "\n") ?? ""
       ExtensionDeclSyntax(
-        leadingTrivia: docComment,
+        leadingTrivia: "\(docComment)\n",
         extendedType: SimpleTypeIdentifierSyntax(name: .identifier(type.syntaxBaseName))
       ) {
         convenienceInit

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxDeclNodes.swift

@@ -3187,7 +3187,14 @@ extension ImportDeclSyntax: CustomReflectable {
 
 // MARK: - InitializerDeclSyntax
 
-
+/// An initializer declaration like the following.
+/// 
+/// ```swift
+/// init(someParameter: Int) {
+/// }
+/// ```
+/// 
+/// The body is optional because this node also represents initializer requirements inside protocols.
 public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
 
@@ -3289,6 +3296,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// Attributes that are attached to the initializer.
   public var attributes: AttributeListSyntax? {
     get {
       return data.child(at: 1, parent: Syntax(self)).map(AttributeListSyntax.init)
@@ -3326,6 +3334,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// Modifiers attached to the initializer
   public var modifiers: ModifierListSyntax? {
     get {
       return data.child(at: 3, parent: Syntax(self)).map(ModifierListSyntax.init)
@@ -3363,6 +3372,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The init keyword
   public var initKeyword: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 5, parent: Syntax(self))!)
@@ -3381,6 +3391,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// If the initializer is failable, a question mark to indicate that.
   public var optionalMark: TokenSyntax? {
     get {
       return data.child(at: 7, parent: Syntax(self)).map(TokenSyntax.init)
@@ -3399,6 +3410,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// Generic parameters of the initializer.
   public var genericParameterClause: GenericParameterClauseSyntax? {
     get {
       return data.child(at: 9, parent: Syntax(self)).map(GenericParameterClauseSyntax.init)
@@ -3417,6 +3429,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The arguments of the initializer. While the function signature allows specifying an return clause, doing so is not semantically valid.
   public var signature: FunctionSignatureSyntax {
     get {
       return FunctionSignatureSyntax(data.child(at: 11, parent: Syntax(self))!)
@@ -3435,6 +3448,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// If the initializer had generic parameters, a where clause that can restrict those
   public var genericWhereClause: GenericWhereClauseSyntax? {
     get {
       return data.child(at: 13, parent: Syntax(self)).map(GenericWhereClauseSyntax.init)
@@ -3453,6 +3467,7 @@ public struct InitializerDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The initializer’s body. Missing if the initialier is a requirement of a protocol declaration.
   public var body: CodeBlockSyntax? {
     get {
       return data.child(at: 15, parent: Syntax(self)).map(CodeBlockSyntax.init)

Sources/SwiftSyntaxBuilder/generated/BuildableNodes.swift

@@ -819,6 +819,14 @@ extension IfExprSyntax {
   }
 }
 
+/// An initializer declaration like the following.
+/// 
+/// ```swift
+/// init(someParameter: Int) {
+/// }
+/// ```
+/// 
+/// The body is optional because this node also represents initializer requirements inside protocols.
 extension InitializerDeclSyntax {
   /// A convenience initializer that allows initializing syntax collections using result builders
   public init(