NatSpec of custom revert errors are not correctly generated

[clemlak]

I've noticed that the NatSpec output (devdoc and userdoc) of custom revert errors is wrapped in an extra array instead of being in a plain object.
I'm not sure if this was intentional or not but I find it weird since it's not the case for events or functions. Is there a real reason behind this behavior?

Quick example, the following code:

/// @notice Thrown when an error happens.
/// @dev More info about the error.
/// @param expected Expected address
/// @param actual Actual address
error RandomError(address expected, address actual);

Will generate the following documentation, in userdoc:

"errors": {
    "RandomError(address,address)": [
        {
            "notice": "Thrown when an error happens."
        }
    ]
}

And in devdoc:

"errors": {
    "RandomError(address,address)": [
        {
            "details": "More info about the error.",
            "params": {
                "actual": "Actual address",
                "expected": "Expected address"
            }
        }
    ]
},

The expected output would be to have the data directly available at the level of the RandomError(address,address) object, instead of having them inside of an extra array.

[cameel]

Yes, that's by design. Multiple error definitions with the same signature can exist and all of them can be documented. See example below. The question is which docs to return in that case. We discussed it at length and came to a conclusion that it's best to make it an array and return them all.

The same is true for events (see #11114), it's just that errors were a new feature so we could make it an array from the start. Events would be a breaking change in natspec so they have to wait for v2 (#11156).

Example

contract A {
    /// Something failed.
    /// @dev an error.
    /// @param x first parameter
    /// @param y second parameter
    error E(uint x, uint y);
}
contract test {
    /// X Something failed.
    /// @dev X an error.
    /// @param a X first parameter
    /// @param b X second parameter
    error E(uint a, uint b);
    function f(bool a) public pure {
        if (a)
            revert E(1, 2);
        else
            revert A.E(5, 6);
    }
}

{
    "contracts": {
        "test.sol:A": {
            "devdoc": {
                "errors": {
                    "E(uint256,uint256)": [
                        {
                            "details": "an error.",
                            "params": {
                                "x": "first parameter",
                                "y": "second parameter"
                            }
                        }
                    ]
                },
                "kind": "dev",
                "methods": {},
                "version": 1
            }
        },
        "test.sol:test": {
            "devdoc": {
                "errors": {
                    "E(uint256,uint256)": [
                        {
                            "details": "an error.",
                            "params": {
                                "x": "first parameter",
                                "y": "second parameter"
                            }
                        },
                        {
                            "details": "X an error.",
                            "params": {
                                "a": "X first parameter",
                                "b": "X second parameter"
                            }
                        }
                    ]
                },
                "kind": "dev",
                "methods": {},
                "version": 1
            }
        }
    },
    "version": "0.8.10+commit.fc410830.Linux.g++"
}