NatSpec parser

[iamdefinitelyahuman]

What I did

Add NatSpec parsing functionality. Closes #1863

How I did it

1. Add logic for parsing natspec in docstrings under ast/natspec.py
2. Add stub files for ast/__init__.py and ast/nodes.py to avoid typing issues
3. Add userdoc and devdoc as compiler output options and enable in vyper-compile and vyper-json.

The output format is identical to that of Solidity >=0.6.0:

1. Docstrings without any natspec tags are handled as @notice.
2. Errors are raised on invalid or duplicate @param fields.
3. Multiple @return values are supported, each value is assigned a name _[n] with n incrementing from 0.

How to verify it

Run tests.

TODO

• Add test cases
• Update documentation

Cute Animal Picture

[codecov-io]

Codecov Report

Merging #1898 into master will increase coverage by <.01%.
The diff coverage is 86.72%.

@@            Coverage Diff             @@
##           master    #1898      +/-   ##
==========================================
+ Coverage      87%   87.01%   +<.01%     
==========================================
  Files          53       54       +1     
  Lines        6187     6275      +88     
  Branches     1600     1622      +22     
==========================================
+ Hits         5383     5460      +77     
- Misses        514      519       +5     
- Partials      290      296       +6

Impacted Files	Coverage Δ
vyper/ast/__init__.py	100% <100%> (ø)	⬆️
vyper/cli/vyper_compile.py	81.65% <100%> (+0.16%)	⬆️
vyper/ast/nodes.py	91.05% <100%> (+0.05%)	⬆️
vyper/compiler.py	94.47% <100%> (+0.25%)	⬆️
vyper/cli/vyper_json.py	85.65% <66.66%> (+0.61%)	⬆️
vyper/ast/natspec.py	82.66% <82.66%> (ø)
vyper/signatures/sig_utils.py	98.33% <91.66%> (+0.11%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 154cf06...d522395. Read the comment docs.

[iamdefinitelyahuman]

This test verifies that the natspec output is identical between solidity and vyper. I'm not including it in our test suite because I don't want to introduce solcx as a test dependency.

import json
import solcx
import vyper

solcx.set_solc_version('0.6.3')
solc_output = solcx.compile_source("""
/// @title A simulator for trees
/// @author Larry A. Gardner
/// @notice You can use this contract for only the most basic simulation
/// @dev All function calls are currently implemented without side effects
contract Tree {
    /// @author Mary A. Botanist
    /// @notice Calculate tree age in years, rounded up, for live trees
    /// @dev The Alexandr N. Tetearing algorithm could increase precision
    /// @param rings The number of rings from dendrochronological sample
    /// @return age in years, rounded up for partial years
    function age(uint256 rings) external pure returns (uint256) {
        return rings + 1;
    }
}
""", output_values=['devdoc', 'userdoc'])['<stdin>:Tree']
solc_output = {k: json.loads(v) for k, v in solc_output.items()}

vyper_output = vyper.compile_code("""
'''
@title A simulator for trees
@author Larry A. Gardner
@notice You can use this contract for only the most basic simulation
@dev All function calls are currently implemented without side effects
'''
@public
@constant
def age(rings: uint256) -> uint256:
    '''
    @author Mary A. Botanist
    @notice Calculate tree age in years, rounded up, for live trees
    @dev The Alexandr N. Tetearing algorithm could increase precision
    @param rings The number of rings from dendrochronological sample
    @return age in years, rounded up for partial years
    '''
    return rings + 1
""", output_formats=['devdoc', 'userdoc'])

assert solc_output == vyper_output