`@inheritdoc` tag in Natspec does not stop at the end of the line
- Dominant language
- C++
- Stars
- 25.7k
- Forks
- 6.2k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 29
Description
## Description
I have a contract that inherits and `interface` and its Natspec documentation. The implementation function from the interface inherits the Natspec docs from the function interface using `@inheritdoc InterfaceName`.
In addition to that, I add some custom `@dev` docs on top of the implementation function.
The problem is it does not compile depending if the `@inheritdoc InterfaceName` is placed at the top and there is a space in between the `@inheritdoc` and the `@dev` tags.
## Environment
- Compiler version: 0.8.19
- Target EVM version (as per compiler settings):
- Framework/IDE (e.g. Truffle or Remix): Hardhat
- EVM execution environment / backend / blockchain client:
- Operating system:
## Steps to Reproduce
Here is my interface.
```solidity
interface ITest {
/// @notice Explain to an end user what this does
/// @dev Explain to a developer any extra details
/// @return Documents the return variables of a contract’s function state variable
function test() external pure returns (bool);
}
```
This will not compile ❌
```solidity
// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;
import {ITest} from "./ITest.sol";
contract MyTest is ITest {
/**
* @inheritdoc ITest
*
* @dev some extra details
*/
function test() external pure override returns (bool) {
return true;
}
}
```
This will compile ✅ (no space between `@inheritdoc` and `@dev` tag.
```solidity
// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;
import {ITest} from "./ITest.sol";
contract MyTest is ITest {
/**
* @inheritdoc ITest
* @dev some extra details
*/
function test() external pure override returns (bool) {
return true;
}
}
```
This will also compile ✅ if `@inheritdoc` is placed after `@dev` tag (whether if there is a space between the `@inheritdoc` and `@dev` tag or not).
```solidity
// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;
import {ITest} from "./ITest.sol";
contract MyTest is ITest {
/**
* @dev some extra details
*
* @inheritdoc ITest
*/
function test() external pure override returns (bool) {
return true;
}
}
```
Contributor guide
Research direction
Reproduce the three NatSpec comment layouts with Solidity 0.8.19, focusing on how a blank line after @inheritdoc is handled. Trace the compiler's NatSpec processing for @inheritdoc and verify that the tag ends at the line while the interface documentation is still inherited and all shown examples compile.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, solidity
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100