argotorg / argotorg/solidity

`@inheritdoc` tag in Natspec does not stop at the end of the line

Open
#14,397 2 comments 0 reactions 0 assignees View on GitHub
annoys users :cry: bug :bug: low effort low impact must have eventually
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.