Skip to content

style: standardise NatSpec on the block comment form - #42

Merged
mfw78 merged 1 commit into
developfrom
style/natspec-block-form
Jul 30, 2026
Merged

style: standardise NatSpec on the block comment form#42
mfw78 merged 1 commit into
developfrom
style/natspec-block-form

Conversation

@mfw78

@mfw78 mfw78 commented Jul 30, 2026

Copy link
Copy Markdown

The tree mixed /// and /** */ NatSpec, and in sixteen files both forms appeared side by side. Standardise on the block form:

  • 57 declaration-level /// runs converted to /** */ across src, test and script
  • block form was already the majority (85 of 142 declaration-level doc comments) and is what the newer interface and handler work in this stack already uses
  • records the rule in docs/style.md so it does not drift again

Deliberately 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-line directive sat in the middle of a /// run in GPv2TradeEncoder.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:

git diff chore/solc-0830-toolchain..style/natspec-block-form -U0 \
  | grep '^[+-]' | grep -v '^\(+++\|---\)' \
  | grep -v '^[+-][[:space:]]*\(///\|/\*\*\|\*/\|\*\)'

That prints nothing: no non-comment line is touched. forge build and forge test are green (74 passing).

Part of #1.

@mfw78
mfw78 force-pushed the style/natspec-block-form branch from 70b5168 to 7a1ee66 Compare July 30, 2026 04:01
@mfw78
mfw78 marked this pull request as ready for review July 30, 2026 06:52
@mfw78
mfw78 force-pushed the chore/solc-0830-toolchain branch from 80f9709 to 70ddd7a Compare July 30, 2026 06:59
@mfw78
mfw78 force-pushed the style/natspec-block-form branch from 7a1ee66 to 5238224 Compare July 30, 2026 06:59
Base automatically changed from chore/solc-0830-toolchain to develop July 30, 2026 07:00
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
mfw78 force-pushed the style/natspec-block-form branch from 5238224 to ce53cef Compare July 30, 2026 07:02
@mfw78
mfw78 merged commit 408a491 into develop Jul 30, 2026
@mfw78
mfw78 deleted the style/natspec-block-form branch July 30, 2026 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant