From 97cc8695eabb6db5426415b3716c01b2a5ccce44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 10:56:02 +0100 Subject: [PATCH 01/13] Improve documentation comments of StringSegmentSyntax --- .../syntaxNodes/SyntaxNodesQRS.swift | 43 ++++++++++++++++--- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index add1bca1a9f..abdee0a5f7e 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2277,16 +2277,31 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf // MARK: - StringSegmentSyntax -/// A literal segment inside a string segment. -/// -/// - SeeAlso: ``ExpressionSegmentSyntax`` +/// A string literal segment that represents plain text content within a string literal expression. +/// +/// Used to construct string literals programmatically, especially in macros that need to generate or manipulate string content. For example, in a string literal `"Hello \(name)"`, the `"Hello "` part would be represented by a `StringSegmentSyntax`. +/// +/// Creating a string segment requires special attention to use `.stringSegment()` for the content token to ensure proper formatting. For example, when creating a simple string segment: +/// ```swift +/// let segment = StringSegmentSyntax(content: .stringSegment("Hello World")) +/// ``` +/// +/// This type is commonly used in macros for: +/// - Creating and validating string literals at compile time (e.g., URL validation) +/// - Building string-based error messages and diagnostics +/// - Generating code that contains string literals +/// - Constructing string interpolations +/// +/// 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 /// /// ### Children -/// +/// /// - `content`: `` /// /// ### Contained in -/// +/// /// - ``SimpleStringLiteralSegmentListSyntax`` /// - ``StringLiteralSegmentListSyntax`` public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodeProtocol { @@ -2299,9 +2314,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")` + /// - 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, From 30a58f2ea7e46446e62ec7a4ab514e1df9857ab6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:12:01 +0100 Subject: [PATCH 02/13] Improve documentation comments of StringLiteralSegmentListSyntax --- .../generated/SyntaxCollections.swift | 109 +++++++++++++++++- 1 file changed, 103 insertions(+), 6 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 096d0512165..06ee2f84f62 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -1397,21 +1397,56 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas public static let syntaxKind = SyntaxKind.specializeAttributeArgumentList } +/// A collection of string literal segments representing both plain text and interpolated expressions. +/// +/// This collection is used to represent the contents of string literals, including both static text segments and interpolated expressions. +/// For example, in the string literal `"Hello \(name)"`, the collection would contain a string segment for `"Hello "` followed by an expression segment for `\(name)`. +/// +/// ```swift +/// let segments = StringLiteralSegmentListSyntax([ +/// .stringSegment(.init(content: .stringSegment("Hello "))), +/// .expressionSegment(/* interpolation expression */) +/// ]) +/// ``` +/// +/// This type is commonly used in macros for: +/// - Building string literals with both static text and interpolations +/// - Validating string literal contents at compile time +/// - Analyzing or transforming string interpolations +/// /// ### Children -/// +/// /// (``StringSegmentSyntax`` | ``ExpressionSegmentSyntax``) `*` /// /// ### Contained in -/// +/// /// - ``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 is used to handle 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)"`) + /// + /// Example: + /// ```swift + /// let segments = [ + /// StringLiteralSegmentListSyntax.Element.stringSegment(.init(content: .stringSegment("Hello "))), + /// StringLiteralSegmentListSyntax.Element.expressionSegment(/* expression */) + /// ] + /// ``` 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 +1459,59 @@ 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 should be created using `.stringSegment()` to ensure proper formatting. + /// + /// Example from warning macro: + /// ```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 from diagnostic message: + /// ```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 an existing syntax node by attempting to cast it to either a string or expression segment. + /// + /// Example from string literal parsing: + /// ```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 attempt to convert into an element. Must be either a StringSegmentSyntax or ExpressionSegmentSyntax. public init?(_ node: __shared some SyntaxProtocol) { if let node = node.as(StringSegmentSyntax.self) { self = .stringSegment(node) @@ -1493,6 +1573,23 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { public let _syntaxNode: Syntax + /// Creates a list of string literal segments from an array of elements. + /// + /// Used to create lists that represent both plain text and interpolated expressions in a string literal. Common in macros where you need to create or modify string literals. + /// + /// Example: + /// ```swift + /// let stringLiteral = StringLiteralExprSyntax( + /// openingQuote: .stringQuoteToken(), + /// segments: StringLiteralSegmentListSyntax([ + /// .stringSegment(.init(content: .stringSegment("Hello"))) + /// ]), + /// closingQuote: .stringQuoteToken() + /// ) + /// ``` + /// + /// - Parameters: + /// - node: The syntax node to create the list from. Must be of kind `.stringLiteralSegmentList`. public init?(_ node: some SyntaxProtocol) { guard node.raw.kind == .stringLiteralSegmentList else { return nil From ed6a983c7ed3b7483f49767b452d655e4becabbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:17:53 +0100 Subject: [PATCH 03/13] Improve documentation comments of LabeledExprListSyntax --- .../generated/SyntaxCollections.swift | 49 ++++++++++++++++++- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 06ee2f84f62..23bf360ff3e 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -855,12 +855,42 @@ 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. +/// +/// Example of creating a list of labeled arguments: +/// ```swift +/// let arguments = LabeledExprListSyntax { +/// LabeledExprSyntax( +/// label: .identifier("localized"), +/// colon: .colonToken(), +/// expression: stringLiteral +/// ) +/// LabeledExprSyntax( +/// label: .identifier("defaultValue"), +/// colon: .colonToken(), +/// expression: defaultValueLiteral +/// ) +/// } +/// ``` +/// +/// Example of creating a function call with labeled arguments: +/// ```swift +/// let functionCall = FunctionCallExprSyntax( +/// calledExpression: ExprSyntax(name), +/// leftParen: .leftParenToken(), +/// arguments: arguments, +/// rightParen: .rightParenToken() +/// ) +/// ``` +/// /// ### Children -/// +/// /// ``LabeledExprSyntax`` `*` /// /// ### Contained in -/// +/// /// - ``AttributeSyntax``.``AttributeSyntax/arguments`` /// - ``ExpressionSegmentSyntax``.``ExpressionSegmentSyntax/expressions`` /// - ``FunctionCallExprSyntax``.``FunctionCallExprSyntax/arguments`` @@ -874,6 +904,21 @@ public struct LabeledExprListSyntax: SyntaxCollection, SyntaxHashable { public let _syntaxNode: Syntax + /// Creates a list of labeled expressions from a syntax node. + /// + /// Example: + /// ```swift + /// let arguments = LabeledExprListSyntax { + /// LabeledExprSyntax( + /// label: .identifier("name"), + /// colon: .colonToken(), + /// expression: nameExpr + /// ) + /// } + /// ``` + /// + /// - Parameters: + /// - node: The syntax node to create the list from. Must be of kind `.labeledExprList`. public init?(_ node: some SyntaxProtocol) { guard node.raw.kind == .labeledExprList else { return nil From f2aff2e36c7ba277ab954f4a2b954776bc8d64d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:22:27 +0100 Subject: [PATCH 04/13] Improve documentation comments of LabeledExprSyntax --- .../syntaxNodes/SyntaxNodesJKLMN.swift | 72 ++++++++++++++++--- 1 file changed, 63 insertions(+), 9 deletions(-) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift index 9f48aab9adf..e1b36abb917 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift @@ -788,25 +788,59 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ // MARK: - LabeledExprSyntax -/// An expression that is prefixed by a label. -/// -/// 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. +/// 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 +/// +/// Example creating a labeled expression for a function call: +/// ```swift +/// let labeledArg = LabeledExprSyntax( +/// label: .identifier("localized"), +/// colon: .colonToken(), +/// expression: stringLiteral +/// ) +/// ``` +/// +/// Example creating multiple labeled expressions in a list: +/// ```swift +/// let arguments = LabeledExprListSyntax { +/// LabeledExprSyntax( +/// label: .identifier("name"), +/// colon: .colonToken(), +/// expression: nameExpr +/// ) +/// LabeledExprSyntax( +/// label: .identifier("value"), +/// colon: .colonToken(), +/// expression: valueExpr, +/// trailingComma: .commaToken() +/// ) +/// } +/// ``` /// /// ### Children -/// +/// /// - `label`: (`` | `_`)? /// - `colon`: `:`? /// - `expression`: ``ExprSyntax`` /// - `trailingComma`: `,`? /// /// ### Contained in -/// +/// /// - ``LabeledExprListSyntax`` 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: An existing syntax node to convert. Must be of kind `.labeledExpr`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .labeledExpr else { return nil @@ -814,9 +848,29 @@ public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNode self._syntaxNode = node._syntaxNode } + /// Creates a new labeled expression with the given components. + /// + /// Example creating a labeled string literal argument: + /// ```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, From bbffc84d52ca18cf1d4c4acb203d71ac87c93793 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:25:12 +0100 Subject: [PATCH 05/13] Improve documentation comments of DeclReferenceExprSyntax --- .../generated/syntaxNodes/SyntaxNodesD.swift | 51 +++++++++++++++++-- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift index 28f6951ec45..45751642564 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift @@ -605,13 +605,35 @@ 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` +/// +/// Example creating a simple reference to a type: +/// ```swift +/// let stringReference = DeclReferenceExprSyntax(baseName: "String") +/// ``` +/// +/// Example using a declaration reference in a function call: +/// ```swift +/// let functionCall = FunctionCallExprSyntax( +/// calledExpression: DeclReferenceExprSyntax(baseName: "print"), +/// leftParen: .leftParenToken(), +/// arguments: arguments, +/// rightParen: .rightParenToken() +/// ) +/// ``` +/// /// ### Children -/// +/// /// - `baseName`: (`` | `self` | `Self` | `init` | `deinit` | `subscript` | `` | `` | ``) /// - `argumentNames`: ``DeclNameArgumentsSyntax``? /// /// ### Contained in -/// +/// /// - ``DynamicReplacementAttributeArgumentsSyntax``.``DynamicReplacementAttributeArgumentsSyntax/declName`` /// - ``ImplementsAttributeArgumentsSyntax``.``ImplementsAttributeArgumentsSyntax/declName`` /// - ``KeyPathPropertyComponentSyntax``.``KeyPathPropertyComponentSyntax/declName`` @@ -620,6 +642,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 +656,23 @@ public struct DeclReferenceExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf self._syntaxNode = node._syntaxNode } + /// Creates a new declaration reference with the given base name and optional components. + /// + /// Example creating a reference to a type: + /// ```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, From 6c686fc0b827303d0ec4eb0dbb04a1407eb6086e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:27:50 +0100 Subject: [PATCH 06/13] Improve documentation comments of FunctionCallExprSyntax --- .../generated/syntaxNodes/SyntaxNodesEF.swift | 82 ++++++++++++++++++- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift index 9be2ca37f77..b81e2cf3616 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift @@ -3039,8 +3039,50 @@ 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 +/// +/// Example creating a simple function call: +/// ```swift +/// let call = FunctionCallExprSyntax( +/// calledExpression: DeclReferenceExprSyntax(baseName: "print"), +/// leftParen: .leftParenToken(), +/// arguments: LabeledExprListSyntax([ +/// LabeledExprSyntax( +/// expression: StringLiteralExprSyntax(content: "Hello") +/// ) +/// ]), +/// rightParen: .rightParenToken() +/// ) +/// ``` +/// +/// Example creating a function call with labeled arguments: +/// ```swift +/// 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`` /// - `leftParen`: `(`? /// - `arguments`: ``LabeledExprListSyntax`` @@ -3050,6 +3092,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 +3106,36 @@ public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafE self._syntaxNode = node._syntaxNode } + /// Creates a new function call expression with the given components. + /// + /// Example: + /// ```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, From 03f75207eb82018f867c82feff18c39282f01adf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:32:15 +0100 Subject: [PATCH 07/13] Improve documentation comments of ExprSyntax --- .../generated/SyntaxBaseNodes.swift | 47 +++++++++++++++++-- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift index 1dd414f2cd5..e2c34642ed4 100644 --- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift +++ b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift @@ -454,6 +454,28 @@ 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 +/// +/// Example converting a specific expression type to ExprSyntax: +/// ```swift +/// let specificExpr = StringLiteralExprSyntax(content: "Hello") +/// let genericExpr = ExprSyntax(specificExpr) +/// ``` +/// +/// Example checking and converting back to a specific type: +/// ```swift +/// if let stringLiteral = expr.as(StringLiteralExprSyntax.self) { +/// // Work with the specific string literal expression +/// } +/// ``` +/// /// ### Subtypes /// /// - ``ArrayExprSyntax`` @@ -509,7 +531,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 +542,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 +553,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 +564,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 +575,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: From 61d84fdcfa71ecb92e23ecb8adff8b213ec3b360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Wed, 18 Dec 2024 11:48:43 +0100 Subject: [PATCH 08/13] Add missing internal initializer documentation comment for StringSegmentSyntax --- .../SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index abdee0a5f7e..2ba8f9779e3 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2307,6 +2307,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. Must be of kind `.stringSegment`. public init?(_ node: __shared some SyntaxProtocol) { guard node.raw.kind == .stringSegment else { return nil From 8a7175fa0057eb1151b73360a6bb1c6b98c41185 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20G=C3=BCnd=C3=BCz?= Date: Thu, 19 Dec 2024 20:14:16 +0100 Subject: [PATCH 09/13] Apply suggestions from code review Co-authored-by: Alex Hoppen --- Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift | 2 +- Sources/SwiftSyntax/generated/SyntaxCollections.swift | 8 +++++--- .../generated/syntaxNodes/SyntaxNodesQRS.swift | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift index e2c34642ed4..909c98ec0ec 100644 --- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift +++ b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift @@ -469,7 +469,7 @@ extension Syntax { /// let genericExpr = ExprSyntax(specificExpr) /// ``` /// -/// Example checking and converting back to a specific type: +/// Example casting a `ExprSyntax` to a more specific `StringLiteralExprSyntax` /// ```swift /// if let stringLiteral = expr.as(StringLiteralExprSyntax.self) { /// // Work with the specific string literal expression diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 23bf360ff3e..3af48927ad9 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -1506,9 +1506,10 @@ 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 should be created using `.stringSegment()` to ensure proper formatting. +/// 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. /// - /// Example from warning macro: + /// ### Example + /// To create a string literal `"warning: invalid configuration"` /// ```swift /// let element = StringLiteralSegmentListSyntax.Element( /// StringSegmentSyntax(content: .stringSegment("warning: invalid configuration")) @@ -1525,7 +1526,8 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// /// This initializer is used when adding interpolated expressions to a string literal. /// - /// Example from diagnostic message: + /// ### Example + /// To create a string interpolation segment containing `\(errorValue)` /// ```swift /// let element = StringLiteralSegmentListSyntax.Element( /// ExpressionSegmentSyntax( diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index 2ba8f9779e3..3eb1444f650 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2292,7 +2292,7 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf /// - Generating code that contains string literals /// - Constructing string interpolations /// -/// 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. +/// - 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 /// From 62c1d9a70055f3a70cbd4619f55464969aae6f31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Thu, 19 Dec 2024 20:42:19 +0100 Subject: [PATCH 10/13] Make more documentation changes to adhere to feedback --- .../generated/SyntaxBaseNodes.swift | 9 ++- .../generated/SyntaxCollections.swift | 67 +++++++++---------- .../generated/syntaxNodes/SyntaxNodesD.swift | 10 +-- .../generated/syntaxNodes/SyntaxNodesEF.swift | 16 ++--- .../syntaxNodes/SyntaxNodesJKLMN.swift | 18 ++--- .../syntaxNodes/SyntaxNodesQRS.swift | 24 ++++--- 6 files changed, 71 insertions(+), 73 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift index 909c98ec0ec..d861bce0dad 100644 --- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift +++ b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift @@ -463,19 +463,18 @@ extension Syntax { /// - Operators (`a + b`) /// - And many more /// -/// Example converting a specific expression type to ExprSyntax: +/// ### Examples /// ```swift +/// // Converting a specific expression type to ExprSyntax /// let specificExpr = StringLiteralExprSyntax(content: "Hello") /// let genericExpr = ExprSyntax(specificExpr) -/// ``` /// -/// Example casting a `ExprSyntax` to a more specific `StringLiteralExprSyntax` -/// ```swift +/// // Casting ExprSyntax to a more specific StringLiteralExprSyntax /// if let stringLiteral = expr.as(StringLiteralExprSyntax.self) { /// // Work with the specific string literal expression /// } /// ``` -/// +/// /// ### Subtypes /// /// - ``ArrayExprSyntax`` diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 3af48927ad9..1468a2ddac2 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -859,7 +859,7 @@ public struct KeyPathComponentListSyntax: SyntaxCollection, SyntaxHashable { /// /// This collection represents a list of expressions that may have labels, such as function call arguments or macro parameters. /// -/// Example of creating a list of labeled arguments: +/// ### Examples /// ```swift /// let arguments = LabeledExprListSyntax { /// LabeledExprSyntax( @@ -875,8 +875,6 @@ public struct KeyPathComponentListSyntax: SyntaxCollection, SyntaxHashable { /// } /// ``` /// -/// Example of creating a function call with labeled arguments: -/// ```swift /// let functionCall = FunctionCallExprSyntax( /// calledExpression: ExprSyntax(name), /// leftParen: .leftParenToken(), @@ -906,19 +904,15 @@ public struct LabeledExprListSyntax: SyntaxCollection, SyntaxHashable { /// Creates a list of labeled expressions from a syntax node. /// - /// Example: + /// ### Example /// ```swift - /// let arguments = LabeledExprListSyntax { - /// LabeledExprSyntax( - /// label: .identifier("name"), - /// colon: .colonToken(), - /// expression: nameExpr - /// ) + /// if let list = LabeledExprListSyntax(someNode) { + /// // Process the labeled expressions /// } /// ``` /// /// - Parameters: - /// - node: The syntax node to create the list from. Must be of kind `.labeledExprList`. + /// - 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 @@ -1444,20 +1438,22 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas /// A collection of string literal segments representing both plain text and interpolated expressions. /// -/// This collection is used to represent the contents of string literals, including both static text segments and interpolated expressions. -/// For example, in the string literal `"Hello \(name)"`, the collection would contain a string segment for `"Hello "` followed by an expression segment for `\(name)`. +/// 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 */) /// ]) -/// ``` /// -/// This type is commonly used in macros for: -/// - Building string literals with both static text and interpolations -/// - Validating string literal contents at compile time -/// - Analyzing or transforming string interpolations +/// let stringLiteral = StringLiteralExprSyntax( +/// openingQuote: .stringQuoteToken(), +/// segments: segments, +/// closingQuote: .stringQuoteToken() +/// ) +/// ``` /// /// ### Children /// @@ -1469,16 +1465,20 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// Represents either a literal string segment or an interpolated expression segment within a string literal. /// - /// This enum is used to handle the two possible types of segments that can appear in 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)"`) /// - /// Example: + /// ### Examples /// ```swift - /// let segments = [ - /// StringLiteralSegmentListSyntax.Element.stringSegment(.init(content: .stringSegment("Hello "))), - /// StringLiteralSegmentListSyntax.Element.expressionSegment(/* expression */) - /// ] + /// 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 text segment inside a string literal. @@ -1506,10 +1506,9 @@ 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. + /// 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. /// - /// ### Example - /// To create a string literal `"warning: invalid configuration"` + /// ### Examples /// ```swift /// let element = StringLiteralSegmentListSyntax.Element( /// StringSegmentSyntax(content: .stringSegment("warning: invalid configuration")) @@ -1544,9 +1543,9 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { self = .expressionSegment(node) } - /// Creates a new Element from an existing syntax node by attempting to cast it to either a string or expression segment. + /// Creates a new Element from a syntax node. /// - /// Example from string literal parsing: + /// ### Examples /// ```swift /// guard /// let stringLiteral = node.as(StringLiteralExprSyntax.self), @@ -1558,7 +1557,7 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// ``` /// /// - Parameters: - /// - node: The syntax node to attempt to convert into an element. Must be either a StringSegmentSyntax or ExpressionSegmentSyntax. + /// - 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) @@ -1620,11 +1619,9 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { public let _syntaxNode: Syntax - /// Creates a list of string literal segments from an array of elements. - /// - /// Used to create lists that represent both plain text and interpolated expressions in a string literal. Common in macros where you need to create or modify string literals. + /// Creates a list of string literal segments from a syntax node. /// - /// Example: + /// ### Example /// ```swift /// let stringLiteral = StringLiteralExprSyntax( /// openingQuote: .stringQuoteToken(), @@ -1636,7 +1633,7 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// ``` /// /// - Parameters: - /// - node: The syntax node to create the list from. Must be of kind `.stringLiteralSegmentList`. + /// - 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/syntaxNodes/SyntaxNodesD.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift index 45751642564..98febdf94e7 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift @@ -612,13 +612,12 @@ public struct DeclNameArgumentsSyntax: SyntaxProtocol, SyntaxHashable, _LeafSynt /// - Variable and property references /// - Special declarations like `self`, `Self`, and `init` /// -/// Example creating a simple reference to a type: +/// ### Examples /// ```swift +/// // Creating a reference to a type /// let stringReference = DeclReferenceExprSyntax(baseName: "String") -/// ``` /// -/// Example using a declaration reference in a function call: -/// ```swift +/// // Using a reference in a function call /// let functionCall = FunctionCallExprSyntax( /// calledExpression: DeclReferenceExprSyntax(baseName: "print"), /// leftParen: .leftParenToken(), @@ -658,7 +657,8 @@ public struct DeclReferenceExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf /// Creates a new declaration reference with the given base name and optional components. /// - /// Example creating a reference to a type: + /// ### Example + /// To create a reference to a declaration: /// ```swift /// let reference = DeclReferenceExprSyntax( /// baseName: .identifier("String") diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift index b81e2cf3616..e294b877772 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift @@ -3046,8 +3046,9 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx /// - Parenthesized arguments (which may be labeled) /// - Optional trailing closures /// -/// Example creating a simple function call: +/// ### Examples /// ```swift +/// // Creating a simple function call /// let call = FunctionCallExprSyntax( /// calledExpression: DeclReferenceExprSyntax(baseName: "print"), /// leftParen: .leftParenToken(), @@ -3058,25 +3059,23 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx /// ]), /// rightParen: .rightParenToken() /// ) -/// ``` /// -/// Example creating a function call with labeled arguments: -/// ```swift +/// // Creating a function call with labeled arguments /// let call = FunctionCallExprSyntax( /// calledExpression: DeclReferenceExprSyntax(baseName: "String"), /// leftParen: .leftParenToken(), -/// arguments: LabeledExprListSyntax { +/// arguments: LabeledExprListSyntax([ /// LabeledExprSyntax( /// label: .identifier("localized"), /// colon: .colonToken(), /// expression: keyExpr -/// ) +/// ), /// LabeledExprSyntax( /// label: .identifier("defaultValue"), /// colon: .colonToken(), /// expression: defaultExpr /// ) -/// }, +/// ]), /// rightParen: .rightParenToken() /// ) /// ``` @@ -3108,7 +3107,8 @@ public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafE /// Creates a new function call expression with the given components. /// - /// Example: + /// ### Example + /// To create a simple function call: /// ```swift /// let call = FunctionCallExprSyntax( /// calledExpression: DeclReferenceExprSyntax(baseName: "print"), diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift index e1b36abb917..179004e4f20 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift @@ -795,30 +795,29 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ /// - Tuple elements with names /// - Macro arguments with labels /// -/// Example creating a labeled expression for a function call: +/// ### Examples /// ```swift +/// // Creating a labeled argument /// let labeledArg = LabeledExprSyntax( /// label: .identifier("localized"), /// colon: .colonToken(), /// expression: stringLiteral /// ) -/// ``` /// -/// Example creating multiple labeled expressions in a list: -/// ```swift -/// let arguments = LabeledExprListSyntax { +/// // 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 @@ -840,7 +839,7 @@ public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNode /// Instead, use the main initializer that accepts individual components. /// /// - Parameters: - /// - node: An existing syntax node to convert. Must be of kind `.labeledExpr`. + /// - 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 @@ -850,7 +849,8 @@ public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNode /// Creates a new labeled expression with the given components. /// - /// Example creating a labeled string literal argument: + /// ### Example + /// To create a labeled argument for a function call: /// ```swift /// let argument = LabeledExprSyntax( /// label: .identifier("defaultValue"), diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index 3eb1444f650..bc8bb60109a 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2279,18 +2279,20 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf /// A string literal segment that represents plain text content within a string literal expression. /// -/// Used to construct string literals programmatically, especially in macros that need to generate or manipulate string content. For example, in a string literal `"Hello \(name)"`, the `"Hello "` part would be represented by a `StringSegmentSyntax`. +/// 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. For example, when creating a simple string segment: +/// 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")) -/// ``` /// -/// This type is commonly used in macros for: -/// - Creating and validating string literals at compile time (e.g., URL validation) -/// - Building string-based error messages and diagnostics -/// - Generating code that contains string literals -/// - Constructing string interpolations +/// 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. /// @@ -2313,7 +2315,7 @@ public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo /// Instead, use the main initializer that accepts individual components. /// /// - Parameters: - /// - node: An existing syntax node to convert. Must be of kind `.stringSegment`. + /// - 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 @@ -2323,7 +2325,7 @@ public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNo /// Creates a new string segment with the given content and optional trivia. /// - /// Example: + /// ### Example /// ```swift /// let stringLiteral = StringLiteralExprSyntax( /// openingQuote: .stringQuoteToken(), @@ -2335,7 +2337,7 @@ public struct StringSegmentSyntax: 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. /// - 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")` + /// - 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( From 07d1233b68cea1775738810e8f74a0753dc88932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Thu, 19 Dec 2024 21:02:47 +0100 Subject: [PATCH 11/13] Add some matched type documentations to code generation package --- .../Sources/SyntaxSupport/CommonNodes.swift | 22 ++++ .../Sources/SyntaxSupport/ExprNodes.swift | 110 +++++++++++++++++- 2 files changed, 129 insertions(+), 3 deletions(-) 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..b1482ed2dde 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,9 +1847,27 @@ public let EXPR_NODES: [Node] = [ base: .syntax, nameForDiagnostics: nil, documentation: """ - 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: [ Child( From 7b1c82ba4cf7e3d1f2a0e65deabccff0ea9344b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Thu, 19 Dec 2024 21:07:51 +0100 Subject: [PATCH 12/13] Avoid differences in whitespacing with re-generated code --- .../generated/SyntaxBaseNodes.swift | 10 +++++----- .../generated/SyntaxCollections.swift | 19 +++++++++---------- .../generated/syntaxNodes/SyntaxNodesD.swift | 10 +++++----- .../generated/syntaxNodes/SyntaxNodesEF.swift | 8 ++++---- .../syntaxNodes/SyntaxNodesJKLMN.swift | 4 ++-- .../syntaxNodes/SyntaxNodesQRS.swift | 17 +++++++++-------- 6 files changed, 34 insertions(+), 34 deletions(-) diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift index d861bce0dad..77390a83b99 100644 --- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift +++ b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift @@ -455,26 +455,26 @@ 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`` diff --git a/Sources/SwiftSyntax/generated/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 1468a2ddac2..3a8b20a0e07 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -884,11 +884,11 @@ public struct KeyPathComponentListSyntax: SyntaxCollection, SyntaxHashable { /// ``` /// /// ### Children -/// +/// /// ``LabeledExprSyntax`` `*` /// /// ### Contained in -/// +/// /// - ``AttributeSyntax``.``AttributeSyntax/arguments`` /// - ``ExpressionSegmentSyntax``.``ExpressionSegmentSyntax/expressions`` /// - ``FunctionCallExprSyntax``.``FunctionCallExprSyntax/arguments`` @@ -1437,17 +1437,17 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas } /// 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, @@ -1456,11 +1456,11 @@ public struct SpecializeAttributeArgumentListSyntax: SyntaxCollection, SyntaxHas /// ``` /// /// ### Children -/// +/// /// (``StringSegmentSyntax`` | ``ExpressionSegmentSyntax``) `*` /// /// ### Contained in -/// +/// /// - ``StringLiteralExprSyntax``.``StringLiteralExprSyntax/segments`` public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// Represents either a literal string segment or an interpolated expression segment within a string literal. @@ -1487,11 +1487,10 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// /// - SeeAlso: ``ExpressionSegmentSyntax`` case stringSegment(StringSegmentSyntax) - /// An interpolated expression segment inside a string literal. - /// + /// /// This case represents interpolated expressions like `\(name)` in `"Hello \(name)"`. - /// + /// /// - SeeAlso: ``StringSegmentSyntax`` case expressionSegment(ExpressionSegmentSyntax) diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift index 98febdf94e7..0ba1ef38ea2 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesD.swift @@ -606,17 +606,17 @@ 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"), @@ -627,12 +627,12 @@ public struct DeclNameArgumentsSyntax: SyntaxProtocol, SyntaxHashable, _LeafSynt /// ``` /// /// ### Children -/// +/// /// - `baseName`: (`` | `self` | `Self` | `init` | `deinit` | `subscript` | `` | `` | ``) /// - `argumentNames`: ``DeclNameArgumentsSyntax``? /// /// ### Contained in -/// +/// /// - ``DynamicReplacementAttributeArgumentsSyntax``.``DynamicReplacementAttributeArgumentsSyntax/declName`` /// - ``ImplementsAttributeArgumentsSyntax``.``ImplementsAttributeArgumentsSyntax/declName`` /// - ``KeyPathPropertyComponentSyntax``.``KeyPathPropertyComponentSyntax/declName`` diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift index e294b877772..a9a53c69c40 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift @@ -3040,12 +3040,12 @@ 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 @@ -3059,7 +3059,7 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx /// ]), /// rightParen: .rightParenToken() /// ) -/// +/// /// // Creating a function call with labeled arguments /// let call = FunctionCallExprSyntax( /// calledExpression: DeclReferenceExprSyntax(baseName: "String"), @@ -3081,7 +3081,7 @@ public struct ForceUnwrapExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _LeafEx /// ``` /// /// ### Children -/// +/// /// - `calledExpression`: ``ExprSyntax`` /// - `leftParen`: `(`? /// - `arguments`: ``LabeledExprListSyntax`` diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift index 179004e4f20..85b63c5fa6b 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift @@ -821,14 +821,14 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ /// ``` /// /// ### Children -/// +/// /// - `label`: (`` | `_`)? /// - `colon`: `:`? /// - `expression`: ``ExprSyntax`` /// - `trailingComma`: `,`? /// /// ### Contained in -/// +/// /// - ``LabeledExprListSyntax`` public struct LabeledExprSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodeProtocol { public let _syntaxNode: Syntax diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift index bc8bb60109a..01753f648bd 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesQRS.swift @@ -2278,32 +2278,33 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable, _Leaf // MARK: - StringSegmentSyntax /// 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 +/// /// /// ### Children -/// +/// /// - `content`: `` /// /// ### Contained in -/// +/// /// - ``SimpleStringLiteralSegmentListSyntax`` /// - ``StringLiteralSegmentListSyntax`` public struct StringSegmentSyntax: SyntaxProtocol, SyntaxHashable, _LeafSyntaxNodeProtocol { From 33227e12a457f0afd137b8bec9c5d912dd3d1f06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cihat=20Gu=CC=88ndu=CC=88z?= Date: Thu, 19 Dec 2024 21:30:46 +0100 Subject: [PATCH 13/13] Get more documentation comments into the CodeGeneration lib --- .../Sources/SyntaxSupport/ExprNodes.swift | 58 +++++++++++-------- .../generated/SyntaxCollections.swift | 4 +- .../generated/raw/RawSyntaxNodesQRS.swift | 8 ++- .../generated/syntaxNodes/SyntaxNodesEF.swift | 4 +- .../syntaxNodes/SyntaxNodesJKLMN.swift | 6 +- 5 files changed, 48 insertions(+), 32 deletions(-) diff --git a/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift b/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift index b1482ed2dde..d0ad3fe8e06 100644 --- a/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift +++ b/CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift @@ -862,7 +862,7 @@ public let EXPR_NODES: [Node] = [ nameForDiagnostics: nil, documentation: """ An interpolated expression segment inside a string literal. - + This case represents interpolated expressions like `\\(name)` in `"Hello \\(name)"`. - SeeAlso: ``StringSegmentSyntax`` @@ -1847,27 +1847,11 @@ public let EXPR_NODES: [Node] = [ base: .syntax, nameForDiagnostics: nil, documentation: """ - 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")) + A literal text segment inside a string literal. - let stringLiteral = StringLiteralExprSyntax( - openingQuote: .stringQuoteToken(), - segments: StringLiteralSegmentListSyntax([.stringSegment(segment)]), - closingQuote: .stringQuoteToken() - ) - ``` + This case represents static text content like `"Hello "` in `"Hello \\(name)"`. - - 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: [ Child( @@ -2175,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/SyntaxCollections.swift b/Sources/SwiftSyntax/generated/SyntaxCollections.swift index 3a8b20a0e07..d89b0d15ccd 100644 --- a/Sources/SwiftSyntax/generated/SyntaxCollections.swift +++ b/Sources/SwiftSyntax/generated/SyntaxCollections.swift @@ -1482,9 +1482,9 @@ public struct StringLiteralSegmentListSyntax: SyntaxCollection, SyntaxHashable { /// ``` public enum Element: SyntaxChildChoices, SyntaxHashable { /// 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 segment inside a string literal. 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/SyntaxNodesEF.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesEF.swift index a9a53c69c40..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`` /// diff --git a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift index 85b63c5fa6b..b595a548864 100644 --- a/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift +++ b/Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesJKLMN.swift @@ -789,12 +789,12 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ // MARK: - LabeledExprSyntax /// 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 -/// +/// /// ### Examples /// ```swift /// // Creating a labeled argument @@ -803,7 +803,7 @@ public struct KeyPathSubscriptComponentSyntax: SyntaxProtocol, SyntaxHashable, _ /// colon: .colonToken(), /// expression: stringLiteral /// ) -/// +/// /// // Creating a list of labeled arguments /// let arguments = LabeledExprListSyntax([ /// LabeledExprSyntax(