From 92ba29455f54e63b73839d2b5238170e59d24563 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Wed, 8 Feb 2023 11:13:33 -0300 Subject: [PATCH 01/19] doc-only pallet --- .../procedural/src/pallet/expand/doc_only.rs | 56 +++++++++++++++++++ .../procedural/src/pallet/expand/mod.rs | 3 + 2 files changed, 59 insertions(+) create mode 100644 frame/support/procedural/src/pallet/expand/doc_only.rs diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs new file mode 100644 index 0000000000000..ef0a4cf07709a --- /dev/null +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -0,0 +1,56 @@ +// This file is part of Substrate. + +// Copyright (C) 2023 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; + +pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { + let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); + let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); + let dispatchables = { + if let Some(call_def) = &def.call { + call_def.methods.iter().map(|method| { + let name = &method.name; + let args = &method.args.iter().map(|(_, arg_name, arg_type)| { + quote::quote!( #arg_name: #arg_type, ) + }).collect::(); + let docs = &method.docs; + + quote::quote!( + #( #[doc = #docs] )* + pub fn #name(#args) { unreachable!(); } + ) + }).collect::() + } else { + quote::quote!() + } + }; + + quote::quote!( + #[cfg(doc)] + pub mod storage_types { + use super::*; + #( + #storage_viss use super::#storage_names; + )* + } + #[cfg(doc)] + pub mod dispatchables { + use super::*; + #dispatchables + } + ) +} diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index 09a25a7101ee7..1b9515aa26dc4 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -33,6 +33,7 @@ mod store_trait; mod tt_default_parts; mod type_value; mod validate_unsigned; +mod doc_only; use crate::pallet::Def; use frame_support_procedural_tools::get_doc_literals; @@ -72,6 +73,7 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream { let origins = origin::expand_origins(&mut def); let validate_unsigned = validate_unsigned::expand_validate_unsigned(&mut def); let tt_default_parts = tt_default_parts::expand_tt_default_parts(&mut def); + let doc_only = doc_only::expand_doc_only(&mut def); if get_doc_literals(&def.item.attrs).is_empty() { def.item.attrs.push(syn::parse_quote!( @@ -103,6 +105,7 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream { #origins #validate_unsigned #tt_default_parts + #doc_only ); def.item From 301547b0b7260766e6077432d068f663ebac094d Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 8 Mar 2023 17:22:17 -0500 Subject: [PATCH 02/19] cargo fmt --- .../procedural/src/pallet/expand/doc_only.rs | 28 +++++++++++-------- .../procedural/src/pallet/expand/mod.rs | 2 +- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index ef0a4cf07709a..ce1f5cb14dcc2 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -22,18 +22,24 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); let dispatchables = { if let Some(call_def) = &def.call { - call_def.methods.iter().map(|method| { - let name = &method.name; - let args = &method.args.iter().map(|(_, arg_name, arg_type)| { - quote::quote!( #arg_name: #arg_type, ) - }).collect::(); - let docs = &method.docs; + call_def + .methods + .iter() + .map(|method| { + let name = &method.name; + let args = &method + .args + .iter() + .map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, )) + .collect::(); + let docs = &method.docs; - quote::quote!( - #( #[doc = #docs] )* - pub fn #name(#args) { unreachable!(); } - ) - }).collect::() + quote::quote!( + #( #[doc = #docs] )* + pub fn #name(#args) { unreachable!(); } + ) + }) + .collect::() } else { quote::quote!() } diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index 1b9515aa26dc4..926ab0ec82d73 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -18,6 +18,7 @@ mod call; mod config; mod constants; +mod doc_only; mod documentation; mod error; mod event; @@ -33,7 +34,6 @@ mod store_trait; mod tt_default_parts; mod type_value; mod validate_unsigned; -mod doc_only; use crate::pallet::Def; use frame_support_procedural_tools::get_doc_literals; From df6f60fb1c5d7973f9820f3222056103754c2b45 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 8 Mar 2023 18:57:16 -0500 Subject: [PATCH 03/19] generics fix for dispatchables --- frame/support/procedural/src/pallet/expand/doc_only.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index ce1f5cb14dcc2..4c107d5548eb5 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -15,6 +15,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +use proc_macro2::Span; + use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { @@ -45,6 +47,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { } }; + let type_impl_generics = def.type_impl_generics(Span::call_site()); + quote::quote!( #[cfg(doc)] pub mod storage_types { @@ -56,7 +60,10 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { #[cfg(doc)] pub mod dispatchables { use super::*; - #dispatchables + pub struct Dispatchables; + impl<#type_impl_generics> Dispatchables { + #dispatchables + } } ) } From 6e770743967a234c9653dd5a0153c3a8977c6678 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Thu, 9 Mar 2023 00:15:32 -0500 Subject: [PATCH 04/19] use a module instead --- .../procedural/src/pallet/expand/doc_only.rs | 13 ++++++------- frame/support/test/pallet/src/lib.rs | 1 + 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 4c107d5548eb5..70f2dca69bc98 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -24,6 +24,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); let dispatchables = { if let Some(call_def) = &def.call { + let type_impl_generics = def.type_impl_generics(Span::call_site()); call_def .methods .iter() @@ -38,7 +39,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { quote::quote!( #( #[doc = #docs] )* - pub fn #name(#args) { unreachable!(); } + pub fn #name<#type_impl_generics>(#args) { unreachable!(); } ) }) .collect::() @@ -47,9 +48,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { } }; - let type_impl_generics = def.type_impl_generics(Span::call_site()); - quote::quote!( + /// Auto-generated docs-only module listing all defined storage types for this pallet #[cfg(doc)] pub mod storage_types { use super::*; @@ -57,13 +57,12 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { #storage_viss use super::#storage_names; )* } + + /// Auto-generated docs-only module listing all defined dispatchables for this pallet #[cfg(doc)] pub mod dispatchables { use super::*; - pub struct Dispatchables; - impl<#type_impl_generics> Dispatchables { - #dispatchables - } + #dispatchables } ) } diff --git a/frame/support/test/pallet/src/lib.rs b/frame/support/test/pallet/src/lib.rs index 82f12ea954614..33563041be9ce 100644 --- a/frame/support/test/pallet/src/lib.rs +++ b/frame/support/test/pallet/src/lib.rs @@ -23,6 +23,7 @@ pub use pallet::*; #[frame_support::pallet] +#[allow(missing_docs)] pub mod pallet { #[allow(unused_imports)] use frame_support::pallet_prelude::*; From ad09c26e60d30d3277f844b06fc520f33e48db2f Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Sat, 11 Mar 2023 02:25:33 -0500 Subject: [PATCH 05/19] add doc comment warning that the dispatchable functions are generated --- .../support/procedural/src/pallet/expand/doc_only.rs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 70f2dca69bc98..cb67857780610 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -36,8 +36,18 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { .map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, )) .collect::(); let docs = &method.docs; - + let line_2 = format!( + " designed to document the [`{}`][`crate::Call::{}`] variant of", + name, name + ); quote::quote!( + /// NOTE: This function is an automatically generated, uncallable stub + #[ doc = #line_2 ] + /// the pallet [`Call`](`crate::Call`) enum. You should not attempt to + /// call this function directly. + /// + /// --- + /// #( #[doc = #docs] )* pub fn #name<#type_impl_generics>(#args) { unreachable!(); } ) From 07014317283ee2db8ba3cbc3238089097f0aaccc Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Tue, 14 Mar 2023 16:16:44 -0400 Subject: [PATCH 06/19] clean up --- .../procedural/src/pallet/expand/doc_only.rs | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index cb67857780610..0393b41325b2c 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -41,14 +41,14 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { name, name ); quote::quote!( + #( #[doc = #docs] )* + /// + /// --- + /// /// NOTE: This function is an automatically generated, uncallable stub #[ doc = #line_2 ] /// the pallet [`Call`](`crate::Call`) enum. You should not attempt to /// call this function directly. - /// - /// --- - /// - #( #[doc = #docs] )* pub fn #name<#type_impl_generics>(#args) { unreachable!(); } ) }) @@ -60,6 +60,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { quote::quote!( /// Auto-generated docs-only module listing all defined storage types for this pallet + /// Note that members of this module cannot be used directly and are only provided for + /// documentation purposes. #[cfg(doc)] pub mod storage_types { use super::*; @@ -68,7 +70,9 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { )* } - /// Auto-generated docs-only module listing all defined dispatchables for this pallet + /// Auto-generated docs-only module listing all defined dispatchables for this pallet. + /// Note that members of this module cannot be used directly and are only provided for + /// documentation purposes. #[cfg(doc)] pub mod dispatchables { use super::*; From 725bed1d4f14103a0758f2cad264d299d720b90f Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Tue, 14 Mar 2023 16:18:33 -0400 Subject: [PATCH 07/19] fix typo --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 0393b41325b2c..8b1ca95529095 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -59,7 +59,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { }; quote::quote!( - /// Auto-generated docs-only module listing all defined storage types for this pallet + /// Auto-generated docs-only module listing all defined storage types for this pallet. /// Note that members of this module cannot be used directly and are only provided for /// documentation purposes. #[cfg(doc)] From 3bd7e4e386cbc5a24de5bd5ac4888f38db0c87f7 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Tue, 14 Mar 2023 16:38:49 -0400 Subject: [PATCH 08/19] hide Instance4-Instance16 from `pallet` module docs --- frame/support/src/instances.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/frame/support/src/instances.rs b/frame/support/src/instances.rs index 482051c1f36d0..1e1d818980406 100644 --- a/frame/support/src/instances.rs +++ b/frame/support/src/instances.rs @@ -44,53 +44,66 @@ pub struct Instance2; pub struct Instance3; /// Instance4 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance4; /// Instance5 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance5; /// Instance6 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance6; /// Instance7 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance7; /// Instance8 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance8; /// Instance9 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance9; /// Instance10 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance10; /// Instance11 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance11; /// Instance12 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance12; /// Instance13 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance13; /// Instance14 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance14; /// Instance15 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance15; /// Instance16 to be used for instantiable pallet define with `pallet` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance16; From ad4bc3fb519c35c4027a20e8c01375dcb7664aac Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Tue, 14 Mar 2023 16:51:43 -0400 Subject: [PATCH 09/19] revamp Instance1-16 comment --- frame/support/src/instances.rs | 36 +++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/frame/support/src/instances.rs b/frame/support/src/instances.rs index 1e1d818980406..396018d5cbd52 100644 --- a/frame/support/src/instances.rs +++ b/frame/support/src/instances.rs @@ -31,79 +31,83 @@ //! NOTE: [`frame_support::pallet`] will reexport them inside the module, in order to make them //! accessible to [`frame_support::construct_runtime`]. -/// Instance1 to be used for instantiable pallet define with `pallet` macro. +/// `Instance1` to be used for instantiable palllets defined with the +/// [`#[pallet]`](`frame_support::pallet`) macro. Instances 2-16 are also available but are hidden +/// from docs. #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance1; -/// Instance2 to be used for instantiable pallet define with `pallet` macro. +/// `Instance2` to be used for instantiable palllets defined with the `#[pallet]` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance2; -/// Instance3 to be used for instantiable pallet define with `pallet` macro. +/// `Instance3` to be used for instantiable palllets defined with the `#[pallet]` macro. +#[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance3; -/// Instance4 to be used for instantiable pallet define with `pallet` macro. +/// `Instance4` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance4; -/// Instance5 to be used for instantiable pallet define with `pallet` macro. +/// `Instance5` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance5; -/// Instance6 to be used for instantiable pallet define with `pallet` macro. +/// `Instance6` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance6; -/// Instance7 to be used for instantiable pallet define with `pallet` macro. +/// `Instance7` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance7; -/// Instance8 to be used for instantiable pallet define with `pallet` macro. +/// `Instance8` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance8; -/// Instance9 to be used for instantiable pallet define with `pallet` macro. +/// `Instance9` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance9; -/// Instance10 to be used for instantiable pallet define with `pallet` macro. +/// `Instance10` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance10; -/// Instance11 to be used for instantiable pallet define with `pallet` macro. +/// `Instance11` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance11; -/// Instance12 to be used for instantiable pallet define with `pallet` macro. +/// `Instance12` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance12; -/// Instance13 to be used for instantiable pallet define with `pallet` macro. +/// `Instance13` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance13; -/// Instance14 to be used for instantiable pallet define with `pallet` macro. +/// `Instance14` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance14; -/// Instance15 to be used for instantiable pallet define with `pallet` macro. +/// `Instance15` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance15; -/// Instance16 to be used for instantiable pallet define with `pallet` macro. +/// `Instance16` to be used for instantiable palllets defined with the `#[pallet]` macro. #[doc(hidden)] #[derive(Clone, Copy, PartialEq, Eq, crate::RuntimeDebugNoBound)] pub struct Instance16; From 2d91eb3c25985d1f81f6c1aae683318b576c8a68 Mon Sep 17 00:00:00 2001 From: Oliver Tale-Yazdi Date: Tue, 14 Mar 2023 21:53:57 +0100 Subject: [PATCH 10/19] Document storage types Signed-off-by: Oliver Tale-Yazdi --- frame/support/procedural/src/pallet/expand/doc_only.rs | 5 ++++- frame/support/test/pallet/src/lib.rs | 1 - 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 8b1ca95529095..543c9c4543d67 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -22,6 +22,8 @@ use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); + let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::>(); + let storage_generics = &def.storages.iter().map(|storage| &storage.named_generics).collect::>(); let dispatchables = { if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); @@ -66,7 +68,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { pub mod storage_types { use super::*; #( - #storage_viss use super::#storage_names; + #( #[doc = #storage_docs] )* + pub struct #storage_names(); )* } diff --git a/frame/support/test/pallet/src/lib.rs b/frame/support/test/pallet/src/lib.rs index 33563041be9ce..82f12ea954614 100644 --- a/frame/support/test/pallet/src/lib.rs +++ b/frame/support/test/pallet/src/lib.rs @@ -23,7 +23,6 @@ pub use pallet::*; #[frame_support::pallet] -#[allow(missing_docs)] pub mod pallet { #[allow(unused_imports)] use frame_support::pallet_prelude::*; From 4b10fe0ae92d1dc5499a50d0e38898251c6f6422 Mon Sep 17 00:00:00 2001 From: Oliver Tale-Yazdi Date: Tue, 14 Mar 2023 21:58:20 +0100 Subject: [PATCH 11/19] fmt Signed-off-by: Oliver Tale-Yazdi --- frame/support/procedural/src/pallet/expand/doc_only.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 543c9c4543d67..cffc563228890 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -23,7 +23,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::>(); - let storage_generics = &def.storages.iter().map(|storage| &storage.named_generics).collect::>(); + let storage_generics = + &def.storages.iter().map(|storage| &storage.named_generics).collect::>(); let dispatchables = { if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); From 09ec374d5c7baa216fa93892a066fdd932b22953 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Tue, 14 Mar 2023 17:04:05 -0400 Subject: [PATCH 12/19] remove unused variables --- frame/support/procedural/src/pallet/expand/doc_only.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index cffc563228890..c2884c7e5ea68 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -21,10 +21,7 @@ use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); - let storage_viss = &def.storages.iter().map(|storage| &storage.vis).collect::>(); let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::>(); - let storage_generics = - &def.storages.iter().map(|storage| &storage.named_generics).collect::>(); let dispatchables = { if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); From 4cf61b216a23744ba420cc26e70b20493624c12d Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:14:41 -0400 Subject: [PATCH 13/19] crate::Call => Call MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index c2884c7e5ea68..3a1c8c0a556b6 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -37,7 +37,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { .collect::(); let docs = &method.docs; let line_2 = format!( - " designed to document the [`{}`][`crate::Call::{}`] variant of", + " designed to document the [`{}`][`Call::{}`] variant of", name, name ); quote::quote!( From 15a65367c69a5df5200706e8cc8637a114409792 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:15:08 -0400 Subject: [PATCH 14/19] fix indentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 3a1c8c0a556b6..1e1e6c6346b9d 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -55,8 +55,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { .collect::() } else { quote::quote!() - } - }; + }; quote::quote!( /// Auto-generated docs-only module listing all defined storage types for this pallet. From 0edcb1b4d3dc842ff52ffec913231e4d378383fe Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:15:33 -0400 Subject: [PATCH 15/19] remove unneeded block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 1e1e6c6346b9d..397427ff021d4 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -22,7 +22,7 @@ use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::>(); - let dispatchables = { + let dispatchables = if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); call_def From 329b8d2c87f291adaae425bb65db315e172f30d3 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:16:16 -0400 Subject: [PATCH 16/19] don't need a Vec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 397427ff021d4..6a470e03fb8cb 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -20,8 +20,8 @@ use proc_macro2::Span; use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { - let storage_names = &def.storages.iter().map(|storage| &storage.ident).collect::>(); - let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::>(); + let storage_names = def.storages.iter().map(|storage| &storage.ident); + let storage_docs = def.storages.iter().map(|storage| &storage.docs); let dispatchables = if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); From 70dd55061b4a9bd8890859906b0afcc25dc53db2 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:16:40 -0400 Subject: [PATCH 17/19] add "doc only" to coment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 6a470e03fb8cb..7f19403e66042 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -45,7 +45,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { /// /// --- /// - /// NOTE: This function is an automatically generated, uncallable stub + /// NOTE: This function is an automatically generated, doc only, uncallable stub. #[ doc = #line_2 ] /// the pallet [`Call`](`crate::Call`) enum. You should not attempt to /// call this function directly. From 9a4d2d0ccd5070d1a6204c716fdd188148f32381 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:17:10 -0400 Subject: [PATCH 18/19] crate::Call => Call MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Köcher --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 7f19403e66042..05022731e97bd 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -47,7 +47,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { /// /// NOTE: This function is an automatically generated, doc only, uncallable stub. #[ doc = #line_2 ] - /// the pallet [`Call`](`crate::Call`) enum. You should not attempt to + /// the pallet [`Call`](`Call`) enum. You should not attempt to /// call this function directly. pub fn #name<#type_impl_generics>(#args) { unreachable!(); } ) From 7c4f2b4d7d88f00064a2be345d24074aca3ea360 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 15 Mar 2023 09:26:52 -0400 Subject: [PATCH 19/19] cargo fmt --- .../procedural/src/pallet/expand/doc_only.rs | 65 +++++++++---------- 1 file changed, 31 insertions(+), 34 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 05022731e97bd..32c9329f29498 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -22,40 +22,37 @@ use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { let storage_names = def.storages.iter().map(|storage| &storage.ident); let storage_docs = def.storages.iter().map(|storage| &storage.docs); - let dispatchables = - if let Some(call_def) = &def.call { - let type_impl_generics = def.type_impl_generics(Span::call_site()); - call_def - .methods - .iter() - .map(|method| { - let name = &method.name; - let args = &method - .args - .iter() - .map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, )) - .collect::(); - let docs = &method.docs; - let line_2 = format!( - " designed to document the [`{}`][`Call::{}`] variant of", - name, name - ); - quote::quote!( - #( #[doc = #docs] )* - /// - /// --- - /// - /// NOTE: This function is an automatically generated, doc only, uncallable stub. - #[ doc = #line_2 ] - /// the pallet [`Call`](`Call`) enum. You should not attempt to - /// call this function directly. - pub fn #name<#type_impl_generics>(#args) { unreachable!(); } - ) - }) - .collect::() - } else { - quote::quote!() - }; + let dispatchables = if let Some(call_def) = &def.call { + let type_impl_generics = def.type_impl_generics(Span::call_site()); + call_def + .methods + .iter() + .map(|method| { + let name = &method.name; + let args = &method + .args + .iter() + .map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, )) + .collect::(); + let docs = &method.docs; + let line_2 = + format!(" designed to document the [`{}`][`Call::{}`] variant of", name, name); + quote::quote!( + #( #[doc = #docs] )* + /// + /// --- + /// + /// NOTE: This function is an automatically generated, doc only, uncallable stub. + #[ doc = #line_2 ] + /// the pallet [`Call`] enum. You should not attempt to call this function + /// directly. + pub fn #name<#type_impl_generics>(#args) { unreachable!(); } + ) + }) + .collect::() + } else { + quote::quote!() + }; quote::quote!( /// Auto-generated docs-only module listing all defined storage types for this pallet.