Improve documentation comments of some commonly used types

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -184,6 +184,28 @@ public let COMMON_NODES: [Node] = [
     kind: .expr,
     base: .syntax,
     nameForDiagnostics: "expression",
+    documentation: """
+      A type-erased expression node in the Swift syntax tree.
+
+      This type provides a common API for working with any kind of Swift expression. It can represent various expression types like:
+      - Function calls (`print("Hello")`)
+      - Literals (`42`, `true`, `"text"`)
+      - Member access (`object.property`)
+      - Operators (`a + b`)
+      - And many more
+
+      ### Examples
+      ```swift
+      // Converting a specific expression type to ExprSyntax
+      let specificExpr = StringLiteralExprSyntax(content: "Hello")
+      let genericExpr = ExprSyntax(specificExpr)
+
+      // Casting ExprSyntax to a more specific StringLiteralExprSyntax
+      if let stringLiteral = expr.as(StringLiteralExprSyntax.self) {
+        // Work with the specific string literal expression
+      }
+      ```  
+      """,
     parserFunction: "parseExpression"
   ),
 

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -861,7 +861,9 @@ public let EXPR_NODES: [Node] = [
     base: .syntax,
     nameForDiagnostics: nil,
     documentation: """
-      An interpolated expression inside a string literal.
+      An interpolated expression segment inside a string literal.
+
+      This case represents interpolated expressions like `\\(name)` in `"Hello \\(name)"`.
 
       - SeeAlso: ``StringSegmentSyntax``
       """,
@@ -935,6 +937,48 @@ public let EXPR_NODES: [Node] = [
     kind: .functionCallExpr,
     base: .expr,
     nameForDiagnostics: "function call",
+    documentation: """
+      A function or method call expression.
+
+      This type represents function calls in Swift syntax, with support for labeled arguments and trailing closures. Function calls have three main parts:
+      - The called expression (like a function name or method reference)
+      - Parenthesized arguments (which may be labeled)
+      - Optional trailing closures
+
+      ### Examples
+      ```swift
+      // Creating a simple function call
+      let call = FunctionCallExprSyntax(
+        calledExpression: DeclReferenceExprSyntax(baseName: "print"),
+        leftParen: .leftParenToken(),
+        arguments: LabeledExprListSyntax([
+          LabeledExprSyntax(
+            expression: StringLiteralExprSyntax(content: "Hello")
+          )
+        ]),
+        rightParen: .rightParenToken()
+      )
+
+      // Creating a function call with labeled arguments
+      let call = FunctionCallExprSyntax(
+        calledExpression: DeclReferenceExprSyntax(baseName: "String"),
+        leftParen: .leftParenToken(),
+        arguments: LabeledExprListSyntax([
+          LabeledExprSyntax(
+            label: .identifier("localized"),
+            colon: .colonToken(),
+            expression: keyExpr
+          ),
+          LabeledExprSyntax(
+            label: .identifier("defaultValue"),
+            colon: .colonToken(),
+            expression: defaultExpr
+          )
+        ]),
+        rightParen: .rightParenToken()
+      )
+      ```
+      """,
     children: [
       Child(
         name: "calledExpression",
@@ -983,6 +1027,28 @@ public let EXPR_NODES: [Node] = [
     kind: .declReferenceExpr,
     base: .expr,
     nameForDiagnostics: nil,
+    documentation: """
+      An expression that refers to a declaration by name, such as a reference to a function, type, or variable.
+
+      This type represents references to declarations in Swift code, commonly used when building syntax for:
+      - Function and type references
+      - Variable and property references
+      - Special declarations like `self`, `Self`, and `init`
+
+      ### Examples
+      ```swift
+      // Creating a reference to a type
+      let stringReference = DeclReferenceExprSyntax(baseName: "String")
+
+      // Using a reference in a function call
+      let functionCall = FunctionCallExprSyntax(
+        calledExpression: DeclReferenceExprSyntax(baseName: "print"),
+        leftParen: .leftParenToken(),
+        arguments: arguments,
+        rightParen: .rightParenToken()
+      )
+      ```
+      """,
     children: [
       Child(
         name: "baseName",
@@ -1721,6 +1787,26 @@ public let EXPR_NODES: [Node] = [
     kind: .stringLiteralSegmentList,
     base: .syntaxCollection,
     nameForDiagnostics: nil,
+    documentation: """
+      A collection of string literal segments representing both plain text and interpolated expressions.
+
+      Represents the contents of a string literal by storing a sequence of segments. Each segment in the collection is either a text segment for static string content or an expression segment for interpolations.
+      For example, in the string literal `"Hello \\(name)"`, the collection contains a text segment for `"Hello "` followed by an expression segment for `\\(name)`.
+
+      ### Examples
+      ```swift
+      let segments = StringLiteralSegmentListSyntax([
+        .stringSegment(.init(content: .stringSegment("Hello "))),
+        .expressionSegment(/* interpolation expression */)
+      ])
+
+      let stringLiteral = StringLiteralExprSyntax(
+        openingQuote: .stringQuoteToken(),
+        segments: segments,
+        closingQuote: .stringQuoteToken()
+      )
+      ```
+      """,
     elementChoices: [.stringSegment, .expressionSegment]
   ),
 
@@ -1761,8 +1847,10 @@ public let EXPR_NODES: [Node] = [
     base: .syntax,
     nameForDiagnostics: nil,
     documentation: """
-      A literal segment inside a string segment.
-
+      A literal text segment inside a string literal.
+
+      This case represents static text content like `"Hello "` in `"Hello \\(name)"`.
+
       - SeeAlso: ``ExpressionSegmentSyntax``
       """,
     children: [
@@ -2071,11 +2159,37 @@ public let EXPR_NODES: [Node] = [
     base: .syntax,
     nameForDiagnostics: nil,
     documentation: """
-      An expression that is prefixed by a label.
+      An expression with an optional label and colon, used in function calls, tuple elements, and macro arguments.
+
+      This type represents labeled expressions in Swift syntax, commonly used for:
+      - Function call arguments with parameter labels
+      - Tuple elements with names
+      - Macro arguments with labels
 
-      For example, labeled expressions occur in
-      - Function calls, where the label is the parameter label.
-      - Tuples, where the label is the name of the tuple element.
+      ### Examples
+      ```swift
+      // Creating a labeled argument
+      let labeledArg = LabeledExprSyntax(
+        label: .identifier("localized"),
+        colon: .colonToken(),
+        expression: stringLiteral
+      )
+
+      // Creating a list of labeled arguments
+      let arguments = LabeledExprListSyntax([
+        LabeledExprSyntax(
+          label: .identifier("name"),
+          colon: .colonToken(),
+          expression: nameExpr
+        ),
+        LabeledExprSyntax(
+          label: .identifier("value"),
+          colon: .colonToken(),
+          expression: valueExpr,
+          trailingComma: .commaToken()
+        )
+      ])
+      ```
       """,
     traits: [
       "WithTrailingComma"

Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift

@@ -454,6 +454,27 @@ extension Syntax {
   }
 }
 
+/// A type-erased expression node in the Swift syntax tree.
+/// 
+/// This type provides a common API for working with any kind of Swift expression. It can represent various expression types like:
+/// - Function calls (`print("Hello")`)
+/// - Literals (`42`, `true`, `"text"`)
+/// - Member access (`object.property`)
+/// - Operators (`a + b`)
+/// - And many more
+/// 
+/// ### Examples
+/// ```swift
+/// // Converting a specific expression type to ExprSyntax
+/// let specificExpr = StringLiteralExprSyntax(content: "Hello")
+/// let genericExpr = ExprSyntax(specificExpr)
+/// 
+/// // Casting ExprSyntax to a more specific StringLiteralExprSyntax
+/// if let stringLiteral = expr.as(StringLiteralExprSyntax.self) {
+///   // Work with the specific string literal expression
+/// }
+/// ```  
+///
 /// ### Subtypes
 /// 
 /// - ``ArrayExprSyntax``
@@ -509,37 +530,56 @@ extension Syntax {
 public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
 
-  /// Create a ``ExprSyntax`` node from a specialized syntax node.
+  /// Creates a type-erased expression from a specialized expression syntax node.
+  ///
+  /// - Parameters:
+  ///   - syntax: The specialized expression node to convert to a generic ExprSyntax.
   public init(_ syntax: __shared some ExprSyntaxProtocol) {
     // We know this cast is going to succeed. Go through init(_: SyntaxData)
     // to do a sanity check and verify the kind matches in debug builds and get
     // maximum performance in release builds.
     self = Syntax(syntax).cast(Self.self)
   }
 
-  /// Create a ``ExprSyntax`` node from a specialized optional syntax node.
+  /// Creates an optional type-erased expression from an optional specialized expression syntax node.
+  ///
+  /// - Parameters:
+  ///   - syntax: The optional specialized expression node to convert to a generic ExprSyntax.
   public init?(_ syntax: __shared (some ExprSyntaxProtocol)?) {
     guard let syntax = syntax else {
       return nil
     }
     self.init(syntax)
   }
 
+  /// Creates a type-erased expression from an expression protocol type.
+  ///
+  /// - Parameters:
+  ///   - syntax: The expression protocol type to convert to a generic ExprSyntax.
   public init(fromProtocol syntax: __shared ExprSyntaxProtocol) {
     // We know this cast is going to succeed. Go through init(_: SyntaxData)
     // to do a sanity check and verify the kind matches in debug builds and get
     // maximum performance in release builds.
     self = Syntax(syntax).cast(Self.self)
   }
 
-  /// Create a ``ExprSyntax`` node from a specialized optional syntax node.
+  /// Creates an optional type-erased expression from an optional expression protocol type.
+  ///
+  /// - Parameters:
+  ///   - syntax: The optional expression protocol type to convert to a generic ExprSyntax.
   public init?(fromProtocol syntax: __shared ExprSyntaxProtocol?) {
     guard let syntax = syntax else {
       return nil
     }
     self.init(fromProtocol: syntax)
   }
 
+  /// Creates a type-erased expression from any syntax node that represents an expression.
+  ///
+  /// This initializer succeeds only for syntax nodes that represent valid Swift expressions.
+  ///
+  /// - Parameters:
+  ///   - node: The syntax node to convert. Must be one of the supported expression kinds.
   public init?(_ node: __shared some SyntaxProtocol) {
     switch node.raw.kind {
     case .arrayExpr, .arrowExpr, .asExpr, .assignmentExpr, .awaitExpr, .binaryOperatorExpr, .booleanLiteralExpr, .borrowExpr, ._canImportExpr, ._canImportVersionInfo, .closureExpr, .consumeExpr, .copyExpr, .declReferenceExpr, .dictionaryExpr, .discardAssignmentExpr, .doExpr, .editorPlaceholderExpr, .floatLiteralExpr, .forceUnwrapExpr, .functionCallExpr, .genericSpecializationExpr, .ifExpr, .inOutExpr, .infixOperatorExpr, .integerLiteralExpr, .isExpr, .keyPathExpr, .macroExpansionExpr, .memberAccessExpr, .missingExpr, .nilLiteralExpr, .optionalChainingExpr, .packElementExpr, .packExpansionExpr, .patternExpr, .postfixIfConfigExpr, .postfixOperatorExpr, .prefixOperatorExpr, .regexLiteralExpr, .sequenceExpr, .simpleStringLiteralExpr, .stringLiteralExpr, .subscriptCallExpr, .superExpr, .switchExpr, .ternaryExpr, .tryExpr, .tupleExpr, .typeExpr, .unresolvedAsExpr, .unresolvedIsExpr, .unresolvedTernaryExpr: