Vyper: Add Natspec in combined_json

[montyly]

Hi,

Would it be possible to add the natspec documentation to the combined json output?

Typically on the following:

@public
def test(a: uint256) -> bool:
    """
    @author montyly
    @notice Nothing
    @dev This is a test
    @param a just a param
    @return always true
    """
    return True

It would be great if vyper test.vy -f combined_json could return the natspec to the json. Solidity output it as two dicts: https://solidity.readthedocs.io/en/latest/natspec-format.html#documentation-output.

This will help third-parties tools integration (such as https://github.com/crytic/crytic-compile/pull/66).

Thanks

[fubuloubu]

Yes! Should be possible. I don't think we actually parse the natspec currently, but it should be easy for someone to build a parser for the docstrings of a method and output the results alongside the other output formats.

[montyly]

Task Description

• Write a parser for natspec
• Parse docstrings comments inside methods as natspec
• Add natspec comments to output from compiler

Acceptance criteria

• Extensive unit tests for parser
• Unit tests for vyper-cli and vyper-json
• Demonstrate compatibility with Solidity

Required skills

• Python 3.6-3.8
• Familiarity with natspec
• Familiarity with Solidity

[gitcoinbot]

Issue Status: 1. Open 2. Started 3. Submitted 4. Done

---

__This issue now has a funding of 200.0 DAI (200.0 USD @ $1.0/DAI) attached to it.__

• If you would like to work on this issue you can 'start work' on the Gitcoin Issue Details page.
  
  
  
  • Want to chip in? Add your own contribution here.
  
  
  • Questions? Checkout Gitcoin Help or the Gitcoin Slack
  
  
  • $79,579.38 more funded OSS Work available on the Gitcoin Issue Explorer
  
  

[gitcoinbot]

Issue Status: 1. Open 2. Started 3. Submitted 4. Done

---

__Work has been started__.

These users each claimed they can complete the work by 11 hours ago.
Please review their action plans below:

1) rjyun has applied to start work _(Funders only: approve worker | reject worker)_.

Finding a way to only separate data that must be separated.
2) developerfred has applied to start work _(Funders only: approve worker | reject worker)_.

my planning is to do the integration and if possible write tests
3) thevertex has applied to start work _(Funders only: approve worker | reject worker)_.

I can assist with this :) and agreed with actions needed.
4) srisankethu has applied to start work _(Funders only: approve worker | reject worker)_.

I am interested on working on this. Familiar with Python and Solidity(and Natspec).
5) bobface has applied to start work _(Funders only: approve worker | reject worker)_.

Work plan:

1. Add an output format "natspec" which will be included in the combined_json output format.
2. Write natspec parser which searches the docstrings of methods in the AST for natspec.
3. Write extensive tests for parser.
   Thanks for considering me!
   6) iamdefinitelyahuman has been approved to start work.

1. Add parsed natspec information to the vyper combined_json output as well as the vyper-json output. The format will mirror that of the solc compiler.
2. Write test cases.

3. Update documentation.
   7) jotafan has applied to start work _(Funders only: approve worker | reject worker)_.

4. Add natspec data to the json file dumped by vyper.

Learn more on the Gitcoin Issue Details page.

[nanspro]

I think this is reserved for @iamdefinitelyahuman so stopping work on this

[acheron2302]

This is not a pr or something like that but i have wrote a natspec conversion but it is still very ugly and i haven't write a test case but it work most of the time: https://github.com/acheron2302/vyper-doc. Sorry if it didn't work as you expect because this was just a fun challenge project for me at that time so i didn't put much effort into it

[fubuloubu]

@acheron2302 thanks for sharing!

[gitcoinbot]

@iamdefinitelyahuman Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!

• [x] reminder (3 days)
• [ ] escalation to mods (6 days)

Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days

[iamdefinitelyahuman]

@gitcoinbot Yes, I'm on it.

[gitcoinbot]

@iamdefinitelyahuman Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!

• [x] reminder (3 days)
• [ ] escalation to mods (6 days)

Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days

[gitcoinbot]

@iamdefinitelyahuman Hello from Gitcoin Core - are you still working on this issue? Please submit a WIP PR or comment back within the next 3 days or you will be removed from this ticket and it will be returned to an ‘Open’ status. Please let us know if you have questions!

• [x] reminder (3 days)
• [ ] escalation to mods (6 days)

Funders only: Snooze warnings for 1 day | 3 days | 5 days | 10 days | 100 days

[iamdefinitelyahuman]

@gitcoinbot yep i'm on it.

[montyly]

Thanks @iamdefinitelyahuman !

@ceresstation, can you validate the bounty? thx

[gitcoinbot]

Issue Status: 1. Open 2. Started 3. Submitted 4. Done

---

__Work for 200.0 DAI (200.0 USD @ $1.0/DAI) has been submitted by__:

1. @iamdefinitelyahuman

@ceresstation please take a look at the submitted work:

• PR by @iamdefinitelyahuman

---

• Learn more on the Gitcoin Issue Details page
• Want to chip in? Add your own contribution here.
• Questions? Checkout Gitcoin Help or the Gitcoin Slack
• $81,163.16 more funded OSS Work available on the Gitcoin Issue Explorer

[iamdefinitelyahuman]

@montyly @ceresstation I just received an email that this bounty expires in two days, and the payment hasn't been released yet. Mind releasing it to me soon? Thanks.

[gitcoinbot]

Issue Status: 1. Open 2. Started 3. Submitted 4. Done

---

__The funding of 200.0 DAI (200.0 USD @ $1.0/DAI) attached to this issue has been approved & issued to @iamdefinitelyahuman.__

• Learn more on the Gitcoin Issue Details page
• Questions? Checkout Gitcoin Help or the Gitcoin Slack
• $83,254.20 more funded OSS Work available on the Gitcoin Issue Explorer