Generate docs in rpc macros (#729)

* Add missing docs to generated rpc

* Remove allow(missing_docs) from query modules

* remove println

* add missing docs for attester-incentives

examples/demo-nft-module/src/query.rs

@@ -1,4 +1,3 @@
-#![allow(missing_docs)]
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_modules_api::Context;
@@ -16,6 +15,7 @@ pub struct OwnerResponse<C: Context> {
 #[rpc_gen(client, server, namespace = "nft")]
 impl<C: Context> NonFungibleToken<C> {
     #[rpc_method(name = "getOwner")]
+    /// Get the owner of a token
     pub fn get_owner(
         &self,
         token_id: u64,

module-system/module-implementations/examples/sov-value-setter/src/query.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Defines rpc queries exposed by the module
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_state::WorkingSet;

module-system/module-implementations/examples/sov-vec-setter/src/query.rs

@@ -1,4 +1,3 @@
-#![allow(missing_docs)]
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_state::WorkingSet;

module-system/module-implementations/sov-accounts/src/query.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Defines rpc queries exposed by the accounts module, along with the relevant types
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_modules_api::AddressBech32;
@@ -23,6 +23,7 @@ pub enum Response {
 #[rpc_gen(client, server, namespace = "accounts")]
 impl<C: sov_modules_api::Context> Accounts<C> {
     #[rpc_method(name = "getAccount")]
+    /// Get the account corresponding to the given public key.
     pub fn get_account(
         &self,
         pub_key: C::PublicKey,

module-system/module-implementations/sov-attester-incentives/src/lib.rs

@@ -11,7 +11,6 @@ pub mod genesis;
 mod tests;
 
 #[cfg(feature = "native")]
-#[allow(missing_docs)]
 pub mod query;
 
 use std::marker::PhantomData;

module-system/module-implementations/sov-attester-incentives/src/query.rs

@@ -1,3 +1,4 @@
+//! Defines the query methods for the attester incentives module
 use borsh::{BorshDeserialize, BorshSerialize};
 use serde::{Deserialize, Serialize};
 use sov_modules_api::Spec;
@@ -8,8 +9,10 @@ use sov_state::{Storage, WorkingSet};
 use super::AttesterIncentives;
 use crate::call::Role;
 
+/// The response type to the `getBondAmount` query.
 #[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
 pub struct BondAmountResponse {
+    /// The value of the bond
     pub value: u64,
 }
 

module-system/module-implementations/sov-bank/src/query.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Defines rpc queries exposed by the bank module, along with the relevant types
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_state::WorkingSet;

module-system/module-implementations/sov-blob-storage/src/query.rs

@@ -1,4 +1,3 @@
-#![allow(missing_docs)]
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_modules_api::ModuleInfo;

module-system/module-implementations/sov-sequencer-registry/src/query.rs

@@ -1,5 +1,4 @@
-#![allow(missing_docs)]
-
+//! Defines rpc queries exposed by the sequencer registry module, along with the relevant types
 use jsonrpsee::core::RpcResult;
 use sov_modules_api::macros::rpc_gen;
 use sov_modules_api::Context;

module-system/sov-modules-macros/src/rpc/expose_rpc.rs

@@ -80,6 +80,7 @@ impl ExposeRpcMacro {
 
             let rpc_trait_impl = quote! {
                 impl #field_generics #rpc_trait_ident #field_path_args for RpcStorage<#context_type> {
+                    /// Get a working set on top of the current storage
                     fn get_working_set(&self) -> ::sov_state::WorkingSet<<#context_type as ::sov_modules_api::Spec>::Storage>
                     {
                         ::sov_state::WorkingSet::new(self.storage.clone())
@@ -90,8 +91,9 @@ impl ExposeRpcMacro {
         }
 
         let get_rpc_methods: proc_macro2::TokenStream = quote! {
-            pub fn get_rpc_methods #impl_generics (storage: <#context_type as ::sov_modules_api::Spec>::Storage) -> jsonrpsee::RpcModule<()> #where_clause {
-                let mut module = jsonrpsee::RpcModule::new(());
+            /// Returns a [`jsonrpsee::RpcModule`] with all the rpc methods exposed by the module
+            pub fn get_rpc_methods #impl_generics (storage: <#context_type as ::sov_modules_api::Spec>::Storage) -> ::jsonrpsee::RpcModule<()> #where_clause{
+                let mut module = ::jsonrpsee::RpcModule::new(());
                 let r = RpcStorage::<#context_type> {
                     storage: storage.clone(),
                 };

module-system/sov-modules-macros/src/rpc/rpc_gen.rs

@@ -71,6 +71,7 @@ struct RpcImplBlock {
 struct RpcEnabledMethod {
     pub(crate) method_name: Ident,
     pub(crate) method_signature: Signature,
+    pub(crate) docs: Vec<Attribute>,
     pub(crate) idx_of_working_set_arg: Option<usize>,
 }
 
@@ -106,6 +107,7 @@ impl RpcImplBlock {
 
             let mut signature = method.method_signature.clone();
             let method_name = &method.method_name;
+            let docs = &method.docs;
 
             let impl_trait_method = if let Some(idx) = method.idx_of_working_set_arg {
                 // If necessary, adjust the signature to remove the working set argument and replace it with one generated by the implementer.
@@ -124,6 +126,7 @@ impl RpcImplBlock {
                 signature.inputs = inputs.into_iter().collect();
 
                 quote! {
+                    #( #docs )*
                     #signature {
                         <#type_name #ty_generics as ::std::default::Default>::default().#method_name(#(#pre_working_set_args,)* &mut Self::get_working_set(self), #(#post_working_set_args),* )
                     }
@@ -147,12 +150,14 @@ impl RpcImplBlock {
                 let pre_working_set_args = arg_values.clone().take(idx);
                 let post_working_set_args = arg_values.clone().skip(idx + 1);
                 quote! {
+                    #( #docs )*
                     #signature {
                         <Self as #impl_trait_name #ty_generics >::#method_name(#(#pre_working_set_args,)* #(#post_working_set_args),* )
                     }
                 }
             } else {
                 quote! {
+                    #( #docs )*
                     #signature {
                         <Self as #impl_trait_name #ty_generics >::#method_name(#(#arg_values),*)
                     }
@@ -164,13 +169,18 @@ impl RpcImplBlock {
 
         let rpc_impl_trait = if let Some(ref working_set_type) = self.working_set_type {
             quote! {
+                /// Allows a Runtime to be converted into a functional RPC server by simply implementing the two required methods -
+                /// `get_backing_impl(&self) -> MyModule` and `get_working_set(&self) -> ::sov_modules_api::WorkingSet<C>`
                 pub trait #impl_trait_name #generics #where_clause {
+                    /// Get a clean working set on top of the latest state
                     fn get_working_set(&self) -> #working_set_type;
                     #(#impl_trait_methods)*
                 }
             }
         } else {
             quote! {
+                /// Allows a Runtime to be converted into a functional RPC server by simply implementing the two required methods -
+                /// `get_backing_impl(&self) -> MyModule` and `get_working_set(&self) -> ::sov_modules_api::WorkingSet<C>`
                 pub trait #impl_trait_name #generics #where_clause {
                     #(#impl_trait_methods)*
                 }
@@ -243,7 +253,7 @@ fn build_rpc_trait(
 
     let generics = &input.generics;
     let mut rpc_info = RpcImplBlock {
-        type_name,
+        type_name: type_name.clone(),
         methods: vec![],
         working_set_type: None,
         generics: generics.clone(),
@@ -269,9 +279,16 @@ fn build_rpc_trait(
                 } else {
                     None
                 };
+                let docs = method
+                    .attrs
+                    .iter()
+                    .filter(|attr| attr.path.is_ident("doc"))
+                    .cloned()
+                    .collect::<Vec<_>>();
                 rpc_info.methods.push(RpcEnabledMethod {
                     method_name: method.sig.ident.clone(),
                     method_signature: method.sig.clone(),
+                    docs: docs.clone(),
                     idx_of_working_set_arg,
                 });
 
@@ -281,6 +298,7 @@ fn build_rpc_trait(
 
                 // Build the annotated signature for the intermediate trait
                 let annotated_signature = quote! {
+                    #( #docs )*
                     #attr
                     #intermediate_signature;
                 };
@@ -303,6 +321,7 @@ fn build_rpc_trait(
         #input
     };
 
+    let doc_string = format!("Generated RPC trait for {}", type_name);
     let where_clause = &generics.where_clause;
 
     let rpc_output = quote! {
@@ -312,10 +331,12 @@ fn build_rpc_trait(
 
 
         #rpc_attribute
+        #[doc = #doc_string]
         pub trait #intermediate_trait_name  #generics #where_clause {
 
             #(#intermediate_trait_items)*
 
+            /// Check the health of the RPC server
             #[method(name = "health")]
             fn health(&self) -> ::jsonrpsee::core::RpcResult<()> {
                 Ok(())