feat(ast): naive natspec

[0xrusowsky]

Motivation

there is this foundry issue to use a 3rd-party library lint natspec comments:

• feat(lint/fmt): Adding NatSpec linting via lintspec foundry-rs/foundry#11471

right now solar doesn't support natspec, which means that the natspec lints that this 3rd-party supports can't be directly implemented on forge-lint.

so i thought i'd be a good opportunity to introduce an initial version.

Solution

this proposal adds the required AST types and implements a minimal (naive) parser, which could be then used by the linter to achieve what community asked for in the linked ticket.

Notes

• i tried implementing it in a backwards-compatible way, although i believe that the only consumer for the existig DocComments may be the wip formatter.

• obviously this feature has never been a priority, as it's never been in the roadmap + it could have a negative impact on performance and increase the size of the generated AST, so we could gate it under a feature flag.

• yul tests are currently failing due to the usage of "non-std" tags. I understand what they do but i wasn't aware of them nor saw them in the official soliditylang spec, so i didn't add support for them (but we could if u think we should)

[0xrusowsky]

@DaniPopes please lmk if this makes sense or not? also feel free to share ur thoughts on the foundry ticket itself

cc: @onbjerg in case u are opinionated

[DaniPopes]

i think this is fine to support in the parser. we'll want something eventually for @\solidity / @\solar anyway, flattening a project wants to update inheritdoc tags, forge doc needs it

for performance this doesn't really matter, feature flag is not needed

for reporting errors, i'd check with solc how they do natspec parsing and if they report a regular parser error if not respected

[beeb]

I stumbled upon this by chance. Do you think it would make sense to use the natspec parser I developed for lintspec? I would be happy to make any changes required for integration. I don't think it makes sense to re-implement it here? I could even isolate it in a separate crate if desired.
At the moment the parser is exposed via https://docs.rs/lintspec/latest/lintspec/natspec/fn.parse_comment.html