Skip to content

docs(natspec): apply house documentation standard across all contracts - #25

Merged
jayeshy14 merged 1 commit into
mainfrom
docs/natspec-standard
Jul 29, 2026
Merged

docs(natspec): apply house documentation standard across all contracts#25
jayeshy14 merged 1 commit into
mainfrom
docs/natspec-standard

Conversation

@jayeshy14

Copy link
Copy Markdown
Owner

Extends the NatSpec + section-banner standard you started by hand in CPPIVault.sol to the entire codebase.

What changed

  • Boxed section banners on every file, replacing the old // ---- x ---- dividers.
  • Per-member NatSpec on every state var, constant, struct (+ @param per field), event (+ @param per param), and error.
  • Full function NatSpec@notice + @param for every argument + @return for every return value — on every external/public/internal function across all 15 source files.
  • IOracleHealth extracted into src/interfaces/IOracleHealth.sol (fixing the IOracleHeath filename typo) and imported into CPPIVault.
  • Trailing inline comments promoted to NatSpec above their declaration.

Preserved deliberately

  • Every audit reference and rationale kept verbatim in meaning (H1/H2, H3, H5, H6, M1, M2, M3, M4, L1–L8, I1–I3, G2 guard).
  • No code, signatures, logic, or ordering changed.

Two benign, intentional deviations from "comments only"

  1. The IOracleHealth interface extraction/rename (you initiated this).
  2. Named previously-unnamed interface return values (e.g. returns (uint256)returns (uint256 valueWad)) so @return tags bind. Return names are not part of the ABI, so this is semantically inert.

Verification

  • forge build clean.
  • 151 / 151 tests pass (proves no behavior changed).
  • A declaration scan reports 0 undocumented functions/events/errors/structs across src/.
  • A diff filter confirms the only non-comment code deltas are the two deviations above.

Docs only.

Extends the NatSpec/section-banner standard (started by hand in CPPIVault) to
every source file: boxed section banners, per-member NatSpec on state vars,
structs, events and errors, and full @notice/@param/@return on every function.

- Extract IOracleHealth into its own interface file (fixing the IOracleHeath
  filename typo) and import it in CPPIVault.
- Promote trailing inline comments to NatSpec above each declaration.
- Preserve every audit reference and rationale verbatim in meaning (H1/H2, H3,
  H5, H6, M1, M2, M3, M4, L1-L8, I1-I3, G2).
- Name previously-unnamed interface return values so @return can bind (inert:
  return names are not part of the ABI).

Comments only; no logic, signatures, or ordering changed. forge build clean,
all 151 tests pass, 0 undocumented declarations remaining.
@jayeshy14
jayeshy14 merged commit b8c94e7 into main Jul 29, 2026
3 checks passed
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