style: standardise NatSpec on the block comment form - #42
Merged
Conversation
mfw78
force-pushed
the
style/natspec-block-form
branch
from
July 30, 2026 04:01
70b5168 to
7a1ee66
Compare
mfw78
marked this pull request as ready for review
July 30, 2026 06:52
mfw78
force-pushed
the
chore/solc-0830-toolchain
branch
from
July 30, 2026 06:59
80f9709 to
70ddd7a
Compare
mfw78
force-pushed
the
style/natspec-block-form
branch
from
July 30, 2026 06:59
7a1ee66 to
5238224
Compare
The tree mixed `///` and `/** */` NatSpec, and in sixteen files both forms appeared side by side. Standardise on the block form, already the majority (85 of 142 declaration-level doc comments) and the form used throughout the most recent interface and handler work. Only declaration-level doc comments are rewritten. solc ignores NatSpec tags inside a function body, so those are implementation comments rather than documentation, and converting a one-line note into a three-line block there would make the code harder to read, not easier. They are addressed separately. The change is comment-only: no non-comment line is modified, and the compiler output is unchanged. Records the rule in docs/style.md so it does not drift again.
mfw78
force-pushed
the
style/natspec-block-form
branch
from
July 30, 2026 07:02
5238224 to
ce53cef
Compare
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
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.
The tree mixed
///and/** */NatSpec, and in sixteen files both forms appeared side by side. Standardise on the block form:///runs converted to/** */acrosssrc,testandscriptdocs/style.mdso it does not drift againDeliberately out of scope: comments inside a function body. solc ignores NatSpec tags there, so those are implementation comments rather than documentation, and expanding a one-line note into a three-line block would make the code harder to read. There are 16 of them and they are handled separately at the tip of the stack, so that PR can be dropped independently.
One case needed care: a
solhint-disable-next-linedirective sat in the middle of a///run inGPv2TradeEncoder.sol. Converting naively split the header into two blocks, which silently orphans the leading one, because only the block immediately preceding a declaration is NatSpec. The halves are rejoined and the directive dropped (solhint is not configured or run anywhere in this repo).How to test
The change is comment-only, which is machine-checkable:
That prints nothing: no non-comment line is touched.
forge buildandforge testare green (74 passing).Part of #1.