From 538500806a4ad2e8fe0d135549e950beeb860569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Thei=C3=9Fen?= Date: Fri, 5 Mar 2021 10:32:23 +0100 Subject: [PATCH] pallet_macro: Generate default documentation for well known types --- .../procedural/src/pallet/expand/call.rs | 12 +++++- .../procedural/src/pallet/expand/config.rs | 43 +++++++++++++++++++ .../procedural/src/pallet/expand/error.rs | 11 ++++- .../procedural/src/pallet/expand/event.rs | 12 +++++- .../src/pallet/expand/genesis_config.rs | 11 ++++- .../procedural/src/pallet/expand/mod.rs | 16 ++++++- .../src/pallet/expand/pallet_struct.rs | 11 ++++- .../procedural/src/pallet/parse/call.rs | 3 ++ 8 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 frame/support/procedural/src/pallet/expand/config.rs diff --git a/frame/support/procedural/src/pallet/expand/call.rs b/frame/support/procedural/src/pallet/expand/call.rs index 830fd267dc9b0..137e055405a38 100644 --- a/frame/support/procedural/src/pallet/expand/call.rs +++ b/frame/support/procedural/src/pallet/expand/call.rs @@ -70,7 +70,17 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream { .collect::>() }); + 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 diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs new file mode 100644 index 0000000000000..1e60313c55317 --- /dev/null +++ b/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() +} diff --git a/frame/support/procedural/src/pallet/expand/error.rs b/frame/support/procedural/src/pallet/expand/error.rs index c8c0a3c0c4d58..000f476d94d8b 100644 --- a/frame/support/procedural/src/pallet/expand/error.rs +++ b/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 diff --git a/frame/support/procedural/src/pallet/expand/event.rs b/frame/support/procedural/src/pallet/expand/event.rs index e04d64750bca4..c4f7aeffa7367 100644 --- a/frame/support/procedural/src/pallet/expand/event.rs +++ b/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); diff --git a/frame/support/procedural/src/pallet/expand/genesis_config.rs b/frame/support/procedural/src/pallet/expand/genesis_config.rs index 1dade8f0144b9..96407cb382bc4 100644 --- a/frame/support/procedural/src/pallet/expand/genesis_config.rs +++ b/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)] diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index c2a81e9bbcd8f..22ef268177789 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/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]) -> Option 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 diff --git a/frame/support/procedural/src/pallet/expand/pallet_struct.rs b/frame/support/procedural/src/pallet/expand/pallet_struct.rs index 6e456695d9a45..47e4344c50d8e 100644 --- a/frame/support/procedural/src/pallet/expand/pallet_struct.rs +++ b/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, diff --git a/frame/support/procedural/src/pallet/parse/call.rs b/frame/support/procedural/src/pallet/parse/call.rs index 39b37157db7d0..c3f6751ef70b6 100644 --- a/frame/support/procedural/src/pallet/parse/call.rs +++ b/frame/support/procedural/src/pallet/parse/call.rs @@ -41,6 +41,8 @@ pub struct CallDef { pub methods: Vec, /// The span of the pallet::call attribute. pub attr_span: proc_macro2::Span, + /// Docs, specified on the impl Block. + pub docs: Vec, } /// 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), }) } }