pallet macros: Improve emitted rustdoc

frame/support/procedural/src/pallet/expand/call.rs

@@ -70,7 +70,17 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 			.collect::<Vec<_>>()
 	});
 
+	let default_docs = [syn::parse_quote!(
+		r"Contains one variant per dispatchable that can be called by an extrinsic."
+	)];
+	let docs = if def.call.docs.is_empty() {
+		&default_docs[..]
+	} else {
+		&def.call.docs[..]
+	};
+
 	quote::quote_spanned!(def.call.attr_span =>
+		#( #[doc = #docs] )*
 		#[derive(
 			#frame_support::RuntimeDebugNoBound,
 			#frame_support::CloneNoBound,
@@ -87,7 +97,7 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 				#frame_support::sp_std::marker::PhantomData<(#type_use_gen,)>,
 				#frame_support::Never,
 			),
-			#( #fn_name( #( #args_compact_attr #args_type ),* ), )*
+			#( #( #[doc = #fn_doc] )* #fn_name( #( #args_compact_attr #args_type ),* ), )*
 		}
 
 		impl<#type_impl_gen> #frame_support::dispatch::GetDispatchInfo

frame/support/procedural/src/pallet/expand/config.rs

@@ -0,0 +1,43 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2020-2021 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::pallet::{Def, parse::helper::get_doc_literals};
+
+/// * Generate default rust doc
+pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream {
+	let config = &def.config;
+	let config_item = {
+		let item = &mut def.item.content.as_mut().expect("Checked by def parser").1[config.index];
+		if let syn::Item::Trait(item) = item {
+			item
+		} else {
+			unreachable!("Checked by config parser")
+		}
+	};
+
+	if get_doc_literals(&config_item.attrs).is_empty() {
+		config_item.attrs.push(syn::parse_quote!(
+			#[doc = r"
+			Configuration trait of this pallet.
+
+			Implement this type for a runtime in order to customize this pallet.
+			"]
+		));
+	}
+
+	Default::default()
+}

frame/support/procedural/src/pallet/expand/error.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::pallet::Def;
+use crate::pallet::{Def, parse::helper::get_doc_literals};
 
 /// * impl various trait on Error
 /// * impl ModuleErrorMetadata for Error
@@ -74,6 +74,15 @@ pub fn expand_error(def: &mut Def) -> proc_macro2::TokenStream {
 
 	error_item.variants.insert(0, phantom_variant);
 
+	if get_doc_literals(&error_item.attrs).is_empty() {
+		error_item.attrs.push(syn::parse_quote!(
+			#[doc = r"
+			Custom [dispatch errors](https://substrate.dev/docs/en/knowledgebase/runtime/errors)
+			of this pallet.
+			"]
+		));
+	}
+
 	quote::quote_spanned!(error.attr_span =>
 		impl<#type_impl_gen> #frame_support::sp_std::fmt::Debug for #error_ident<#type_use_gen>
 			#config_where_clause

frame/support/procedural/src/pallet/expand/event.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::pallet::Def;
+use crate::pallet::{Def, parse::helper::get_doc_literals};
 
 /// * Add __Ignore variant on Event
 /// * Impl various trait on Event including metadata
@@ -81,6 +81,15 @@ pub fn expand_event(def: &mut Def) -> proc_macro2::TokenStream {
 		event_item.variants.push(variant);
 	}
 
+	if get_doc_literals(&event_item.attrs).is_empty() {
+		event_item.attrs.push(syn::parse_quote!(
+			#[doc = r"
+			The [event](https://substrate.dev/docs/en/knowledgebase/runtime/events) emitted
+			by this pallet.
+			"]
+		));
+	}
+
 	// derive some traits because system event require Clone, FullCodec, Eq, PartialEq and Debug
 	event_item.attrs.push(syn::parse_quote!(
 		#[derive(
@@ -93,7 +102,6 @@ pub fn expand_event(def: &mut Def) -> proc_macro2::TokenStream {
 		)]
 	));
 
-
 	let deposit_event = if let Some((fn_vis, fn_span)) = &event.deposit_event {
 		let event_use_gen = &event.gen_kind.type_use_gen(event.attr_span);
 		let trait_use_gen = &def.trait_use_generics(event.attr_span);

frame/support/procedural/src/pallet/expand/genesis_config.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::pallet::Def;
+use crate::pallet::{Def, parse::helper::get_doc_literals};
 
 /// * add various derive trait on GenesisConfig struct.
 pub fn expand_genesis_config(def: &mut Def) -> proc_macro2::TokenStream {
@@ -33,6 +33,15 @@ pub fn expand_genesis_config(def: &mut Def) -> proc_macro2::TokenStream {
 		syn::Item::Enum(syn::ItemEnum { attrs, ..}) |
 		syn::Item::Struct(syn::ItemStruct { attrs, .. }) |
 		syn::Item::Type(syn::ItemType { attrs, .. }) => {
+			if get_doc_literals(&attrs).is_empty() {
+				attrs.push(syn::parse_quote!(
+					#[doc = r"
+					Can be used to configure the
+					[genesis state](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec#the-genesis-state)
+					of the contracts pallet.
+					"]
+				));
+			}
 			attrs.push(syn::parse_quote!( #[cfg(feature = "std")] ));
 			attrs.push(syn::parse_quote!(
 				#[derive(#frame_support::Serialize, #frame_support::Deserialize)]

frame/support/procedural/src/pallet/expand/mod.rs

@@ -18,6 +18,7 @@
 mod constants;
 mod pallet_struct;
 mod call;
+mod config;
 mod error;
 mod event;
 mod storage;
@@ -28,7 +29,7 @@ mod genesis_build;
 mod genesis_config;
 mod type_value;
 
-use crate::pallet::Def;
+use crate::pallet::{Def, parse::helper::get_doc_literals};
 use quote::ToTokens;
 
 /// Merge where clause together, `where` token span is taken from the first not none one.
@@ -48,6 +49,7 @@ pub fn merge_where_clauses(clauses: &[&Option<syn::WhereClause>]) -> Option<syn:
 pub fn expand(mut def: Def) -> proc_macro2::TokenStream {
 	let constants = constants::expand_constants(&mut def);
 	let pallet_struct = pallet_struct::expand_pallet_struct(&mut def);
+	let config = config::expand_config(&mut def);
 	let call = call::expand_call(&mut def);
 	let error = error::expand_error(&mut def);
 	let event = event::expand_event(&mut def);
@@ -59,9 +61,21 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream {
 	let genesis_config = genesis_config::expand_genesis_config(&mut def);
 	let type_values = type_value::expand_type_values(&mut def);
 
+	if get_doc_literals(&def.item.attrs).is_empty() {
+		def.item.attrs.push(syn::parse_quote!(
+			#[doc = r"
+			The module that hosts all the
+			[FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame)
+			types needed to add this pallet to a
+			[runtime](https://substrate.dev/docs/en/knowledgebase/runtime/).
+			"]
+		));
+	}
+
 	let new_items = quote::quote!(
 		#constants
 		#pallet_struct
+		#config
 		#call
 		#error
 		#event

frame/support/procedural/src/pallet/expand/pallet_struct.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::pallet::Def;
+use crate::pallet::{Def, parse::helper::get_doc_literals};
 
 /// * Add derive trait on Pallet
 /// * Implement GetPalletVersion on Pallet
@@ -51,6 +51,15 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream {
 		}
 	}
 
+	if get_doc_literals(&pallet_item.attrs).is_empty() {
+		pallet_item.attrs.push(syn::parse_quote!(
+			#[doc = r"
+			The [pallet](https://substrate.dev/docs/en/knowledgebase/runtime/pallets) implementing
+			the on-chain logic.
+			"]
+		));
+	}
+
 	pallet_item.attrs.push(syn::parse_quote!(
 		#[derive(
 			#frame_support::CloneNoBound,

frame/support/procedural/src/pallet/parse/call.rs

@@ -41,6 +41,8 @@ pub struct CallDef {
 	pub methods: Vec<CallVariantDef>,
 	/// The span of the pallet::call attribute.
 	pub attr_span: proc_macro2::Span,
+	/// Docs, specified on the impl Block.
+	pub docs: Vec<syn::Lit>,
 }
 
 /// Definition of dispatchable typically: `#[weight...] fn foo(origin .., param1: ...) -> ..`
@@ -228,6 +230,7 @@ impl CallDef {
 			instances,
 			methods,
 			where_clause: item.generics.where_clause.clone(),
+			docs: helper::get_doc_literals(&item.attrs),
 		})
 	}
 }