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 <oliver.tale-yazdi@parity.io>

* fmt

Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>

* remove unused variables

* crate::Call => Call

Co-authored-by: Bastian Köcher <git@kchr.de>

* fix indentation

Co-authored-by: Bastian Köcher <git@kchr.de>

* remove unneeded block

Co-authored-by: Bastian Köcher <git@kchr.de>

* don't need a Vec

Co-authored-by: Bastian Köcher <git@kchr.de>

* add "doc only" to coment

Co-authored-by: Bastian Köcher <git@kchr.de>

* crate::Call => Call

Co-authored-by: Bastian Köcher <git@kchr.de>

* cargo fmt

---------

Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
Co-authored-by: Sam Johnson <sam@durosoft.com>
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
Co-authored-by: Bastian Köcher <git@kchr.de>
Co-authored-by: parity-processbot <>

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
+		}
+	)
+}

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

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;