NatSpec v2

[chriseth]

Natspec JSON changes (non-breaking):

• NatSpec and multiple events with identical signature #11114 (events and errors as arrays instead of hashmap)
• Natspec: change parameters and return values to be an array #11120 (change params/returns into an array instead of hashmap)
• Natspec: include events/errors in devdoc too #11158 (include events/errors in the devdoc)
• include the @notice in the devdoc too

Natspec syntax changes (potentially breaking -- maybe has to wait for 0.9.0):

• Natspec: Don't copy from base function if return parameters differ #10921 -- explanation here
• disallow @return for events

[axic]

We may want to consider the following too:

• Allow natspec documentation for non-public functions. #3097 to also output internal functions in the devdocs, given that could change the format as well.
• NatSpec on contracts is not inherited #9553 and Natspec: text before the @notice tag gets included as part of it #10281 to clear up the behaviour of the notice and dev tags
• Natspec: include events/errors in devdoc too #11158 to include events/errors in the devdoc
• anything I missed from Missing entries in devdoc / userdoc [natspec] #1141

Lastly we may want to consider merging devdoc/userdoc into a single output.

[chriseth]

Do we also want to output free functions?

[axic]

I think so, under the "internal functions" umbrella.

[Marenz]

Should we maybe have an extra issue for turning returns into an array? Or do you expect it to be part of #10921?

[axic]

@Marenz #11120 should cover both.

[axic]

For #10921 we discussed to change how public struct state variables work:

• In the syntax for @return each of the member variables should be described.
• In the JSON the returns field should contain an array (the same structure as Natspec: change parameters and return values to be an array #11120).

[axic]

We also discussed:

• Allow natspec documentation for non-public functions. #3097 -- we definitely want to include non-public functions, but it seems to be quite a bit of design work left to be done
• Natspec: text before the @notice tag gets included as part of it #10281 -- we may want this, but need to agree on rules