Allow NatSpec comments for variables

[fulldecent]

Test case

pragma solidity ^0.5.0;

/// @title A simulator for Bug Bunny, the most famous Rabbit
/// @author Warned Bros
/// @notice You can use this contract for only the most basic simulation
/// @dev All function calls are currently implement without side effects
contract BugsBunny {
    /// @author Bob Clampett
    /// @notice Determine if Bugs will or will not accept given food
    /// @dev Food must be provided in UTF-8 format
    /// @param _food The name of a food to evaluate (English)
    /// @return true if Bugs will eat it, false otherwise
    function doesEat(string calldata _food) external pure returns (bool) {
        return keccak256(bytes(_food)) == keccak256("carrot");
    }
    
    /// @title example of title
    /// @author example of author
    /// @notice example of notice
    /// @dev example of dev
    /// @param example of param
    /// @return example of return
    string public constant name = "Bugs";
}

Run the command:

solc -o outputDirectory --userdoc --devdoc tmp.sol

Then test output with:

jq .methods outputDirectory/*

Expected outcome

Documentation is output for doesEat and name public functions.

Actual outcome

{
  "doesEat(string)": {
    "author": "Bob Clampett",
    "details": "Food must be provided in UTF-8 format",
    "params": {
      "_food": "The name of a food to evaluate (English)"
    },
    "return": "true if Bugs will eat it, false otherwise"
  }
}
{
  "doesEat(string)": {
    "notice": "Determine if Bugs will or will not accept given food"
  }
}

Follow on work

• Update documentation at https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format

[axic]

This depends on accepting #3411 first.

[fulldecent]

#3411 is closed

[fulldecent]

I do not think this depends on #3411 (CLOSED, WONTFIX).

The #3411 only relates to variables in interfaces. But this issue regards variables in contracts.

[bshastry]

summary from the call: waiting for further clarification from @fulldecent

[fulldecent]

Updated issue with test case for 0.6

[fulldecent]

Also added PR for documentation (which is blocked against here). #7857

[fulldecent]

Related #7834 #7835

[erak]

This is up for grabs again. Please see #8399.

[axic]

Since #3514 was fixed, the (in my opinion) best pattern is using interfaces to define public functions and those have to be NatSpec documented. Interfaces can't have "getters", but getters can implement functions of interfaces. This removes the need for NatSpec documenting internal functions -- probably the bigger questions is defining the goals and use case of NatSpec to properly decide its features.

[fulldecent]

Yes agreed. interface is now working great and it is the primary way to document interfaces and that is the primary use for NatSpec.

All is good in the world, there is no need for this feature. Closing.

There is no harm in implementing this feature and it can be opened later if desired but there is no need for it.

[axic]

Hm, it seems this was a duplicate for #2795.

[Marenz]

@axic I am not sure why you reopened this, isn't this fixed by #8532