[ETHEREUM-CONTRACTS] Integrate solidity-docgen for dev branch

[hellwolf]

Summary

In order to make the https://docs.superfluid.finance site an one-stop shop for our developers, we would like to host our reference docs for both ethereum-contracts, generated by solidity-docgen and jsdoc.

Technical Description

(To be finalized)

1. Our doc site is a gitbook project available at https://github.com/superfluid-finance/superfluid-protocol-docs
2. Integrate solidity-docgen and jsdoc as part of ci-canary workflow.
3. Generated docs should be to hosted and referenced in superfluid docs site nicely (how?)

Bounty Info

Bounty Prize: TBD

Bonus question:

• How about the subgraph reference docs?

[d10r]

Custom styling can be applied to the output, see e.g. https://docs.uniswap.org/protocol/reference/core/UniswapV3Factory

There was a rewrite of solidity-docgen (between v0.5 and v0.6), see OpenZeppelin/solidity-docgen#350.
Best usage example for v0.6 I found: frangio/hifi@abea0bc

[d10r]

Note that the tool will fail if there's @return tags without description. For other tags, that's already flagged by solhint, but not for this one.

Next: figure out what we want to include in the docs (e.g. only interfaces?) and how to style.

First shot with vanilla config

Second shot with this template files

[d10r]

cmd for quickly iterating on natspec and templates:

cd packages/ethereum-contracts
nodemon -w docs/docgen-templates/ -w contracts/ -e hbs,sol --exec npx hardhat docgen

Issues/improvements partially left after first PR:

• clarify our use of @notice vs @dev tags and the order in which to show, currently inconsistent (see e.g. registerAppWithKey)
• (higher order) comment blocks not specific to particular functions (especially in ISuperfluid.sol) are currently lost, they are not natspec items. Need to figure out a way to include them, e.g. by splitting up into sub-interfaces or making them interface-wide doc
• line breaks in @params and @returns items not supported. Make sure we don't have that
• if tags stand alone on a line (often the case with @Custom tags), a trailing whitespaces is needed for the parser to catch them. Currently the case, but I'm afraid linters/editors may auto-remove them. Could probably be fixed in the parser.
• structs doc currently missing (see Context)
• check if we have custom errors to be included
• all non-natspec tags (e.g. NOTE, Security) should be @Custom tags.
• wanted to print the content of @dev tags italic, but that breaks for multi-paragraph items
• the gitbook search index wasn't cleaned of (re)moved entries. Helpdesk request was sent
• better separation btw. item type and item name (e.g. "(Fn) distribute", or with colors/grey tone) - see Automated generation and publishing of contract API docs with solidity-docgen #880 (comment)