Pallet dispatchable+storage doc module. (paritytech#13341)

* doc-only pallet * cargo fmt * generics fix for dispatchables * use a module instead * add doc comment warning that the dispatchable functions are generated * clean up * fix typo * hide Instance4-Instance16 from `pallet` module docs * revamp Instance1-16 comment * Document storage types Signed-off-by: Oliver Tale-Yazdi <[email protected]> * fmt Signed-off-by: Oliver Tale-Yazdi <[email protected]> * remove unused variables * crate::Call => Call Co-authored-by: Bastian Köcher <[email protected]> * fix indentation Co-authored-by: Bastian Köcher <[email protected]> * remove unneeded block Co-authored-by: Bastian Köcher <[email protected]> * don't need a Vec Co-authored-by: Bastian Köcher <[email protected]> * add "doc only" to coment Co-authored-by: Bastian Köcher <[email protected]> * crate::Call => Call Co-authored-by: Bastian Köcher <[email protected]> * cargo fmt --------- Signed-off-by: Oliver Tale-Yazdi <[email protected]> Co-authored-by: Sam Johnson <[email protected]> Co-authored-by: Oliver Tale-Yazdi <[email protected]> Co-authored-by: Bastian Köcher <[email protected]> Co-authored-by: parity-processbot <>
gear-tech · Apr 10, 2023 · b658fef · b658fef
1 parent b91eaa3
commit b658fef
Show file tree

Hide file tree

Showing 3 changed files with 115 additions and 16 deletions.
diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs
@@ -0,0 +1,79 @@
+// 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 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);
+	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::<proc_macro2::TokenStream>();
+				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::<proc_macro2::TokenStream>()
+	} else {
+		quote::quote!()
+	};
+
+	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::*;
+			#(
+				#( #[doc = #storage_docs] )*
+				pub struct #storage_names();
+			)*
+		}
+
+		/// 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::*;
+			#dispatchables
+		}
+	)
+}
diff --git 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;
@@ -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

diff --git a/frame/support/src/instances.rs b/frame/support/src/instances.rs
@@ -31,66 +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;