Pallet dispatchable+storage doc module.

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

@@ -0,0 +1,83 @@
+// 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).collect::<Vec<_>>();
+	let storage_docs = &def.storages.iter().map(|storage| &storage.docs).collect::<Vec<_>>();
+	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 [`{}`][`crate::Call::{}`] variant of",
+						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.
+						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;