Add a convenience init to ClosureCaptureSyntax #2127

natikgadzhi · 2023-08-31T20:35:44Z

Summary

This adds a convenience init to ClosureCaptureSyntax that adds an equal token if the provided name is not nil.

It's supposed to be used by developers, so it omits the unexpected tokens.

Related: #1984

ahoppen

Could you add an entry for this PR and #2112 to the new release notes file https://github.com/apple/swift-syntax/blob/main/Release%20Notes/510.md?

Provides release notes entries for: - `ClosureCaptureSyntax.init` apple#2127 - `EnumCaseParameterSyntax.init` apple#2112

natikgadzhi · 2023-08-31T23:16:43Z

@ahoppen done: 23c2098

kimdv · 2023-09-01T05:51:39Z

@swift-ci please test

Matejkob

Thanks for the updates—great work! My internal nitpick radar 📡 kicked in, so I've left a few comments. Not sure how helpful they are, but there you go! 🙈

Matejkob · 2023-09-01T06:48:30Z

Release Notes/510.md

+- `ClosureCaptureSyntax.init(leadingTrivia: Trivia? = nil, specifier: ClosureCaptureSpecifierSyntax? = nil, name: TokenSyntax, equal: TokenSyntax = TokenSyntax.equalToken(), expression: some ExprSyntaxProtocol, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`
+  - Description: Provides a convenience initializer for `ClosureCaptureSyntax` that takes a concrete `name` argument and automatically adds `equal = TokenSyntax.equalToken()` to it.
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2127
+- `EnumCaseParameterSyntax.init(leadingTrivia: Trivia? = nil, modifiers: DeclModifierListSyntax = [], firstName: TokenSyntax, secondName: TokenSyntax? = nil, colon: TokenSyntax = TokenSyntax.colonToken(), type: some TypeSyntaxProtocol, defaultValue: InitializerClauseSyntax? = nil, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`
+  - Description: Provides a convenience initializer for `EnumCaseParameterSyntax` that takes a concrete `firstName` value and adds `colon = TokenSyntax.colonToken()` automatically to it.
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2112


The issue related to these changes contains important information about the new APIs. I would consider adding a link to it, as stated in the template below. What do you think about it?

Suggested change

- `ClosureCaptureSyntax.init(leadingTrivia: Trivia? = nil, specifier: ClosureCaptureSpecifierSyntax? = nil, name: TokenSyntax, equal: TokenSyntax = TokenSyntax.equalToken(), expression: some ExprSyntaxProtocol, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`

- Description: Provides a convenience initializer for `ClosureCaptureSyntax` that takes a concrete `name` argument and automatically adds `equal = TokenSyntax.equalToken()` to it.

- Pull Request: https://github.com/apple/swift-syntax/pull/2127

- `EnumCaseParameterSyntax.init(leadingTrivia: Trivia? = nil, modifiers: DeclModifierListSyntax = [], firstName: TokenSyntax, secondName: TokenSyntax? = nil, colon: TokenSyntax = TokenSyntax.colonToken(), type: some TypeSyntaxProtocol, defaultValue: InitializerClauseSyntax? = nil, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`

- Description: Provides a convenience initializer for `EnumCaseParameterSyntax` that takes a concrete `firstName` value and adds `colon = TokenSyntax.colonToken()` automatically to it.

- Pull Request: https://github.com/apple/swift-syntax/pull/2112

- `ClosureCaptureSyntax.init(leadingTrivia: Trivia? = nil, specifier: ClosureCaptureSpecifierSyntax? = nil, name: TokenSyntax, equal: TokenSyntax = TokenSyntax.equalToken(), expression: some ExprSyntaxProtocol, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`

- Description: Provides a convenience initializer for `ClosureCaptureSyntax` that takes a concrete `name` argument and automatically adds `equal = TokenSyntax.equalToken()` to it.

- Issue: https://github.com/apple/swift-syntax/issues/1984

- Pull Request: https://github.com/apple/swift-syntax/pull/2127

- `EnumCaseParameterSyntax.init(leadingTrivia: Trivia? = nil, modifiers: DeclModifierListSyntax = [], firstName: TokenSyntax, secondName: TokenSyntax? = nil, colon: TokenSyntax = TokenSyntax.colonToken(), type: some TypeSyntaxProtocol, defaultValue: InitializerClauseSyntax? = nil, trailingComma: TokenSyntax? = nil, trailingTrivia: Trivia? = nil)`

- Description: Provides a convenience initializer for `EnumCaseParameterSyntax` that takes a concrete `firstName` value and adds `colon = TokenSyntax.colonToken()` automatically to it.

- Issue: https://github.com/apple/swift-syntax/issues/1984

- Pull Request: https://github.com/apple/swift-syntax/pull/2112

Yes, I think linking the issue would be valuable.

Also, I think the full API signature isn’t that enlightening. What I would do instead is name the items

ClosureCaptureSyntax.init with a required name

EnumCaseParameterSyntax.init with a required firstName

How about incorporating release notes into the DocC documentation for SwiftSyntax package? With this approach, it would be really easy to add direct links to specific methods right in the code.

The problem is that we would need to decide which module to put the release notes in. If we put it in the SwiftSyntax module, you can’t link to any API in e.g. SwiftParser. Since the release notes are for the entire package and not one specific module, I think having them at a top-level makes sense for now.

I wasn't aware of this restriction that you can't link to any API from a different target. That's unfortunate. :/

FWIW apple/swift-docc#208 is tracking this restriction.

Thank you both for the review! I'll clean up the changelog for now. Hopefully, I can get a generator-based version quickly enough and clean them up altogether in a few days.

Sources/SwiftSyntax/Convenience.swift

**Summary** This adds a convenience init to ClosureCaptureSyntax that adds equal token if the provided `name` is not nil. It's supposed to be used by developers, so it omits the unexpected tokens. Related: apple#1984

Provides release notes entries for: - `ClosureCaptureSyntax.init` apple#2127 - `EnumCaseParameterSyntax.init` apple#2112 Co-authored-by: Mateusz Bąk <bakmatthew@icloud.com>

natikgadzhi · 2023-09-01T20:42:46Z

Alright! Should be good to go for this PR.

ahoppen · 2023-09-01T20:51:38Z

@swift-ci Please test

ahoppen · 2023-09-01T20:55:19Z

@swift-ci Please test Windows

ahoppen · 2023-09-02T01:20:12Z

@swift-ci Please test macOS

ahoppen · 2023-09-02T01:20:20Z

@swift-ci Please test Windows

natikgadzhi requested a review from ahoppen as a code owner August 31, 2023 20:35

natikgadzhi mentioned this pull request Aug 31, 2023

Add initializer to LabeledExprSyntax that automatically adds a colon if the label exists #1984

Open

ahoppen reviewed Aug 31, 2023

View reviewed changes

natikgadzhi added a commit to natikgadzhi/swift-syntax that referenced this pull request Aug 31, 2023

Provides release notes entries for new APIs

23c2098

Provides release notes entries for: - `ClosureCaptureSyntax.init` apple#2127 - `EnumCaseParameterSyntax.init` apple#2112

kimdv approved these changes Sep 1, 2023

View reviewed changes

Matejkob reviewed Sep 1, 2023

View reviewed changes

Add a convenience init to ClosureCaptureSyntax

8fb3713

**Summary** This adds a convenience init to ClosureCaptureSyntax that adds equal token if the provided `name` is not nil. It's supposed to be used by developers, so it omits the unexpected tokens. Related: apple#1984

natikgadzhi force-pushed the syntax/convenience/closure-capture branch from 4d6c9b0 to 440b6da Compare September 1, 2023 20:40

Provides release notes entries for new APIs

a9acb00

Provides release notes entries for: - `ClosureCaptureSyntax.init` apple#2127 - `EnumCaseParameterSyntax.init` apple#2112 Co-authored-by: Mateusz Bąk <bakmatthew@icloud.com>

natikgadzhi force-pushed the syntax/convenience/closure-capture branch from 440b6da to a9acb00 Compare September 1, 2023 20:42

ahoppen approved these changes Sep 1, 2023

View reviewed changes

ahoppen enabled auto-merge September 1, 2023 20:51

natikgadzhi mentioned this pull request Sep 1, 2023

WIP: Make convenience initializers with CodeGeneration #2142

Draft

8 tasks

ahoppen merged commit 6a00dbe into apple:main Sep 2, 2023
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a convenience init to ClosureCaptureSyntax #2127

Add a convenience init to ClosureCaptureSyntax #2127

natikgadzhi commented Aug 31, 2023

ahoppen left a comment

natikgadzhi commented Aug 31, 2023

kimdv commented Sep 1, 2023

Matejkob left a comment

Matejkob Sep 1, 2023

ahoppen Sep 1, 2023

Matejkob Sep 1, 2023

ahoppen Sep 1, 2023

Matejkob Sep 1, 2023

ahoppen Sep 1, 2023

natikgadzhi Sep 1, 2023

natikgadzhi commented Sep 1, 2023

ahoppen commented Sep 1, 2023

ahoppen commented Sep 1, 2023

ahoppen commented Sep 2, 2023

ahoppen commented Sep 2, 2023

Add a convenience init to ClosureCaptureSyntax #2127

Add a convenience init to ClosureCaptureSyntax #2127

Conversation

natikgadzhi commented Aug 31, 2023

Summary

ahoppen left a comment

Choose a reason for hiding this comment

natikgadzhi commented Aug 31, 2023

kimdv commented Sep 1, 2023

Matejkob left a comment

Choose a reason for hiding this comment

Matejkob Sep 1, 2023

Choose a reason for hiding this comment

ahoppen Sep 1, 2023

Choose a reason for hiding this comment

Matejkob Sep 1, 2023

Choose a reason for hiding this comment

ahoppen Sep 1, 2023

Choose a reason for hiding this comment

Matejkob Sep 1, 2023

Choose a reason for hiding this comment

ahoppen Sep 1, 2023

Choose a reason for hiding this comment

natikgadzhi Sep 1, 2023

Choose a reason for hiding this comment

natikgadzhi commented Sep 1, 2023

ahoppen commented Sep 1, 2023

ahoppen commented Sep 1, 2023

ahoppen commented Sep 2, 2023

ahoppen commented Sep 2, 2023