Merge pull request #2035 from ahoppen/ahoppen/binding-documentation

Add documentation on pattern bindings

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/AttributeNodes.swift

@@ -153,7 +153,12 @@ public let ATTRIBUTE_NODES: [Node] = [
             kind: .node(kind: .documentationAttributeArgumentList)
           ),
         ]),
-        documentation: "The arguments of the attribute. In case the attribute takes multiple arguments, they are gather in the appropriate takes first.",
+        documentation: """
+          The arguments of the attribute.
+
+          In case of user-defined attributes, such as macros, property wrappers or result builders,
+          this is always either an `argumentList` of type ``LabeledExprListSyntax`` or `nil`.
+          """,
         isOptional: true
       ),
       Child(

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, for example
+
+          ```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, for example
+  /// 
+  /// ```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

@@ -913,7 +913,7 @@ public struct AttributeSyntax: SyntaxProtocol, SyntaxHashable {
   ///   - atSign: The `@` sign.
   ///   - attributeName: The name of the attribute.
   ///   - leftParen: If the attribute takes arguments, the opening parenthesis.
-  ///   - arguments: The arguments of the attribute. In case the attribute takes multiple arguments, they are gather in the appropriate takes first.
+  ///   - arguments: The arguments of the attribute.
   ///   - rightParen: If the attribute takes arguments, the closing parenthesis.
   ///   - 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(
@@ -1039,7 +1039,10 @@ public struct AttributeSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
-  /// The arguments of the attribute. In case the attribute takes multiple arguments, they are gather in the appropriate takes first.
+  /// The arguments of the attribute.
+  /// 
+  /// In case of user-defined attributes, such as macros, property wrappers or result builders,
+  /// this is always either an `argumentList` of type ``LabeledExprListSyntax`` or `nil`.
   public var arguments: Arguments? {
     get {
       return data.child(at: 7, parent: Syntax(self)).map(Arguments.init)
@@ -14112,6 +14115,8 @@ public struct OriginallyDefinedInAttributeArgumentsSyntax: SyntaxProtocol, Synta
 
 // MARK: - PatternBindingSyntax
 
+/// Defines variables inside a variable declaration.
+///
 /// ### Children
 /// 
 ///  - `pattern`: ``PatternSyntax``
@@ -14143,6 +14148,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 +14219,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 +14248,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 +14269,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 +14288,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)