OpenZeppelin / OpenZeppelin/openzeppelin-contracts

Improve NatSpec readability for inherited method references in generated docs

Open
#6,595 1 comment 0 reactions 0 assignees View on GitHub

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.

Image

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:

  1. Use a self-contained description for public-facing method documentation, or
  2. 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`.
 */

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.