feat(forge): add params natspec for enums (foundry-rs#10022)

* feat(forge): add params natspec for enums

* chore: cargo fmt

* fix: clippy errors

* add @gregorsternat as co-author given their earlier work on foundry-rs#9905

Co-authored-by: gregorsternat <[email protected]>

* refactor: add variant constructor

* style: clippy issue

* docs: remove formating

* refactor(doc): remove the custom variant natspec for enum

---------

Co-authored-by: zerosnacks <[email protected]>
Co-authored-by: gregorsternat <[email protected]>

Author: 3 people

crates/doc/src/writer/as_doc.rs

@@ -229,7 +229,8 @@ 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)?;
+                                writer.try_write_variant_table(item, comments)
                             })?;
                         }
                     }

crates/doc/src/writer/buf_writer.rs

@@ -1,6 +1,8 @@
 use crate::{AsDoc, CommentTag, Comments, Deployment, Markdown, writer::traits::ParamLike};
 use itertools::Itertools;
-use solang_parser::pt::{ErrorParameter, EventParameter, Parameter, VariableDeclaration};
+use solang_parser::pt::{
+    EnumDefinition, ErrorParameter, EventParameter, Parameter, VariableDeclaration,
+};
 use std::{
     fmt::{self, Display, Write},
     sync::LazyLock,
@@ -19,6 +21,11 @@ const DEPLOYMENTS_TABLE_HEADERS: &[&str] = &["Network", "Address"];
 static DEPLOYMENTS_TABLE_SEPARATOR: LazyLock<String> =
     LazyLock::new(|| DEPLOYMENTS_TABLE_HEADERS.iter().map(|h| "-".repeat(h.len())).join("|"));
 
+/// Headers and separator for rendering the variants table.
+const VARIANTS_TABLE_HEADERS: &[&str] = &["Name", "Description"];
+static VARIANTS_TABLE_SEPARATOR: LazyLock<String> =
+    LazyLock::new(|| VARIANTS_TABLE_HEADERS.iter().map(|h| "-".repeat(h.len())).join("|"));
+
 /// The buffered writer.
 /// Writes various display items into the internal buffer.
 #[derive(Debug, Default)]
@@ -177,6 +184,45 @@ impl BufWriter {
         self.try_write_table(CommentTag::Param, params, comments, "Properties")
     }
 
+    /// Tries to write the variant table to the buffer.
+    /// Doesn't write anything if either params or comments are empty.
+    pub fn try_write_variant_table(
+        &mut self,
+        params: &EnumDefinition,
+        comments: &Comments,
+    ) -> fmt::Result {
+        let comments = comments.include_tags(&[CommentTag::Param]);
+
+        // There is nothing to write.
+        if comments.is_empty() {
+            return Ok(());
+        }
+
+        self.write_bold("Variants")?;
+        self.writeln()?;
+
+        self.write_piped(&VARIANTS_TABLE_HEADERS.join("|"))?;
+        self.write_piped(&VARIANTS_TABLE_SEPARATOR)?;
+
+        for value in &params.values {
+            let param_name = value.as_ref().map(|v| v.name.clone());
+
+            let comment = param_name.as_ref().and_then(|name| {
+                comments.iter().find_map(|comment| comment.match_first_word(name))
+            });
+
+            let row = [
+                Markdown::Code(&param_name.unwrap_or("<none>".to_string())).as_doc()?,
+                comment.unwrap_or_default().replace('\n', " "),
+            ];
+            self.write_piped(&row.join("|"))?;
+        }
+
+        self.writeln()?;
+
+        Ok(())
+    }
+
     /// Tries to write the parameters table to the buffer.
     /// Doesn't write anything if either params or comments are empty.
     pub fn try_write_events_table(