feat(forge): add params natspec for enums

crates/doc/src/parser/comment.rs

@@ -46,7 +46,7 @@ impl CommentTag {
             }
             _ => {
                 warn!(target: "forge::doc", tag=trimmed, "unknown comment tag. custom tags must be preceded by `custom:`");
-                return None
+                return None;
             }
         };
         Some(tag)
@@ -157,6 +157,12 @@ impl From<Vec<DocCommentTag>> for Comments {
     }
 }
 
+impl From<Vec<Comment>> for Comments {
+    fn from(value: Vec<Comment>) -> Self {
+        Self(value)
+    }
+}
+
 /// The collection of references to natspec [Comment] items.
 #[derive(Debug, Default, PartialEq, Deref)]
 pub struct CommentsRef<'a>(Vec<&'a Comment>);

crates/doc/src/writer/as_doc.rs

@@ -229,7 +229,16 @@ 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)
+
+                                let filtered_comments: Comments = (*comments)
+                                    .iter()
+                                    .filter(|c| c.tag != CommentTag::Custom("variant".to_string()))
+                                    .cloned()
+                                    .collect::<Vec<_>>()
+                                    .into();
+
+                                writer.write_section(&filtered_comments, code)?;
+                                writer.try_write_variant_table(item, comments)
                             })?;
                         }
                     }

crates/doc/src/writer/buf_writer.rs

@@ -1,6 +1,8 @@
 use crate::{writer::traits::ParamLike, AsDoc, CommentTag, Comments, Deployment, Markdown};
 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)]
@@ -132,7 +139,7 @@ impl BufWriter {
 
         // There is nothing to write.
         if params.is_empty() || comments.is_empty() {
-            return Ok(())
+            return Ok(());
         }
 
         self.write_bold(heading)?;
@@ -177,6 +184,46 @@ 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, CommentTag::Custom("variant".to_string())]);
+
+        // 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.iter() {
+            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(