feat(doc): add support for @custom:variant documentation for enums #9905
Conversation
Solidity currently doesn't support @param for enums according to the Natspec format,making it impossible to document each enum variant using forge doc. This commit introducesa new @Custom:variant tag to allow individual enum variant descriptions.Changes:- Updated parsing in `crates/doc/src/parser/comment.rs` to extract @Custom:variant tags.- Modified documentation generation in `crates/doc/src/writer/as_doc.rs` to include variant descriptions.
| writer.write_section(comments, code) | ||
| writer.write_section(comments, code)?; | ||
|
|
||
| let variants: Vec<_> = comments |
There was a problem hiding this comment.
Don't forget to format your code, with cargo +nightly fmt, to avoid this indentation issue. Also, you can use collect::<Vec<_>>() instead of : Vec<_>
| Some((name.trim().to_string(), desc.trim().to_string())) | ||
| }) | ||
| .collect(); | ||
| if !variants.is_empty() { |
There was a problem hiding this comment.
I think you can add a break line before and after the if statement
| writer.writeln_raw(&format!("| `{}` | {} |", name, desc))?; | ||
| } | ||
| } | ||
| Ok::<_, std::fmt::Error>(()) |
There was a problem hiding this comment.
I don't think the type needs to be explicit
| writer.writeln_doc(&item.comments)?; | ||
| writer.write_code(&item.code)?; | ||
|
|
||
| let variants: Vec<_> = item.comments |
| Some((name.trim().to_string(), desc.trim().to_string())) | ||
| }) | ||
| .collect(); | ||
| if !variants.is_empty() { |
There was a problem hiding this comment.
A breakline before the if statement can be appreciate
| @@ -21,6 +21,7 @@ pub enum CommentTag { | |||
| /// Copies all missing tags from the base function (must be followed by the contract name) | |||
| Inheritdoc, | |||
| /// Custom tag, semantics is application-defined | |||
| Variant, | |||
There was a problem hiding this comment.
Every element of this enum is one of the natspec tags defined in the specs here. And variant isn't one of them.
Instead, is it not possible to parse this as Custom("variant") and do the filtering in the writer?
|
Hi @gregorsternat thanks for your PR I would prefer if we can get this resolved in Solidity with this PR: ethereum/solidity#14193 rather than Foundry implementing a workaround From basic tests I can confirm enum value definitions are not outputted by The proposed format would look like: |
…s#9905 Co-authored-by: gregorsternat <[email protected]>
|
Hi @gregorsternat thanks for your PR, given that Solidity has been slow to implement this I would like to move ahead with this but in the meantime a different PR addressing this has been raised. I've added you as co-author on #10022 given your work on this. Closing in favor of #10022 |
Motivation
Currently, Solidity doesn't support
@paramdocumentation for enum variants,resulting in incomplete documentation when using
forge doc. This change addressesthe issue by allowing developers to document each enum variant individually using a
new
@custom:varianttag.Solution
This PR updates the documentation parser to recognize the
@custom:varianttag incrates/doc/src/parser/comment.rsand modifies the documentation writer incrates/doc/src/writer/as_doc.rsto include the variant descriptions in the generateddocumentation. This enhancement enables more granular and clear documentation for enums,
thereby improving the developer experience.
PR Checklist