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..32c9329f29498 --- /dev/null +++ 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::(); + 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. + /// 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 index 09a25a7101ee7..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; @@ -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 index 482051c1f36d0..396018d5cbd52 100644 --- 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;