Add documentation on pattern bindings

Another area that’s not super obvious. Add some documentation that hopefully sheds some light into why pattern bindings exist and what thye do.

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -1619,29 +1619,56 @@ public let DECL_NODES: [Node] = [
     kind: .patternBinding,
     base: .syntax,
     nameForDiagnostics: nil,
+    documentation: """
+      Defines variables inside a variable declaration.
+      """,
     traits: [
       "WithTrailingComma"
     ],
     children: [
       Child(
         name: "Pattern",
-        kind: .node(kind: .pattern)
+        kind: .node(kind: .pattern),
+        documentation: """
+          The pattern that defines the variables.
+
+          In simple variable declarations this is an ``IdentifierPatternSyntax``, which defines
+          the name of a single variable.
+
+          In more complex variable declaration, this can, for example, be a ``TuplePatternSyntax``
+          that destructures a tuple.
+
+          ```swift
+          let (x, y) = (1, 2)
+          ```
+          """
       ),
       Child(
         name: "TypeAnnotation",
         kind: .node(kind: .typeAnnotation),
         nameForDiagnostics: "type annotation",
+        documentation: """
+          The type of the variables defined by the pattern.
+
+          Can be omitted, in which case the variables’ types are inferred from the initializer.
+          """,
         isOptional: true
       ),
       Child(
         name: "Initializer",
         kind: .node(kind: .initializerClause),
+        documentation: """
+          If the variables have a default value, the clause that initializes them.
+          """,
         isOptional: true
       ),
       Child(
         name: "AccessorBlock",
         deprecatedName: "Accessor",
         kind: .node(kind: .accessorBlock),
+        documentation: """
+          If the variable is computed, the accessors that get (and optionally set) the value.
+          """,
         isOptional: true
       ),
       Child(
@@ -2296,6 +2323,12 @@ public let DECL_NODES: [Node] = [
     kind: .variableDecl,
     base: .decl,
     nameForDiagnostics: "variable",
+    documentation: """
+      Declaration of one or more variables
+
+      The core of a variable declaration consists of a binding specifier (`let` or `var),
+      followed by any number of pattern bindings, which define the variables.
+      """,
     traits: [
       "WithAttributes",
       "WithModifiers",
@@ -2316,13 +2349,28 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "BindingSpecifier",
         deprecatedName: "BindingKeyword",
-        kind: .token(choices: [.keyword(text: "let"), .keyword(text: "var"), .keyword(text: "inout")])
+        kind: .token(choices: [.keyword(text: "let"), .keyword(text: "var"), .keyword(text: "inout")]),
+        documentation: """
+          The specifier that defines the type of the variables declared (`let` or `var`).
+          """
       ),
       Child(
         name: "Bindings",
-        kind: .collection(kind: .patternBindingList, collectionElementName: "Binding")
+        kind: .collection(kind: .patternBindingList, collectionElementName: "Binding"),
+        documentation: """
+          The pattern bindings that define the actual variables.
+
+          The pattern bindings contain the declared variables’ names, their types,
+          initializers and accessors.
+
+          A variable declaration can contain multiple pattern bindings, because it’s possible
+          to define multiple variables after a single `let` keyword as follows.
+
+          ```swift
+          let x: Int = 1, y: Int = 2
+          ```
+          """
       ),
     ]
   ),
-
 ]

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxDeclNodes.swift

@@ -6969,6 +6969,11 @@ public struct TypeAliasDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
 
 // MARK: - VariableDeclSyntax
 
+/// Declaration of one or more variables
+/// 
+/// The core of a variable declaration consists of a binding specifier (`let` or `var),
+/// followed by any number of pattern bindings, which define the variables.
+///
 /// ### Children
 /// 
 ///  - `attributes`: ``AttributeListSyntax``
@@ -6995,6 +7000,8 @@ public struct VariableDeclSyntax: DeclSyntaxProtocol, 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.
+  ///   - bindingSpecifier: The specifier that defines the type of the variables declared (`let` or `var`).
+  ///   - bindings: The pattern bindings that define the actual variables.
   ///   - 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,
@@ -7142,6 +7149,7 @@ public struct VariableDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The specifier that defines the type of the variables declared (`let` or `var`).
   public var bindingSpecifier: TokenSyntax {
     get {
       return TokenSyntax(data.child(at: 5, parent: Syntax(self))!)
@@ -7160,6 +7168,17 @@ public struct VariableDeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The pattern bindings that define the actual variables.
+  /// 
+  /// The pattern bindings contain the declared variables’ names, their types,
+  /// initializers and accessors.
+  /// 
+  /// A variable declaration can contain multiple pattern bindings, because it’s possible
+  /// to define multiple variables after a single `let` keyword as follows.
+  /// 
+  /// ```swift
+  /// let x: Int = 1, y: Int = 2
+  /// ```
   public var bindings: PatternBindingListSyntax {
     get {
       return PatternBindingListSyntax(data.child(at: 7, parent: Syntax(self))!)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodes.swift

@@ -14112,6 +14112,8 @@ public struct OriginallyDefinedInAttributeArgumentsSyntax: SyntaxProtocol, Synta
 
 // MARK: - PatternBindingSyntax
 
+/// Defines variables inside a variable declaration.
+///
 /// ### Children
 /// 
 ///  - `pattern`: ``PatternSyntax``
@@ -14143,6 +14145,10 @@ public struct PatternBindingSyntax: SyntaxProtocol, 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.
+  ///   - pattern: The pattern that defines the variables.
+  ///   - typeAnnotation: The type of the variables defined by the pattern.
+  ///   - initializer: If the variables have a default value, the clause that initializes them.
+  ///   - accessorBlock: If the variable is computed, the accessors that get (and optionally set) the value.
   ///   - 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,
@@ -14210,6 +14216,17 @@ public struct PatternBindingSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The pattern that defines the variables.
+  /// 
+  /// In simple variable declarations this is an ``IdentifierPatternSyntax``, which defines
+  /// the name of a single variable.
+  /// 
+  /// In more complex variable declaration, this can, for example, be a ``TuplePatternSyntax``
+  /// that destructures a tuple.
+  /// 
+  /// ```swift
+  /// let (x, y) = (1, 2)
+  /// ```
   public var pattern: PatternSyntax {
     get {
       return PatternSyntax(data.child(at: 1, parent: Syntax(self))!)
@@ -14228,6 +14245,9 @@ public struct PatternBindingSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The type of the variables defined by the pattern.
+  /// 
+  /// Can be omitted, in which case the variables’ types are inferred from the initializer.
   public var typeAnnotation: TypeAnnotationSyntax? {
     get {
       return data.child(at: 3, parent: Syntax(self)).map(TypeAnnotationSyntax.init)
@@ -14246,6 +14266,7 @@ public struct PatternBindingSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// If the variables have a default value, the clause that initializes them.
   public var initializer: InitializerClauseSyntax? {
     get {
       return data.child(at: 5, parent: Syntax(self)).map(InitializerClauseSyntax.init)
@@ -14264,6 +14285,7 @@ public struct PatternBindingSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// If the variable is computed, the accessors that get (and optionally set) the value.
   public var accessorBlock: AccessorBlockSyntax? {
     get {
       return data.child(at: 7, parent: Syntax(self)).map(AccessorBlockSyntax.init)