diff --git a/examples/demo-nft-module/src/query.rs b/examples/demo-nft-module/src/query.rs index 4b429363fa..aaeb7806f9 100644 --- a/examples/demo-nft-module/src/query.rs +++ b/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 { #[rpc_gen(client, server, namespace = "nft")] impl NonFungibleToken { #[rpc_method(name = "getOwner")] + /// Get the owner of a token pub fn get_owner( &self, token_id: u64, diff --git a/module-system/module-implementations/examples/sov-value-setter/src/query.rs b/module-system/module-implementations/examples/sov-value-setter/src/query.rs index 092b02f675..07ad7a3bab 100644 --- a/module-system/module-implementations/examples/sov-value-setter/src/query.rs +++ b/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; diff --git a/module-system/module-implementations/examples/sov-vec-setter/src/query.rs b/module-system/module-implementations/examples/sov-vec-setter/src/query.rs index 80a6e9e41f..17e4d710ae 100644 --- a/module-system/module-implementations/examples/sov-vec-setter/src/query.rs +++ b/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; diff --git a/module-system/module-implementations/sov-accounts/src/query.rs b/module-system/module-implementations/sov-accounts/src/query.rs index e89a5106d6..28a854f764 100644 --- a/module-system/module-implementations/sov-accounts/src/query.rs +++ b/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 Accounts { #[rpc_method(name = "getAccount")] + /// Get the account corresponding to the given public key. pub fn get_account( &self, pub_key: C::PublicKey, diff --git a/module-system/module-implementations/sov-attester-incentives/src/lib.rs b/module-system/module-implementations/sov-attester-incentives/src/lib.rs index 908ca8be2d..52aa59cc91 100644 --- a/module-system/module-implementations/sov-attester-incentives/src/lib.rs +++ b/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; diff --git a/module-system/module-implementations/sov-attester-incentives/src/query.rs b/module-system/module-implementations/sov-attester-incentives/src/query.rs index 4244df30a4..db1781bdc1 100644 --- a/module-system/module-implementations/sov-attester-incentives/src/query.rs +++ b/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, } diff --git a/module-system/module-implementations/sov-bank/src/query.rs b/module-system/module-implementations/sov-bank/src/query.rs index edadefe127..c683d6dc3e 100644 --- a/module-system/module-implementations/sov-bank/src/query.rs +++ b/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; diff --git a/module-system/module-implementations/sov-blob-storage/src/query.rs b/module-system/module-implementations/sov-blob-storage/src/query.rs index 788eb52a2f..b0f3483f26 100644 --- a/module-system/module-implementations/sov-blob-storage/src/query.rs +++ b/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; diff --git a/module-system/module-implementations/sov-sequencer-registry/src/query.rs b/module-system/module-implementations/sov-sequencer-registry/src/query.rs index 04faddf1ac..c316d45a62 100644 --- a/module-system/module-implementations/sov-sequencer-registry/src/query.rs +++ b/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; diff --git a/module-system/sov-modules-macros/src/rpc/expose_rpc.rs b/module-system/sov-modules-macros/src/rpc/expose_rpc.rs index 0691eff4db..7e7f3459f7 100644 --- a/module-system/sov-modules-macros/src/rpc/expose_rpc.rs +++ b/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(), }; diff --git a/module-system/sov-modules-macros/src/rpc/rpc_gen.rs b/module-system/sov-modules-macros/src/rpc/rpc_gen.rs index 8a0b8d56ff..afc4f3c2ec 100644 --- a/module-system/sov-modules-macros/src/rpc/rpc_gen.rs +++ b/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, pub(crate) idx_of_working_set_arg: Option, } @@ -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 { ::#method_name(#(#pre_working_set_args,)* #(#post_working_set_args),* ) } } } else { quote! { + #( #docs )* #signature { ::#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` 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` 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::>(); 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(())