Skip to content

Make generated files // swift-format-ignore #738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
weissi opened this issue Feb 15, 2025 · 9 comments · Fixed by #773
Closed

Make generated files // swift-format-ignore #738

weissi opened this issue Feb 15, 2025 · 9 comments · Fixed by #773
Labels
area/generator Affects: plugin, CLI, config file. good first issue Good for newcomers kind/enhancement Improvements to existing feature.
Milestone
Post-1.0

Comments

@weissi
Copy link
Member

weissi commented Feb 15, 2025

Description

I have generated files & swift-format. I don't want the formatter to reformat the generated code though. So it'd be awesome if it could generate a line with // swift-format-ignore which will disable formatting for that file.

Reproduction

N/a

Package version(s)

All

Expected behavior

No formatting

Environment

All

Additional information

No response
@weissi weissi added kind/bug Feature doesn't work as expected. status/triage Collecting information required to triage the issue. labels Feb 15, 2025
@czechboy0 czechboy0 added area/generator Affects: plugin, CLI, config file. kind/enhancement Improvements to existing feature. good first issue Good for newcomers and removed kind/bug Feature doesn't work as expected. status/triage Collecting information required to triage the issue. labels Feb 15, 2025
@czechboy0 czechboy0 added this to the Post-1.0 milestone Feb 15, 2025
@simonjbeaumont
Copy link
Collaborator

Sounds good.

Are we happy for it to be behind a config option for those that do want to include the generated files in their format?

@MahdiBM
Copy link
Contributor

MahdiBM commented Feb 15, 2025

This is probably the better solution although we could have something in the meanwhile.
We use .swiftformatignore in different projects for now, which has turned out to be fine. The formatting script in .github-workflows repo has been configured to use .swiftformatignore. swift-format itself doesn't really care about it.

@simonjbeaumont
Copy link
Collaborator

I agree that swift-format would benefit from ignore support in its own config file. You’re right that the reusable GitHub workflows have support for this already, but I don’t think we can expect that all adopters use these. @weissi presumably you don’t use the reusable script since you filed the issue?

@weissi
Copy link
Member Author

weissi commented Feb 26, 2025

I agree that swift-format would benefit from ignore support in its own config file. You’re right that the reusable GitHub workflows have support for this already, but I don’t think we can expect that all adopters use these. @weissi presumably you don’t use the reusable script since you filed the issue?

Correct, not using those. I'm fine with a configuration option to turn on/off // swift-format-ignore comments in gen'd files.

@MahdiBM
Copy link
Contributor

MahdiBM commented Feb 26, 2025 •
edited
Loading

That'd be fine with me, I'd just make sure it's not tied to swift-format.

Maybe a "top-level-comments" property, then users can specify "swift-format-ignore".
+ good docs.

@FranzBusch
Copy link
Member

FWIW swift-protobuf generates both swift-format and SwiftLint comments automatically

@simonjbeaumont
Copy link
Collaborator

@MahdiBM wrote:

That'd be fine with me, I'd just make sure it's not tied to swift-format.

Maybe a "top-level-comments" property, then users can specify "swift-format-ignore". + good docs.

I'm less inclined to make this super generalisable. Seems like an odd thing for folks to be inserting arbitrary things at the top of the generated file and, while I would be sympathetic to not wanting to over-index on one tool if we had an ecosystem of tens of linters, swift-format is now in the Swift toolchain so IMHO we could just add this unilaterally.

Sounds like @FranzBusch agrees (#738 (comment)) and if Swift Protobuf is doing this, then I'm inclined for us to.

What do others think. I know I originally suggested we make this configurable but maybe we should just add the comment(s) unilaterally? Any objections?

@MahdiBM
Copy link
Contributor

MahdiBM commented Mar 11, 2025 •
edited
Loading

@simonjbeaumont

swift-format is now in the Swift toolchain so IMHO we could just add this unilaterally.

I wish swift-format was good enough so one can just use it and not worry about much else, but in its current form it has some pretty bad formatting behaviors so I'm not excited to get the whole ecosystem locked on it. It would have been fine by me if swift-format could actually do its job properly.

See this about possibility of support for other formatters in sourcekit-lsp.

@simonjbeaumont
Copy link
Collaborator

If we're really against just hardcoding it, then I guess an additionalFileComments: could live alongside the additionalImports: config file option. Probably a list of strings, each of which becomes its own line comment.

additionalFileComments:
  - "swift-format-ignore-file"
  - "swiftlint:disable all"
  - "mumble mumble mumble"
// swift-format-ignore-file
// swiftlint:disable all
// mumble mumble mumble

We haven't had many requests for it, so as long as there's a way to it, for those that want it, I'm pretty flexible on how.

simonjbeaumont added a commit to simonjbeaumont/swift-openapi-generator that referenced this issue May 23, 2025
@simonjbeaumont
Add support for configurable comments in generated files
0964f1c 
Users want the ability to add custom comments to generated files. One
concrete use case is adding directives like `swift-format-ignore-file`
and `swiftlint:disable all` to prevent these tools from processing
generated code.

- Added `additionalFileComments` property to `Config` and `UserConfig` structs
- Modified `FileTranslator` to include additional comments along with the do-not-edit comment
- Added CLI support with `--additional-file-comment` option
- Added config tests to confirm the option propagates and the default is empty
- Added snippet tests to validate the actual rendering
- Updated documentation with examples and usage instructions

Users can now configure additional comments to be added to generated
files using either the config file or a command line option.

Fixes apple#738.

- Added unit tests for `Config`
- Added snippet tests for rendering
- Manual tests of generator using config and CLI on real OpenAPI doc:

```console
% swift run swift-openapi-generator generate openapi-documents/petstore.yaml \
  --mode types \
  --output-directory test-output-cli \
  --additional-file-comment "hello world" \
  --additional-file-comment "testing, testing, 1, 2, 3"
Build of product 'swift-openapi-generator' complete! (3.27s)
Swift OpenAPI Generator is running with the following configuration:
- OpenAPI document path: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/openapi-documents/petstore.yaml
- Configuration path: <none>
- Generator modes: types
- Access modifier: internal
- Naming strategy: defensive
- Name overrides: <none>
- Feature flags: <none>
- Output file names: Types.swift
- Output directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator/test-output-cli
- Diagnostics output path: <none - logs to stderr>
- Current directory: /Users/Si/work/code/swift-openapi-workspace/packages/swift-openapi-generator
- Plugin source: <none>
- Is dry run: false
- Additional imports: <none>
- Additional file comments: hello world, testing, testing, 1, 2, 3
Writing data to file Types.swift...

% head -5 test-output-cli/Types.swift
// Generated by swift-openapi-generator, do not modify.
// hello world
// testing, testing, 1, 2, 3
@_spi(Generated) import OpenAPIRuntime
```
@simonjbeaumont simonjbeaumont mentioned this issue May 23, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area/generator Affects: plugin, CLI, config file. good first issue Good for newcomers kind/enhancement Improvements to existing feature.
Projects
None yet
Milestone
Post-1.0
Development

Successfully merging a pull request may close this issue.

Add support for configurable comments in generated files simonjbeaumont/swift-openapi-generator
5 participants
@weissi @simonjbeaumont @czechboy0 @FranzBusch @MahdiBM