From 1d49ef997046f84a5663dbfd3c03c710ceb735d6 Mon Sep 17 00:00:00 2001 From: gregorsternat Date: Mon, 17 Feb 2025 18:21:51 +0100 Subject: [PATCH 1/2] feat(doc): add support for @custom:variant documentation for enums 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. --- crates/doc/src/parser/comment.rs | 2 ++ crates/doc/src/writer/as_doc.rs | 47 ++++++++++++++++++++++++++++++-- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/crates/doc/src/parser/comment.rs b/crates/doc/src/parser/comment.rs index bf2b0ad7b4f0d..cf6be1053f2bc 100644 --- a/crates/doc/src/parser/comment.rs +++ b/crates/doc/src/parser/comment.rs @@ -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, Custom(String), } @@ -41,6 +42,7 @@ impl CommentTag { let custom_tag = trimmed.trim_start_matches("custom:").trim(); match custom_tag { "param" => Self::Param, + "variant" => Self::Variant, _ => Self::Custom(custom_tag.to_owned()), } } diff --git a/crates/doc/src/writer/as_doc.rs b/crates/doc/src/writer/as_doc.rs index 56a0a4026c504..22de009585533 100644 --- a/crates/doc/src/writer/as_doc.rs +++ b/crates/doc/src/writer/as_doc.rs @@ -229,7 +229,27 @@ impl AsDoc for Document { writer.write_subtitle("Enums")?; enums.into_iter().try_for_each(|(item, comments, code)| { writer.write_heading(&item.name.safe_unwrap().name)?; - writer.write_section(comments, code) + writer.write_section(comments, code)?; + + // Extraire les descriptions des variants + let variants: Vec<_> = comments + .include_tag(CommentTag::Variant) + .iter() + .filter_map(|c| { + let (name, desc) = c.value.split_once(' ')?; + Some((name.trim().to_string(), desc.trim().to_string())) + }) + .collect(); + if !variants.is_empty() { + writer.writeln()?; + writer.write_bold("Cases:")?; + writer.writeln_raw("| Name | Description |")?; + writer.writeln_raw("|------|-------------|")?; + for (name, desc) in variants { + writer.writeln_raw(&format!("| `{}` | {} |", name, desc))?; + } + } + Ok::<_, std::fmt::Error>(()) })?; } } @@ -273,7 +293,30 @@ impl AsDoc for Document { writer.write_section(&item.comments, &item.code)?; writer.try_write_errors_table(&err.fields, &item.comments)?; } - ParseSource::Variable(_) | ParseSource::Enum(_) | ParseSource::Type(_) => { + ParseSource::Enum(_) => { + writer.writeln_doc(&item.comments)?; + writer.write_code(&item.code)?; + + // Extraire les descriptions des variants + let variants: Vec<_> = item.comments + .include_tag(CommentTag::Variant) + .iter() + .filter_map(|c| { + let (name, desc) = c.value.split_once(' ')?; + Some((name.trim().to_string(), desc.trim().to_string())) + }) + .collect(); + if !variants.is_empty() { + writer.writeln()?; + writer.write_bold("Cases:")?; + writer.writeln_raw("| Name | Description |")?; + writer.writeln_raw("|------|-------------|")?; + for (name, desc) in variants { + writer.writeln_raw(&format!("| `{}` | {} |", name, desc))?; + } + } + } + ParseSource::Variable(_) | ParseSource::Type(_) => { writer.write_section(&item.comments, &item.code)?; } } From d89c9f13ae4bc08f8b2141f461272610c1d79c74 Mon Sep 17 00:00:00 2001 From: gregorsternat Date: Mon, 17 Feb 2025 19:38:51 +0100 Subject: [PATCH 2/2] style: remove comments --- crates/doc/src/writer/as_doc.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/crates/doc/src/writer/as_doc.rs b/crates/doc/src/writer/as_doc.rs index 22de009585533..36254733b642e 100644 --- a/crates/doc/src/writer/as_doc.rs +++ b/crates/doc/src/writer/as_doc.rs @@ -231,7 +231,6 @@ impl AsDoc for Document { writer.write_heading(&item.name.safe_unwrap().name)?; writer.write_section(comments, code)?; - // Extraire les descriptions des variants let variants: Vec<_> = comments .include_tag(CommentTag::Variant) .iter() @@ -297,7 +296,6 @@ impl AsDoc for Document { writer.writeln_doc(&item.comments)?; writer.write_code(&item.code)?; - // Extraire les descriptions des variants let variants: Vec<_> = item.comments .include_tag(CommentTag::Variant) .iter()