feat(sol-macro): improve generated docs

crates/sol-macro/src/attr.rs

@@ -42,6 +42,7 @@ pub fn derives_mapped(attrs: &[Attribute]) -> impl Iterator<Item = Path> + '_ {
 pub struct SolAttrs {
     pub all_derives: Option<bool>,
     pub extra_methods: Option<bool>,
+    pub docs: Option<bool>,
 
     // TODO: Implement
     pub rename: Option<LitStr>,
@@ -113,6 +114,7 @@ impl SolAttrs {
                 match_! {
                     all_derives => bool()?,
                     extra_methods => bool()?,
+                    docs => bool()?,
 
                     rename => lit()?,
                     rename_all => CasingStyle::from_lit(&lit()?)?,
@@ -270,6 +272,10 @@ mod tests {
             #[sol(extra_methods)] => Ok(sol_attrs! { extra_methods: true }),
             #[sol(extra_methods = true)] => Ok(sol_attrs! { extra_methods: true }),
             #[sol(extra_methods = false)] => Ok(sol_attrs! { extra_methods: false }),
+
+            #[sol(docs)] => Ok(sol_attrs! { docs: true }),
+            #[sol(docs = true)] => Ok(sol_attrs! { docs: true }),
+            #[sol(docs = false)] => Ok(sol_attrs! { docs: false }),
         }
 
         rename {

crates/sol-macro/src/expand/contract.rs

@@ -31,6 +31,7 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, contract: &ItemContract) -> Result<TokenS
         .extra_methods
         .or(cx.attrs.extra_methods)
         .unwrap_or(false);
+    let docs = sol_attrs.docs.or(cx.attrs.docs).unwrap_or(true);
 
     let bytecode = sol_attrs.bytecode.map(|lit| {
         let name = Ident::new("BYTECODE", lit.span());
@@ -88,8 +89,8 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, contract: &ItemContract) -> Result<TokenS
     });
 
     let mod_attrs = attr::docs(&attrs);
-    let mod_docs = (!attr::has_docs(&attrs))
-        .then(|| attr::mk_doc("Module containing a contract's types and functions."));
+    let mod_docs =
+        docs.then(|| attr::mk_doc("Module containing a contract's types and functions."));
     let tokens = quote! {
         #mod_docs
         #(#mod_attrs)*

crates/sol-macro/src/expand/error.rs

@@ -27,8 +27,9 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, error: &ItemError) -> Result<TokenStream>
     } = error;
     cx.assert_resolved(params)?;
 
-    let (_sol_attrs, mut attrs) = crate::attr::SolAttrs::parse(attrs)?;
+    let (sol_attrs, mut attrs) = crate::attr::SolAttrs::parse(attrs)?;
     cx.derives(&mut attrs, params, true);
+    let docs = sol_attrs.docs.or(cx.attrs.docs).unwrap_or(true);
 
     let tokenize_impl = expand_tokenize_func(params.iter());
 
@@ -37,10 +38,11 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, error: &ItemError) -> Result<TokenStream>
 
     let converts = expand_from_into_tuples(&name.0, params);
     let fields = expand_fields(params);
-    let doc = (!attr::has_docs(&attrs)).then(|| {
+    let doc = docs.then(|| {
         let selector = hex::encode_prefixed(selector.array);
         attr::mk_doc(format!(
-            "Custom error with signature `{signature}` and selector `{selector}`."
+            "Custom error with signature `{signature}` and selector `{selector}`.\n\
+             ```solidity\n{error}\n```"
         ))
     });
     let tokens = quote! {

crates/sol-macro/src/expand/event.rs

@@ -22,8 +22,9 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, event: &ItemEvent) -> Result<TokenStream>
     let ItemEvent { attrs, .. } = event;
     let params = event.params();
 
-    let (_sol_attrs, mut attrs) = crate::attr::SolAttrs::parse(attrs)?;
+    let (sol_attrs, mut attrs) = crate::attr::SolAttrs::parse(attrs)?;
     cx.derives(&mut attrs, &params, true);
+    let docs = sol_attrs.docs.or(cx.attrs.docs).unwrap_or(true);
 
     cx.assert_resolved(&params)?;
     event.assert_valid()?;
@@ -105,10 +106,11 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, event: &ItemEvent) -> Result<TokenStream>
         .enumerate()
         .map(|(i, assign)| quote!(out[#i] = #assign;));
 
-    let doc = (!attr::has_docs(&attrs)).then(|| {
+    let doc = docs.then(|| {
         let selector = hex::encode_prefixed(selector.array);
         attr::mk_doc(format!(
-            "Event with signature `{signature}` and selector `{selector}`."
+            "Event with signature `{signature}` and selector `{selector}`.\n\
+            ```solidity\n{event}\n```"
         ))
     });
     let tokens = quote! {

crates/sol-macro/src/expand/function.rs

@@ -44,12 +44,13 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, function: &ItemFunction) -> Result<TokenS
         cx.assert_resolved(returns)?;
     }
 
-    let (_sol_attrs, mut call_attrs) = crate::attr::SolAttrs::parse(attrs)?;
+    let (sol_attrs, mut call_attrs) = crate::attr::SolAttrs::parse(attrs)?;
     let mut return_attrs = call_attrs.clone();
     cx.derives(&mut call_attrs, arguments, true);
     if !returns.is_empty() {
         cx.derives(&mut return_attrs, returns, true);
     }
+    let docs = sol_attrs.docs.or(cx.attrs.docs).unwrap_or(true);
 
     let call_name = cx.call_name(function);
     let return_name = cx.return_name(function);
@@ -67,13 +68,14 @@ pub(super) fn expand(cx: &ExpCtxt<'_>, function: &ItemFunction) -> Result<TokenS
     let selector = crate::utils::selector(&signature);
     let tokenize_impl = expand_tokenize_func(arguments.iter());
 
-    let call_doc = (!attr::has_docs(attrs)).then(|| {
+    let call_doc = docs.then(|| {
         let selector = hex::encode_prefixed(selector.array);
         attr::mk_doc(format!(
-            "Function with signature `{signature}` and selector `0x{selector}`."
+            "Function with signature `{signature}` and selector `0x{selector}`.\n\
+            ```solidity\n{function}\n```"
         ))
     });
-    let return_doc = (!attr::has_docs(&return_attrs)).then(|| {
+    let return_doc = docs.then(|| {
         attr::mk_doc(format!(
             "Container type for the return parameters of the [`{signature}`]({call_name}) function."
         ))

crates/sol-macro/src/lib.rs

@@ -96,12 +96,17 @@ mod utils;
 /// but this may change in the future.
 ///
 /// List of all `#[sol(...)]` supported attributes:
-/// - `all_derives`: adds all possible `#[derive(...)]` attributes to all
-///   generated types. May significantly increase compile times due to all the
-///   extra generated code. This is the default behaviour of [`abigen`][abigen]
-/// - `extra_methods`: adds extra implementations and methods to all applicable
-///   generated types, such as `From` impls and `as_<variant>` methods. May
-///   significantly increase compile times due to all the extra generated code
+/// - `all_derives [ = <bool = false>]`: adds all possible `#[derive(...)]`
+///   attributes to all generated types. May significantly increase compile
+///   times due to all the extra generated code. This is the default behaviour
+///   of [`abigen`][abigen]
+/// - `extra_methods [ = <bool = false>]`: adds extra implementations and
+///   methods to all applicable generated types, such as `From` impls and
+///   `as_<variant>` methods. May significantly increase compile times due to
+///   all the extra generated code. This is the default behaviour of
+///   [`abigen`][abigen]
+/// - `docs [ = <bool = true>]`: adds doc comments to all generated types. This
+///   is the default behaviour of [`abigen`][abigen]
 /// - `bytecode = <hex string literal>`: specifies the creation/init bytecode of
 ///   a contract. This will emit a `static` item with the specified bytes.
 /// - `deployed_bytecode = <hex string literal>`: specifies the deployed