fix(proc macros): generate documentation for trait methods. (#453)

* fix(proc macros): generate documentation

Fixes #449

* revert proc macro example

* add test that docs are generated

* use import

* address grumbles

* make the code less ugly

* simplify more

* fix grumbles: check ident before parse

* more grumbles: filter_map -> filter

proc-macros/src/helpers.rs

@@ -25,7 +25,7 @@
 // DEALINGS IN THE SOFTWARE.
 
 use crate::visitor::{FindAllParams, FindSubscriptionParams};
-use proc_macro2::Span;
+use proc_macro2::{Span, TokenStream as TokenStream2};
 use proc_macro_crate::{crate_name, FoundCrate};
 use quote::quote;
 use std::collections::HashSet;
@@ -165,6 +165,18 @@ pub(crate) fn is_option(ty: &syn::Type) -> bool {
 	false
 }
 
+/// Iterates over all Attribute's and parses only the attributes that are doc comments.
+///
+/// Note that `doc comments` are expanded into `#[doc = "some comment"]`
+/// Thus, if the attribute starts with `doc` => it's regarded as a doc comment.
+pub(crate) fn extract_doc_comments(attrs: &[syn::Attribute]) -> TokenStream2 {
+	let docs = attrs.iter().filter(|attr| attr.path.is_ident("doc")).filter(|attr| match attr.parse_meta() {
+		Ok(syn::Meta::NameValue(meta)) if matches!(&meta.lit, syn::Lit::Str(_)) => true,
+		_ => false,
+	});
+	quote! ( #(#docs)* )
+}
+
 #[cfg(test)]
 mod tests {
 	use super::is_option;

proc-macros/src/render_client.rs

@@ -108,10 +108,10 @@ impl RpcDescription {
 		};
 
 		// Doc-comment to be associated with the method.
-		let doc_comment = format!("Invokes the RPC method `{}`.", rpc_method_name);
+		let docs = &method.docs;
 
 		let method = quote! {
-			#[doc = #doc_comment]
+			#docs
 			async fn #rust_method_name(#rust_method_params) -> #returns {
 				self.#called_method(#rpc_method_name, #parameters).await
 			}
@@ -151,10 +151,10 @@ impl RpcDescription {
 		};
 
 		// Doc-comment to be associated with the method.
-		let doc_comment = format!("Subscribes to the RPC method `{}`.", rpc_sub_name);
+		let docs = &sub.docs;
 
 		let method = quote! {
-			#[doc = #doc_comment]
+			#docs
 			async fn #rust_method_name(#rust_method_params) -> #returns {
 				self.subscribe(#rpc_sub_name, #parameters, #rpc_unsub_name).await
 			}

proc-macros/src/render_server.rs

@@ -39,7 +39,6 @@ impl RpcDescription {
 
 		let method_impls = self.render_methods()?;
 		let into_rpc_impl = self.render_into_rpc()?;
-
 		let async_trait = self.jrps_server_item(quote! { types::__reexports::async_trait });
 
 		// Doc-comment to be associated with the server.
@@ -58,14 +57,26 @@ impl RpcDescription {
 	}
 
 	fn render_methods(&self) -> Result<TokenStream2, syn::Error> {
-		let methods = self.methods.iter().map(|method| &method.signature);
+		let methods = self.methods.iter().map(|method| {
+			let docs = &method.docs;
+			let method_sig = &method.signature;
+			quote! {
+				#docs
+				#method_sig
+			}
+		});
 
-		let subscription_sink_ty = self.jrps_server_item(quote! { SubscriptionSink });
-		let subscriptions = self.subscriptions.iter().cloned().map(|mut sub| {
+		let subscriptions = self.subscriptions.iter().map(|sub| {
+			let docs = &sub.docs;
+			let subscription_sink_ty = self.jrps_server_item(quote! { SubscriptionSink });
 			// Add `SubscriptionSink` as the second input parameter to the signature.
 			let subscription_sink: syn::FnArg = syn::parse_quote!(subscription_sink: #subscription_sink_ty);
-			sub.signature.sig.inputs.insert(1, subscription_sink);
-			sub.signature
+			let mut sub_sig = sub.signature.clone();
+			sub_sig.sig.inputs.insert(1, subscription_sink);
+			quote! {
+				#docs
+				#sub_sig
+			}
 		});
 
 		Ok(quote! {

proc-macros/src/rpc_macro.rs

@@ -26,7 +26,7 @@
 
 //! Declaration of the JSON RPC generator procedural macros.
 
-use crate::{attributes, respan::Respan};
+use crate::{attributes, helpers::extract_doc_comments, respan::Respan};
 
 use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
@@ -35,6 +35,7 @@ use syn::Attribute;
 #[derive(Debug, Clone)]
 pub struct RpcMethod {
 	pub name: String,
+	pub docs: TokenStream2,
 	pub params: Vec<(syn::PatIdent, syn::Type)>,
 	pub returns: Option<syn::Type>,
 	pub signature: syn::TraitItemMethod,
@@ -46,6 +47,7 @@ impl RpcMethod {
 		let attributes = attributes::Method::from_attributes(&method.attrs).respan(&method.attrs.first())?;
 		let sig = method.sig.clone();
 		let name = attributes.name.value();
+		let docs = extract_doc_comments(&method.attrs);
 		let aliases = attributes.aliases.map(|a| a.value().split(',').map(Into::into).collect()).unwrap_or_default();
 		let params: Vec<_> = sig
 			.inputs
@@ -67,13 +69,14 @@ impl RpcMethod {
 		// We've analyzed attributes and don't need them anymore.
 		method.attrs.clear();
 
-		Ok(Self { aliases, name, params, returns, signature: method })
+		Ok(Self { aliases, name, params, returns, signature: method, docs })
 	}
 }
 
 #[derive(Debug, Clone)]
 pub struct RpcSubscription {
 	pub name: String,
+	pub docs: TokenStream2,
 	pub unsubscribe: String,
 	pub params: Vec<(syn::PatIdent, syn::Type)>,
 	pub item: syn::Type,
@@ -87,6 +90,7 @@ impl RpcSubscription {
 		let attributes = attributes::Subscription::from_attributes(&sub.attrs).respan(&sub.attrs.first())?;
 		let sig = sub.sig.clone();
 		let name = attributes.name.value();
+		let docs = extract_doc_comments(&sub.attrs);
 		let unsubscribe = build_unsubscribe_method(&name);
 		let item = attributes.item;
 		let aliases = attributes.aliases.map(|a| a.value().split(',').map(Into::into).collect()).unwrap_or_default();
@@ -107,7 +111,7 @@ impl RpcSubscription {
 		// We've analyzed attributes and don't need them anymore.
 		sub.attrs.clear();
 
-		Ok(Self { name, unsubscribe, unsubscribe_aliases, params, item, signature: sub, aliases })
+		Ok(Self { name, unsubscribe, unsubscribe_aliases, params, item, signature: sub, aliases, docs })
 	}
 }
 

proc-macros/tests/ui/correct/rpc_deny_missing_docs.rs

@@ -0,0 +1,18 @@
+//! Test to check that the proc macros actually generates documentation.
+
+#![deny(missing_docs)]
+
+use jsonrpsee::proc_macros::rpc;
+
+#[rpc(client, server)]
+pub trait ApiWithoutDocumentation {
+	/// Async method.
+	#[method(name = "foo")]
+	async fn async_method(&self) -> jsonrpsee::types::JsonRpcResult<u8>;
+
+	/// Subscription docs.
+	#[subscription(name = "sub", item = String)]
+	fn sub(&self);
+}
+
+fn main() {}