OpenZeppelin / OpenZeppelin/openzeppelin-contracts
Improve NatSpec readability for inherited method references in generated docs
Nobody has claimed this yet.
- Dominant language
- Solidity
- Stars
- 27.2k
- Forks
- 12.4k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 33
Description
Summary
Some NatSpec comments currently rely on references such as See {IERC20-transfer}. This is correct from a Solidity/NatSpec perspective, but several downstream tools and explorers that consume ABI/userdoc/devdoc metadata do not resolve those references when rendering contract methods.
As a result, users may see a method description like:
See {IERC20-transfer}. Requirements: -
tocannot be the zero address. - the caller must have a balance of at leastvalue.
instead of a self-contained explanation of what the method does.
Why this matters
NatSpec is often surfaced directly by tools, dashboards, explorers, and contract interaction UIs to help users understand what a function does before calling it. When the rendered text points to another method that the UI does not resolve, the documentation becomes less useful for end users.
This is especially visible for common ERC20 methods such as transfer, where the main behavior is hidden behind an unresolved reference while only the requirements are shown inline.
Suggested improvement
Would it make sense to make the comments more explicit in the implementation contracts, instead of relying on references that many tools do not resolve?
For example, either:
- Use a self-contained description for public-facing method documentation, or
- Add an explicit
@noticefor the user-facing behavior and keep technical details / inheritance references in@dev.
Possible direction:
/**
* @notice Transfers `value` tokens from the caller to `to`.
* @dev See {IERC20-transfer}.
*
* Requirements:
*
* - `to` cannot be the zero address.
* - the caller must have a balance of at least `value`.
*/
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the implementation contracts whose NatSpec comments reference IERC20-transfer, then inspect how those comments appear in ABI, userdoc, and devdoc metadata. Update the public-facing documentation so the rendered method description is self-contained, while preserving technical inheritance references where appropriate; verify the generated documentation output no longer depends on unresolved references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- solidity
- Domain
- blockchain, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100