Allow NatSpec tag `@inheritdoc` to be used with contracts
- Dominant language
- C++
- Stars
- 25.7k
- Forks
- 6.2k
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 21
Description
## Motivation
Many Ethereum-based protocols, such Uniswap, choose to document their functions only in their interface files, [applying the `@inheritdoc` NatSpec tag in the implementation functions](https://twitter.com/PaulRBerg/status/1536002060818305024).
It would be nice to be able to do the same thing for contracts themselves, i.e. keep the documentation in the interface, and apply `@inheritdoc` in the implementation. This would help with:
1. Avoid duplication.
2. Automate documentation generation with tools like `forge doc`
Applying this tag to contracts with the latest version of Solidity (v0.8.19 at the time of posting this) produces the following error:
> Documentation tag @inheritdoc not valid for contracts.
## Specification
```solidity
/// @notice This is my interface
interface MyInterface {}
/// @inheritdoc MyInterface
contract MyContract is MyInterface {}
```
## Backwards Compatibility
Adding support for this should be entirely backward-compatible.
Contributor guide
Research direction
Start by locating the NatSpec validation that emits “Documentation tag @inheritdoc not valid for contracts.” Use the Solidity example in the specification as the acceptance case, and verify that contract documentation can be inherited for documentation generation such as forge doc without breaking existing validation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- solidity
- Domain
- compilers
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100