Skip to content

fix: correct NatSpec tags, typo, and parameter naming#287

Open
memosr wants to merge 1 commit into
base:mainfrom
memosr:fix/natspec-and-naming-issues
Open

fix: correct NatSpec tags, typo, and parameter naming#287
memosr wants to merge 1 commit into
base:mainfrom
memosr:fix/natspec-and-naming-issues

Conversation

@memosr
Copy link
Copy Markdown

@memosr memosr commented May 15, 2026

Summary

Three small but real fixes across dispute game and system config contracts.

Changes

1. @notice@param for _disputed parameter (2 files)

The wrong tag type means NatSpec tooling (forge doc, etherscan) renders these parameters as undocumented while the description shows up as a stray contract notice.

src/L1/proofs/v2/FaultDisputeGameV2.sol (line 567, defend()):

- /// @notice _disputed The `Claim` being defended.
+ /// @param _disputed The `Claim` being defended.

src/L1/proofs/v2/PermissionedDisputeGameV2.sol (line 52, move()):

- /// @notice _disputed The disputed `Claim`.
+ /// @param _disputed The disputed `Claim`.

The sibling attack() function already uses the correct @param _disputed tag, making the inconsistency obvious.

2. Typo: PreimageOralcePreimageOracle

src/L1/proofs/v2/FaultDisputeGameV2.sol (line 575):

- /// @notice Posts the requested local data to the VM's `PreimageOralce`.
+ /// @notice Posts the requested local data to the VM's `PreimageOracle`.

The contract name is misspelled in a backtick-wrapped type reference, which would render as a broken link in generated docs.

3. Parameter naming: _dAFootprintGasScalar_daFootprintGasScalar

src/L1/SystemConfig.sol (lines 479-482):

- function _setDAFootprintGasScalar(uint16 _dAFootprintGasScalar) internal {
-     daFootprintGasScalar = _dAFootprintGasScalar;
-     bytes memory data = abi.encode(_dAFootprintGasScalar);
+ function _setDAFootprintGasScalar(uint16 _daFootprintGasScalar) internal {
+     daFootprintGasScalar = _daFootprintGasScalar;
+     bytes memory data = abi.encode(_daFootprintGasScalar);

The "DA" abbreviation should be a single lowercase prefix in camelCase. The public wrapper, the storage variable (daFootprintGasScalar), and the NatSpec @param tag at line 473 all use the lowercase-a form. This was likely a copy-paste error where "DA" was typed as two separate letters.

Verification

  • ✅ All changes verified locally
  • ✅ Only the 3 specified files touched
  • ✅ Internal naming consistency confirmed against existing patterns in each file

Three small but real fixes in dispute-game and system config contracts:

1. FaultDisputeGameV2.sol (line 567) and PermissionedDisputeGameV2.sol
   (line 52) — Change @notice to @param for the _disputed parameter.
   The wrong tag means NatSpec tooling renders the parameter as
   undocumented and treats the description as a stray contract notice.

2. FaultDisputeGameV2.sol (line 575) — Fix backtick-wrapped type
   reference PreimageOralce → PreimageOracle.

3. SystemConfig.sol (lines 479-482) — Rename internal function parameter
   _dAFootprintGasScalar → _daFootprintGasScalar to match the public
   wrapper, the storage variable, and the NatSpec @param tag at line 473.
@cb-heimdall
Copy link
Copy Markdown
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 1
Sum 2

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.

2 participants