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: - to cannot be the zero address. - the caller must have a balance of at least value.
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
@notice for 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`.
*/
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:
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:
@noticefor the user-facing behavior and keep technical details / inheritance references in@dev.Possible direction: