Is your feature request related to a problem? Please describe.
Solidity contracts can have a form of comments that provide rich documentation to others reading the code as well as end-users. This is called the Ethereum Natural Language Specification Format, or NatSpec. Currently all code documentation is contained in natspec comments and only accessible within the contract files in the monorepo. We'd like to extract that in a dev docs set of pages, preferably in markdown format so they are easily accessible by developers, contributors and integrators.
Describe the solution you'd like
-
Natspec enforced in CI
It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces and we'd like to enforce that in CI (using our github actions setup). Preference is that Interfaces are documented while contracts that implement them use the @inheritdoc tag to adopt the interface documentation.
-
Dev docs are auto generated in the repo. One suggested tool is dodoc https://github.com/primitivefinance/primitive-dodoc/blob/main/README.md but others are acceptable, whichever produces better end result.
Describe alternatives you've considered
We have previously tested https://github.com/ItsNickBarry/hardhat-docgen because it's close to vue setup which we use for the community site https://community.optimism.io/. Even though it does the job, the formatting of the output there isn't ideal.
Additional context
There is a very nice contracts overview diagram in the State channels team site, which is built using mermaid 🧜♀️. We spoke with them and they confirmed that the mermaid config has been done by hand. This is a nice-to-have part of this task alternatively it will be logged and done separately.
Is your feature request related to a problem? Please describe.
Solidity contracts can have a form of comments that provide rich documentation to others reading the code as well as end-users. This is called the Ethereum Natural Language Specification Format, or NatSpec. Currently all code documentation is contained in natspec comments and only accessible within the contract files in the monorepo. We'd like to extract that in a dev docs set of pages, preferably in markdown format so they are easily accessible by developers, contributors and integrators.
Describe the solution you'd like
Natspec enforced in CI
It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces and we'd like to enforce that in CI (using our github actions setup). Preference is that Interfaces are documented while contracts that implement them use the
@inheritdoctag to adopt the interface documentation.Dev docs are auto generated in the repo. One suggested tool is
dodochttps://github.com/primitivefinance/primitive-dodoc/blob/main/README.md but others are acceptable, whichever produces better end result.Describe alternatives you've considered
We have previously tested https://github.com/ItsNickBarry/hardhat-docgen because it's close to vue setup which we use for the community site https://community.optimism.io/. Even though it does the job, the formatting of the output there isn't ideal.
Additional context
There is a very nice contracts overview diagram in the State channels team site, which is built using
mermaid🧜♀️. We spoke with them and they confirmed that themermaidconfig has been done by hand. This is a nice-to-have part of this task alternatively it will be logged and done separately.