diff --git a/CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift b/CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift index 7247e17a909..dfabc5c64a7 100644 --- a/CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift +++ b/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" ), diff --git a/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift b/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift index fdad15af88d..d0ad3fe8e06 100644 --- a/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift +++ b/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" diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift index 1dd414f2cd5..77390a83b99 100644 --- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift +++ b/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,7 +530,10 @@ 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 @@ -517,7 +541,10 @@ public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable { 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 @@ -525,6 +552,10 @@ public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable { 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 @@ -532,7 +563,10 @@ public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable { 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 @@ -540,6 +574,12 @@ public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable { 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: diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 096d0512165..d89b0d15ccd 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -855,6 +855,34 @@ public struct KeyPathComponentListSyntax: SyntaxCollection, SyntaxHashable { public static let syntaxKind = SyntaxKind.keyPathComponentList } +/// A list of labeled expressions used in function calls, macro expansions, and other contexts where arguments can have labels. +/// +/// This collection represents a list of expressions that may have labels, such as function call arguments or macro parameters. +/// +/// ### Examples +/// ```swift +/// let arguments = LabeledExprListSyntax { +/// LabeledExprSyntax( +/// label: .identifier("localized"), +/// colon: .colonToken(), +/// expression: stringLiteral +/// ) +/// LabeledExprSyntax( +/// label: .identifier("defaultValue"), +/// colon: .colonToken(), +/// expression: defaultValueLiteral +/// ) +/// } +/// ``` +/// +/// let functionCall = FunctionCallExprSyntax( +/// calledExpression: ExprSyntax(name), +/// leftParen: .leftParenToken(), +/// arguments: arguments, +/// rightParen: .rightParenToken() +/// ) +/// ``` +/// /// ### Children /// /// ``LabeledExprSyntax`` `*` @@ -874,6 +902,17 @@ public struct LabeledExprListSyntax: SyntaxCollection, SyntaxHashable { public let _syntaxNode: Syntax + /// Creates a list of labeled expressions from a syntax node. + /// + /// ### Example + /// ```swift + /// if let list = LabeledExprListSyntax(someNode) { + /// // Process the labeled expressions + /// } + /// ``` + /// + /// - Parameters: + /// - node: The syntax node to convert. Returns nil if the node is not of kind `.labeledExprList`. public init?(_ node: some SyntaxProtocol) { guard node.raw.kind == .labeledExprList else { return nil @@ -1397,6 +1436,25 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas public static let syntaxKind = SyntaxKind.specializeAttributeArgumentList } +/// 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() +/// ) +/// ``` +/// /// ### Children /// /// (``StringSegmentSyntax`` | ``ExpressionSegmentSyntax``) `*` @@ -1405,12 +1463,33 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas /// /// - ``StringLiteralExprSyntax``.``StringLiteralExprSyntax/segments`` public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { + /// Represents either a literal string segment or an interpolated expression segment within a string literal. + /// + /// This enum handles the two possible types of segments that can appear in a string literal: + /// - Plain text segments (like `"Hello "` in `"Hello \(name)"`) + /// - Expression segments (like `\(name)` in `"Hello \(name)"`) + /// + /// ### Examples + /// ```swift + /// let segments = StringLiteralSegmentListSyntax([ + /// .stringSegment(.init(content: .stringSegment("Hello "))), + /// .expressionSegment(.init( + /// leftParen: .leftParenToken(), + /// expressions: ExprListSyntax([ExprSyntax("name")]), + /// rightParen: .rightParenToken() + /// )) + /// ]) + /// ``` public enum Element: SyntaxChildChoices, SyntaxHashable { - /// 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`` case stringSegment(StringSegmentSyntax) - /// 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`` case expressionSegment(ExpressionSegmentSyntax) @@ -1424,14 +1503,60 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { } } + /// Creates a new Element wrapping a string segment. + /// + /// This initializer is used when adding literal text content to a string literal. The string segment's content token should be created using `.stringSegment()` to ensure proper formatting. + /// + /// ### Examples + /// ```swift + /// let element = StringLiteralSegmentListSyntax.Element( + /// StringSegmentSyntax(content: .stringSegment("warning: invalid configuration")) + /// ) + /// ``` + /// + /// - Parameters: + /// - node: The string segment to wrap in this element. public init(_ node: StringSegmentSyntax) { self = .stringSegment(node) } + /// Creates a new Element wrapping an expression segment. + /// + /// This initializer is used when adding interpolated expressions to a string literal. + /// + /// ### Example + /// To create a string interpolation segment containing `\(errorValue)` + /// ```swift + /// let element = StringLiteralSegmentListSyntax.Element( + /// ExpressionSegmentSyntax( + /// expressions: ExprListSyntax([ + /// ExprSyntax("errorValue") + /// ]) + /// ) + /// ) + /// ``` + /// + /// - Parameters: + /// - node: The expression segment to wrap in this element. public init(_ node: ExpressionSegmentSyntax) { self = .expressionSegment(node) } + /// Creates a new Element from a syntax node. + /// + /// ### Examples + /// ```swift + /// guard + /// let stringLiteral = node.as(StringLiteralExprSyntax.self), + /// let firstSegment = stringLiteral.segments.first, + /// case .stringSegment(let segment) = firstSegment + /// else { + /// throw CustomError.message("Expected string literal") + /// } + /// ``` + /// + /// - Parameters: + /// - node: The syntax node to convert. Returns nil if node is neither a StringSegmentSyntax nor an ExpressionSegmentSyntax. public init?(_ node: __shared some SyntaxProtocol) { if let node = node.as(StringSegmentSyntax.self) { self = .stringSegment(node) @@ -1493,6 +1618,21 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { public let _syntaxNode: Syntax + /// Creates a list of string literal segments from a syntax node. + /// + /// ### Example + /// ```swift + /// let stringLiteral = StringLiteralExprSyntax( + /// openingQuote: .stringQuoteToken(), + /// segments: StringLiteralSegmentListSyntax([ + /// .stringSegment(.init(content: .stringSegment("Hello"))) + /// ]), + /// closingQuote: .stringQuoteToken() + /// ) + /// ``` + /// + /// - Parameters: + /// - node: The syntax node to convert. Returns nil if the node is not of kind `.stringLiteralSegmentList`. public init?(_ node: some SyntaxProtocol) { guard node.raw.kind == .stringLiteralSegmentList else { return nil diff --git a/Sources/SwiftSyntax/generated/raw/RawSyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/raw/RawSyntaxNodesQRS.swift index fb8d2038f1a..456313d495a 100644 --- a/Sources/SwiftSyntax/generated/raw/RawSyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/raw/RawSyntaxNodesQRS.swift @@ -1345,11 +1345,15 @@ public struct RawStringLiteralExprSyntax: RawExprSyntaxNodeProtocol { @_spi(RawSyntax) public struct RawStringLiteralSegmentListSyntax: RawSyntaxNodeProtocol { public enum Element: RawSyntaxNodeProtocol { - /// 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`` case stringSegment(RawStringSegmentSyntax) - /// 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`` case expressionSegment(RawExpressionSegmentSyntax) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift index 28f6951ec45..0ba1ef38ea2 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift @@ -605,6 +605,27 @@ public struct DeclNameArgumentsSyntax: SyntaxProtocol, SyntaxHashable, _LeafSynt // MARK: - DeclReferenceExprSyntax +/// 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 /// /// - `baseName`: (`` | `self` | `Self` | `init` | `deinit` | `subscript` | `` | `` | ``) @@ -620,6 +641,13 @@ public struct DeclNameArgumentsSyntax: SyntaxProtocol, SyntaxHashable, _LeafSynt public struct DeclReferenceExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafExprSyntaxNodeProtocol { public let _syntaxNode: Syntax + /// Internal initializer used by swift-syntax to create declaration references from existing syntax nodes. + /// + /// This initializer is not intended for direct use when creating declaration references programmatically. + /// Instead, use the main initializer that accepts individual components. + /// + /// - Parameters: + /// - node: An existing syntax node to convert. Must be of kind `.declReferenceExpr`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .declReferenceExpr else { return nil @@ -627,9 +655,24 @@ public struct DeclReferenceExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf self._syntaxNode = node._syntaxNode } + /// Creates a new declaration reference with the given base name and optional components. + /// + /// ### Example + /// To create a reference to a declaration: + /// ```swift + /// let reference = DeclReferenceExprSyntax( + /// baseName: .identifier("String") + /// ) + /// ``` + /// /// - 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. - /// - 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. + /// - 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. + /// - unexpectedBeforeBaseName: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - baseName: The name of the declaration being referenced. + /// - unexpectedBetweenBaseNameAndArgumentNames: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - argumentNames: Optional argument labels when referring to specific function overloads. + /// - unexpectedAfterArgumentNames: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - 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, _ unexpectedBeforeBaseName: UnexpectedNodesSyntax? = nil, diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift index 9be2ca37f77..678d141e810 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift @@ -1798,7 +1798,9 @@ public struct ExpressionPatternSyntax: PatternSyntaxProtocol, SyntaxHashable, _L // MARK: - ExpressionSegmentSyntax -/// 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`` /// @@ -3039,6 +3041,47 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx // MARK: - FunctionCallExprSyntax +/// 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 /// /// - `calledExpression`: ``ExprSyntax`` @@ -3050,6 +3093,13 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafExprSyntaxNodeProtocol { public let _syntaxNode: Syntax + /// Internal initializer used by swift-syntax to create function calls from existing syntax nodes. + /// + /// This initializer is not intended for direct use when creating function calls programmatically. + /// Instead, use the main initializer that accepts individual components. + /// + /// - Parameters: + /// - node: An existing syntax node to convert. Must be of kind `.functionCallExpr`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .functionCallExpr else { return nil @@ -3057,9 +3107,37 @@ public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafE self._syntaxNode = node._syntaxNode } + /// Creates a new function call expression with the given components. + /// + /// ### Example + /// To create a simple function call: + /// ```swift + /// let call = FunctionCallExprSyntax( + /// calledExpression: DeclReferenceExprSyntax(baseName: "print"), + /// leftParen: .leftParenToken(), + /// arguments: LabeledExprListSyntax([ + /// LabeledExprSyntax(expression: valueExpr) + /// ]), + /// rightParen: .rightParenToken() + /// ) + /// ``` + /// /// - 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. - /// - 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. + /// - 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. + /// - unexpectedBeforeCalledExpression: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - calledExpression: The expression being called (usually a reference to a function or method). + /// - unexpectedBetweenCalledExpressionAndLeftParen: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - leftParen: The opening parenthesis token, created using `.leftParenToken()`. + /// - unexpectedBetweenLeftParenAndArguments: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - arguments: The list of arguments to the function. + /// - unexpectedBetweenArgumentsAndRightParen: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - rightParen: The closing parenthesis token, created using `.rightParenToken()`. + /// - unexpectedBetweenRightParenAndTrailingClosure: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - trailingClosure: An optional trailing closure argument. + /// - unexpectedBetweenTrailingClosureAndAdditionalTrailingClosures: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - additionalTrailingClosures: Additional trailing closure arguments. + /// - unexpectedAfterAdditionalTrailingClosures: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - 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, _ unexpectedBeforeCalledExpression: UnexpectedNodesSyntax? = nil, diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift index 9f48aab9adf..b595a548864 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift @@ -788,11 +788,37 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ // MARK: - LabeledExprSyntax -/// 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. /// -/// 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. +/// 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 +/// +/// ### 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() +/// ) +/// ]) +/// ``` /// /// ### Children /// @@ -807,6 +833,13 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodeProtocol { public let _syntaxNode: Syntax + /// Internal initializer used by swift-syntax to create labeled expressions from existing syntax nodes. + /// + /// This initializer is not intended for direct use when creating labeled expressions programmatically. + /// Instead, use the main initializer that accepts individual components. + /// + /// - Parameters: + /// - node: The syntax node to convert. Returns nil if the node is not of kind `.labeledExpr`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .labeledExpr else { return nil @@ -814,9 +847,30 @@ public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNode self._syntaxNode = node._syntaxNode } + /// Creates a new labeled expression with the given components. + /// + /// ### Example + /// To create a labeled argument for a function call: + /// ```swift + /// let argument = LabeledExprSyntax( + /// label: .identifier("defaultValue"), + /// colon: .colonToken(), + /// expression: stringLiteral + /// ) + /// ``` + /// /// - 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. - /// - 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. + /// - 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. + /// - unexpectedBeforeLabel: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - label: The optional label for this expression, created using `.identifier()` for named labels or `._` for unnamed ones. + /// - unexpectedBetweenLabelAndColon: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - colon: The colon token that follows the label, created using `.colonToken()`. + /// - unexpectedBetweenColonAndExpression: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - expression: The expression being labeled. + /// - unexpectedBetweenExpressionAndTrailingComma: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - trailingComma: An optional trailing comma, useful when this expression is part of a list. + /// - unexpectedAfterTrailingComma: Used internally by swift-syntax to handle malformed source code. When creating expressions programmatically, you should pass nil. + /// - 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, _ unexpectedBeforeLabel: UnexpectedNodesSyntax? = nil, diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index add1bca1a9f..01753f648bd 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2277,9 +2277,27 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf // MARK: - StringSegmentSyntax -/// A literal segment inside a string segment. +/// A string literal segment that represents plain text content within a string literal expression. +/// +/// In a string literal `"Hello \(name)"`, the `"Hello "` part is represented by a `StringSegmentSyntax`, while `\(name)` is represented by an `ExpressionSegmentSyntax`. +/// +/// Creating a string segment requires special attention to use `.stringSegment()` for the content token to ensure proper formatting. +/// +/// ### Examples +/// ```swift +/// let segment = StringSegmentSyntax(content: .stringSegment("Hello World")) +/// +/// let stringLiteral = StringLiteralExprSyntax( +/// openingQuote: .stringQuoteToken(), +/// segments: StringLiteralSegmentListSyntax([.stringSegment(segment)]), +/// closingQuote: .stringQuoteToken() +/// ) +/// ``` +/// +/// - Important: When creating a string segment from a string literal, always use `.stringSegment(string)` rather than just passing the string directly. Using the raw string will create an identifier token instead of a string segment token, which can lead to formatting issues. +/// +/// - SeeAlso: ``ExpressionSegmentSyntax`` for segments containing string interpolations /// -/// - SeeAlso: ``ExpressionSegmentSyntax`` /// /// ### Children /// @@ -2292,6 +2310,13 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodeProtocol { public let _syntaxNode: Syntax + /// Internal initializer used by swift-syntax to create string segments from existing syntax nodes. + /// + /// This initializer is not intended for direct use when creating string segments programmatically. + /// Instead, use the main initializer that accepts individual components. + /// + /// - Parameters: + /// - node: An existing syntax node to convert. Returns nil if the node is not of kind `.stringSegment`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .stringSegment else { return nil @@ -2299,9 +2324,23 @@ public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo self._syntaxNode = node._syntaxNode } + /// Creates a new string segment with the given content and optional trivia. + /// + /// ### Example + /// ```swift + /// let stringLiteral = StringLiteralExprSyntax( + /// openingQuote: .stringQuoteToken(), + /// segments: StringLiteralSegmentListSyntax([.stringSegment(.stringSegment("Some Text"))]), + /// closingQuote: .stringQuoteToken() + /// ) + /// ``` + /// /// - 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. - /// - 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. + /// - 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. + /// - unexpectedBeforeContent: Used internally by swift-syntax to handle malformed source code. When creating string segments programmatically, you should pass nil. + /// - content: The string content token, created using `.stringSegment("your string")` to ensure proper formatting. + /// - unexpectedAfterContent: Used internally by swift-syntax to handle malformed source code. When creating string segments programmatically, you should pass nil. + /// - 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, _ unexpectedBeforeContent: UnexpectedNodesSyntax? = nil,