Add more documentation do Syntax nodes

Author: kimdv

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -66,7 +66,8 @@ public let COMMON_NODES: [Node] = [
     children: [
       Child(
         name: "leftBrace",
-        kind: .token(choices: [.token(.leftBrace)])
+        kind: .token(choices: [.token(.leftBrace)]),
+        documentation: "The brace introducing the code block."
       ),
       Child(
         name: "statements",
@@ -75,7 +76,8 @@ public let COMMON_NODES: [Node] = [
       ),
       Child(
         name: "rightBrace",
-        kind: .token(choices: [.token(.rightBrace)])
+        kind: .token(choices: [.token(.rightBrace)]),
+        documentation: "The brace closing the code block."
       ),
     ]
   ),
@@ -92,11 +94,13 @@ public let COMMON_NODES: [Node] = [
       Child(
         name: "asyncSpecifier",
         kind: .token(choices: [.keyword(.async)]),
+        documentation: "The `async` keyword.",
         isOptional: true
       ),
       Child(
         name: "throwsSpecifier",
         kind: .token(choices: [.keyword(.throws)]),
+        documentation: "The `throws` keyword.",
         isOptional: true
       ),
     ]
@@ -114,11 +118,13 @@ public let COMMON_NODES: [Node] = [
       Child(
         name: "asyncSpecifier",
         kind: .token(choices: [.keyword(.async), .keyword(.reasync)]),
+        documentation: "The `async` or `reasync` keyword.",
         isOptional: true
       ),
       Child(
         name: "throwsSpecifier",
         kind: .token(choices: [.keyword(.throws), .keyword(.rethrows)]),
+        documentation: "The `throws` or `rethrows` keyword.",
         isOptional: true
       ),
     ]
@@ -134,6 +140,7 @@ public let COMMON_NODES: [Node] = [
       Child(
         name: "asyncSpecifier",
         kind: .token(choices: [.keyword(.async)]),
+        documentation: "The `async` keyword.",
         isOptional: true
       )
     ]

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -53,7 +53,8 @@ public let DECL_NODES: [Node] = [
     children: [
       Child(
         name: "leftBrace",
-        kind: .token(choices: [.token(.leftBrace)])
+        kind: .token(choices: [.token(.leftBrace)]),
+        documentation: "The brace introducing the accessor block."
       ),
       Child(
         name: "accessors",
@@ -70,7 +71,8 @@ public let DECL_NODES: [Node] = [
       ),
       Child(
         name: "rightBrace",
-        kind: .token(choices: [.token(.rightBrace)])
+        kind: .token(choices: [.token(.rightBrace)]),
+        documentation: "The brace closing the accessor block."
       ),
     ]
   ),
@@ -191,16 +193,19 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
-        nameForDiagnostics: "modifiers"
+        nameForDiagnostics: "modifiers",
+        documentation: "Modifiers like `public` that are attached to the actor declaration."
       ),
       Child(
         name: "actorKeyword",
-        kind: .token(choices: [.keyword(.actor)])
+        kind: .token(choices: [.keyword(.actor)]),
+        documentation: "The `actor` keyword."
       ),
       Child(
         name: "name",
         deprecatedName: "identifier",
-        kind: .token(choices: [.token(.identifier)])
+        kind: .token(choices: [.token(.identifier)]),
+        documentation: "The name of the actor. If the name matches a reserved keyword use backticks to escape it."
       ),
       Child(
         name: "genericParameterClause",
@@ -281,7 +286,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers attached to the associated type declaration."
+        documentation: "Modifiers like `public` that are attached to the associated type declaration."
       ),
       Child(
         name: "associatedtypeKeyword",
@@ -371,7 +376,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers attached to the class declaration, such as `public`."
+        documentation: "Modifiers like `public` that are attached to the class declaration."
       ),
       Child(
         name: "classKeyword",
@@ -519,7 +524,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers that are attached to the deinitializer."
+        documentation: "Modifiers like `public` that are attached to the deinitializer."
       ),
       Child(
         name: "deinitKeyword",
@@ -857,7 +862,8 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
-        nameForDiagnostics: "modifiers"
+        nameForDiagnostics: "modifiers",
+        documentation: "Modifiers like `public` that are attached to the extension declaration."
       ),
       Child(
         name: "extensionKeyword",
@@ -906,7 +912,8 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
-        nameForDiagnostics: "modifiers"
+        nameForDiagnostics: "modifiers",
+        documentation: "Modifiers like `public` that are attached to the function declaration."
       ),
       Child(
         name: "funcKeyword",
@@ -1142,7 +1149,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers attached to the import declaration. Currently, no modifiers are supported by Swift."
+        documentation: "Modifiers that are attached to the import declaration. Currently, no modifiers are supported by Swift."
       ),
       Child(
         name: "importKeyword",
@@ -1256,7 +1263,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers attached to the initializer"
+        documentation: "Modifiers that are attached to the initializer declaration."
       ),
       Child(
         name: "initKeyword",
@@ -1289,7 +1296,7 @@ public let DECL_NODES: [Node] = [
         name: "genericWhereClause",
         kind: .node(kind: .genericWhereClause),
         nameForDiagnostics: "generic where clause",
-        documentation: "If the initializer had generic parameters, a where clause that can restrict those",
+        documentation: "If the initializer had generic parameters, a where clause that can restrict those.",
         isOptional: true
       ),
       Child(
@@ -2110,7 +2117,7 @@ public let DECL_NODES: [Node] = [
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
         nameForDiagnostics: "modifiers",
-        documentation: "Modifiers that are attached to the struct declaration."
+        documentation: "Modifiers like `public` that are attached to the struct declaration."
       ),
       Child(
         name: "structKeyword",
@@ -2324,7 +2331,8 @@ public let DECL_NODES: [Node] = [
       Child(
         name: "modifiers",
         kind: .collection(kind: .declModifierList, collectionElementName: "Modifier", defaultsToEmpty: true),
-        nameForDiagnostics: "modifiers"
+        nameForDiagnostics: "modifiers",
+        documentation: "Modifiers modifiers applied to the variable declaration."
       ),
       Child(
         name: "bindingSpecifier",

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -1683,37 +1683,51 @@ public let EXPR_NODES: [Node] = [
 
   // switch-expr -> identifier? ':'? 'switch' expr '{'
   //   switch-case-list '}' ';'?
-  //
-  // This node represents both a 'switch' expression, as well as a 'switch'
-  // statement when wrapped in an ExpressionStmt node.
   Node(
     kind: .switchExpr,
     base: .expr,
     nameForDiagnostics: "'switch' statement",
+    documentation: """
+      A `switch` expression.
+
+      This node represents both a 'switch' expression.
+
+      ```swift
+      switch self.foo {
+      }
+      ```
+
+      A switch ecpression may be declared without any cases.
+      """,
     traits: [
       "Braced"
     ],
     children: [
       Child(
         name: "switchKeyword",
-        kind: .token(choices: [.keyword(.switch)])
+        kind: .token(choices: [.keyword(.switch)]),
+        documentation: "The `switch` keyword."
       ),
       Child(
         name: "subject",
         deprecatedName: "expression",
-        kind: .node(kind: .expr)
+        kind: .node(kind: .expr),
+        documentation: "The expression to switch over."
       ),
       Child(
         name: "leftBrace",
-        kind: .token(choices: [.token(.leftBrace)])
+        kind: .token(choices: [.token(.leftBrace)]),
+        documentation: "The brace introducing the switch body."
       ),
       Child(
         name: "cases",
-        kind: .collection(kind: .switchCaseList, collectionElementName: "Case")
+        kind: .collection(kind: .switchCaseList, collectionElementName: "Case"),
+        documentation: "The switch's body that contains all possible cases."
       ),
       Child(
         name: "rightBrace",
-        kind: .token(choices: [.token(.rightBrace)])
+        kind: .token(choices: [.token(.rightBrace)]),
+        documentation: "The brace closing the switch body."
       ),
     ]
   ),

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesAB.swift

@@ -74,6 +74,8 @@ public struct AccessorBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo
 
   /// - 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.
+  ///   - leftBrace: The brace introducing the accessor block.
+  ///   - rightBrace: The brace closing the accessor block.
   ///   - 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,
@@ -128,6 +130,7 @@ public struct AccessorBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo
     }
   }
 
+  /// The brace introducing the accessor block.
   public var leftBrace: TokenSyntax {
     get {
       return Syntax(self).child(at: 1)!.cast(TokenSyntax.self)
@@ -164,6 +167,7 @@ public struct AccessorBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo
     }
   }
 
+  /// The brace closing the accessor block.
   public var rightBrace: TokenSyntax {
     get {
       return Syntax(self).child(at: 5)!.cast(TokenSyntax.self)
@@ -469,6 +473,8 @@ public struct AccessorEffectSpecifiersSyntax: SyntaxProtocol, SyntaxHashable, _L
 
   /// - 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.
+  ///   - asyncSpecifier: The `async` keyword.
+  ///   - throwsSpecifier: The `throws` keyword.
   ///   - 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,
@@ -517,6 +523,7 @@ public struct AccessorEffectSpecifiersSyntax: SyntaxProtocol, SyntaxHashable, _L
     }
   }
 
+  /// The `async` keyword.
   public var asyncSpecifier: TokenSyntax? {
     get {
       return Syntax(self).child(at: 1)?.cast(TokenSyntax.self)
@@ -535,6 +542,7 @@ public struct AccessorEffectSpecifiersSyntax: SyntaxProtocol, SyntaxHashable, _L
     }
   }
 
+  /// The `throws` keyword.
   public var throwsSpecifier: TokenSyntax? {
     get {
       return Syntax(self).child(at: 3)?.cast(TokenSyntax.self)
@@ -732,6 +740,9 @@ public struct ActorDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
 
   /// - 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.
+  ///   - modifiers: Modifiers like `public` that are attached to the actor declaration.
+  ///   - actorKeyword: The `actor` keyword.
+  ///   - name: The name of the actor. If the name matches a reserved keyword use backticks to escape it.
   ///   - genericParameterClause: The parameter clause that defines the generic parameters.
   ///   - genericWhereClause: A `where` clause that places additional constraints on generic parameters like `where Element: Hashable`.
   ///   - 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.
@@ -863,6 +874,7 @@ public struct ActorDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
     }
   }
 
+  /// Modifiers like `public` that are attached to the actor declaration.
   public var modifiers: DeclModifierListSyntax {
     get {
       return Syntax(self).child(at: 3)!.cast(DeclModifierListSyntax.self)
@@ -908,6 +920,7 @@ public struct ActorDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
     }
   }
 
+  /// The `actor` keyword.
   public var actorKeyword: TokenSyntax {
     get {
       return Syntax(self).child(at: 5)!.cast(TokenSyntax.self)
@@ -926,6 +939,7 @@ public struct ActorDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
     }
   }
 
+  /// The name of the actor. If the name matches a reserved keyword use backticks to escape it.
   public var name: TokenSyntax {
     get {
       return Syntax(self).child(at: 7)!.cast(TokenSyntax.self)
@@ -1869,7 +1883,7 @@ public struct AssociatedTypeDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _Lea
   /// - 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.
   ///   - attributes: Attributes attached to the associated type declaration.
-  ///   - modifiers: Modifiers attached to the associated type declaration.
+  ///   - modifiers: Modifiers like `public` that are attached to the associated type declaration.
   ///   - associatedtypeKeyword: The `associatedtype` keyword for this declaration.
   ///   - name: The name of this associated type.
   ///   - inheritanceClause: The inheritance clause describing conformances for this associated type declaration.
@@ -1999,7 +2013,7 @@ public struct AssociatedTypeDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _Lea
     }
   }
 
-  /// Modifiers attached to the associated type declaration.
+  /// Modifiers like `public` that are attached to the associated type declaration.
   public var modifiers: DeclModifierListSyntax {
     get {
       return Syntax(self).child(at: 3)!.cast(DeclModifierListSyntax.self)

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesC.swift

@@ -741,7 +741,7 @@ public struct ClassDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
   /// - 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.
   ///   - attributes: Attributes attached to the class declaration, such as an `@available` attribute.
-  ///   - modifiers: Modifiers attached to the class declaration, such as `public`.
+  ///   - modifiers: Modifiers like `public` that are attached to the class declaration.
   ///   - classKeyword: The `class` keyword for this declaration.
   ///   - name: The name of the class.
   ///   - genericParameterClause: The generic parameters, if any, of the class declaration.
@@ -878,7 +878,7 @@ public struct ClassDeclSyntax: DeclSyntaxProtocol, SyntaxHashable, _LeafDeclSynt
     }
   }
 
-  /// Modifiers attached to the class declaration, such as `public`.
+  /// Modifiers like `public` that are attached to the class declaration.
   public var modifiers: DeclModifierListSyntax {
     get {
       return Syntax(self).child(at: 3)!.cast(DeclModifierListSyntax.self)
@@ -3013,6 +3013,8 @@ public struct CodeBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodePr
 
   /// - 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.
+  ///   - leftBrace: The brace introducing the code block.
+  ///   - rightBrace: The brace closing the code block.
   ///   - 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,
@@ -3067,6 +3069,7 @@ public struct CodeBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodePr
     }
   }
 
+  /// The brace introducing the code block.
   public var leftBrace: TokenSyntax {
     get {
       return Syntax(self).child(at: 1)!.cast(TokenSyntax.self)
@@ -3130,6 +3133,7 @@ public struct CodeBlockSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodePr
     }
   }
 
+  /// The brace closing the code block.
   public var rightBrace: TokenSyntax {
     get {
       return Syntax(self).child(at: 5)!.cast(TokenSyntax.self)