Add rule to place doc comments before any attributes #281
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
calda
commented
Jul 26, 2024
Member
Author
calda
left a comment
There was a problem hiding this comment.
Strong internal support for this rule 👍🏻
bachand
approved these changes
Jul 26, 2024
README.md
Outdated
|
|
||
| </details> | ||
|
|
||
| * <a id='doc-comments-before-attributes'></a>(<a href='#doc-comments-before-declarations'>link</a>) **Place doc comments for a declaration before any attributes.** [](https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md#docCommentsBeforeAttributes) |
Contributor
There was a problem hiding this comment.
I like the placement of the rule below a similar rule 👍
Comment on lines
+1881
to
+1887
| /// A spacecraft with everything you need to explore the universe. | ||
| struct Spaceship { … } | ||
|
|
||
| // RIGHT | ||
|
|
||
| /// A spacecraft with everything you need to explore the universe. | ||
| @MainActor |
Contributor
There was a problem hiding this comment.
Does this apply to property wrappers and builtin attributes like @objc or @dynamicMemberLookup as well?
Member
Author
There was a problem hiding this comment.
Yes! It applies to everything that starts with an @.
(In the Swift grammar everything that starts with an @ is an attribute -- you can confirm this by searching for @ in the grammar documentation and seeing that it only appears once, as the start of an attribute.)
Co-authored-by: Michael Bachand <michael.bachand@airbnb.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a new rule to place doc comments for a declaration before any attributes on the declaration.
Autocorrect support is implemented in the SwiftFormat
docCommentsBeforeAttributesrule, which was added in nicklockwood/SwiftFormat#1766.Reasoning
Placing the doc comment before any attributes is the most common practice, but I noticed some examples in our codebase where the doc comment is between the attributes and the rest of the declaration.
On the tooling side, Xcode correctly handles doc comments placed above attributes (see how the doc comment shows up in the inspector on the right):
But doesn't correctly handle doc comments placed after the attributes (see how the doc comment doesn't show up in the inspector on the right):