docs(natspec): add @param operand, @return, and rounding direction to ConvertToAssets/Shares run()

[thedavidmeister]

Both LibOpERC4626ConvertToAssets.run and LibOpERC4626ConvertToShares.run were missing @param operand for the unnamed OperandV2 parameter and @return describing the single-element output. ConvertToShares.run also had no note on EIP-4626's floor-rounding direction.

• Name the OperandV2 parameter operand so the @param tag resolves.
• Add @return to both functions describing the single-element [... as Float] output.
• Add a rounding-direction sentence to ConvertToShares.run: EIP-4626 mandates convertToShares rounds DOWN (toward zero), favouring the vault.

Closes #94
Closes #101
Closes #110

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Clarified ERC-4626 conversion behavior and data formats in the asset/share conversion operations.
  • Improved guidance on expected inputs and outputs, including rounding behavior and decimal handling.
  • Named an unused parameter in the public interface for consistency and readability.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 037d33e9-e38e-4c2b-b0eb-116f860c7a11

📥 Commits

Reviewing files that changed from the base of the PR and between 70b2aa5 and 5a8784f.

📒 Files selected for processing (2)

• src/lib/op/erc4626/LibOpERC4626ConvertToAssets.sol
• src/lib/op/erc4626/LibOpERC4626ConvertToShares.sol

---

Walkthrough

This PR updates NatSpec documentation in two ERC-4626 operation libraries. The previously unnamed OperandV2 parameter in each run function is now named operand, and comments clarify input/output stack formats, decimal semantics, and rounding behavior (EIP-4626 rounds down, favoring the vault). No functional logic changes.

Changes

ERC-4626 Convert NatSpec Updates

Layer / File(s)	Summary
ConvertToAssets documentation src/lib/op/erc4626/LibOpERC4626ConvertToAssets.sol	Named the OperandV2 parameter operand and clarified NatSpec describing vault address, shares as Float, and assets output at underlying token decimals.
ConvertToShares documentation src/lib/op/erc4626/LibOpERC4626ConvertToShares.sol	Named the OperandV2 parameter operand and clarified NatSpec describing rounding-down behavior per EIP-4626 and decimal semantics of inputs/outputs.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

• run() missing @return and @param for operand #94: Requests adding missing @param and @return NatSpec tags to LibOpERC4626ConvertToAssets.run(), directly addressed by this PR.
• Documentation omits rounding direction of convertToShares #101: Requests documenting rounding direction for convertToShares, directly addressed by this PR's updated comments.
• run NatSpec omits the OperandV2 param and the @return, mislabels input semantics #110: Requests naming the operand parameter and adding @return/@param docs for LibOpERC4626ConvertToShares.run(), directly addressed by this PR.
• Rounding direction of convertToShares is undocumented and uncontrolled relative to the non-interactive-party rule #109: Concerns rounding-direction documentation gap addressed by the ConvertToShares doc updates in this PR.
• run() missing @return and operand @param documentation #111: Concerns missing @param/@return docs for LibOpERC4626ConvertToShares.run() addressed by this PR.
• Vault address and returned assets value are taken from an untrusted vault with no bounds/sanity checks (view-reentrancy / adversarial return #99: Concerns documentation gaps in LibOpERC4626ConvertToAssets.run() addressed by this PR's NatSpec-only update.

Possibly related PRs

• rainlanguage/rain.erc4626.words#168: Adds edge-case tests for convertToShares behavior, related to the ConvertToShares documentation updates in this PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the NatSpec documentation updates to the ERC-4626 conversion ops.
Linked Issues check	✅ Passed	The PR appears to satisfy #94, #101, and #110 by naming operand, adding return docs, fixing input semantics, and documenting rounding.
Out of Scope Changes check	✅ Passed	The changes stay within the documented NatSpec-only scope for the ERC-4626 conversion operations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2026-07-02-issue-94-101-110-run-natspec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}