Natspec completions

[antico5]

closes #342
closes #343
closes #296

This one is branched off a rebased version of PR #328

[kanej]

This is great.

I have pinged the channel to confirm people are happy with the suggestion we are making to users.

Reading through the spec I suspect we need to support completions on /// comments as well. Does that require a different approach?

[antico5]

This is great.

I have pinged the channel to confirm people are happy with the suggestion we are making to users.

Reading through the spec I suspect we need to support completions on /// comments as well. Does that require a different approach?

I think we can achieve that with some small adaptation. Should I add that to this PR?

[kanej]

This is great.
I have pinged the channel to confirm people are happy with the suggestion we are making to users.
Reading through the spec I suspect we need to support completions on /// comments as well. Does that require a different approach?

I think we can achieve that with some small adaptation. Should I add that to this PR?

Yes, lets add that to the requirement.

[antico5]

@kanej triple forward slash format is implemented! ready to re-review

[kanej]

Based on feedback can we change:

function

• remove @dev and @notice and rely on the default text at the top to populate @notice
• do not put in @return if there is only one return entry

Contract/Library/Interface

• drop @dev so it is only @title, @author and @notice

Event

• remove @dev and @notice and rely on the default text

State Variable

• keep @dev

Public state variable

• keep @notice but drop @return (less sure on this one)

Can we check that the gif matches this version?

[antico5]

@kanej ready for review!

[kanej]

I have tested and generated docs from the defaults using solc: https://docs.soliditylang.org/en/latest/natspec-format.html#documentation-output.

I am approving, but can I request one change which is that public state variables should not default to @dev, just @notice.