feat(forge): add params natspec for enums

[samooyo]

Motivation

• Closes Added NatSpec support for enum value definitions #9545.

Solution

The forge doc comment parser now supports parsing Enum variants in Natspecs and displaying them in a table. To declare these variants, you can use either the @param or @custom:variant tag.

To implement this feature:

• Comments containing the @custom:variant tag are filtered out to prevent them from being displayed in the Note field.
• Both the variant and param tags are parsed to properly display the table.

Additionally:

• The From trait was implemented for the Comments struct to enable the construction of the returned vector from the filtered comments.
• A dedicated table header and separator were added specifically for variants.

PR Checklist

• Added Tests
• Added Documentation
• Breaking changes

[zerosnacks]

Hi @samooyo, thanks for your PR!

Given that Solidity has not prioritised adding support for this in the current release I think it is reasonable to add this ahead of time and make adjustments where needed afterwards.

Would you mind adding a test case for this?

The proposed syntax of Solidity (argotorg/solidity#14193) is as follows:

    enum Color {
        Red,
        /// @notice example of notice
        /// @dev example of dev
        Green,
        /// @dev example of dev
        Blue
    }

Once Solidity has implement support for this in-line syntax we can expand it to also cover this case.

Personally I think the @param syntax as proposed makes most sense here

[srdtrk]

Since it seems like CommentTag::Custom("variant".to_string()) is commonly used in this PR. Would it be ok to add the following method to CommentTag in parser.

    /// Create a new instance of [CommentTag::Custom] with the `variant` tag.
    pub fn variant() -> Self {
        Self::Custom("variant".to_string())
    }

On a side note @zerosnacks, I'm using the parser crate in an external project for a natspec linter I'm building (it's private at the moment) in my free time. I also have to maintain a copy of the parser module since it is not published on crates.io. Would you be open to refactor and publish the parser as a crate if I create an issue for this?

[samooyo]

Hi @samooyo, thanks for your PR!

Given that Solidity has not prioritised adding support for this in the current release I think it is reasonable to add this ahead of time and make adjustments where needed afterwards.

Would you mind adding a test case for this?

The proposed syntax of Solidity (ethereum/solidity#14193) is as follows:

    enum Color {
        Red,
        /// @notice example of notice
        /// @dev example of dev
        Green,
        /// @dev example of dev
        Blue
    }

Once Solidity has implement support for this in-line syntax we can expand it to also cover this case.

Personally I think the @param syntax as proposed makes most sense here

Hi @zerosnacks, thanks for the feedback!

From what I can see, there currently aren’t any existing tests for the writer part of the doc generation. Could you point me to where those tests should go, or how you'd like them structured? I'd be happy to add them accordingly.

[zerosnacks]

0.8.30 adds NatSpec support for enum value definitions: #10455

https://github.com/ethereum/solidity/releases/tag/v0.8.30

[onbjerg]

Hi @samooyo, could you take a look at updating this implementation for the new feature as released in solc 0.8.30?:)

[onbjerg]

Hi @samooyo, let me know if you are blocked on supporting variant docs from argotorg/solidity#15956

[samooyo]

Hi @samooyo, let me know if you are blocked on supporting variant docs from argotorg/solidity#15956

Hi @onbjerg, from my understanding, Solang has not yet implemented this new Solidity feature. So I’ve just removed the @custom:variant to prioritize the @param. Is there anything else I should add?

[onbjerg]

no this is ok, ty