argotorg / argotorg/solidity

Allow NatSpec tag `@inheritdoc` to be used with contracts

Open
#14,045 3 comments 0 reactions 0 assignees View on GitHub
medium effort medium impact must have eventually
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.