forge(doc): @inheritdoc does not pickup description

[PierrickGT]

Component

Forge

Describe the feature you would like

@inheritdoc should pickup the parameters description even if the parameters name differ.

Additional context

I have the following Natspec doc in my interface:

    /**
     * @notice Mints `amount` token to `recipient`.
     * @param  recipient The address of the account receiving minted token.
     * @param  amount    The amount of token to mint.
     */
    function mint(address recipient, uint256 amount) external;

In my contract, I inherit from the Natspec doc the following way:

    /// @inheritdoc IZeroToken
    function mint(address recipient_, uint256 amount_) external onlyStandardGovernor {
        _mint(recipient_, amount_);
    }

As you can see, the parameters are suffixed by _ and in consequence, forge doc does not pickup the parameters description:

I think the try_match_inheritdoc function can be improved to match parameters that are prefixed or suffixed by _:

foundry/crates/doc/src/preprocessor/inheritdoc.rs

Line 81 in b6e7c8b

if source.ident() == children.source.ident() {

[kamuik16]

Component

Forge

Describe the feature you would like

@inheritdoc should pickup the parameters description even if the parameters name differ.

Additional context

I have the following Natspec doc in my interface:

    /**
     * @notice Mints `amount` token to `recipient`.
     * @param  recipient The address of the account receiving minted token.
     * @param  amount    The amount of token to mint.
     */
    function mint(address recipient, uint256 amount) external;

In my contract, I inherit from the Natspec doc the following way:

    /// @inheritdoc IZeroToken
    function mint(address recipient_, uint256 amount_) external onlyStandardGovernor {
        _mint(recipient_, amount_);
    }

As you can see, the parameters are suffixed by _ and in consequence, forge doc does not pickup the parameters description:

I think the try_match_inheritdoc function can be improved to match parameters that are prefixed or suffixed by _:

foundry/crates/doc/src/preprocessor/inheritdoc.rs

Line 81 in b6e7c8b

if source.ident() == children.source.ident() {

Does the foundry team want this feature? If yes, can I work on this issue? Thanks.

[zerosnacks]

I'm not sure if the right approach to this is making the matching more lenient considering the lack of a code style standard for prefixing / postfixing function arguments. In my opinion your interface should just match your implementation.

[mattsse]

@kamuik16 I think checking for trailing _ would make sense here, but to @zerosnacks point ideally the args match the interface

[kamuik16]

@kamuik16 I think checking for trailing _ would make sense here, but to @zerosnacks point ideally the args match the interface

Can I work on the trailing _ case?

[mattsse]

@kamuik16 I think checking for trailing _ would make sense here, but to @zerosnacks point ideally the args match the interface

Can I work on the trailing _ case?

that'd be great, yes!

[kamuik16]

@kamuik16 I think checking for trailing _ would make sense here, but to @zerosnacks point ideally the args match the interface

Can I work on the trailing _ case?

that'd be great, yes!

Hey @mattsse, I compiled the doc crate and have made changes, but I am struggling with how to test it. Could you help me with how can I test my changes? Thanks.

[kamuik16]

I give up! I couldn't solve this.

[mattsse]

no worries, thanks for trying 🙏
I'll try looking into this

[kamuik16]

no worries, thanks for trying 🙏 I'll try looking into this

Hey @mattsse, while I couldn't solve this, I found out another issue and made a PR #7369 on it. Waiting for your feedback.

[deluca-mike]

I believe the issue may be that the whatever generates the devdoc/usedoc json uses parameter names as keys rather than as an array, without overriding\based on parameter order. So, instead of

{
    "arguments": [
        {
            "type": "address",
            "name": "foo",
            "description": "This is a foo.",
        },
        {
            "type": "uint256",
            "name": "bar",
            "description": "This is a bar.",
        },
    ],
}

it comes out as

{
    "arguments": {
        "foo": {
            "type": "address",
            "description": "This is a foo.",
        },
        "foo_": {
            "type": "address",
        },
        "bar": {
            "type": "uint256",
            "description": "This is a bar.",
        },
        "bar_": {
            "type": "uint256",
        },
    },
}

or just

{
    "arguments": {
        "foo_": {
            "type": "address",
        },
        "bar_": {
            "type": "uint256",
        },
    },
}

where the more-described/more-decorated elements are dropped.

The first is better as the interface can override the contract natspec where not empty. It may be a compiler devdoc/usedoc generation oversight that has results in parameter entries being unique if their name is unique, despite only order mattering. If this is true, then the problem can be fixed by just matching/overriding based on order rather than name, or using arrays in the devdoc (which may not be standaard, and thus not a good solution).

I believe any solution that is based on special regex matching (being lenient to trailing _), while great for us at M^0, would be a subpar solution and way too opinionated for a universal tool like foundry. And I'd hate for us to be the reason for code smells at foundry.