From c7c2e9833d0e97c9b81698e6cc904227c9f62cc2 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 16:22:52 +0400 Subject: [PATCH 01/57] fixing links and improving comments --- substrate/frame/support/procedural/src/lib.rs | 70 ++++++++----------- 1 file changed, 29 insertions(+), 41 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 682b135fa143..1c12c1558a12 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -412,13 +412,17 @@ pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStre .unwrap_or_else(|e| e.to_compile_error().into()) } -/// Derive [`Clone`] but do not bound any generic. Docs are at `frame_support::CloneNoBound`. +/// Derive [`Clone`] but do not bound any generic. +/// +/// Docs at [`frame_support::CloneNoBound`](../../frame_support/derive.CloneNoBound.html). #[proc_macro_derive(CloneNoBound)] pub fn derive_clone_no_bound(input: TokenStream) -> TokenStream { no_bound::clone::derive_clone_no_bound(input) } -/// Derive [`Debug`] but do not bound any generics. Docs are at `frame_support::DebugNoBound`. +/// Derive [`Debug`] but do not bound any generics. +/// +/// Docs at [`frame_support::DebugNoBound`](../../frame_support/derive.DebugNoBound.html). #[proc_macro_derive(DebugNoBound)] pub fn derive_debug_no_bound(input: TokenStream) -> TokenStream { no_bound::debug::derive_debug_no_bound(input) @@ -453,14 +457,17 @@ pub fn derive_runtime_debug_no_bound(input: TokenStream) -> TokenStream { } } -/// Derive [`PartialEq`] but do not bound any generic. Docs are at -/// `frame_support::PartialEqNoBound`. +/// Derive [`PartialEq`] but do not bound any generic. +/// +/// Docs at [`frame_support::PartialEqNoBound`](../../frame_support/derive.PartialEqNoBound.html). #[proc_macro_derive(PartialEqNoBound)] pub fn derive_partial_eq_no_bound(input: TokenStream) -> TokenStream { no_bound::partial_eq::derive_partial_eq_no_bound(input) } -/// derive Eq but do no bound any generic. Docs are at `frame_support::EqNoBound`. +/// DeriveEq but do no bound any generic. +/// +/// Docs at [`frame_support::EqNoBound`](../../frame_support/derive.EqNoBound.html). #[proc_macro_derive(EqNoBound)] pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { let input: syn::DeriveInput = match syn::parse(input) { @@ -480,6 +487,8 @@ pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { } /// derive `Default` but do no bound any generic. Docs are at `frame_support::DefaultNoBound`. +/// +/// Docs at [`frame_support::DefaultNoBound`](../../frame_support/derive.PartialEqNoBound.html). #[proc_macro_derive(DefaultNoBound, attributes(default))] pub fn derive_default_no_bound(input: TokenStream) -> TokenStream { no_bound::default::derive_default_no_bound(input) @@ -979,21 +988,15 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::constant`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::constant`](../../frame_support/pallet_macros/attr.constant.html). #[proc_macro_attribute] pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::constant_name`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::constant_name`](../../frame_support/pallet_macros/attr.constant_name.html). #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1097,20 +1100,14 @@ pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::call`](../../frame_support/pallet_macros/attr.call.html). +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::compact`](../../frame_support/pallet_macros/attr.compact.html). #[proc_macro_attribute] pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in +/// Documentation for this item can be found at /// [`frame_support::pallet_macros::call`](../../frame_support/pallet_macros/attr.call.html). #[proc_macro_attribute] pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { @@ -1122,8 +1119,8 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { /// /// --- /// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::call`](../../frame_support/pallet_macros/attr.call.html). +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::call_index`](../../frame_support/pallet_macros/attr.call_index.html). #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1285,11 +1282,8 @@ pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::storage`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::storage`](../../frame_support/pallet_macros/attr.storage.html). #[proc_macro_attribute] pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1392,21 +1386,15 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::genesis_config`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::genesis_config`](../../frame_support/pallet_macros/attr.genesis_config.html). #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// -/// --- -/// -/// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::genesis_build`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::genesis_build`](../../frame_support/pallet_macros/attr.genesis_build.html). #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() From de5e6e209bc581577ae7be273c2a39dcd1205383 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:15:23 +0400 Subject: [PATCH 02/57] document crate_to_crate_version --- substrate/frame/support/procedural/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 1c12c1558a12..70c9335b3d63 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -494,6 +494,7 @@ pub fn derive_default_no_bound(input: TokenStream) -> TokenStream { no_bound::default::derive_default_no_bound(input) } +/// Macro used internally in FRAME to generate the crate version for a pallet. #[proc_macro] pub fn crate_to_crate_version(input: TokenStream) -> TokenStream { crate_version::crate_to_crate_version(input) From cf3ce886bb7af7892f43658ca84bcfc21740260f Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:21:51 +0400 Subject: [PATCH 03/57] fix bench links --- substrate/frame/support/procedural/src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 70c9335b3d63..351bfdee1f68 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -321,7 +321,7 @@ pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as a benchmarking module. /// -/// See `frame_benchmarking::v2` for more info. +/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. #[proc_macro_attribute] pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, false) { @@ -333,7 +333,7 @@ pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as an instance benchmarking module. /// -/// See `frame_benchmarking::v2` for more info. +/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. #[proc_macro_attribute] pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, true) { @@ -372,7 +372,7 @@ pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream /// enclosing benchmark function, This attribute is also used as a boundary designating where /// the benchmark setup code ends, and the benchmark verification code begins. /// -/// See `frame_benchmarking::v2` for more info. +/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. #[proc_macro_attribute] pub fn block(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( From 0abcfea167e62f15ed6274f0459f3b2e323b1273 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:30:31 +0400 Subject: [PATCH 04/57] move error docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 45 +-------------- substrate/frame/support/src/lib.rs | 55 +++++++++++++++++-- 2 files changed, 52 insertions(+), 48 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 351bfdee1f68..42349e8994bc 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1182,49 +1182,8 @@ pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::error]` attribute allows you to define an error enum that will be returned -/// from the dispatchable when an error occurs. The information for this error type is then -/// stored in metadata. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::error] -/// pub enum Error { -/// /// $some_optional_doc -/// $SomeFieldLessVariant, -/// /// $some_more_optional_doc -/// $SomeVariantWithOneField(FieldType), -/// ... -/// } -/// ``` -/// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field -/// variants. -/// -/// Any field type in the enum variants must implement `TypeInfo` in order to be properly used -/// in the metadata, and its encoded size should be as small as possible, preferably 1 byte in -/// size in order to reduce storage size. The error enum itself has an absolute maximum encoded -/// size specified by `MAX_MODULE_ERROR_ENCODED_SIZE`. -/// -/// (1 byte can still be 256 different errors. The more specific the error, the easier it is to -/// diagnose problems and give a better experience to the user. Don't skimp on having lots of -/// individual error conditions.) -/// -/// Field types in enum variants must also implement `PalletError`, otherwise the pallet will -/// fail to compile. Rust primitive types have already implemented the `PalletError` trait -/// along with some commonly used stdlib types such as [`Option`] and `PhantomData`, and hence -/// in most use cases, a manual implementation is not necessary and is discouraged. -/// -/// The generic `T` must not bound anything and a `where` clause is not allowed. That said, -/// bounds and/or a where clause should not needed for any use-case. -/// -/// ## Macro expansion -/// -/// The macro implements the [`Debug`] trait and functions `as_u8` using variant position, and -/// `as_str` using variant doc. -/// -/// The macro also implements `From>` for `&'static str` and `From>` for -/// `DispatchError`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::error`](../../frame_support/pallet_macros/attr.error.html). #[proc_macro_attribute] pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index fd348f62b4f7..0df94db412d9 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2228,13 +2228,58 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - composite_enum, config, disable_frame_system_supertrait_check, error, event, - extra_constants, feeless_if, generate_deposit, generate_store, getter, hooks, - import_section, inherent, no_default, no_default_bounds, origin, pallet_section, - storage_prefix, storage_version, type_value, unbounded, validate_unsigned, weight, - whitelist_storage, + composite_enum, config, disable_frame_system_supertrait_check, event, extra_constants, + feeless_if, generate_deposit, generate_store, getter, hooks, import_section, inherent, + no_default, no_default_bounds, origin, pallet_section, storage_prefix, storage_version, + type_value, unbounded, validate_unsigned, weight, whitelist_storage, }; + /// The `#[pallet::error]` attribute allows you to define an error enum that will be + /// returned from the dispatchable when an error occurs. The information for this error + /// type is then stored in metadata. + /// + /// Item must be defined as: + /// + /// ```ignore + /// #[pallet::error] + /// pub enum Error { + /// /// $some_optional_doc + /// $SomeFieldLessVariant, + /// /// $some_more_optional_doc + /// $SomeVariantWithOneField(FieldType), + /// ... + /// } + /// ``` + /// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field + /// variants. + /// + /// Any field type in the enum variants must implement [`TypeInfo`] in order to be properly + /// used in the metadata, and its encoded size should be as small as possible, preferably 1 + /// byte in size in order to reduce storage size. The error enum itself has an absolute + /// maximum encoded size specified by [`frame_support::MAX_MODULE_ERROR_ENCODED_SIZE`]. + /// + /// (1 byte can still be 256 different errors. The more specific the error, the easier it + /// is to diagnose problems and give a better experience to the user. Don't skimp on having + /// lots of individual error conditions.) + /// + /// Field types in enum variants must also implement [`frame_support::PalletError`], + /// otherwise the pallet will fail to compile. Rust primitive types have already + /// implemented the [`frame_support::PalletError`] trait along with some commonly used + /// stdlib types such as [`Option`] and [`sp_std::marker::PhantomData`], and hence + /// in most use cases, a manual implementation is not necessary and is discouraged. + /// + /// The generic `T` must not bound anything and a `where` clause is not allowed. That said, + /// bounds and/or a where clause should not needed for any use-case. + /// + /// ## Macro expansion + /// + /// The macro implements the [`Debug`] trait and functions `as_u8` using variant position, + /// and `as_str` using variant doc. + /// + /// The macro also implements `From>` for `&'static str` and `From>` for + /// `DispatchError`. + pub use frame_support_procedural::error; + /// Allows a pallet to declare a set of functions as a *dispatchable extrinsic*. In /// slightly simplified terms, this macro declares the set of "transactions" of a pallet. /// From b13b793ac9abf074b418454d089059cbb5f65145 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:37:39 +0400 Subject: [PATCH 05/57] move event docs to frame support and fix links --- substrate/frame/support/procedural/src/lib.rs | 24 +---------- substrate/frame/support/src/lib.rs | 41 +++++++++++++++---- 2 files changed, 35 insertions(+), 30 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 42349e8994bc..0b74855ce94f 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1189,28 +1189,8 @@ pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::event]` attribute allows you to define pallet events. Pallet events are -/// stored under the `system` / `events` key when the block is applied (and then replaced when -/// the next block writes it's events). -/// -/// The Event enum must be defined as follows: -/// -/// ```ignore -/// #[pallet::event] -/// #[pallet::generate_deposit($visibility fn deposit_event)] // Optional -/// pub enum Event<$some_generic> $optional_where_clause { -/// /// Some doc -/// $SomeName($SomeType, $YetanotherType, ...), -/// ... -/// } -/// ``` -/// -/// I.e. an enum (with named or unnamed fields variant), named `Event`, with generic: none or -/// `T` or `T: Config`, and optional w here clause. -/// -/// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], `Encode`, `Decode`, and -/// [`Debug`] (on std only). For ease of use, bound by the trait `Member`, available in -/// `frame_support::pallet_prelude`. +/// Documentation for this item can be found at +/// [`frame_support::pallet_macros::event`](../../frame_support/pallet_macros/attr.event.html). #[proc_macro_attribute] pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 0df94db412d9..2144478f80db 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2228,10 +2228,10 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - composite_enum, config, disable_frame_system_supertrait_check, event, extra_constants, - feeless_if, generate_deposit, generate_store, getter, hooks, import_section, inherent, - no_default, no_default_bounds, origin, pallet_section, storage_prefix, storage_version, - type_value, unbounded, validate_unsigned, weight, whitelist_storage, + composite_enum, config, disable_frame_system_supertrait_check, extra_constants, feeless_if, + generate_deposit, generate_store, getter, hooks, import_section, inherent, no_default, + no_default_bounds, origin, pallet_section, storage_prefix, storage_version, type_value, + unbounded, validate_unsigned, weight, whitelist_storage, }; /// The `#[pallet::error]` attribute allows you to define an error enum that will be @@ -2253,10 +2253,11 @@ pub mod pallet_macros { /// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field /// variants. /// - /// Any field type in the enum variants must implement [`TypeInfo`] in order to be properly - /// used in the metadata, and its encoded size should be as small as possible, preferably 1 - /// byte in size in order to reduce storage size. The error enum itself has an absolute - /// maximum encoded size specified by [`frame_support::MAX_MODULE_ERROR_ENCODED_SIZE`]. + /// Any field type in the enum variants must implement [`scale_info::TypeInfo`] in order to + /// be properly used in the metadata, and its encoded size should be as small as possible, + /// preferably 1 byte in size in order to reduce storage size. The error enum itself has an + /// absolute maximum encoded size specified by + /// [`frame_support::MAX_MODULE_ERROR_ENCODED_SIZE`]. /// /// (1 byte can still be 256 different errors. The more specific the error, the easier it /// is to diagnose problems and give a better experience to the user. Don't skimp on having @@ -2280,6 +2281,30 @@ pub mod pallet_macros { /// `DispatchError`. pub use frame_support_procedural::error; + /// The `#[pallet::event]` attribute allows you to define pallet events. Pallet events are + /// stored under the `system` / `events` key when the block is applied (and then replaced + /// when the next block writes it's events). + /// + /// The Event enum must be defined as follows: + /// + /// ```ignore + /// #[pallet::event] + /// #[pallet::generate_deposit($visibility fn deposit_event)] // Optional + /// pub enum Event<$some_generic> $optional_where_clause { + /// /// Some doc + /// $SomeName($SomeType, $YetanotherType, ...), + /// ... + /// } + /// ``` + /// + /// I.e. an enum (with named or unnamed fields variant), named `Event`, with generic: none + /// or `T` or `T: Config`, and optional w here clause. + /// + /// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], [`codec::Encode`], + /// [`codec::Decode`], and [`Debug`] (on std only). For ease of use, bound by the trait + /// `Member`, available in `frame_support::pallet_prelude`. + pub use frame_support_procedural::event; + /// Allows a pallet to declare a set of functions as a *dispatchable extrinsic*. In /// slightly simplified terms, this macro declares the set of "transactions" of a pallet. /// From 00b909c807198252e9b13bcd78fc9d86dd9f4f01 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:39:18 +0400 Subject: [PATCH 06/57] fix extrinsic call --- substrate/frame/support/procedural/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 0b74855ce94f..ff804b62fc46 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -359,7 +359,7 @@ pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { /// used as a boundary designating where the benchmark setup code ends, and the benchmark /// verification code begins. /// -/// See `frame_benchmarking::v2` for more info. +/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. #[proc_macro_attribute] pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( From cf3c9f78d4928545984654e6ad6e7e80d47423a7 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 17:59:33 +0400 Subject: [PATCH 07/57] add links to feeless_if macro --- substrate/frame/support/procedural/src/lib.rs | 56 ++++++------------- substrate/frame/support/src/lib.rs | 32 ++++++++++- 2 files changed, 48 insertions(+), 40 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index ff804b62fc46..f0a27eade0cb 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -414,7 +414,7 @@ pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStre /// Derive [`Clone`] but do not bound any generic. /// -/// Docs at [`frame_support::CloneNoBound`](../../frame_support/derive.CloneNoBound.html). +/// Docs at [`frame_support::CloneNoBound`](../frame_support/derive.CloneNoBound.html). #[proc_macro_derive(CloneNoBound)] pub fn derive_clone_no_bound(input: TokenStream) -> TokenStream { no_bound::clone::derive_clone_no_bound(input) @@ -422,7 +422,7 @@ pub fn derive_clone_no_bound(input: TokenStream) -> TokenStream { /// Derive [`Debug`] but do not bound any generics. /// -/// Docs at [`frame_support::DebugNoBound`](../../frame_support/derive.DebugNoBound.html). +/// Docs at [`frame_support::DebugNoBound`](../frame_support/derive.DebugNoBound.html). #[proc_macro_derive(DebugNoBound)] pub fn derive_debug_no_bound(input: TokenStream) -> TokenStream { no_bound::debug::derive_debug_no_bound(input) @@ -459,7 +459,7 @@ pub fn derive_runtime_debug_no_bound(input: TokenStream) -> TokenStream { /// Derive [`PartialEq`] but do not bound any generic. /// -/// Docs at [`frame_support::PartialEqNoBound`](../../frame_support/derive.PartialEqNoBound.html). +/// Docs at [`frame_support::PartialEqNoBound`](../frame_support/derive.PartialEqNoBound.html). #[proc_macro_derive(PartialEqNoBound)] pub fn derive_partial_eq_no_bound(input: TokenStream) -> TokenStream { no_bound::partial_eq::derive_partial_eq_no_bound(input) @@ -467,7 +467,7 @@ pub fn derive_partial_eq_no_bound(input: TokenStream) -> TokenStream { /// DeriveEq but do no bound any generic. /// -/// Docs at [`frame_support::EqNoBound`](../../frame_support/derive.EqNoBound.html). +/// Docs at [`frame_support::EqNoBound`](../frame_support/derive.EqNoBound.html). #[proc_macro_derive(EqNoBound)] pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { let input: syn::DeriveInput = match syn::parse(input) { @@ -488,7 +488,7 @@ pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { /// derive `Default` but do no bound any generic. Docs are at `frame_support::DefaultNoBound`. /// -/// Docs at [`frame_support::DefaultNoBound`](../../frame_support/derive.PartialEqNoBound.html). +/// Docs at [`frame_support::DefaultNoBound`](../frame_support/derive.PartialEqNoBound.html). #[proc_macro_derive(DefaultNoBound, attributes(default))] pub fn derive_default_no_bound(input: TokenStream) -> TokenStream { no_bound::default::derive_default_no_bound(input) @@ -990,14 +990,14 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::constant`](../../frame_support/pallet_macros/attr.constant.html). +/// [`frame_support::pallet_macros::constant`](../frame_support/pallet_macros/attr.constant.html). #[proc_macro_attribute] pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::constant_name`](../../frame_support/pallet_macros/attr.constant_name.html). +/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr.constant_name.html). #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1102,14 +1102,14 @@ pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream { } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::compact`](../../frame_support/pallet_macros/attr.compact.html). +/// [`frame_support::pallet_macros::compact`](../frame_support/pallet_macros/attr.compact.html). #[proc_macro_attribute] pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::call`](../../frame_support/pallet_macros/attr.call.html). +/// [`frame_support::pallet_macros::call`](../frame_support/pallet_macros/attr.call.html). #[proc_macro_attribute] pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1121,37 +1121,15 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::call_index`](../../frame_support/pallet_macros/attr.call_index.html). +/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index.html). #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` attribute, -/// which explicitly defines the condition for the dispatchable to be feeless. -/// -/// The arguments for the closure must be the referenced arguments of the dispatchable function. -/// -/// The closure must return `bool`. -/// -/// ### Example -/// ```ignore -/// #[pallet::feeless_if(|_origin: &OriginFor, something: &u32| -> bool { -/// *something == 0 -/// })] -/// pub fn do_something(origin: OriginFor, something: u32) -> DispatchResult { -/// .... -/// } -/// ``` -/// -/// Please note that this only works for signed dispatchables and requires a signed extension -/// such as `SkipCheckIfFeeless` as defined in `pallet-skip-feeless-payment` to wrap the existing -/// payment extension. Else, this is completely ignored and the dispatchable is still charged. -/// -/// ### Macro expansion +/// Documentation for this item can be found at /// -/// The macro implements the `CheckIfFeeless` trait on the dispatchable and calls the corresponding -/// closure in the implementation. +/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if.html). #[proc_macro_attribute] pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1183,14 +1161,14 @@ pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::error`](../../frame_support/pallet_macros/attr.error.html). +/// [`frame_support::pallet_macros::error`](../frame_support/pallet_macros/attr.error.html). #[proc_macro_attribute] pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::event`](../../frame_support/pallet_macros/attr.event.html). +/// [`frame_support::pallet_macros::event`](../frame_support/pallet_macros/attr.event.html). #[proc_macro_attribute] pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1223,7 +1201,7 @@ pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::storage`](../../frame_support/pallet_macros/attr.storage.html). +/// [`frame_support::pallet_macros::storage`](../frame_support/pallet_macros/attr.storage.html). #[proc_macro_attribute] pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1327,14 +1305,14 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::genesis_config`](../../frame_support/pallet_macros/attr.genesis_config.html). +/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr.genesis_config.html). #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } /// Documentation for this item can be found at -/// [`frame_support::pallet_macros::genesis_build`](../../frame_support/pallet_macros/attr.genesis_build.html). +/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr.genesis_build.html). #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 2144478f80db..4832e227af4b 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2228,12 +2228,42 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - composite_enum, config, disable_frame_system_supertrait_check, extra_constants, feeless_if, + composite_enum, config, disable_frame_system_supertrait_check, extra_constants, generate_deposit, generate_store, getter, hooks, import_section, inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, storage_version, type_value, unbounded, validate_unsigned, weight, whitelist_storage, }; + /// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` attribute, + /// which explicitly defines the condition for the dispatchable to be feeless. + /// + /// The arguments for the closure must be the referenced arguments of the dispatchable function. + /// + /// The closure must return `bool`. + /// + /// ### Example + /// ```ignore + /// #[pallet::feeless_if(|_origin: &OriginFor, something: &u32| -> bool { + /// *something == 0 + /// })] + /// pub fn do_something(origin: OriginFor, something: u32) -> DispatchResult { + /// .... + /// } + /// ``` + /// + /// Please note that this only works for signed dispatchables and requires a signed extension + /// such as [`pallet_skip_feeless_payment::SkipCheckIfFeeless`] to wrap the existing payment + /// extension. Else, this is completely ignored and the dispatchable is still charged. + /// + /// ### Macro expansion + /// + /// The macro implements the [`pallet_skip_feeless_payment::CheckIfFeeless`] trait on the + /// dispatchable and calls the corresponding closure in the implementation. + /// + /// [`pallet_skip_feeless_payment::SkipCheckIfFeeless`]: ../../pallet_skip_feeless_payment/struct.SkipCheckIfFeeless.html + /// [`pallet_skip_feeless_payment::CheckIfFeeless`]: ../../pallet_skip_feeless_payment/struct.SkipCheckIfFeeless.html + pub use frame_support_procedural::feeless_if; + /// The `#[pallet::error]` attribute allows you to define an error enum that will be /// returned from the dispatchable when an error occurs. The information for this error /// type is then stored in metadata. From e9be90b5ec1d253c9edca76940ebf49089a4bf14 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 6 Dec 2023 18:27:27 +0400 Subject: [PATCH 08/57] fix generate deposit docs --- substrate/frame/support/procedural/src/lib.rs | 74 +++++++++++-------- substrate/frame/support/src/lib.rs | 25 ++++++- 2 files changed, 68 insertions(+), 31 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index f0a27eade0cb..4f7252044c35 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -989,14 +989,20 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::constant`](../frame_support/pallet_macros/attr.constant.html). #[proc_macro_attribute] pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr.constant_name.html). #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { @@ -1101,14 +1107,20 @@ pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::compact`](../frame_support/pallet_macros/attr.compact.html). #[proc_macro_attribute] pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::call`](../frame_support/pallet_macros/attr.call.html). #[proc_macro_attribute] pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { @@ -1120,14 +1132,17 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { /// /// --- /// -/// Documentation for this item can be found at +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index.html). #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// /// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if.html). #[proc_macro_attribute] @@ -1160,47 +1175,40 @@ pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::error`](../frame_support/pallet_macros/attr.error.html). #[proc_macro_attribute] pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::event`](../frame_support/pallet_macros/attr.event.html). #[proc_macro_attribute] pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a -/// helper function on `Pallet` that handles deposit events. /// -/// NOTE: For instantiable pallets, the event must be generic over `T` and `I`. -/// -/// ## Macro expansion -/// -/// The macro will add on enum `Event` the attributes: -/// * `#[derive(frame_support::CloneNoBound)]` -/// * `#[derive(frame_support::EqNoBound)]` -/// * `#[derive(frame_support::PartialEqNoBound)]` -/// * `#[derive(frame_support::RuntimeDebugNoBound)]` -/// * `#[derive(codec::Encode)]` -/// * `#[derive(codec::Decode)]` -/// -/// The macro implements `From>` for (). -/// -/// The macro implements a metadata function on `Event` returning the `EventMetadata`. +/// --- /// -/// If `#[pallet::generate_deposit]` is present then the macro implements `fn deposit_event` on -/// `Pallet`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr.generate_deposit.html). #[proc_macro_attribute] pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::storage`](../frame_support/pallet_macros/attr.storage.html). #[proc_macro_attribute] pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { @@ -1304,14 +1312,20 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr.genesis_config.html). #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Documentation for this item can be found at +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at /// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr.genesis_build.html). #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 4832e227af4b..ebae60c11389 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2229,11 +2229,34 @@ pub use frame_support_procedural::pallet; pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, - generate_deposit, generate_store, getter, hooks, import_section, inherent, no_default, + generate_store, getter, hooks, import_section, inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, storage_version, type_value, unbounded, validate_unsigned, weight, whitelist_storage, }; + /// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a + /// helper function on `Pallet` that handles deposit events. + /// + /// NOTE: For instantiable pallets, the event must be generic over `T` and `I`. + /// + /// ## Macro expansion + /// + /// The macro will add on enum `Event` the attributes: + /// * `#[derive(`[`frame_support::CloneNoBound`]`)]` + /// * `#[derive(`[`frame_support::EqNoBound`]`)]` + /// * `#[derive(`[`frame_support::PartialEqNoBound`]`)]` + /// * `#[derive(`[`frame_support::RuntimeDebugNoBound`]`)]` + /// * `#[derive(`[`codec::Encode`]`)]` + /// * `#[derive(`[`codec::Decode`]`)]` + /// + /// The macro implements `From>` for (). + /// + /// The macro implements a metadata function on `Event` returning the `EventMetadata`. + /// + /// If `#[pallet::generate_deposit]` is present then the macro implements `fn deposit_event` on + /// `Pallet`. + pub use frame_support_procedural::generate_deposit; + /// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` attribute, /// which explicitly defines the condition for the dispatchable to be feeless. /// From 0c7d71567491b805ea6f8def559b37eb9fec36ee Mon Sep 17 00:00:00 2001 From: command-bot <> Date: Thu, 7 Dec 2023 06:05:42 +0000 Subject: [PATCH 09/57] ".git/.scripts/commands/fmt/fmt.sh" --- substrate/frame/support/procedural/src/lib.rs | 18 +++++++++----- substrate/frame/support/src/lib.rs | 24 ++++++++++--------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 4f7252044c35..51386b87ad21 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1003,7 +1003,8 @@ pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr.constant_name.html). +/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr. +/// constant_name.html). #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1133,7 +1134,8 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index.html). +/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index. +/// html). #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1144,7 +1146,8 @@ pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { /// /// Rust-Analyzer Users: Documentation for this macro can be found at /// -/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if.html). +/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if. +/// html). #[proc_macro_attribute] pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1199,7 +1202,8 @@ pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr.generate_deposit.html). +/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr. +/// generate_deposit.html). #[proc_macro_attribute] pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1316,7 +1320,8 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr.genesis_config.html). +/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr. +/// genesis_config.html). #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1326,7 +1331,8 @@ pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr.genesis_build.html). +/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr. +/// genesis_build.html). #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index ebae60c11389..1348e9f3b0e4 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2229,9 +2229,9 @@ pub use frame_support_procedural::pallet; pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, - generate_store, getter, hooks, import_section, inherent, no_default, - no_default_bounds, origin, pallet_section, storage_prefix, storage_version, type_value, - unbounded, validate_unsigned, weight, whitelist_storage, + generate_store, getter, hooks, import_section, inherent, no_default, no_default_bounds, + origin, pallet_section, storage_prefix, storage_version, type_value, unbounded, + validate_unsigned, weight, whitelist_storage, }; /// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a @@ -2253,14 +2253,15 @@ pub mod pallet_macros { /// /// The macro implements a metadata function on `Event` returning the `EventMetadata`. /// - /// If `#[pallet::generate_deposit]` is present then the macro implements `fn deposit_event` on - /// `Pallet`. + /// If `#[pallet::generate_deposit]` is present then the macro implements `fn + /// deposit_event` on `Pallet`. pub use frame_support_procedural::generate_deposit; - /// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` attribute, - /// which explicitly defines the condition for the dispatchable to be feeless. + /// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` + /// attribute, which explicitly defines the condition for the dispatchable to be feeless. /// - /// The arguments for the closure must be the referenced arguments of the dispatchable function. + /// The arguments for the closure must be the referenced arguments of the dispatchable + /// function. /// /// The closure must return `bool`. /// @@ -2274,9 +2275,10 @@ pub mod pallet_macros { /// } /// ``` /// - /// Please note that this only works for signed dispatchables and requires a signed extension - /// such as [`pallet_skip_feeless_payment::SkipCheckIfFeeless`] to wrap the existing payment - /// extension. Else, this is completely ignored and the dispatchable is still charged. + /// Please note that this only works for signed dispatchables and requires a signed + /// extension such as [`pallet_skip_feeless_payment::SkipCheckIfFeeless`] to wrap the + /// existing payment extension. Else, this is completely ignored and the dispatchable is + /// still charged. /// /// ### Macro expansion /// From fcc59947e6da57edae73a8f75337755b76bc9588 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 13:51:33 +0400 Subject: [PATCH 10/57] fix rustfmt --- substrate/frame/support/procedural/src/lib.rs | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 51386b87ad21..6d53560a2073 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -999,12 +999,12 @@ pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr. -/// constant_name.html). +/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr.constant_name.html). #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1128,26 +1128,26 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// Each dispatchable may also be annotated with the `#[pallet::call_index($idx)]` attribute, /// which explicitly defines the codec index for the dispatchable function in the `Call` enum. /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index. -/// html). +/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index.html). #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at /// -/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if. -/// html). +/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if.html). #[proc_macro_attribute] pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1198,12 +1198,12 @@ pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr. -/// generate_deposit.html). +/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr.generate_deposit.html). #[proc_macro_attribute] pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1316,23 +1316,23 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr. -/// genesis_config.html). +/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr.genesis_config.html). #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr. -/// genesis_build.html). +/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr.genesis_build.html). #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() From 4a9c9d43c1abe5812ae6e01b2b1d96b4ea1dabfa Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 14:14:32 +0400 Subject: [PATCH 11/57] fix hooks docs --- substrate/frame/support/procedural/src/lib.rs | 32 ++----------- substrate/frame/support/src/lib.rs | 45 +++++++++++++++++-- 2 files changed, 45 insertions(+), 32 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 6d53560a2073..0d3c8d2e6eb6 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1065,37 +1065,11 @@ pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::hooks]` attribute allows you to specify a `Hooks` implementation for -/// `Pallet` that specifies pallet-specific logic. /// -/// The item the attribute attaches to must be defined as follows: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet $optional_where_clause { -/// ... -/// } -/// ``` -/// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait -/// `Hooks>` (they are defined in preludes), for the type `Pallet` and -/// with an optional where clause. -/// -/// If no `#[pallet::hooks]` exists, then the following default implementation is -/// automatically generated: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet {} -/// ``` -/// -/// ## Macro expansion -/// -/// The macro implements the traits `OnInitialize`, `OnIdle`, `OnFinalize`, `OnRuntimeUpgrade`, -/// `OffchainWorker`, and `IntegrityTest` using the provided `Hooks` implementation. -/// -/// NOTE: `OnRuntimeUpgrade` is implemented with `Hooks::on_runtime_upgrade` and some -/// additional logic. E.g. logic to write the pallet version into storage. +/// --- /// -/// NOTE: The macro also adds some tracing logic when implementing the above traits. The -/// following hooks emit traces: `on_initialize`, `on_finalize` and `on_runtime_upgrade`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::hooks`](../frame_support/pallet_macros/attr.hooks.html). #[proc_macro_attribute] pub fn hooks(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 1348e9f3b0e4..e2573000bb2d 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -2229,11 +2229,50 @@ pub use frame_support_procedural::pallet; pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, - generate_store, getter, hooks, import_section, inherent, no_default, no_default_bounds, - origin, pallet_section, storage_prefix, storage_version, type_value, unbounded, - validate_unsigned, weight, whitelist_storage, + generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, + pallet_section, storage_prefix, storage_version, type_value, unbounded, validate_unsigned, + weight, whitelist_storage, }; + /// The `#[pallet::hooks]` attribute allows you to specify a `Hooks` implementation for + /// `Pallet` that specifies pallet-specific logic. + /// + /// The item the attribute attaches to must be defined as follows: + /// ```ignore + /// #[pallet::hooks] + /// impl Hooks> for Pallet $optional_where_clause { + /// ... + /// } + /// ``` + /// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait + /// `Hooks>` (they are defined in preludes), for the type `Pallet` and + /// with an optional where clause. + /// + /// If no `#[pallet::hooks]` exists, then the following default implementation is + /// automatically generated: + /// ```ignore + /// #[pallet::hooks] + /// impl Hooks> for Pallet {} + /// ``` + /// + /// ## Macro expansion + /// + /// The macro implements the traits + /// [`OnInitialize`](frame_support::traits::OnInitialize), + /// [`OnIdle`](frame_support::traits::OnIdle), + /// [`OnFinalize`](frame_support::traits::OnFinalize), + /// [`OnRuntimeUpgrade`](frame_support::traits::OnRuntimeUpgrade), + /// [`OffchainWorker`](frame_support::traits::OffchainWorker), and + /// [`IntegrityTest`](frame_support::traits::IntegrityTest) using + /// the provided [`Hooks`](frame_support::traits::Hooks) implementation. + /// + /// NOTE: `OnRuntimeUpgrade` is implemented with `Hooks::on_runtime_upgrade` and some + /// additional logic. E.g. logic to write the pallet version into storage. + /// + /// NOTE: The macro also adds some tracing logic when implementing the above traits. The + /// following hooks emit traces: `on_initialize`, `on_finalize` and `on_runtime_upgrade`. + pub use frame_support_procedural::hooks; + /// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a /// helper function on `Pallet` that handles deposit events. /// From 3a0e2d56388281dd4bd6dd0fa06a38d05b129149 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 14:22:33 +0400 Subject: [PATCH 12/57] fix inject_runtime_type doc --- substrate/frame/support/procedural/src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 0d3c8d2e6eb6..f6f75ffcd967 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -885,6 +885,12 @@ pub fn register_default_impl(attrs: TokenStream, tokens: TokenStream) -> TokenSt } } +#[rustfmt::skip] +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_prelude::inject_runtime_type`](../frame_support/pallet_prelude/attr.inject_runtime_type.html). #[proc_macro_attribute] pub fn inject_runtime_type(_: TokenStream, tokens: TokenStream) -> TokenStream { let item = tokens.clone(); From 5cffe3fb7053128819aca47b731cbef70f68459a Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 15:09:25 +0400 Subject: [PATCH 13/57] fix links --- substrate/frame/support/procedural/src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index f6f75ffcd967..2020fd0997d9 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -346,7 +346,7 @@ pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStrea /// attached to a function definition containing an `#[extrinsic_call]` or `#[block]` /// attribute. /// -/// See `frame_benchmarking::v2` for more info. +/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. #[proc_macro_attribute] pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -1388,8 +1388,8 @@ pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { /// ``` /// /// **WARNING**: modifying origin changes the outer runtime origin. This outer runtime origin -/// can be stored on-chain (e.g. in `pallet-scheduler`), thus any change must be done with care -/// as it might require some migration. +/// can be stored on-chain (e.g. in [`pallet_scheduler`](../pallet_scheduler/index.html)), +/// thus any change must be done with care as it might require some migration. /// /// NOTE: for instantiable pallets, the origin must be generic over `T` and `I`. #[proc_macro_attribute] From d2babe6e96a5de2f990ab9f92e2ff33f4e492bf8 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 15:49:56 +0400 Subject: [PATCH 14/57] use latest pallet docs --- substrate/frame/support/procedural/src/lib.rs | 129 +- substrate/frame/support/src/lib.rs | 1366 +---------------- 2 files changed, 84 insertions(+), 1411 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 2020fd0997d9..9da65b4bf56a 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -186,133 +186,12 @@ pub fn construct_runtime(input: TokenStream) -> TokenStream { construct_runtime::construct_runtime(input) } -/// The pallet struct placeholder `#[pallet::pallet]` is mandatory and allows you to specify -/// pallet information. -/// -/// The struct must be defined as follows: -/// ```ignore -/// #[pallet::pallet] -/// pub struct Pallet(_); -/// ``` -/// I.e. a regular struct definition named `Pallet`, with generic T and no where clause. -/// -/// ## Macro expansion: -/// -/// The macro adds this attribute to the struct definition: -/// ```ignore -/// #[derive( -/// frame_support::CloneNoBound, -/// frame_support::EqNoBound, -/// frame_support::PartialEqNoBound, -/// frame_support::RuntimeDebugNoBound, -/// )] -/// ``` -/// and replaces the type `_` with `PhantomData`. It also implements on the pallet: -/// * `GetStorageVersion` -/// * `OnGenesis`: contains some logic to write the pallet version into storage. -/// * `PalletErrorTypeInfo`: provides the type information for the pallet error, if defined. -/// -/// It declares `type Module` type alias for `Pallet`, used by `construct_runtime`. -/// -/// It implements `PalletInfoAccess` on `Pallet` to ease access to pallet information given by -/// `frame_support::traits::PalletInfo`. (The implementation uses the associated type -/// `frame_system::Config::PalletInfo`). -/// -/// It implements `StorageInfoTrait` on `Pallet` which give information about all storages. -/// -/// If the attribute `generate_store` is set then the macro creates the trait `Store` and -/// implements it on `Pallet`. -/// -/// If the attribute `set_storage_max_encoded_len` is set then the macro calls -/// `StorageInfoTrait` for each storage in the implementation of `StorageInfoTrait` for the -/// pallet. Otherwise it implements `StorageInfoTrait` for the pallet using the -/// `PartialStorageInfoTrait` implementation of storages. -/// -/// ## Dev Mode (`#[pallet(dev_mode)]`) -/// -/// Specifying the argument `dev_mode` will allow you to enable dev mode for a pallet. The aim -/// of dev mode is to loosen some of the restrictions and requirements placed on production -/// pallets for easy tinkering and development. Dev mode pallets should not be used in -/// production. Enabling dev mode has the following effects: -/// -/// * Weights no longer need to be specified on every `#[pallet::call]` declaration. By default, dev -/// mode pallets will assume a weight of zero (`0`) if a weight is not specified. This is -/// equivalent to specifying `#[weight(0)]` on all calls that do not specify a weight. -/// * Call indices no longer need to be specified on every `#[pallet::call]` declaration. By -/// default, dev mode pallets will assume a call index based on the order of the call. -/// * All storages are marked as unbounded, meaning you do not need to implement `MaxEncodedLen` on -/// storage types. This is equivalent to specifying `#[pallet::unbounded]` on all storage type -/// definitions. -/// * Storage hashers no longer need to be specified and can be replaced by `_`. In dev mode, these -/// will be replaced by `Blake2_128Concat`. In case of explicit key-binding, `Hasher` can simply -/// be ignored when in `dev_mode`. -/// -/// Note that the `dev_mode` argument can only be supplied to the `#[pallet]` or -/// `#[frame_support::pallet]` attribute macro that encloses your pallet module. This argument -/// cannot be specified anywhere else, including but not limited to the `#[pallet::pallet]` -/// attribute macro. -/// -/// 
-/// WARNING:
-/// You should not deploy or use dev mode pallets in production. Doing so can break your chain
-/// and therefore should never be done. Once you are done tinkering, you should remove the
-/// 'dev_mode' argument from your #[pallet] declaration and fix any compile errors before
-/// attempting to use your pallet in a production scenario.
-///
-/// -/// See `frame_support::pallet` docs for more info. -/// -/// ## Runtime Metadata Documentation -/// -/// The documentation added to this pallet is included in the runtime metadata. -/// -/// The documentation can be defined in the following ways: -/// -/// ```ignore -/// #[pallet::pallet] -/// /// Documentation for pallet 1 -/// #[doc = "Documentation for pallet 2"] -/// #[doc = include_str!("../README.md")] -/// #[pallet_doc("../doc1.md")] -/// #[pallet_doc("../doc2.md")] -/// pub mod pallet {} -/// ``` -/// -/// The runtime metadata for this pallet contains the following -/// - " Documentation for pallet 1" (captured from `///`) -/// - "Documentation for pallet 2" (captured from `#[doc]`) -/// - content of ../README.md (captured from `#[doc]` with `include_str!`) -/// - content of "../doc1.md" (captured from `pallet_doc`) -/// - content of "../doc2.md" (captured from `pallet_doc`) -/// -/// ### `doc` attribute -/// -/// The value of the `doc` attribute is included in the runtime metadata, as well as -/// expanded on the pallet module. The previous example is expanded to: -/// -/// ```ignore -/// /// Documentation for pallet 1 -/// /// Documentation for pallet 2 -/// /// Content of README.md -/// pub mod pallet {} -/// ``` -/// -/// If you want to specify the file from which the documentation is loaded, you can use the -/// `include_str` macro. However, if you only want the documentation to be included in the -/// runtime metadata, use the `pallet_doc` attribute. -/// -/// ### `pallet_doc` attribute -/// -/// Unlike the `doc` attribute, the documentation provided to the `pallet_doc` attribute is -/// not inserted on the module. +#[rustfmt::skip] /// -/// The `pallet_doc` attribute can only be provided with one argument, -/// which is the file path that holds the documentation to be added to the metadata. +/// --- /// -/// This approach is beneficial when you use the `include_str` macro at the beginning of the file -/// and want that documentation to extend to the runtime metadata, without reiterating the -/// documentation on the pallet module itself. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet`](../frame_support/attr.pallet.html). #[proc_macro_attribute] pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream { pallet::pallet(attr, item) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index e2573000bb2d..fee47ee2c7d2 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -887,118 +887,8 @@ pub mod pallet_prelude { pub use sp_weights::Weight; } -/// The `pallet` attribute macro defines a pallet that can be used with -/// [`construct_runtime!`]. It must be attached to a module named `pallet` as follows: -/// -/// ```ignore -/// #[pallet] -/// pub mod pallet { -/// ... -/// } -/// ``` -/// -/// Note that various types can be automatically imported using -/// [`frame_support::pallet_prelude`] and `frame_system::pallet_prelude`: -/// -/// ```ignore -/// #[pallet] -/// pub mod pallet { -/// use frame_support::pallet_prelude::*; -/// use frame_system::pallet_prelude::*; -/// ... -/// } -/// ``` -/// -/// # pallet::* Attributes -/// -/// The `pallet` macro will parse any items within your `pallet` module that are annotated with -/// `#[pallet::*]` attributes. Some of these attributes are mandatory and some are optional, -/// and they can attach to different types of items within your pallet depending on the -/// attribute in question. The full list of `#[pallet::*]` attributes is shown below in the -/// order in which they are mentioned in this document: -/// -/// * [`pallet::pallet`](#pallet-struct-placeholder-palletpallet-mandatory) -/// * [`pallet::config`](#config-trait-palletconfig-mandatory) -/// * [`pallet::constant`](#palletconstant) -/// * [`pallet::disable_frame_system_supertrait_check`](#disable_supertrait_check) -/// * [`pallet::generate_store($vis trait Store)`](#palletgenerate_storevis-trait-store) -/// * [`pallet::storage_version`](#palletstorage_version) -/// * [`pallet::hooks`](#hooks-pallethooks-optional) -/// * [`pallet::call`](#call-palletcall-optional) -/// * [`pallet::weight($expr)`](#palletweightexpr) -/// * [`pallet::compact`](#palletcompact-some_arg-some_type) -/// * [`pallet::call_index($idx)`](#palletcall_indexidx) -/// * [`pallet::extra_constants`](#extra-constants-palletextra_constants-optional) -/// * [`pallet::error`](#error-palleterror-optional) -/// * [`pallet::event`](#event-palletevent-optional) -/// * [`pallet::generate_deposit($visibility fn -/// deposit_event)`](#palletgenerate_depositvisibility-fn-deposit_event) -/// * [`pallet::storage`](#storage-palletstorage-optional) -/// * [`pallet::getter(fn $my_getter_fn_name)`](#palletgetterfn-my_getter_fn_name-optional) -/// * [`pallet::storage_prefix = "SomeName"`](#palletstorage_prefix--somename-optional) -/// * [`pallet::unbounded`](#palletunbounded-optional) -/// * [`pallet::whitelist_storage`](#palletwhitelist_storage-optional) -/// * [`cfg(..)`](#cfg-for-storage) (on storage items) -/// * [`pallet::type_value`](#type-value-pallettype_value-optional) -/// * [`pallet::genesis_config`](#genesis-config-palletgenesis_config-optional) -/// * [`pallet::genesis_build`](#genesis-build-palletgenesis_build-optional) -/// * [`pallet::inherent`](#inherent-palletinherent-optional) -/// * [`pallet::validate_unsigned`](#validate-unsigned-palletvalidate_unsigned-optional) -/// * [`pallet::origin`](#origin-palletorigin-optional) -/// * [`pallet::composite_enum`](#composite-enum-palletcomposite_enum-optional) -/// -/// Note that at compile-time, the `#[pallet]` macro will analyze and expand all of these -/// attributes, ultimately removing their AST nodes before they can be parsed as real -/// attribute macro calls. This means that technically we do not need attribute macro -/// definitions for any of these attributes, however, for consistency and discoverability -/// reasons, we still maintain stub attribute macro definitions for all of these attributes in -/// the [`pallet_macros`] module which is automatically included in all pallets as part of the -/// pallet prelude. The actual "work" for all of these attribute macros can be found in the -/// macro expansion for `#[pallet]`. -/// -/// Also note that in this document, pallet attributes are explained using the syntax of -/// non-instantiable pallets. For an example of an instantiable pallet, see [this -/// example](#example-of-an-instantiable-pallet). -/// -/// # Dev Mode (`#[pallet(dev_mode)]`) -/// -/// Specifying the argument `dev_mode` on the `#[pallet]` or `#[frame_support::pallet]` -/// attribute attached to your pallet module will allow you to enable dev mode for a pallet. -/// The aim of dev mode is to loosen some of the restrictions and requirements placed on -/// production pallets for easy tinkering and development. Dev mode pallets should not be used -/// in production. Enabling dev mode has the following effects: -/// -/// * Weights no longer need to be specified on every `#[pallet::call]` declaration. By -/// default, dev mode pallets will assume a weight of zero (`0`) if a weight is not -/// specified. This is equivalent to specifying `#[weight(0)]` on all calls that do not -/// specify a weight. -/// * Call indices no longer need to be specified on every `#[pallet::call]` declaration. By -/// default, dev mode pallets will assume a call index based on the order of the call. -/// * All storages are marked as unbounded, meaning you do not need to implement -/// `MaxEncodedLen` on storage types. This is equivalent to specifying `#[pallet::unbounded]` -/// on all storage type definitions. -/// * Storage hashers no longer need to be specified and can be replaced by `_`. In dev mode, -/// these will be replaced by `Blake2_128Concat`. In case of explicit key-binding, `Hasher` -/// can simply be ignored when in `dev_mode`. -/// -/// Note that the `dev_mode` argument can only be supplied to the `#[pallet]` or -/// `#[frame_support::pallet]` attribute macro that encloses your pallet module. This argument -/// cannot be specified anywhere else, including but not limited to the `#[pallet::pallet]` -/// attribute macro. -/// -/// 
-/// WARNING:
-/// You should not deploy or use dev mode pallets in production. Doing so can break your chain
-/// and therefore should never be done. Once you are done tinkering, you should remove the
-/// 'dev_mode' argument from your #[pallet] declaration and fix any compile errors before
-/// attempting to use your pallet in a production scenario.
-///
-/// -/// # Pallet struct placeholder: `#[pallet::pallet]` (mandatory) -/// -/// The pallet struct placeholder `#[pallet::pallet]` is mandatory and allows you to specify -/// pallet information. +/// The pallet struct placeholder `#[pallet::pallet]` is mandatory and allows you to +/// specify pallet information. /// /// The struct must be defined as follows: /// ```ignore @@ -1019,1210 +909,114 @@ pub mod pallet_prelude { /// )] /// ``` /// and replaces the type `_` with `PhantomData`. It also implements on the pallet: -/// * [`GetStorageVersion`](`traits::GetStorageVersion`) -/// * [`OnGenesis`](`traits::OnGenesis`): contains some logic to write the pallet version into -/// storage. -/// * `PalletErrorTypeInfo`: provides the type information for the pallet error, if defined. +/// * [`GetStorageVersion`](frame_support::traits::GetStorageVersion) +/// * [`OnGenesis`](frame_support::traits::OnGenesis): contains some logic to write the pallet +/// version into storage. /// /// It declares `type Module` type alias for `Pallet`, used by `construct_runtime`. /// -/// It implements [`PalletInfoAccess`](`traits::PalletInfoAccess') on `Pallet` to ease access -/// to pallet information given by [`frame_support::traits::PalletInfo`]. (The implementation -/// uses the associated type `frame_system::Config::PalletInfo`). +/// It implements [`PalletInfoAccess`](frame_support::traits::PalletInfoAccess) on `Pallet` +/// to ease access to pallet information given by [`frame_support::traits::PalletInfo`]. +/// (The implementation uses the associated type [`frame_support::traits::PalletInfo`]). /// -/// It implements [`StorageInfoTrait`](`traits::StorageInfoTrait`) on `Pallet` which give -/// information about all storages. +/// It implements [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) on `Pallet` +/// which give information about all storages. /// -/// If the attribute `generate_store` is set then the macro creates the trait `Store` and -/// implements it on `Pallet`. +/// If the attribute [`generate_store`](frame_support::pallet_macros::generate_store) is +/// set then the macro creates the trait `Store` and implements it on `Pallet`. /// /// If the attribute `set_storage_max_encoded_len` is set then the macro calls -/// [`StorageInfoTrait`](`traits::StorageInfoTrait`) for each storage in the implementation of -/// [`StorageInfoTrait`](`traits::StorageInfoTrait`) for the pallet. Otherwise it implements -/// [`StorageInfoTrait`](`traits::StorageInfoTrait`) for the pallet using the -/// [`PartialStorageInfoTrait`](`traits::PartialStorageInfoTrait`) implementation of storages. -/// -/// # Config trait: `#[pallet::config]` (mandatory) +/// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for each storage in the +/// implementation of [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the +/// pallet. Otherwise it implements +/// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the pallet using the +/// [`PartialStorageInfoTrait`](frame_support::traits::PartialStorageInfoTrait) +/// implementation of storages. /// -/// The mandatory attribute `#[pallet::config]` defines the configurable options for the -/// pallet. +/// ## Dev Mode (`#[pallet(dev_mode)]`) /// -/// Item must be defined as: +/// Specifying the argument `dev_mode` will allow you to enable dev mode for a pallet. The +/// aim of dev mode is to loosen some of the restrictions and requirements placed on +/// production pallets for easy tinkering and development. Dev mode pallets should not be +/// used in production. Enabling dev mode has the following effects: /// -/// ```ignore -/// #[pallet::config] -/// pub trait Config: frame_system::Config + $optionally_some_other_supertraits -/// $optional_where_clause -/// { -/// ... -/// } -/// ``` -/// -/// I.e. a regular trait definition named `Config`, with the supertrait -/// `frame_system::pallet::Config`, and optionally other supertraits and a where clause. -/// (Specifying other supertraits here is known as [tight -/// coupling](https://docs.substrate.io/reference/how-to-guides/pallet-design/use-tight-coupling/)) -/// -/// The associated type `RuntimeEvent` is reserved. If defined, it must have the bounds -/// `From` and `IsType<::RuntimeEvent>`. -/// -/// [`pallet::event`](`frame_support::pallet_macros::event`) must be present if `RuntimeEvent` -/// exists as a config item in your `#[pallet::config]`. -/// -/// Also see [`pallet::config`](`frame_support::pallet_macros::config`) -/// -/// ## `pallet::constant` -/// -/// The `#[pallet::constant]` attribute can be used to add an associated type trait bounded by -/// [`Get`](crate::traits::Get) from [`pallet::config`](#palletconfig) into metadata, e.g.: -/// -/// ```ignore -/// #[pallet::config] -/// pub trait Config: frame_system::Config { -/// #[pallet::constant] -/// type Foo: Get; -/// } -/// ``` -/// -/// Also see [`pallet::constant`](`frame_support::pallet_macros::constant`) -/// -/// ## `pallet::disable_frame_system_supertrait_check` -/// -/// -/// To bypass the `frame_system::Config` supertrait check, use the attribute -/// `pallet::disable_frame_system_supertrait_check`, e.g.: -/// -/// ```ignore -/// #[pallet::config] -/// #[pallet::disable_frame_system_supertrait_check] -/// pub trait Config: pallet_timestamp::Config {} -/// ``` -/// -/// NOTE: Bypassing the `frame_system::Config` supertrait check is typically desirable when you -/// want to write an alternative to the `frame_system` pallet. -/// -/// Also see -/// [`pallet::disable_frame_system_supertrait_check`](`frame_support::pallet_macros::disable_frame_system_supertrait_check`) -/// -/// ## Macro expansion: -/// -/// The macro expands pallet constant metadata with the information given by -/// `#[pallet::constant]`. -/// -/// # `pallet::generate_store($vis trait Store)` -/// -/// To generate a `Store` trait associating all storages, annotate your `Pallet` struct with -/// the attribute `#[pallet::generate_store($vis trait Store)]`, e.g.: -/// -/// ```ignore -/// #[pallet::pallet] -/// #[pallet::generate_store(pub(super) trait Store)] -/// pub struct Pallet(_); -/// ``` -/// More precisely, the `Store` trait contains an associated type for each storage. It is -/// implemented for `Pallet` allowing access to the storage from pallet struct. +/// * Weights no longer need to be specified on every `#[pallet::call]` declaration. By +/// default, dev mode pallets will assume a weight of zero (`0`) if a weight is not +/// specified. This is equivalent to specifying `#[weight(0)]` on all calls that do not +/// specify a weight. +/// * Call indices no longer need to be specified on every `#[pallet::call]` declaration. By +/// default, dev mode pallets will assume a call index based on the order of the call. +/// * All storages are marked as unbounded, meaning you do not need to implement +/// [`MaxEncodedLen`](frame_support::pallet_prelude::MaxEncodedLen) on storage types. This is +/// equivalent to specifying `#[pallet::unbounded]` on all storage type definitions. +/// * Storage hashers no longer need to be specified and can be replaced by `_`. In dev mode, +/// these will be replaced by `Blake2_128Concat`. In case of explicit key-binding, `Hasher` +/// can simply be ignored when in `dev_mode`. /// -/// Thus when defining a storage named `Foo`, it can later be accessed from `Pallet` using -/// `::Foo`. +/// Note that the `dev_mode` argument can only be supplied to the `#[pallet]` or +/// `#[frame_support::pallet]` attribute macro that encloses your pallet module. This +/// argument cannot be specified anywhere else, including but not limited to the +/// `#[pallet::pallet]` attribute macro. /// -/// NOTE: this attribute is only valid when applied _directly_ to your `Pallet` struct -/// definition. +/// 
+/// WARNING:
+/// You should not deploy or use dev mode pallets in production. Doing so can break your
+/// chain and therefore should never be done. Once you are done tinkering, you should
+/// remove the 'dev_mode' argument from your #[pallet] declaration and fix any compile
+/// errors before attempting to use your pallet in a production scenario.
+///
/// -/// Also see [`pallet::generate_store`](`frame_support::pallet_macros::generate_store`). +/// ## Runtime Metadata Documentation /// -/// # `pallet::storage_version` +/// The documentation added to this pallet is included in the runtime metadata. /// -/// Because the [`pallet::pallet`](#pallet-struct-placeholder-palletpallet-mandatory) macro -/// implements [`traits::GetStorageVersion`], the current storage version needs to be -/// communicated to the macro. This can be done by using the `pallet::storage_version` -/// attribute: +/// The documentation can be defined in the following ways: /// /// ```ignore -/// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); -/// /// #[pallet::pallet] -/// #[pallet::storage_version(STORAGE_VERSION)] -/// pub struct Pallet(_); +/// /// Documentation for pallet 1 +/// #[doc = "Documentation for pallet 2"] +/// #[doc = include_str!("../README.md")] +/// #[pallet_doc("../doc1.md")] +/// #[pallet_doc("../doc2.md")] +/// pub mod pallet {} /// ``` /// -/// If not present, the current storage version is set to the default value. -/// -/// Also see [`pallet::storage_version`](`frame_support::pallet_macros::storage_version`) +/// The runtime metadata for this pallet contains the following +/// - "Documentation for pallet 1" (captured from `///`) +/// - "Documentation for pallet 2" (captured from `#[doc]`) +/// - content of ../README.md (captured from `#[doc]` with `include_str!`) +/// - content of "../doc1.md" (captured from `pallet_doc`) +/// - content of "../doc2.md" (captured from `pallet_doc`) /// -/// # Hooks: `#[pallet::hooks]` (optional) +/// ### `doc` attribute /// -/// The `pallet::hooks` attribute allows you to specify a `Hooks` implementation for `Pallet` -/// that specifies pallet-specific logic. +/// The value of the `doc` attribute is included in the runtime metadata, as well as +/// expanded on the pallet module. The previous example is expanded to: /// -/// The item the attribute attaches to must be defined as follows: /// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet $optional_where_clause { -/// ... -/// } +/// /// Documentation for pallet 1 +/// /// Documentation for pallet 2 +/// /// Content of README.md +/// pub mod pallet {} /// ``` -/// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait -/// `Hooks>` (they are defined in preludes), for the type `Pallet` and -/// with an optional where clause. -/// -/// If no `#[pallet::hooks]` exists, then the following default implementation is -/// automatically generated: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet {} -/// ``` -/// -/// Also see [`pallet::hooks`](`frame_support::pallet_macros::hooks`) -/// -/// # Call: `#[pallet::call]` (optional) -/// -/// Implementation of pallet dispatchables. -/// -/// Item must be defined as: -/// ```ignore -/// #[pallet::call] -/// impl Pallet { -/// /// $some_doc -/// #[pallet::weight($ExpressionResultingInWeight)] -/// pub fn $fn_name( -/// origin: OriginFor, -/// $some_arg: $some_type, -/// // or with compact attribute: #[pallet::compact] $some_arg: $some_type, -/// ... -/// ) -> DispatchResultWithPostInfo { // or `-> DispatchResult` -/// ... -/// } -/// ... -/// } -/// ``` -/// I.e. a regular type implementation, with generic `T: Config`, on type `Pallet`, with -/// an optional where clause. -/// -/// ## `#[pallet::weight($expr)]` -/// -/// Each dispatchable needs to define a weight with `#[pallet::weight($expr)]` attribute, the -/// first argument must be `origin: OriginFor`. -/// -/// Also see [`pallet::weight`](`frame_support::pallet_macros::weight`) -/// -/// ### `#[pallet::compact] $some_arg: $some_type` -/// -/// Compact encoding for arguments can be achieved via `#[pallet::compact]`. The function must -/// return a `DispatchResultWithPostInfo` or `DispatchResult`. -/// -/// Also see [`pallet::compact`](`frame_support::pallet_macros::compact`) -/// -/// ## `#[pallet::call_index($idx)]` /// -/// Each dispatchable may also be annotated with the `#[pallet::call_index($idx)]` attribute, -/// which explicitly defines the codec index for the dispatchable function in the `Call` enum. -/// -/// All call indexes start from 0, until it encounters a dispatchable function with a defined -/// call index. The dispatchable function that lexically follows the function with a defined -/// call index will have that call index, but incremented by 1, e.g. if there are 3 -/// dispatchable functions `fn foo`, `fn bar` and `fn qux` in that order, and only `fn bar` -/// has a call index of 10, then `fn qux` will have an index of 11, instead of 1. -/// -/// **WARNING**: modifying dispatchables, changing their order, removing some, etc., must be -/// done with care. Indeed this will change the outer runtime call type (which is an enum with -/// one variant per pallet), this outer runtime call can be stored on-chain (e.g. in -/// `pallet-scheduler`). Thus migration might be needed. To mitigate against some of this, the -/// `#[pallet::call_index($idx)]` attribute can be used to fix the order of the dispatchable so -/// that the `Call` enum encoding does not change after modification. As a general rule of -/// thumb, it is therefore adventageous to always add new calls to the end so you can maintain -/// the existing order of calls. -/// -/// Also see [`pallet::call_index`](`frame_support::pallet_macros::call_index`) -/// -/// # Extra constants: `#[pallet::extra_constants]` (optional) -/// -/// Allows you to define some extra constants to be added into constant metadata. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::extra_constants] -/// impl Pallet where $optional_where_clause { -/// /// $some_doc -/// $vis fn $fn_name() -> $some_return_type { -/// ... -/// } -/// ... -/// } -/// ``` -/// I.e. a regular rust `impl` block with some optional where clause and functions with 0 args, -/// 0 generics, and some return type. -/// -/// ## Macro expansion -/// -/// The macro add some extra constants to pallet constant metadata. -/// -/// Also see: [`pallet::extra_constants`](`frame_support::pallet_macros::extra_constants`) -/// -/// # Error: `#[pallet::error]` (optional) -/// -/// The `#[pallet::error]` attribute allows you to define an error enum that will be returned -/// from the dispatchable when an error occurs. The information for this error type is then -/// stored in metadata. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::error] -/// pub enum Error { -/// /// $some_optional_doc -/// $SomeFieldLessVariant, -/// /// $some_more_optional_doc -/// $SomeVariantWithOneField(FieldType), -/// ... -/// } -/// ``` -/// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field -/// variants. -/// -/// Any field type in the enum variants must implement [`scale_info::TypeInfo`] in order to be -/// properly used in the metadata, and its encoded size should be as small as possible, -/// preferably 1 byte in size in order to reduce storage size. The error enum itself has an -/// absolute maximum encoded size specified by [`MAX_MODULE_ERROR_ENCODED_SIZE`]. -/// -/// (1 byte can still be 256 different errors. The more specific the error, the easier it is to -/// diagnose problems and give a better experience to the user. Don't skimp on having lots of -/// individual error conditions.) -/// -/// Field types in enum variants must also implement [`PalletError`](traits::PalletError), -/// otherwise the pallet will fail to compile. Rust primitive types have already implemented -/// the [`PalletError`](traits::PalletError) trait along with some commonly used stdlib types -/// such as [`Option`] and -/// [`PhantomData`](`frame_support::__private::sp_std::marker::PhantomData`), and hence in most -/// use cases, a manual implementation is not necessary and is discouraged. -/// -/// The generic `T` must not bound anything and a `where` clause is not allowed. That said, -/// bounds and/or a where clause should not needed for any use-case. -/// -/// Also see: [`pallet::error`](`frame_support::pallet_macros::error`) -/// -/// # Event: `#[pallet::event]` (optional) -/// -/// Allows you to define pallet events. Pallet events are stored under the `system` / `events` -/// key when the block is applied (and then replaced when the next block writes it's events). -/// -/// The Event enum must be defined as follows: -/// -/// ```ignore -/// #[pallet::event] -/// #[pallet::generate_deposit($visibility fn deposit_event)] // Optional -/// pub enum Event<$some_generic> $optional_where_clause { -/// /// Some doc -/// $SomeName($SomeType, $YetanotherType, ...), -/// ... -/// } -/// ``` +/// If you want to specify the file from which the documentation is loaded, you can use the +/// `include_str` macro. However, if you only want the documentation to be included in the +/// runtime metadata, use the `pallet_doc` attribute. /// -/// I.e. an enum (with named or unnamed fields variant), named `Event`, with generic: none or -/// `T` or `T: Config`, and optional w here clause. +/// ### `pallet_doc` attribute /// -/// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], [`Encode`], [`Decode`], and -/// [`Debug`] (on std only). For ease of use, bound by the trait -/// [`Member`](`frame_support::pallet_prelude::Member`), available in -/// frame_support::pallet_prelude. +/// Unlike the `doc` attribute, the documentation provided to the `pallet_doc` attribute is +/// not inserted on the module. /// -/// Also see [`pallet::event`](`frame_support::pallet_macros::event`) -/// -/// ## `#[pallet::generate_deposit($visibility fn deposit_event)]` -/// -/// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a -/// helper function on `Pallet` that handles deposit events. -/// -/// NOTE: For instantiable pallets, the event must be generic over `T` and `I`. -/// -/// Also see [`pallet::generate_deposit`](`frame_support::pallet_macros::generate_deposit`) -/// -/// # Storage: `#[pallet::storage]` (optional) -/// -/// The `#[pallet::storage]` attribute lets you define some abstract storage inside of runtime -/// storage and also set its metadata. This attribute can be used multiple times. -/// -/// Item should be defined as: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn $getter_name)] // optional -/// $vis type $StorageName<$some_generic> $optional_where_clause -/// = $StorageType<$generic_name = $some_generics, $other_name = $some_other, ...>; -/// ``` -/// -/// or with unnamed generic: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn $getter_name)] // optional -/// $vis type $StorageName<$some_generic> $optional_where_clause -/// = $StorageType<_, $some_generics, ...>; -/// ``` -/// -/// I.e. it must be a type alias, with generics: `T` or `T: Config`. The aliased type must be -/// one of [`StorageValue`](`pallet_prelude::StorageValue`), -/// [`StorageMap`](`pallet_prelude::StorageMap`) or -/// [`StorageDoubleMap`](`pallet_prelude::StorageDoubleMap`). The generic arguments of the -/// storage type can be given in two manners: named and unnamed. For named generic arguments, -/// the name for each argument should match the name defined for it on the storage struct: -/// * [`StorageValue`](`pallet_prelude::StorageValue`) expects `Value` and optionally -/// `QueryKind` and `OnEmpty`, -/// * [`StorageMap`](`pallet_prelude::StorageMap`) expects `Hasher`, `Key`, `Value` and -/// optionally `QueryKind` and `OnEmpty`, -/// * [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`) expects `Hasher`, `Key`, -/// `Value` and optionally `QueryKind` and `OnEmpty`, -/// * [`StorageDoubleMap`](`pallet_prelude::StorageDoubleMap`) expects `Hasher1`, `Key1`, -/// `Hasher2`, `Key2`, `Value` and optionally `QueryKind` and `OnEmpty`. -/// -/// For unnamed generic arguments: Their first generic must be `_` as it is replaced by the -/// macro and other generic must declared as a normal generic type declaration. -/// -/// The `Prefix` generic written by the macro is generated using -/// `PalletInfo::name::>()` and the name of the storage type. E.g. if runtime names -/// the pallet "MyExample" then the storage `type Foo = ...` should use the prefix: -/// `Twox128(b"MyExample") ++ Twox128(b"Foo")`. -/// -/// For the [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`) variant, the `Prefix` -/// also implements -/// [`CountedStorageMapInstance`](`frame_support::storage::types::CountedStorageMapInstance`). -/// It also associates a [`CounterPrefix`](`pallet_prelude::CounterPrefix'), which is -/// implemented the same as above, but the storage prefix is prepend with `"CounterFor"`. E.g. -/// if runtime names the pallet "MyExample" then the storage `type Foo = -/// CountedStorageaMap<...>` will store its counter at the prefix: `Twox128(b"MyExample") ++ -/// Twox128(b"CounterForFoo")`. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::storage] -/// pub(super) type MyStorage = StorageMap; -/// ``` -/// -/// In this case the final prefix used by the map is `Twox128(b"MyExample") ++ -/// Twox128(b"OtherName")`. -/// -/// Also see [`pallet::storage`](`frame_support::pallet_macros::storage`) -/// -/// ## `#[pallet::getter(fn $my_getter_fn_name)]` (optional) -/// -/// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define a -/// getter function on `Pallet`. -/// -/// Also see [`pallet::getter`](`frame_support::pallet_macros::getter`) -/// -/// ## `#[pallet::storage_prefix = "SomeName"]` (optional) -/// -/// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define the -/// storage prefix to use, see how `Prefix` generic is implemented above. This is helpful if -/// you wish to rename the storage field but don't want to perform a migration. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::storage_prefix = "foo"] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap; -/// ``` -/// -/// or -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap<_, Blake2_128Concat, u32, u32>; -/// ``` -/// -/// Also see [`pallet::storage_prefix`](`frame_support::pallet_macros::storage_prefix`) -/// -/// ## `#[pallet::unbounded]` (optional) -/// -/// The optional attribute `#[pallet::unbounded]` declares the storage as unbounded. When -/// implementating the storage info (when `#[pallet::generate_storage_info]` is specified on -/// the pallet struct placeholder), the size of the storage will be declared as unbounded. This -/// can be useful for storage which can never go into PoV (Proof of Validity). -/// -/// Also see [`pallet::unbounded`](`frame_support::pallet_macros::unbounded`) -/// -/// ## `#[pallet::whitelist_storage]` (optional) -/// -/// The optional attribute `#[pallet::whitelist_storage]` will declare the storage as -/// whitelisted from benchmarking. -/// -/// See -/// [`pallet::whitelist_storage`](frame_support::pallet_macros::whitelist_storage) -/// for more info. -/// -/// ## `#[cfg(..)]` (for storage) -/// The optional attributes `#[cfg(..)]` allow conditional compilation for the storage. -/// -/// E.g: -/// -/// ```ignore -/// #[cfg(feature = "my-feature")] -/// #[pallet::storage] -/// pub(super) type MyStorage = StorageValue; -/// ``` -/// -/// All the `cfg` attributes are automatically copied to the items generated for the storage, -/// i.e. the getter, storage prefix, and the metadata element etc. -/// -/// Any type placed as the `QueryKind` parameter must implement -/// [`frame_support::storage::types::QueryKindTrait`]. There are 3 implementations of this -/// trait by default: -/// -/// 1. [`OptionQuery`](`frame_support::storage::types::OptionQuery`), the default `QueryKind` -/// used when this type parameter is omitted. Specifying this as the `QueryKind` would cause -/// storage map APIs that return a `QueryKind` to instead return an [`Option`], returning -/// `Some` when a value does exist under a specified storage key, and `None` otherwise. -/// 2. [`ValueQuery`](`frame_support::storage::types::ValueQuery`) causes storage map APIs that -/// return a `QueryKind` to instead return the value type. In cases where a value does not -/// exist under a specified storage key, the `OnEmpty` type parameter on `QueryKindTrait` is -/// used to return an appropriate value. -/// 3. [`ResultQuery`](`frame_support::storage::types::ResultQuery`) causes storage map APIs -/// that return a `QueryKind` to instead return a `Result`, with `T` being the value -/// type and `E` being the pallet error type specified by the `#[pallet::error]` attribute. -/// In cases where a value does not exist under a specified storage key, an `Err` with the -/// specified pallet error variant is returned. -/// -/// NOTE: If the `QueryKind` generic parameter is still generic at this stage or is using some -/// type alias then the generation of the getter might fail. In this case the getter can be -/// implemented manually. -/// -/// NOTE: The generic `Hasher` must implement the [`StorageHasher`] trait (or the type is not -/// usable at all). We use [`StorageHasher::METADATA`] for the metadata of the hasher of the -/// storage item. Thus generic hasher is supported. -/// -/// ## Macro expansion -/// -/// For each storage item the macro generates a struct named -/// `_GeneratedPrefixForStorage$NameOfStorage`, and implements -/// [`StorageInstance`](traits::StorageInstance) on it using the pallet and storage name. It -/// then uses it as the first generic of the aliased type. For -/// [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`), -/// [`CountedStorageMapInstance`](`frame_support::storage::types::CountedStorageMapInstance`) -/// is implemented, and another similar struct is generated. -/// -/// For a named generic, the macro will reorder the generics, and remove the names. -/// -/// The macro implements the function `storage_metadata` on the `Pallet` implementing the -/// metadata for all storage items based on their kind: -/// * for a storage value, the type of the value is copied into the metadata -/// * for a storage map, the type of the values and the key's type is copied into the metadata -/// * for a storage double map, the type of the values, and the types of `key1` and `key2` are -/// copied into the metadata. -/// -/// # Type value: `#[pallet::type_value]` (optional) -/// -/// The `#[pallet::type_value]` attribute lets you define a struct implementing the -/// [`Get`](crate::traits::Get) trait to ease use of storage types. This attribute is meant to -/// be used alongside [`#[pallet::storage]`](#storage-palletstorage-optional) to define a -/// storage's default value. This attribute can be used multiple times. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } -/// ``` -/// -/// I.e.: a function definition with generics none or `T: Config` and a returned type. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn MyDefault() -> T::Balance { 3.into() } -/// ``` -/// -/// Also see [`pallet::type_value`](`frame_support::pallet_macros::type_value`) -/// -/// # Genesis config: `#[pallet::genesis_config]` (optional) -/// -/// The `#[pallet::genesis_config]` attribute allows you to define the genesis configuration -/// for the pallet. -/// -/// Item is defined as either an enum or a struct. It needs to be public and implement the -/// trait [`BuildGenesisConfig`](`traits::BuildGenesisConfig`) with -/// [`#[pallet::genesis_build]`](#genesis-build-palletgenesis_build-optional). The type -/// generics are constrained to be either none, or `T` or `T: Config`. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::genesis_config] -/// pub struct GenesisConfig { -/// _myfield: BalanceOf, -/// } -/// ``` -/// -/// Also see [`pallet::genesis_config`](`frame_support::pallet_macros::genesis_config`) -/// -/// # Genesis build: `#[pallet::genesis_build]` (optional) -/// -/// The `#[pallet::genesis_build]` attribute allows you to define how `genesis_configuration` -/// is built. This takes as input the `GenesisConfig` type (as `self`) and constructs the -/// pallet's initial state. -/// -/// The impl must be defined as: -/// -/// ```ignore -/// #[pallet::genesis_build] -/// impl GenesisBuild for GenesisConfig<$maybe_generics> { -/// fn build(&self) { $expr } -/// } -/// ``` -/// -/// I.e. a trait implementation with generic `T: Config`, of trait `GenesisBuild` on -/// type `GenesisConfig` with generics none or `T`. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::genesis_build] -/// impl GenesisBuild for GenesisConfig { -/// fn build(&self) {} -/// } -/// ``` -/// -/// Also see [`pallet::genesis_build`](`frame_support::pallet_macros::genesis_build`) -/// -/// # Inherent: `#[pallet::inherent]` (optional) -/// -/// The `#[pallet::inherent]` attribute allows the pallet to provide some -/// [inherent](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). -/// An inherent is some piece of data that is inserted by a block authoring node at block -/// creation time and can either be accepted or rejected by validators based on whether the -/// data falls within an acceptable range. -/// -/// The most common inherent is the `timestamp` that is inserted into every block. Since there -/// is no way to validate timestamps, validators simply check that the timestamp reported by -/// the block authoring node falls within an acceptable range. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::inherent] -/// impl ProvideInherent for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait -/// [`ProvideInherent`](`pallet_prelude::ProvideInherent`) for type `Pallet`, and some -/// optional where clause. -/// -/// Also see [`pallet::inherent`](`frame_support::pallet_macros::inherent`) -/// -/// # Validate unsigned: `#[pallet::validate_unsigned]` (optional) -/// -/// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some unsigned -/// transaction: -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::validate_unsigned] -/// impl ValidateUnsigned for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait -/// [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) for type `Pallet`, and some -/// optional where clause. -/// -/// NOTE: There is also the [`sp_runtime::traits::SignedExtension`] trait that can be used to -/// add some specific logic for transaction validation. -/// -/// Also see [`pallet::validate_unsigned`](`frame_support::pallet_macros::validate_unsigned`) -/// -/// # Origin: `#[pallet::origin]` (optional) -/// -/// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. -/// -/// Item must be either a type alias, an enum, or a struct. It needs to be public. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::origin] -/// pub struct Origin(PhantomData<(T)>); -/// ``` -/// -/// **WARNING**: modifying origin changes the outer runtime origin. This outer runtime origin -/// can be stored on-chain (e.g. in `pallet-scheduler`), thus any change must be done with care -/// as it might require some migration. -/// -/// NOTE: for instantiable pallets, the origin must be generic over `T` and `I`. -/// -/// Also see [`pallet::origin`](`frame_support::pallet_macros::origin`) -/// -/// # Composite enum `#[pallet::composite_enum]` (optional) -/// -/// The `#[pallet::composite_enum]` attribute allows you to define an enum on the pallet which -/// will then instruct `construct_runtime` to amalgamate all similarly-named enums from other -/// pallets into an aggregate enum. This is similar in principle with how the aggregate enum is -/// generated for `#[pallet::event]` or `#[pallet::error]`. -/// -/// The item tagged with `#[pallet::composite_enum]` MUST be an enum declaration, and can ONLY -/// be the following identifiers: `FreezeReason`, `HoldReason`, `LockId` or `SlashReason`. -/// Custom identifiers are not supported. -/// -/// NOTE: For ease of usage, when no `#[derive]` attributes are detected, the -/// `#[pallet::composite_enum]` attribute will automatically derive the following traits for -/// the enum: -/// -/// ```ignore -/// Copy, Clone, Eq, PartialEq, Encode, Decode, MaxEncodedLen, TypeInfo, RuntimeDebug -/// ``` -/// -/// The inverse is also true: if there are any #[derive] attributes present for the enum, then -/// the attribute will not automatically derive any of the traits described above. -/// -/// # General notes on instantiable pallets -/// -/// An instantiable pallet is one where Config is generic, i.e. `Config`. This allows -/// runtime to implement multiple instances of the pallet, by using different types for the -/// generic. This is the sole purpose of the generic `I`, but because -/// [`PalletInfo`](`traits::PalletInfo`) requires the `Pallet` placeholder to be static, it is -/// important to bound by `'static` whenever [`PalletInfo`](`traits::PalletInfo`) can be used. -/// Additionally, in order to make an instantiable pallet usable as a regular pallet without an -/// instance, it is important to bound by `= ()` on every type. -/// -/// Thus impl bound looks like `impl, I: 'static>`, and types look like -/// `SomeType` or `SomeType, I: 'static = ()>`. -/// -/// # Example of a non-instantiable pallet -/// -/// ``` -/// pub use pallet::*; // reexport in crate namespace for `construct_runtime!` -/// -/// #[frame_support::pallet] -/// // NOTE: The name of the pallet is provided by `construct_runtime` and is used as -/// // the unique identifier for the pallet's storage. It is not defined in the pallet itself. -/// pub mod pallet { -/// use frame_support::pallet_prelude::*; // Import various types used in the pallet definition -/// use frame_system::pallet_prelude::*; // Import some system helper types. -/// -/// type BalanceOf = ::Balance; -/// -/// // Define the generic parameter of the pallet -/// // The macro parses `#[pallet::constant]` attributes and uses them to generate metadata -/// // for the pallet's constants. -/// #[pallet::config] -/// pub trait Config: frame_system::Config { -/// #[pallet::constant] // put the constant in metadata -/// type MyGetParam: Get; -/// type Balance: Parameter + MaxEncodedLen + From; -/// type RuntimeEvent: From> + IsType<::RuntimeEvent>; -/// } -/// -/// // Define some additional constant to put into the constant metadata. -/// #[pallet::extra_constants] -/// impl Pallet { -/// /// Some description -/// fn exra_constant_name() -> u128 { 4u128 } -/// } -/// -/// // Define the pallet struct placeholder, various pallet function are implemented on it. -/// #[pallet::pallet] -/// #[pallet::generate_store(pub(super) trait Store)] -/// pub struct Pallet(_); -/// -/// // Implement the pallet hooks. -/// #[pallet::hooks] -/// impl Hooks> for Pallet { -/// fn on_initialize(_n: BlockNumberFor) -> Weight { -/// unimplemented!(); -/// } -/// -/// // can implement also: on_finalize, on_runtime_upgrade, offchain_worker, ... -/// // see `Hooks` trait -/// } -/// -/// // Declare Call struct and implement dispatchables. -/// // -/// // WARNING: Each parameter used in functions must implement: Clone, Debug, Eq, PartialEq, -/// // Codec. -/// // -/// // The macro parses `#[pallet::compact]` attributes on function arguments and implements -/// // the `Call` encoding/decoding accordingly. -/// #[pallet::call] -/// impl Pallet { -/// /// Doc comment put in metadata -/// #[pallet::weight(0)] // Defines weight for call (function parameters are in scope) -/// pub fn toto( -/// origin: OriginFor, -/// #[pallet::compact] _foo: u32, -/// ) -> DispatchResultWithPostInfo { -/// let _ = origin; -/// unimplemented!(); -/// } -/// } -/// -/// // Declare the pallet `Error` enum (this is optional). -/// // The macro generates error metadata using the doc comment on each variant. -/// #[pallet::error] -/// pub enum Error { -/// /// doc comment put into metadata -/// InsufficientProposersBalance, -/// } -/// -/// // Declare pallet Event enum (this is optional). -/// // -/// // WARNING: Each type used in variants must implement: Clone, Debug, Eq, PartialEq, Codec. -/// // -/// // The macro generates event metadata, and derive Clone, Debug, Eq, PartialEq and Codec -/// #[pallet::event] -/// // Generate a funciton on Pallet to deposit an event. -/// #[pallet::generate_deposit(pub(super) fn deposit_event)] -/// pub enum Event { -/// /// doc comment put in metadata -/// // `::AccountId` is not defined in metadata list, the last -/// // Thus the metadata is `::AccountId`. -/// Proposed(::AccountId), -/// /// doc -/// // here metadata will be `Balance` as define in metadata list -/// Spending(BalanceOf), -/// // here metadata will be `Other` as define in metadata list -/// Something(u32), -/// } -/// -/// // Define a struct which implements `frame_support::traits::Get` (optional). -/// #[pallet::type_value] -/// pub(super) fn MyDefault() -> T::Balance { 3.into() } -/// -/// // Declare a storage item. Any amount of storage items can be declared (optional). -/// // -/// // Is expected either `StorageValue`, `StorageMap` or `StorageDoubleMap`. -/// // The macro generates the prefix type and replaces the first generic `_`. -/// // -/// // The macro expands the metadata for the storage item with the type used: -/// // * for a storage value the type of the value is copied into the metadata -/// // * for a storage map the type of the values and the type of the key is copied into the metadata -/// // * for a storage double map the types of the values and keys are copied into the -/// // metadata. -/// // -/// // NOTE: The generic `Hasher` must implement the `StorageHasher` trait (or the type is not -/// // usable at all). We use [`StorageHasher::METADATA`] for the metadata of the hasher of the -/// // storage item. Thus generic hasher is supported. -/// #[pallet::storage] -/// pub(super) type MyStorageValue = -/// StorageValue>; -/// -/// // Another storage declaration -/// #[pallet::storage] -/// #[pallet::getter(fn my_storage)] -/// #[pallet::storage_prefix = "SomeOtherName"] -/// pub(super) type MyStorage = -/// StorageMap; -/// -/// // Declare the genesis config (optional). -/// // -/// // The macro accepts either a struct or an enum; it checks that generics are consistent. -/// // -/// // Type must implement the `Default` trait. -/// #[pallet::genesis_config] -/// #[derive(frame_support::DefaultNoBound)] -/// pub struct GenesisConfig { -/// _config: sp_std::marker::PhantomData, -/// _myfield: u32, -/// } -/// -/// // Declare genesis builder. (This is need only if GenesisConfig is declared) -/// #[pallet::genesis_build] -/// impl BuildGenesisConfig for GenesisConfig { -/// fn build(&self) {} -/// } -/// -/// // Declare a pallet origin (this is optional). -/// // -/// // The macro accept type alias or struct or enum, it checks generics are consistent. -/// #[pallet::origin] -/// pub struct Origin(PhantomData); -/// -/// // Declare a hold reason (this is optional). -/// // -/// // Creates a hold reason for this pallet that is aggregated by `construct_runtime`. -/// // A similar enum can be defined for `FreezeReason`, `LockId` or `SlashReason`. -/// #[pallet::composite_enum] -/// pub enum HoldReason { -/// SomeHoldReason -/// } -/// -/// // Declare validate_unsigned implementation (this is optional). -/// #[pallet::validate_unsigned] -/// impl ValidateUnsigned for Pallet { -/// type Call = Call; -/// fn validate_unsigned( -/// source: TransactionSource, -/// call: &Self::Call -/// ) -> TransactionValidity { -/// Err(TransactionValidityError::Invalid(InvalidTransaction::Call)) -/// } -/// } -/// -/// // Declare inherent provider for pallet (this is optional). -/// #[pallet::inherent] -/// impl ProvideInherent for Pallet { -/// type Call = Call; -/// type Error = InherentError; -/// -/// const INHERENT_IDENTIFIER: InherentIdentifier = INHERENT_IDENTIFIER; -/// -/// fn create_inherent(_data: &InherentData) -> Option { -/// unimplemented!(); -/// } -/// -/// fn is_inherent(_call: &Self::Call) -> bool { -/// unimplemented!(); -/// } -/// } -/// -/// // Regular rust code needed for implementing ProvideInherent trait -/// -/// #[derive(codec::Encode, sp_runtime::RuntimeDebug)] -/// #[cfg_attr(feature = "std", derive(codec::Decode))] -/// pub enum InherentError { -/// } -/// -/// impl sp_inherents::IsFatalError for InherentError { -/// fn is_fatal_error(&self) -> bool { -/// unimplemented!(); -/// } -/// } -/// -/// pub const INHERENT_IDENTIFIER: sp_inherents::InherentIdentifier = *b"testpall"; -/// } -/// ``` -/// -/// # Example of an instantiable pallet -/// -/// ``` -/// pub use pallet::*; -/// -/// #[frame_support::pallet] -/// pub mod pallet { -/// use frame_support::pallet_prelude::*; -/// use frame_system::pallet_prelude::*; -/// -/// type BalanceOf = >::Balance; -/// -/// #[pallet::config] -/// pub trait Config: frame_system::Config { -/// #[pallet::constant] -/// type MyGetParam: Get; -/// type Balance: Parameter + MaxEncodedLen + From; -/// type RuntimeEvent: From> + IsType<::RuntimeEvent>; -/// } -/// -/// #[pallet::extra_constants] -/// impl, I: 'static> Pallet { -/// /// Some description -/// fn extra_constant_name() -> u128 { 4u128 } -/// } -/// -/// #[pallet::pallet] -/// #[pallet::generate_store(pub(super) trait Store)] -/// pub struct Pallet(PhantomData<(T, I)>); -/// -/// #[pallet::hooks] -/// impl, I: 'static> Hooks> for Pallet { -/// } -/// -/// #[pallet::call] -/// impl, I: 'static> Pallet { -/// /// Doc comment put in metadata -/// #[pallet::weight(0)] -/// pub fn toto(origin: OriginFor, #[pallet::compact] _foo: u32) -> DispatchResultWithPostInfo { -/// let _ = origin; -/// unimplemented!(); -/// } -/// } -/// -/// #[pallet::error] -/// pub enum Error { -/// /// doc comment put into metadata -/// InsufficientProposersBalance, -/// } -/// -/// #[pallet::event] -/// #[pallet::generate_deposit(pub(super) fn deposit_event)] -/// pub enum Event, I: 'static = ()> { -/// /// doc comment put in metadata -/// Proposed(::AccountId), -/// /// doc -/// Spending(BalanceOf), -/// Something(u32), -/// } -/// -/// #[pallet::type_value] -/// pub(super) fn MyDefault, I: 'static>() -> T::Balance { 3.into() } -/// -/// #[pallet::storage] -/// pub(super) type MyStorageValue, I: 'static = ()> = -/// StorageValue>; -/// -/// #[pallet::storage] -/// #[pallet::getter(fn my_storage)] -/// #[pallet::storage_prefix = "SomeOtherName"] -/// pub(super) type MyStorage = -/// StorageMap; -/// -/// #[pallet::genesis_config] -/// #[derive(frame_support::DefaultNoBound)] -/// pub struct GenesisConfig, I: 'static = ()> { -/// _config: sp_std::marker::PhantomData<(T,I)>, -/// _myfield: u32, -/// } -/// -/// #[pallet::genesis_build] -/// impl, I: 'static> BuildGenesisConfig for GenesisConfig { -/// fn build(&self) {} -/// } -/// -/// #[pallet::origin] -/// pub struct Origin(PhantomData<(T, I)>); -/// -/// #[pallet::composite_enum] -/// pub enum HoldReason { -/// SomeHoldReason -/// } -/// -/// #[pallet::validate_unsigned] -/// impl, I: 'static> ValidateUnsigned for Pallet { -/// type Call = Call; -/// fn validate_unsigned( -/// source: TransactionSource, -/// call: &Self::Call -/// ) -> TransactionValidity { -/// Err(TransactionValidityError::Invalid(InvalidTransaction::Call)) -/// } -/// } -/// -/// #[pallet::inherent] -/// impl, I: 'static> ProvideInherent for Pallet { -/// type Call = Call; -/// type Error = InherentError; -/// -/// const INHERENT_IDENTIFIER: InherentIdentifier = INHERENT_IDENTIFIER; -/// -/// fn create_inherent(_data: &InherentData) -> Option { -/// unimplemented!(); -/// } -/// -/// fn is_inherent(_call: &Self::Call) -> bool { -/// unimplemented!(); -/// } -/// } -/// -/// // Regular rust code needed for implementing ProvideInherent trait -/// -/// #[derive(codec::Encode, sp_runtime::RuntimeDebug)] -/// #[cfg_attr(feature = "std", derive(codec::Decode))] -/// pub enum InherentError { -/// } -/// -/// impl sp_inherents::IsFatalError for InherentError { -/// fn is_fatal_error(&self) -> bool { -/// unimplemented!(); -/// } -/// } -/// -/// pub const INHERENT_IDENTIFIER: sp_inherents::InherentIdentifier = *b"testpall"; -/// } -/// ``` +/// The `pallet_doc` attribute can only be provided with one argument, +/// which is the file path that holds the documentation to be added to the metadata. /// -/// # Upgrade guidelines -/// -/// 1. Export the metadata of the pallet for later checks -/// - run your node with the pallet active -/// - query the metadata using the `state_getMetadata` RPC and curl, or use `subsee -p -/// > meta.json` -/// 2. Generate the template upgrade for the pallet provided by `decl_storage` with the -/// environment variable `PRINT_PALLET_UPGRADE`: `PRINT_PALLET_UPGRADE=1 cargo check -p -/// my_pallet`. This template can be used as it contains all information for storages, -/// genesis config and genesis build. -/// 3. Reorganize the pallet to have the trait `Config`, `decl_*` macros, -/// [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`), -/// [`ProvideInherent`](`pallet_prelude::ProvideInherent`), and Origin` all together in one -/// file. Suggested order: -/// * `Config`, -/// * `decl_module`, -/// * `decl_event`, -/// * `decl_error`, -/// * `decl_storage`, -/// * `origin`, -/// * `validate_unsigned`, -/// * `provide_inherent`, so far it should compile and all be correct. -/// 4. start writing the new pallet module -/// ```ignore -/// pub use pallet::*; -/// -/// #[frame_support::pallet] -/// pub mod pallet { -/// use frame_support::pallet_prelude::*; -/// use frame_system::pallet_prelude::*; -/// use super::*; -/// -/// #[pallet::pallet] -/// #[pallet::generate_store($visibility_of_trait_store trait Store)] -/// // NOTE: if the visibility of trait store is private but you want to make it available -/// // in super, then use `pub(super)` or `pub(crate)` to make it available in crate. -/// pub struct Pallet(_); -/// // pub struct Pallet(PhantomData); // for instantiable pallet -/// } -/// ``` -/// 5. **migrate Config**: move trait into the module with -/// * all const in `decl_module` to [`#[pallet::constant]`](#palletconstant) -/// * add the bound `IsType<::RuntimeEvent>` to `type -/// RuntimeEvent` -/// 7. **migrate decl_module**: write: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks for Pallet { -/// } -/// ``` -/// and write inside `on_initialize`, `on_finalize`, `on_runtime_upgrade`, -/// `offchain_worker`, and `integrity_test`. -/// -/// then write: -/// ```ignore -/// #[pallet::call] -/// impl Pallet { -/// } -/// ``` -/// and write inside all the calls in `decl_module` with a few changes in the signature: -/// - origin must now be written completely, e.g. `origin: OriginFor` -/// - result type must be `DispatchResultWithPostInfo`, you need to write it and also you -/// might need to put `Ok(().into())` at the end or the function. -/// - `#[compact]` must now be written -/// [`#[pallet::compact]`](#palletcompact-some_arg-some_type) -/// - `#[weight = ..]` must now be written [`#[pallet::weight(..)]`](#palletweightexpr) -/// -/// 7. **migrate event**: rewrite as a simple enum with the attribute -/// [`#[pallet::event]`](#event-palletevent-optional), use [`#[pallet::generate_deposit($vis -/// fn deposit_event)]`](#event-palletevent-optional) to generate `deposit_event`, -/// 8. **migrate error**: rewrite it with attribute -/// [`#[pallet::error]`](#error-palleterror-optional). -/// 9. **migrate storage**: `decl_storage` provide an upgrade template (see 3.). All storages, -/// genesis config, genesis build and default implementation of genesis config can be taken -/// from it directly. -/// -/// Otherwise here is the manual process: -/// -/// first migrate the genesis logic. write: -/// ```ignore -/// #[pallet::genesis_config] -/// struct GenesisConfig { -/// // fields of add_extra_genesis -/// } -/// impl Default for GenesisConfig { -/// // type default or default provided for fields -/// } -/// #[pallet::genesis_build] -/// impl GenesisBuild for GenesisConfig { -/// // for instantiable pallet: -/// // `impl GenesisBuild for GenesisConfig { -/// fn build() { -/// // The add_extra_genesis build logic -/// } -/// } -/// ``` -/// for each storage, if it contains `config(..)` then add fields, and make it default to -/// the value in `= ..;` or the type default if none, if it contains no build then also add -/// the logic to build the value. for each storage if it contains `build(..)` then add the -/// logic to `genesis_build`. -/// -/// NOTE: within `decl_storage`: the individual config is executed first, followed by the -/// build and finally the `add_extra_genesis` build. -/// -/// Once this is done you can migrate storages individually, a few notes: -/// - for private storage use `pub(crate) type ` or `pub(super) type` or nothing, -/// - for storages with `get(fn ..)` use [`#[pallet::getter(fn -/// ...)]`](#palletgetterfn-my_getter_fn_name-optional) -/// - for storages with value being `Option<$something>` make generic `Value` being -/// `$something` and generic `QueryKind` being `OptionQuery` (note: this is default). -/// Otherwise make `Value` the complete value type and `QueryKind` being `ValueQuery`. -/// - for storages with default value: `= $expr;` provide some specific `OnEmpty` generic. -/// To do so use of `#[pallet::type_value]` to generate the wanted struct to put. -/// example: `MyStorage: u32 = 3u32` would be written: -/// -/// ```ignore -/// #[pallet::type_value] fn MyStorageOnEmpty() -> u32 { 3u32 } -/// #[pallet::storage] -/// pub(super) type MyStorage = StorageValue<_, u32, ValueQuery, MyStorageOnEmpty>; -/// ``` -/// -/// NOTE: `decl_storage` also generates the functions `assimilate_storage` and -/// `build_storage` directly on `GenesisConfig`, and these are sometimes used in tests. -/// In order not to break they can be implemented manually, one can implement those -/// functions by calling the `GenesisBuild` implementation. -/// 10. **migrate origin**: move the origin to the pallet module to be under a -/// [`#[pallet::origin]`](#origin-palletorigin-optional) attribute -/// 11. **migrate validate_unsigned**: move the -/// [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) implementation to the pallet -/// module under a -/// [`#[pallet::validate_unsigned]`](#validate-unsigned-palletvalidate_unsigned-optional) -/// attribute -/// 12. **migrate provide_inherent**: move the -/// [`ProvideInherent`](`pallet_prelude::ProvideInherent`) implementation to the pallet -/// module under a [`#[pallet::inherent]`](#inherent-palletinherent-optional) attribute -/// 13. rename the usage of `Module` to `Pallet` inside the crate. -/// 14. migration is done, now double check the migration with the checking migration -/// guidelines shown below. -/// -/// # Checking upgrade guidelines: -/// -/// * compare metadata. Use [subsee](https://github.com/ascjones/subsee) to fetch the metadata -/// and do a diff of the resulting json before and after migration. This checks for: -/// * call, names, signature, docs -/// * event names, docs -/// * error names, docs -/// * storage names, hasher, prefixes, default value -/// * error, error, constant -/// * manually check that: -/// * `Origin` was moved inside the macro under -/// [`#[pallet::origin]`](#origin-palletorigin-optional) if it exists -/// * [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) was moved inside the macro -/// under -/// [`#[pallet::validate_unsigned)]`](#validate-unsigned-palletvalidate_unsigned-optional) -/// if it exists -/// * [`ProvideInherent`](`pallet_prelude::ProvideInherent`) was moved inside the macro -/// under [`#[pallet::inherent)]`](#inherent-palletinherent-optional) if it exists -/// * `on_initialize` / `on_finalize` / `on_runtime_upgrade` / `offchain_worker` were moved -/// to the `Hooks` implementation -/// * storages with `config(..)` were converted to `GenesisConfig` field, and their default -/// is `= $expr;` if the storage has a default value -/// * storages with `build($expr)` or `config(..)` were built in `GenesisBuild::build` -/// * `add_extra_genesis` fields were converted to `GenesisConfig` field with their correct -/// default if specified -/// * `add_extra_genesis` build was written into `GenesisBuild::build` -/// * storage items defined with [`pallet`] use the name of the pallet provided by -/// [`traits::PalletInfo::name`] as `pallet_prefix` (in `decl_storage`, storage items used -/// the `pallet_prefix` given as input of `decl_storage` with the syntax `as Example`). Thus -/// a runtime using the pallet must be careful with this change. To handle this change: -/// * either ensure that the name of the pallet given to `construct_runtime!` is the same -/// as the name the pallet was giving to `decl_storage`, -/// * or do a storage migration from the old prefix used to the new prefix used. -/// -/// NOTE: The prefixes used by storage items are in metadata. Thus, ensuring the metadata -/// hasn't changed ensures that the `pallet_prefix`s used by the storage items haven't changed. -/// -/// # Notes when macro fails to show proper error message spans: -/// -/// Rustc loses span for some macro input. Some tips to fix it: -/// * do not use inner attribute: -/// ```ignore -/// #[pallet] -/// pub mod pallet { -/// //! This inner attribute will make span fail -/// .. -/// } -/// ``` -/// * use the newest nightly possible. +/// This approach is beneficial when you use the `include_str` macro at the beginning of +/// the file and want that documentation to extend to the runtime metadata, without +/// reiterating the documentation on the pallet module itself. pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros From 350a4d3f9e0526a48f704c6f3dcdf385110c7c5d Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 18:30:51 +0400 Subject: [PATCH 15/57] add doc for require transactional --- substrate/frame/support/procedural/src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 9da65b4bf56a..2131525d9b5b 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -285,6 +285,12 @@ pub fn transactional(attr: TokenStream, input: TokenStream) -> TokenStream { transactional::transactional(attr, input).unwrap_or_else(|e| e.to_compile_error().into()) } +#[rustfmt::skip] +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::require_transactional`](../frame_support/attr.require_transactional.html). #[proc_macro_attribute] pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStream { transactional::require_transactional(attr, input) From 2d64a11211da85911ef776ed8e54a777ee0e8c47 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 18:33:59 +0400 Subject: [PATCH 16/57] doc storage alias --- substrate/frame/support/procedural/src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 2131525d9b5b..670ac6f8f7b4 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -441,6 +441,12 @@ pub fn __create_tt_macro(input: TokenStream) -> TokenStream { tt_macro::create_tt_return_macro(input) } +#[rustfmt::skip] +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::storage_alias`](../frame_support/attr.storage_alias.html). #[proc_macro_attribute] pub fn storage_alias(attributes: TokenStream, input: TokenStream) -> TokenStream { storage_alias::storage_alias(attributes.into(), input.into()) From 4b4da8db7f898d00ff4c6e4ad4da571cb888657e Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 18:39:13 +0400 Subject: [PATCH 17/57] storage version doc --- substrate/frame/support/procedural/src/lib.rs | 15 ++++---------- substrate/frame/support/src/lib.rs | 20 +++++++++++++++++-- 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 670ac6f8f7b4..33aad264e042 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -944,19 +944,12 @@ pub fn generate_store(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Because the `pallet::pallet` macro implements `GetStorageVersion`, the current storage -/// version needs to be communicated to the macro. This can be done by using the -/// `pallet::storage_version` attribute: -/// -/// ```ignore -/// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); +#[rustfmt::skip] /// -/// #[pallet::pallet] -/// #[pallet::storage_version(STORAGE_VERSION)] -/// pub struct Pallet(_); -/// ``` +/// --- /// -/// If not present, the current storage version is set to the default value. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::storage_version`](../frame_support/pallet_macros/attr.storage_version.html). #[proc_macro_attribute] pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index fee47ee2c7d2..f68ce8c4f8d5 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1024,10 +1024,26 @@ pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, - pallet_section, storage_prefix, storage_version, type_value, unbounded, validate_unsigned, - weight, whitelist_storage, + pallet_section, storage_prefix, type_value, unbounded, validate_unsigned, weight, + whitelist_storage, }; + /// Because the `pallet::pallet` macro implements + /// [`GetStorageVersion`](frame_support::traits::GetStorageVersion), the current storage + /// version needs to be communicated to the macro. This can be done by using the + /// `pallet::storage_version` attribute: + /// + /// ```ignore + /// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); + /// + /// #[pallet::pallet] + /// #[pallet::storage_version(STORAGE_VERSION)] + /// pub struct Pallet(_); + /// ``` + /// + /// If not present, the current storage version is set to the default value. + pub use frame_support_procedural::storage_version; + /// The `#[pallet::hooks]` attribute allows you to specify a `Hooks` implementation for /// `Pallet` that specifies pallet-specific logic. /// From db6b68db8ec790a0bf25559b74c7c33472d5f1bb Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 18:41:58 +0400 Subject: [PATCH 18/57] type_value doc --- substrate/frame/support/procedural/src/lib.rs | 28 +++-------------- substrate/frame/support/src/lib.rs | 31 +++++++++++++++++-- 2 files changed, 33 insertions(+), 26 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 33aad264e042..c707e68a2dc0 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1149,32 +1149,12 @@ pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::type_value]` attribute lets you define a struct implementing the `Get` trait -/// to ease the use of storage types. This attribute is meant to be used alongside -/// [`#[pallet::storage]`](`macro@storage`) to define a storage's default value. This attribute -/// can be used multiple times. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } -/// ``` -/// -/// I.e.: a function definition with generics none or `T: Config` and a returned type. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn MyDefault() -> T::Balance { 3.into() } -/// ``` +#[rustfmt::skip] /// -/// ## Macro expansion +/// --- /// -/// The macro renames the function to some internal name, generates a struct with the original -/// name of the function and its generic, and implements `Get<$ReturnType>` by calling the user -/// defined function. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::type_value`](../frame_support/pallet_macros/attr.type_value.html). #[proc_macro_attribute] pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index f68ce8c4f8d5..5fc98d951e80 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1024,10 +1024,37 @@ pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, - pallet_section, storage_prefix, type_value, unbounded, validate_unsigned, weight, - whitelist_storage, + pallet_section, storage_prefix, unbounded, validate_unsigned, weight, whitelist_storage, }; + /// The `#[pallet::type_value]` attribute lets you define a struct implementing the + /// [`Get`](frame_support::traits::Get) trait to ease the use of storage types. This + /// attribute is meant to be used alongside [`#[pallet::storage]`](`macro@storage`) to + /// define a storage's default value. This attribute can be used multiple times. + /// + /// Item must be defined as: + /// + /// ```ignore + /// #[pallet::type_value] + /// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } + /// ``` + /// + /// I.e.: a function definition with generics none or `T: Config` and a returned type. + /// + /// E.g.: + /// + /// ```ignore + /// #[pallet::type_value] + /// fn MyDefault() -> T::Balance { 3.into() } + /// ``` + /// + /// ## Macro expansion + /// + /// The macro renames the function to some internal name, generates a struct with the + /// original name of the function and its generic, and implements `Get<$ReturnType>` by + /// calling the user defined function. + pub use frame_support_procedural::type_value; + /// Because the `pallet::pallet` macro implements /// [`GetStorageVersion`](frame_support::traits::GetStorageVersion), the current storage /// version needs to be communicated to the macro. This can be done by using the From 7b8ecfb378487ff39557fcec23bccffbdc8bc015 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 7 Dec 2023 18:52:11 +0400 Subject: [PATCH 19/57] validate unsigned links --- substrate/frame/support/procedural/src/lib.rs | 24 +++-------------- substrate/frame/support/src/lib.rs | 27 ++++++++++++++++++- 2 files changed, 30 insertions(+), 21 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index c707e68a2dc0..7ac2bfe69acf 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1213,28 +1213,12 @@ pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some unsigned -/// transaction: -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::validate_unsigned] -/// impl ValidateUnsigned for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait `ValidateUnsigned` for type -/// `Pallet`, and some optional where clause. -/// -/// NOTE: There is also the `sp_runtime::traits::SignedExtension` trait that can be used to add -/// some specific logic for transaction validation. +#[rustfmt::skip] /// -/// ## Macro expansion +/// --- /// -/// The macro currently makes no use of this information, but it might use this information in -/// the future to give information directly to `construct_runtime`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::validate_unsigned`](../frame_support/pallet_macros/attr.validate_unsigned.html). #[proc_macro_attribute] pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 5fc98d951e80..ae0c77a1e2a1 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1024,9 +1024,34 @@ pub mod pallet_macros { pub use frame_support_procedural::{ composite_enum, config, disable_frame_system_supertrait_check, extra_constants, generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, - pallet_section, storage_prefix, unbounded, validate_unsigned, weight, whitelist_storage, + pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some + /// unsigned transaction: + /// + /// Item must be defined as: + /// + /// ```ignore + /// #[pallet::validate_unsigned] + /// impl ValidateUnsigned for Pallet { + /// // ... regular trait implementation + /// } + /// ``` + /// + /// I.e. a trait implementation with bound `T: Config`, of trait + /// [`ValidateUnsigned`](frame_support::pallet_prelude::ValidateUnsigned) for + /// type `Pallet`, and some optional where clause. + /// + /// NOTE: There is also the `sp_runtime::traits::SignedExtension` trait that can be used to + /// add some specific logic for transaction validation. + /// + /// ## Macro expansion + /// + /// The macro currently makes no use of this information, but it might use this information + /// in the future to give information directly to [`frame_support::construct_runtime`]. + pub use frame_support_procedural::validate_unsigned; + /// The `#[pallet::type_value]` attribute lets you define a struct implementing the /// [`Get`](frame_support::traits::Get) trait to ease the use of storage types. This /// attribute is meant to be used alongside [`#[pallet::storage]`](`macro@storage`) to From 3fcbf6041e15cd40d882e2f436d0a47456e80704 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Mon, 26 Feb 2024 17:49:12 +1100 Subject: [PATCH 20/57] doc tests --- substrate/frame/support/src/lib.rs | 222 +++++++++++++++++++++-------- 1 file changed, 162 insertions(+), 60 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index f6e55d4a9ad2..ac66df96c8a5 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -891,15 +891,21 @@ pub mod pallet_prelude { /// specify pallet information. /// /// The struct must be defined as follows: -/// ```ignore -/// #[pallet::pallet] -/// pub struct Pallet(_); +/// ``` +/// #[frame_support::pallet] +/// mod pallet { +/// #[pallet::pallet] // <- the macro +/// pub struct Pallet(_); // <- the struct definition +/// +/// #[pallet::config] +/// pub trait Config: frame_system::Config {} +/// } /// ``` /// I.e. a regular struct definition named `Pallet`, with generic T and no where clause. /// /// ## Macro expansion: /// -/// The macro adds this attribute to the struct definition: +/// The macro adds this attribute to the Pallet struct definition: /// ```ignore /// #[derive( /// frame_support::CloneNoBound, @@ -1032,10 +1038,26 @@ pub mod pallet_macros { /// /// Item must be defined as: /// - /// ```ignore - /// #[pallet::validate_unsigned] - /// impl ValidateUnsigned for Pallet { - /// // ... regular trait implementation + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::validate_unsigned] + /// impl sp_runtime::traits::ValidateUnsigned for Pallet { + /// type Call = Call; + /// + /// fn validate_unsigned(_source: TransactionSource, _call: &Self::Call) -> TransactionValidity { + /// // Your implementation details here + /// unimplemented!() + /// } + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1059,18 +1081,28 @@ pub mod pallet_macros { /// /// Item must be defined as: /// - /// ```ignore - /// #[pallet::type_value] - /// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use sp_runtime::FixedU128; + /// use frame_support::pallet_prelude::*; /// - /// I.e.: a function definition with generics none or `T: Config` and a returned type. + /// #[pallet::pallet] + /// pub struct Pallet(_); /// - /// E.g.: + /// #[pallet::storage] + /// pub(super) type SomeStorage = + /// StorageValue<_, FixedU128, ValueQuery, DefaultForSomeValue>; /// - /// ```ignore - /// #[pallet::type_value] - /// fn MyDefault() -> T::Balance { 3.into() } + /// // Define default for ParachainId + /// #[pallet::type_value] + /// pub fn DefaultForSomeValue() -> FixedU128 { + /// FixedU128::from_u32(1) + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } /// ``` /// /// ## Macro expansion @@ -1085,12 +1117,21 @@ pub mod pallet_macros { /// version needs to be communicated to the macro. This can be done by using the /// `pallet::storage_version` attribute: /// - /// ```ignore - /// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::StorageVersion; + /// use frame_support::traits::GetStorageVersion; + /// + /// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); /// - /// #[pallet::pallet] - /// #[pallet::storage_version(STORAGE_VERSION)] - /// pub struct Pallet(_); + /// #[pallet::pallet] + /// #[pallet::storage_version(STORAGE_VERSION)] + /// pub struct Pallet(_); + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } /// ``` /// /// If not present, the current storage version is set to the default value. @@ -1100,22 +1141,29 @@ pub mod pallet_macros { /// `Pallet` that specifies pallet-specific logic. /// /// The item the attribute attaches to must be defined as follows: - /// ```ignore - /// #[pallet::hooks] - /// impl Hooks> for Pallet $optional_where_clause { - /// ... + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::hooks] + /// impl Hooks> for Pallet { + /// // Implement hooks here + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} /// } /// ``` /// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait - /// `Hooks>` (they are defined in preludes), for the type `Pallet` and - /// with an optional where clause. - /// - /// If no `#[pallet::hooks]` exists, then the following default implementation is - /// automatically generated: - /// ```ignore - /// #[pallet::hooks] - /// impl Hooks> for Pallet {} - /// ``` + /// `Hooks>` (they are defined in preludes), for the type `Pallet`. + /// + /// Optionally, you could add a where clause. /// /// ## Macro expansion /// @@ -1167,12 +1215,33 @@ pub mod pallet_macros { /// The closure must return `bool`. /// /// ### Example - /// ```ignore - /// #[pallet::feeless_if(|_origin: &OriginFor, something: &u32| -> bool { - /// *something == 0 - /// })] - /// pub fn do_something(origin: OriginFor, something: u32) -> DispatchResult { - /// .... + /// + /// ``` + /// #[frame_support::pallet(dev_mode)] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::call] + /// impl Pallet { + /// #[pallet::call_index(0)] + /// /// Marks this call as feeless if `foo` is zero. + /// #[pallet::feeless_if(|_origin: &OriginFor, foo: &u32| -> bool { + /// *foo == 0 + /// })] + /// pub fn something( + /// _: OriginFor, + /// foo: u32, + /// ) -> DispatchResult { + /// unimplemented!() + /// } + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1194,16 +1263,24 @@ pub mod pallet_macros { /// returned from the dispatchable when an error occurs. The information for this error /// type is then stored in metadata. /// - /// Item must be defined as: + /// Item must be defined as so: + /// + /// ``` + /// #[frame_support::pallet(dev_mode)] + /// mod pallet { + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::error] + /// pub enum Error { + /// /// SomeFieldLessVariant doc + /// SomeFieldLessVariant, + /// /// SomeVariantWithOneField doc + /// SomeVariantWithOneField(u32), + /// } /// - /// ```ignore - /// #[pallet::error] - /// pub enum Error { - /// /// $some_optional_doc - /// $SomeFieldLessVariant, - /// /// $some_more_optional_doc - /// $SomeVariantWithOneField(FieldType), - /// ... + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} /// } /// ``` /// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field @@ -1241,21 +1318,37 @@ pub mod pallet_macros { /// stored under the `system` / `events` key when the block is applied (and then replaced /// when the next block writes it's events). /// - /// The Event enum must be defined as follows: + /// The Event enum can be defined as follows: /// - /// ```ignore - /// #[pallet::event] - /// #[pallet::generate_deposit($visibility fn deposit_event)] // Optional - /// pub enum Event<$some_generic> $optional_where_clause { - /// /// Some doc - /// $SomeName($SomeType, $YetanotherType, ...), - /// ... + /// ``` + /// #[frame_support::pallet(dev_mode)] + /// mod pallet { + /// use frame_support::pallet_prelude::IsType; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::event] + /// #[pallet::generate_deposit(fn deposit_event)] // Optional + /// pub enum Event { + /// /// SomeEvent doc + /// SomeEvent(u16, u32), // SomeEvent with two fields + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config { + /// /// The overarching runtime event type. + /// type RuntimeEvent: From> + /// + IsType<::RuntimeEvent>; + /// } /// } /// ``` /// /// I.e. an enum (with named or unnamed fields variant), named `Event`, with generic: none /// or `T` or `T: Config`, and optional w here clause. /// + /// `RuntimeEvent` must be defined in the `Config`, as shown in the example. + /// /// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], [`codec::Encode`], /// [`codec::Decode`], and [`Debug`] (on std only). For ease of use, bound by the trait /// `Member`, available in `frame_support::pallet_prelude`. @@ -1364,9 +1457,18 @@ pub mod pallet_macros { /// If no `#[pallet::call]` exists, then a default implementation corresponding to the /// following code is automatically generated: /// - /// ```ignore - /// #[pallet::call] - /// impl Pallet {} + /// ``` + /// #[frame_support::pallet(dev_mode)] + /// mod pallet { + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::call] // <- automatically generated + /// impl Pallet {} // <- automatically generated + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } /// ``` pub use frame_support_procedural::call; From 98db02fa98fd59180a4fafaacf923af8d60d6ecc Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 11:47:22 +1100 Subject: [PATCH 21/57] move composite_enum docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 23 ++------ substrate/frame/support/src/lib.rs | 54 +++++++++++++++++-- 2 files changed, 54 insertions(+), 23 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 4d264a70816b..fba8ae8a991d 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1245,28 +1245,11 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::composite_enum]` attribute allows you to define an enum that gets composed as an -/// aggregate enum by `construct_runtime`. This is similar in principle with `#[pallet::event]` and -/// `#[pallet::error]`. /// -/// The attribute currently only supports enum definitions, and identifiers that are named -/// `FreezeReason`, `HoldReason`, `LockId` or `SlashReason`. Arbitrary identifiers for the enum are -/// not supported. The aggregate enum generated by `construct_runtime` will have the name of -/// `RuntimeFreezeReason`, `RuntimeHoldReason`, `RuntimeLockId` and `RuntimeSlashReason` -/// respectively. -/// -/// NOTE: The aggregate enum generated by `construct_runtime` generates a conversion function from -/// the pallet enum to the aggregate enum, and automatically derives the following traits: -/// -/// ```ignore -/// Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, MaxEncodedLen, TypeInfo, -/// RuntimeDebug -/// ``` +/// --- /// -/// For ease of usage, when no `#[derive]` attributes are found for the enum under -/// `#[pallet::composite_enum]`, the aforementioned traits are automatically derived for it. The -/// inverse is also true: if there are any `#[derive]` attributes found for the enum, then no traits -/// will automatically be derived for it. +/// **Rust-Analyzer users**: See the documentation of the Rust item in +/// `frame_support::pallet_macros::composite_enum`. #[proc_macro_attribute] pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index ac66df96c8a5..5837e3563df0 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1028,11 +1028,59 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - composite_enum, config, disable_frame_system_supertrait_check, extra_constants, - generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, - pallet_section, storage_prefix, unbounded, weight, whitelist_storage, + config, disable_frame_system_supertrait_check, extra_constants, generate_store, getter, + import_section, inherent, no_default, no_default_bounds, origin, pallet_section, + storage_prefix, unbounded, weight, whitelist_storage, }; + /// The `#[pallet::composite_enum]` attribute allows you to define an enum that gets + /// composed as an aggregate enum by `construct_runtime`. This is similar in principle with + /// [frame_support_procedural::event] and [frame_support_procedural::error]. + /// + /// The attribute currently only supports enum definitions, and identifiers that are named + /// `FreezeReason`, `HoldReason`, `LockId` or `SlashReason`. Arbitrary identifiers for the + /// enum are not supported. The aggregate enum generated by + /// [frame_support::construct_runtime] will have the name of `RuntimeFreezeReason`, + /// `RuntimeHoldReason`, `RuntimeLockId` and `RuntimeSlashReason` respectively. + /// + /// NOTE: The aggregate enum generated by `construct_runtime` generates a conversion + /// function from the pallet enum to the aggregate enum, and automatically derives the + /// following traits: + /// + /// ```ignore + /// Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, MaxEncodedLen, TypeInfo, + /// RuntimeDebug + /// ``` + /// + /// For ease of usage, when no `#[derive]` attributes are found for the enum under + /// `#[pallet::composite_enum]`, the aforementioned traits are automatically derived for + /// it. The inverse is also true: if there are any `#[derive]` attributes found for the + /// enum, then no traits will automatically be derived for it. + /// + /// e.g, defining `HoldReason` in a pallet + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::composite_enum] + /// pub enum HoldReason { + /// /// The NIS Pallet has reserved it for a non-fungible receipt. + /// #[codec(index = 0)] + /// SomeHoldReason, + /// #[codec(index = 1)] + /// SomeOtherHoldReason, + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + pub use frame_support_procedural::composite_enum; + /// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some /// unsigned transaction: /// From 90e5ca684439041d5dd41cdc673ebd92d0d228f6 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 16:36:49 +1100 Subject: [PATCH 22/57] move pallet::config docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 86 +++---------- substrate/frame/support/src/lib.rs | 115 ++++++++++++++++-- 2 files changed, 121 insertions(+), 80 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index fba8ae8a991d..a37f3424a0b5 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -812,75 +812,11 @@ fn pallet_macro_stub() -> TokenStream { .into() } -/// The mandatory attribute `#[pallet::config]` defines the configurable options for the pallet. /// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::config] -/// pub trait Config: frame_system::Config + $optionally_some_other_supertraits -/// $optional_where_clause -/// { -/// ... -/// } -/// ``` -/// -/// I.e. a regular trait definition named `Config`, with the supertrait -/// `frame_system::pallet::Config`, and optionally other supertraits and a where clause. -/// (Specifying other supertraits here is known as [tight -/// coupling](https://docs.substrate.io/reference/how-to-guides/pallet-design/use-tight-coupling/)) -/// -/// The associated type `RuntimeEvent` is reserved. If defined, it must have the bounds -/// `From` and `IsType<::RuntimeEvent>`. -/// -/// [`pallet::event`](`macro@event`) must be present if `RuntimeEvent` exists as a config item -/// in your `#[pallet::config]`. -/// -/// ## Optional: `with_default` -/// -/// An optional `with_default` argument may also be specified. Doing so will automatically -/// generate a `DefaultConfig` trait inside your pallet which is suitable for use with -/// [`[#[derive_impl(..)]`](`macro@derive_impl`) to derive a default testing config: -/// -/// ```ignore -/// #[pallet::config(with_default)] -/// pub trait Config: frame_system::Config { -/// type RuntimeEvent: Parameter -/// + Member -/// + From> -/// + Debug -/// + IsType<::RuntimeEvent>; -/// -/// #[pallet::no_default] -/// type BaseCallFilter: Contains; -/// // ... -/// } -/// ``` -/// -/// As shown above, you may also attach the [`#[pallet::no_default]`](`macro@no_default`) -/// attribute to specify that a particular trait item _cannot_ be used as a default when a test -/// `Config` is derived using the [`#[derive_impl(..)]`](`macro@derive_impl`) attribute macro. -/// This will cause that particular trait item to simply not appear in default testing configs -/// based on this config (the trait item will not be included in `DefaultConfig`). -/// -/// ### `DefaultConfig` Caveats -/// -/// The auto-generated `DefaultConfig` trait: -/// - is always a _subset_ of your pallet's `Config` trait. -/// - can only contain items that don't rely on externalities, such as `frame_system::Config`. -/// -/// Trait items that _do_ rely on externalities should be marked with -/// [`#[pallet::no_default]`](`macro@no_default`) -/// -/// Consequently: -/// - Any items that rely on externalities _must_ be marked with -/// [`#[pallet::no_default]`](`macro@no_default`) or your trait will fail to compile when used -/// with [`derive_impl`](`macro@derive_impl`). -/// - Items marked with [`#[pallet::no_default]`](`macro@no_default`) are entirely excluded from the -/// `DefaultConfig` trait, and therefore any impl of `DefaultConfig` doesn't need to implement -/// such items. +/// --- /// -/// For more information, see [`macro@derive_impl`]. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::config`](../frame_support/pallet_macros/attr.config.html). #[proc_macro_attribute] pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1245,61 +1181,69 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::composite_enum`. +/// [`frame_support::pallet_macros::composite_enum`](../frame_support/pallet_macros/attr.composite_enum.html). #[proc_macro_attribute] pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::tasks_experimental`. +/// [`frame_support::pallet_macros::tasks_experimental`](../frame_support/pallet_macros/attr.tasks_experimental.html). #[proc_macro_attribute] pub fn tasks_experimental(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::task_list`. +/// [`frame_support::pallet_macros::task_list`](../frame_support/pallet_macros/attr.task_list.html). #[proc_macro_attribute] pub fn task_list(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::task_condition`. +/// [`frame_support::pallet_macros::task_condition`](../frame_support/pallet_macros/attr.task_condition.html). #[proc_macro_attribute] pub fn task_condition(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::task_weight`. +/// [`frame_support::pallet_macros::task_weight`](../frame_support/pallet_macros/attr.task_weight.html). #[proc_macro_attribute] pub fn task_weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } +#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// `frame_support::pallet_macros::task_index`. +/// [`frame_support::pallet_macros::task_index`](../frame_support/pallet_macros/attr.task_index.html). #[proc_macro_attribute] pub fn task_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 5837e3563df0..cfe1e33df0f3 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -856,18 +856,19 @@ pub mod pallet_prelude { }; pub use codec::{Decode, Encode, MaxEncodedLen}; pub use frame_support::pallet_macros::*; + /// The optional attribute `#[inject_runtime_type]` can be attached to `RuntimeCall`, /// `RuntimeEvent`, `RuntimeOrigin` or `PalletInfo` in an impl statement that has /// `#[register_default_impl]` attached to indicate that this item is generated by /// `construct_runtime`. /// /// Attaching this attribute to such an item ensures that the combined impl generated via - /// [`#[derive_impl(..)]`](`macro@super::derive_impl`) will use the correct type + /// [`#[derive_impl(..)]`](`frame_support::derive_impl`) will use the correct type /// auto-generated by `construct_runtime!`. #[doc = docify::embed!("src/tests/inject_runtime_type.rs", derive_impl_works_with_runtime_type_injection)] /// /// However, if `no_aggregated_types` is specified while using - /// `[`#[derive_impl(..)]`](`macro@super::derive_impl`)`, then these items are attached + /// `[`#[derive_impl(..)]`](`frame_support::derive_impl`)`, then these items are attached /// verbatim to the combined impl. #[doc = docify::embed!("src/tests/inject_runtime_type.rs", derive_impl_works_with_no_aggregated_types)] pub use frame_support_procedural::inject_runtime_type; @@ -1028,11 +1029,106 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - config, disable_frame_system_supertrait_check, extra_constants, generate_store, getter, + disable_frame_system_supertrait_check, extra_constants, generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// The mandatory attribute `#[pallet::config]` defines the configurable options for the + /// pallet. + /// + /// Item must be defined as: + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config // + $optionally_some_other_supertraits + /// // $optional_where_clause + /// { + /// // config items here + /// } + /// } + /// ``` + /// + /// I.e. a regular trait definition named `Config`, with the supertrait + /// [`frame_system::pallet::Config`](../../frame_system/pallet/trait.Config.html), and + /// optionally other supertraits and a where clause. (Specifying other supertraits here is + /// known as [tight coupling](https://docs.substrate.io/reference/how-to-guides/pallet-design/use-tight-coupling/)) + /// + /// The associated type `RuntimeEvent` is reserved. If defined, it must have the bounds + /// `From` and `IsType<::RuntimeEvent>`. + /// + /// [`#[pallet::event]`](`event`) must be present if `RuntimeEvent` + /// exists as a config item in your `#[pallet::config]`. + /// + /// ## Optional: `with_default` + /// + /// An optional `with_default` argument may also be specified. Doing so will automatically + /// generate a `DefaultConfig` trait inside your pallet which is suitable for use with + /// [`#[derive_impl(..)`](`frame_support::derive_impl`) to derive a default testing + /// config: + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// use core::fmt::Debug; + /// use frame_support::traits::Contains; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::config(with_default)] // <- with_default is optional + /// pub trait Config: frame_system::Config { + /// /// The overarching event type. + /// #[pallet::no_default_bounds] // Default is not supported for RuntimeEvent + /// type RuntimeEvent: From> + IsType<::RuntimeEvent>; + /// + /// // ...other config items get default + /// } + /// + /// #[pallet::event] + /// pub enum Event { + /// SomeEvent(u16, u32), + /// } + /// } + /// ``` + /// + /// As shown above, you may also attach the [`#[pallet::no_default]`](`no_default`) + /// attribute to specify that a particular trait item _cannot_ be used as a default when a + /// test `Config` is derived using the [`#[derive_impl(..)]`](`frame_support::derive_impl`) + /// attribute macro. This will cause that particular trait item to simply not appear in + /// default testing configs based on this config (the trait item will not be included in + /// `DefaultConfig`). + /// + /// ### `DefaultConfig` Caveats + /// + /// The auto-generated `DefaultConfig` trait: + /// - is always a _subset_ of your pallet's `Config` trait. + /// - can only contain items that don't rely on externalities, such as + /// `frame_system::Config`. + /// + /// Trait items that _do_ rely on externalities should be marked with + /// [`#[pallet::no_default]`](`no_default`) + /// + /// Consequently: + /// - Any items that rely on externalities _must_ be marked with + /// [`#[pallet::no_default]`](`no_default`) or your trait will fail to compile when used + /// with [`derive_impl`](`frame_support::derive_impl`). + /// - Items marked with [`#[pallet::no_default]`](`no_default`) are entirely excluded from + /// the `DefaultConfig` trait, and therefore any impl of `DefaultConfig` doesn't need to + /// implement such items. + /// + /// For more information, see [`frame_support::derive_impl`]. + pub use frame_support_procedural::config; + /// The `#[pallet::composite_enum]` attribute allows you to define an enum that gets /// composed as an aggregate enum by `construct_runtime`. This is similar in principle with /// [frame_support_procedural::event] and [frame_support_procedural::error]. @@ -1040,8 +1136,9 @@ pub mod pallet_macros { /// The attribute currently only supports enum definitions, and identifiers that are named /// `FreezeReason`, `HoldReason`, `LockId` or `SlashReason`. Arbitrary identifiers for the /// enum are not supported. The aggregate enum generated by - /// [frame_support::construct_runtime] will have the name of `RuntimeFreezeReason`, - /// `RuntimeHoldReason`, `RuntimeLockId` and `RuntimeSlashReason` respectively. + /// [`frame_support::construct_runtime`](frame_support::construct_runtime) will have the + /// name of `RuntimeFreezeReason`, `RuntimeHoldReason`, `RuntimeLockId` and + /// `RuntimeSlashReason` respectively. /// /// NOTE: The aggregate enum generated by `construct_runtime` generates a conversion /// function from the pallet enum to the aggregate enum, and automatically derives the @@ -1053,9 +1150,9 @@ pub mod pallet_macros { /// ``` /// /// For ease of usage, when no `#[derive]` attributes are found for the enum under - /// `#[pallet::composite_enum]`, the aforementioned traits are automatically derived for - /// it. The inverse is also true: if there are any `#[derive]` attributes found for the - /// enum, then no traits will automatically be derived for it. + /// [`#[pallet::composite_enum]`](composite_enum), the aforementioned traits are + /// automatically derived for it. The inverse is also true: if there are any `#[derive]` + /// attributes found for the enum, then no traits will automatically be derived for it. /// /// e.g, defining `HoldReason` in a pallet /// @@ -1124,7 +1221,7 @@ pub mod pallet_macros { /// The `#[pallet::type_value]` attribute lets you define a struct implementing the /// [`Get`](frame_support::traits::Get) trait to ease the use of storage types. This - /// attribute is meant to be used alongside [`#[pallet::storage]`](`macro@storage`) to + /// attribute is meant to be used alongside [`#[pallet::storage]`](`storage`) to /// define a storage's default value. This attribute can be used multiple times. /// /// Item must be defined as: From a96119e5c52074f7da642cc5b5782c9ab8b2e2d0 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 16:51:44 +1100 Subject: [PATCH 23/57] move disable_frame_system_supertrait docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 13 +++----- substrate/frame/support/src/lib.rs | 32 +++++++++++++++++-- 2 files changed, 33 insertions(+), 12 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index a37f3424a0b5..c2030686a594 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -843,17 +843,12 @@ pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// To bypass the `frame_system::Config` supertrait check, use the attribute -/// `pallet::disable_frame_system_supertrait_check`, e.g.: +#[rustfmt::skip] /// -/// ```ignore -/// #[pallet::config] -/// #[pallet::disable_frame_system_supertrait_check] -/// pub trait Config: pallet_timestamp::Config {} -/// ``` +/// --- /// -/// NOTE: Bypassing the `frame_system::Config` supertrait check is typically desirable when you -/// want to write an alternative to the `frame_system` pallet. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::disable_frame_system_supertrait_check`](../frame_support/pallet_macros/attr.disable_frame_system_supertrait_check.html). #[proc_macro_attribute] pub fn disable_frame_system_supertrait_check(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index cfe1e33df0f3..35c24c5fa2a1 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,11 +1029,37 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - disable_frame_system_supertrait_check, extra_constants, generate_store, getter, - import_section, inherent, no_default, no_default_bounds, origin, pallet_section, - storage_prefix, unbounded, weight, whitelist_storage, + extra_constants, generate_store, getter, import_section, inherent, no_default, + no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, + whitelist_storage, }; + #[rustfmt::skip] + /// To bypass the `frame_system::Config` supertrait check, use the attribute + /// `pallet::disable_frame_system_supertrait_check`, e.g.: + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::config] + /// #[pallet::disable_frame_system_supertrait_check] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// Bypassing the `frame_system::Config` supertrait check is typically desirable when + /// you want to write an alternative to the `frame_system` pallet. + /// + /// To learn more about supertraits, see the + /// [trait_based_programming](../../polkadot_sdk_docs/reference_docs/trait_based_programming/index.html) + /// reference doc. + pub use frame_support_procedural::disable_frame_system_supertrait_check; + /// The mandatory attribute `#[pallet::config]` defines the configurable options for the /// pallet. /// From c7052c03d9799382b038e342b5ede9bd74500732 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 16:58:29 +1100 Subject: [PATCH 24/57] move extra_constants docs to frame_system --- substrate/frame/support/procedural/src/lib.rs | 21 ++--------- substrate/frame/support/src/lib.rs | 37 +++++++++++++++++-- 2 files changed, 38 insertions(+), 20 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index c2030686a594..1d47ff1fb186 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -948,26 +948,13 @@ pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Allows you to define some extra constants to be added into constant metadata. -/// -/// Item must be defined as: +#[rustfmt::skip] /// -/// ```ignore -/// #[pallet::extra_constants] -/// impl Pallet where $optional_where_clause { -/// /// $some_doc -/// $vis fn $fn_name() -> $some_return_type { -/// ... -/// } -/// ... -/// } -/// ``` -/// I.e. a regular rust `impl` block with some optional where clause and functions with 0 args, -/// 0 generics, and some return type. +/// --- /// -/// ## Macro expansion +/// Rust-Analyzer Users: Documentation for this macro can be found at /// -/// The macro add some extra constants to pallet constant metadata. +/// [`frame_support::pallet_macros::extra_constants`](../frame_support/pallet_macros/attr.extra_constants.html). #[proc_macro_attribute] pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 35c24c5fa2a1..bea6f52e46fc 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,11 +1029,42 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - extra_constants, generate_store, getter, import_section, inherent, no_default, - no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, - whitelist_storage, + generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, + pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// Allows you to define some extra constants to be added into constant metadata. + /// + /// Must be defined like: + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::config] + /// #[pallet::disable_frame_system_supertrait_check] + /// pub trait Config: frame_system::Config {} + /// + /// #[pallet::extra_constants] + /// impl Pallet // $optional_where_clause + /// { + /// #[pallet::constant_name(SomeU32ConstantName)] + /// /// Some doc + /// fn some_u32_constant() -> u32 { + /// 100u32 + /// } + /// } + /// } + /// ``` + /// + /// I.e. a regular rust `impl` block with some optional where clause and functions with 0 + /// args, 0 generics, and some return type. + pub use frame_support_procedural::extra_constants; + #[rustfmt::skip] /// To bypass the `frame_system::Config` supertrait check, use the attribute /// `pallet::disable_frame_system_supertrait_check`, e.g.: From eaa0559ec4e2887ddd99b77906ce16bda48be6c2 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 17:07:57 +1100 Subject: [PATCH 25/57] move generate_store doc to frame_support --- substrate/frame/support/procedural/src/lib.rs | 18 +++---------- substrate/frame/support/src/lib.rs | 25 +++++++++++++++++-- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 1d47ff1fb186..830c843c07bc 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -854,22 +854,12 @@ pub fn disable_frame_system_supertrait_check(_: TokenStream, _: TokenStream) -> pallet_macro_stub() } -/// To generate a `Store` trait associating all storages, annotate your `Pallet` struct with -/// the attribute `#[pallet::generate_store($vis trait Store)]`, e.g.: -/// -/// ```ignore -/// #[pallet::pallet] -/// #[pallet::generate_store(pub(super) trait Store)] -/// pub struct Pallet(_); -/// ``` -/// More precisely, the `Store` trait contains an associated type for each storage. It is -/// implemented for `Pallet` allowing access to the storage from pallet struct. +#[rustfmt::skip] /// -/// Thus when defining a storage named `Foo`, it can later be accessed from `Pallet` using -/// `::Foo`. +/// --- /// -/// NOTE: this attribute is only valid when applied _directly_ to your `Pallet` struct -/// definition. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::generate_store`](../frame_support/pallet_macros/attr.generate_store.html). #[proc_macro_attribute] pub fn generate_store(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index bea6f52e46fc..0a4dffbda7be 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,10 +1029,31 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - generate_store, getter, import_section, inherent, no_default, no_default_bounds, origin, - pallet_section, storage_prefix, unbounded, weight, whitelist_storage, + getter, import_section, inherent, no_default, no_default_bounds, origin, pallet_section, + storage_prefix, unbounded, weight, whitelist_storage, }; + /// DEPRECATED: Will be removed, do not use. + /// See https://github.com/paritytech/substrate/pull/13535 for more details. + /// + /// To generate a `Store` trait associating all storages, annotate your `Pallet` struct + /// with the attribute `#[pallet::generate_store($vis trait Store)]`, e.g.: + /// + /// ```ignore + /// #[pallet::pallet] + /// #[pallet::generate_store(pub(super) trait Store)] + /// pub struct Pallet(_); + /// ``` + /// More precisely, the `Store` trait contains an associated type for each storage. It is + /// implemented for `Pallet` allowing access to the storage from pallet struct. + /// + /// Thus when defining a storage named `Foo`, it can later be accessed from `Pallet` using + /// `::Foo`. + /// + /// NOTE: this attribute is only valid when applied _directly_ to your `Pallet` struct + /// definition. + pub use frame_support_procedural::generate_store; + /// Allows you to define some extra constants to be added into constant metadata. /// /// Must be defined like: From a83253ec91afef93719fc29f0662349da7986a5e Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 17:13:58 +1100 Subject: [PATCH 26/57] move getter docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 8 +++--- substrate/frame/support/src/lib.rs | 27 ++++++++++++++++++- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 830c843c07bc..c4450e4231a4 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -991,10 +991,12 @@ pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define a -/// getter function on `Pallet`. +#[rustfmt::skip] +/// +/// --- /// -/// Also see [`pallet::storage`](`macro@storage`) +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::getter`](../frame_support/pallet_macros/attr.getter.html). #[proc_macro_attribute] pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 0a4dffbda7be..57cef2e72a73 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,10 +1029,35 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - getter, import_section, inherent, no_default, no_default_bounds, origin, pallet_section, + import_section, inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define + /// a getter function on `Pallet` storage. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::getter(fn my_getter_fn_name)] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// See [`pallet::storage`](`frame_support::pallet_macros::storage`) for more info. + pub use frame_support_procedural::getter; + /// DEPRECATED: Will be removed, do not use. /// See https://github.com/paritytech/substrate/pull/13535 for more details. /// From 4bd0054c86917ccc100e7954bb5b44361a84fe9b Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 17:55:33 +1100 Subject: [PATCH 27/57] move import_section docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 36 ++---------- substrate/frame/support/src/lib.rs | 56 ++++++++++++++++++- 2 files changed, 59 insertions(+), 33 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index c4450e4231a4..9d27f0f268fa 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1255,39 +1255,13 @@ pub fn pallet_section(attr: TokenStream, tokens: TokenStream) -> TokenStream { } } -/// An attribute macro that can be attached to a module declaration. Doing so will -/// Imports the contents of the specified external pallet section that was defined -/// previously using [`#[pallet_section]`](`macro@pallet_section`). -/// -/// ## Example -/// ```ignore -/// #[import_section(some_section)] -/// #[pallet] -/// pub mod pallet { -/// // ... -/// } -/// ``` -/// where `some_section` was defined elsewhere via: -/// ```ignore -/// #[pallet_section] -/// pub mod some_section { -/// // ... -/// } -/// ``` -/// -/// This will result in the contents of `some_section` being _verbatim_ imported into -/// the pallet above. Note that since the tokens for `some_section` are essentially -/// copy-pasted into the target pallet, you cannot refer to imports that don't also -/// exist in the target pallet, but this is easily resolved by including all relevant -/// `use` statements within your pallet section, so they are imported as well, or by -/// otherwise ensuring that you have the same imports on the target pallet. +#[rustfmt::skip] /// -/// It is perfectly permissible to import multiple pallet sections into the same pallet, -/// which can be done by having multiple `#[import_section(something)]` attributes -/// attached to the pallet. +/// --- /// -/// Note that sections are imported by their module name/ident, and should be referred to by -/// their _full path_ from the perspective of the target pallet. +/// **Rust-Analyzer users**: See the documentation of the Rust item in +/// `frame_support::pallet_macros::import_section`. +/// [`frame_support::pallet_macros::import_section`](../frame_support/pallet_macros/attr.import_section.html). #[import_tokens_attr { format!( "{}::macro_magic", diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 57cef2e72a73..f64946c8ff58 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,10 +1029,62 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - import_section, inherent, no_default, no_default_bounds, origin, pallet_section, - storage_prefix, unbounded, weight, whitelist_storage, + inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, + weight, whitelist_storage, }; + /// An attribute macro that can be attached to a module declaration. Doing so will + /// import the contents of the specified external pallet section that is defined + /// elsewhere using [`#[pallet_section]`](`pallet_section`). + /// + /// ## Example + /// ``` + /// use frame_support::pallet_macros::pallet_section; + /// use frame_support::pallet_macros::import_section; + /// + /// /// A [`pallet_section`] that defines the events for a pallet. + /// /// This can later be imported into the pallet using [`import_section`]. + /// #[pallet_section] + /// mod events { + /// #[pallet::event] + /// #[pallet::generate_deposit(pub(super) fn deposit_event)] + /// pub enum Event { + /// /// Event documentation should end with an array that provides descriptive names for event + /// /// parameters. [something, who] + /// SomethingStored { something: u32, who: T::AccountId }, + /// } + /// } + /// + /// #[import_section(events)] + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config { + /// type RuntimeEvent: From> + IsType<::RuntimeEvent>; + /// } + /// } + /// ``` + /// + /// This will result in the contents of `some_section` being _verbatim_ imported into + /// the pallet above. Note that since the tokens for `some_section` are essentially + /// copy-pasted into the target pallet, you cannot refer to imports that don't also + /// exist in the target pallet, but this is easily resolved by including all relevant + /// `use` statements within your pallet section, so they are imported as well, or by + /// otherwise ensuring that you have the same imports on the target pallet. + /// + /// It is perfectly permissible to import multiple pallet sections into the same pallet, + /// which can be done by having multiple `#[import_section(something)]` attributes + /// attached to the pallet. + /// + /// Note that sections are imported by their module name/ident, and should be referred to + /// by their _full path_ from the perspective of the target pallet. + pub use frame_support_procedural::import_section; + /// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define /// a getter function on `Pallet` storage. /// From a6902da47a941eda9bf2972d6dc6628f095a5bbf Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 19:53:17 +1100 Subject: [PATCH 28/57] move inherent docs to frame_support --- Cargo.lock | 1 + substrate/frame/support/Cargo.toml | 1 + substrate/frame/support/procedural/src/lib.rs | 28 ++------ substrate/frame/support/src/lib.rs | 66 ++++++++++++++++++- 4 files changed, 70 insertions(+), 26 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 849bc069d20c..d5c05fd68d49 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5698,6 +5698,7 @@ dependencies = [ "sp-staking", "sp-state-machine", "sp-std 8.0.0", + "sp-timestamp", "sp-tracing 10.0.0", "sp-weights", "static_assertions", diff --git a/substrate/frame/support/Cargo.toml b/substrate/frame/support/Cargo.toml index dafb86bd660e..bfe9584ecffd 100644 --- a/substrate/frame/support/Cargo.toml +++ b/substrate/frame/support/Cargo.toml @@ -55,6 +55,7 @@ aquamarine = { version = "0.5.0" } [dev-dependencies] assert_matches = "1.3.0" pretty_assertions = "1.2.1" +sp-timestamp = { path = "../../primitives/timestamp", default-features = false } frame-system = { path = "../system" } [features] diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 9d27f0f268fa..e92814fea448 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1092,32 +1092,12 @@ pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::inherent]` attribute allows the pallet to provide some -/// [inherent](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). -/// An inherent is some piece of data that is inserted by a block authoring node at block -/// creation time and can either be accepted or rejected by validators based on whether the -/// data falls within an acceptable range. -/// -/// The most common inherent is the `timestamp` that is inserted into every block. Since there -/// is no way to validate timestamps, validators simply check that the timestamp reported by -/// the block authoring node falls within an acceptable range. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::inherent] -/// impl ProvideInherent for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait `ProvideInherent` for type -/// `Pallet`, and some optional where clause. +#[rustfmt::skip] /// -/// ## Macro expansion +/// --- /// -/// The macro currently makes no use of this information, but it might use this information in -/// the future to give information directly to `construct_runtime`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::inherent`](../frame_support/pallet_macros/attr.inherent.html). #[proc_macro_attribute] pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index f64946c8ff58..c4e245c8275e 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,10 +1029,72 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - inherent, no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, - weight, whitelist_storage, + no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, + whitelist_storage, }; + /// The `#[pallet::inherent]` attribute allows the pallet to provide + /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). + /// An inherent is some piece of data that is inserted by a block authoring node at block + /// creation time and can either be accepted or rejected by validators based on whether the + /// data falls within an acceptable range. + /// + /// The most common inherent is the `timestamp` that is inserted into every block. Since + /// there is no way to validate timestamps, validators simply check that the timestamp + /// reported by the block authoring node falls within an acceptable range. + /// + /// Example usage: + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_support::inherent::IsFatalError; + /// use sp_timestamp::InherentError; + /// use sp_std::result; + /// + /// // Example inherent identifier + /// pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"timstap0"; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::inherent] + /// impl ProvideInherent for Pallet { + /// type Call = Call; + /// type Error = InherentError; + /// const INHERENT_IDENTIFIER: InherentIdentifier = INHERENT_IDENTIFIER; + /// + /// fn create_inherent(data: &InherentData) -> Option { + /// unimplemented!() + /// } + /// + /// fn check_inherent( + /// call: &Self::Call, + /// data: &InherentData, + /// ) -> result::Result<(), Self::Error> { + /// unimplemented!() + /// } + /// + /// fn is_inherent(call: &Self::Call) -> bool { + /// unimplemented!() + /// } + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// I.e. a trait implementation with bound `T: Config`, of trait `ProvideInherent` for type + /// `Pallet`, and some optional where clause. + /// + /// ## Macro expansion + /// + /// The macro currently makes no use of this information, but it might use this information + /// in the future to give information directly to `construct_runtime`. + pub use frame_support_procedural::inherent; + /// An attribute macro that can be attached to a module declaration. Doing so will /// import the contents of the specified external pallet section that is defined /// elsewhere using [`#[pallet_section]`](`pallet_section`). From 6ddb7624d66b299f04051f82cadcda062efa876a Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:02:43 +1100 Subject: [PATCH 29/57] move no_default docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 9 +++++---- substrate/frame/support/src/lib.rs | 13 +++++++++++-- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index e92814fea448..a14d8ecc8519 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -677,11 +677,12 @@ pub fn derive_impl(attrs: TokenStream, input: TokenStream) -> TokenStream { .into() } -/// The optional attribute `#[pallet::no_default]` can be attached to trait items within a -/// `Config` trait impl that has [`#[pallet::config(with_default)]`](`macro@config`) attached. +#[rustfmt::skip] /// -/// Attaching this attribute to a trait item ensures that that trait item will not be used as a -/// default with the [`#[derive_impl(..)]`](`macro@derive_impl`) attribute macro. +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::no_default`](../frame_support/pallet_macros/attr.no_default.html). #[proc_macro_attribute] pub fn no_default(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index c4e245c8275e..87d45f78603e 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,10 +1029,19 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - no_default, no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, + no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a + /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) + /// attached. + /// + /// Attaching this attribute to a trait item ensures that that trait item will not be used + /// as a default with the [`#[derive_impl(..)]`](`frame_support::derive_impl`) attribute + /// macro. + pub use frame_support_procedural::no_default; + /// The `#[pallet::inherent]` attribute allows the pallet to provide /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). /// An inherent is some piece of data that is inserted by a block authoring node at block @@ -1173,7 +1182,7 @@ pub mod pallet_macros { pub use frame_support_procedural::getter; /// DEPRECATED: Will be removed, do not use. - /// See https://github.com/paritytech/substrate/pull/13535 for more details. + /// See for more details. /// /// To generate a `Store` trait associating all storages, annotate your `Pallet` struct /// with the attribute `#[pallet::generate_store($vis trait Store)]`, e.g.: From b79a7f4ed32281df08cb0165768322406feb861b Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:04:26 +1100 Subject: [PATCH 30/57] move no_default_bounds docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 10 ++++------ substrate/frame/support/src/lib.rs | 12 ++++++++++++ 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index a14d8ecc8519..91fac7202eff 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -688,14 +688,12 @@ pub fn no_default(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items within a -/// `Config` trait impl that has [`#[pallet::config(with_default)]`](`macro@config`) attached. +#[rustfmt::skip] /// -/// Attaching this attribute to a trait item ensures that the generated trait `DefaultConfig` -/// will not have any bounds for this trait item. +/// --- /// -/// As an example, if you have a trait item `type AccountId: SomeTrait;` in your `Config` trait, -/// the generated `DefaultConfig` will only have `type AccountId;` with no trait bound. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::no_default_bounds`](../frame_support/pallet_macros/attr.no_default_bounds.html). #[proc_macro_attribute] pub fn no_default_bounds(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 87d45f78603e..4ba5274a4275 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1033,6 +1033,18 @@ pub mod pallet_macros { whitelist_storage, }; + /// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items + /// within a `Config` trait impl that has + /// [`#[pallet::config(with_default)]`](`frame_support::config`) attached. + /// + /// Attaching this attribute to a trait item ensures that the generated trait + /// `DefaultConfig` will not have any bounds for this trait item. + /// + /// As an example, if you have a trait item `type AccountId: SomeTrait;` in your `Config` + /// trait, the generated `DefaultConfig` will only have `type AccountId;` with no trait + /// bound. + pub use frame_support_procedural::no_default_bounds; + /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) /// attached. From 9eda61c65c20aa3b68538a08d6944f6c24826fec Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:26:21 +1100 Subject: [PATCH 31/57] move origin docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 18 ++------ substrate/frame/support/src/lib.rs | 44 +++++++++++++++++-- 2 files changed, 45 insertions(+), 17 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 91fac7202eff..882a67260c31 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1113,22 +1113,12 @@ pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. -/// -/// Item must be either a type alias, an enum, or a struct. It needs to be public. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::origin] -/// pub struct Origin(PhantomData<(T)>); -/// ``` +#[rustfmt::skip] /// -/// **WARNING**: modifying origin changes the outer runtime origin. This outer runtime origin -/// can be stored on-chain (e.g. in [`pallet_scheduler`](../pallet_scheduler/index.html)), -/// thus any change must be done with care as it might require some migration. +/// --- /// -/// NOTE: for instantiable pallets, the origin must be generic over `T` and `I`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::origin`](../frame_support/pallet_macros/attr.origin.html). #[proc_macro_attribute] pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 4ba5274a4275..218259b37c4b 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,13 +1029,51 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the pallet:: macros pub mod pallet_macros { pub use frame_support_procedural::{ - no_default_bounds, origin, pallet_section, storage_prefix, unbounded, weight, - whitelist_storage, + pallet_section, storage_prefix, unbounded, weight, whitelist_storage, }; + /// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. + /// + /// Item must be either a type alias, an enum, or a struct. It needs to be public. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[derive(PartialEq, Eq, Clone, MaxEncodedLen, Encode, Decode, TypeInfo, RuntimeDebug)] + /// #[pallet::origin] + /// pub enum Origin { + /// /// SomeOrigin doc. + /// SomeOrigin, + /// /// AnotherOrigin doc. + /// AnotherOrigin, + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// **WARNING**: modifying origin changes the outer runtime origin. This outer runtime + /// origin can be stored on-chain (e.g. in + /// [`pallet_scheduler`](../../pallet_scheduler/index.html), thus any change must be + /// done with care as it might require some migration. + /// + /// NOTE: for instantiable pallets, the origin must be generic over `T` and `I`. + /// + /// Read more about origins at the [Origin Reference + /// Docs](../../polkadot_sdk_docs/reference_docs/frame_origin/index.html). + pub use frame_support_procedural::origin; + /// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items /// within a `Config` trait impl that has - /// [`#[pallet::config(with_default)]`](`frame_support::config`) attached. + /// [`#[pallet::config(with_default)]`](`config`) attached. /// /// Attaching this attribute to a trait item ensures that the generated trait /// `DefaultConfig` will not have any bounds for this trait item. From 6123c84c5eef34e4a863e68882ed49291a0362ab Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:31:19 +1100 Subject: [PATCH 32/57] move pallet_section docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 21 +++----------- substrate/frame/support/src/lib.rs | 28 ++++++++++++++++--- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 882a67260c31..48c9f018422e 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1192,25 +1192,12 @@ pub fn task_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Can be attached to a module. Doing so will declare that module as importable into a pallet -/// via [`#[import_section]`](`macro@import_section`). -/// -/// Note that sections are imported by their module name/ident, and should be referred to by -/// their _full path_ from the perspective of the target pallet. Do not attempt to make use -/// of `use` statements to bring pallet sections into scope, as this will not work (unless -/// you do so as part of a wildcard import, in which case it will work). -/// -/// ## Naming Logistics +#[rustfmt::skip] /// -/// Also note that because of how `#[pallet_section]` works, pallet section names must be -/// globally unique _within the crate in which they are defined_. For more information on -/// why this must be the case, see macro_magic's -/// [`#[export_tokens]`](https://docs.rs/macro_magic/latest/macro_magic/attr.export_tokens.html) macro. +/// --- /// -/// Optionally, you may provide an argument to `#[pallet_section]` such as -/// `#[pallet_section(some_ident)]`, in the event that there is another pallet section in -/// same crate with the same ident/name. The ident you specify can then be used instead of -/// the module's ident name when you go to import it via `#[import_section]`. +/// **Rust-Analyzer users**: See the documentation of the Rust item in +/// [`frame_support::pallet_macros::pallet_section`](../frame_support/pallet_macros/attr.pallet_section.html). #[proc_macro_attribute] pub fn pallet_section(attr: TokenStream, tokens: TokenStream) -> TokenStream { let tokens_clone = tokens.clone(); diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 218259b37c4b..031f57768998 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1026,11 +1026,31 @@ pub mod pallet_prelude { /// reiterating the documentation on the pallet module itself. pub use frame_support_procedural::pallet; -/// Contains macro stubs for all of the pallet:: macros +/// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - pub use frame_support_procedural::{ - pallet_section, storage_prefix, unbounded, weight, whitelist_storage, - }; + pub use frame_support_procedural::{storage_prefix, unbounded, weight, whitelist_storage}; + + /// Can be attached to a module. Doing so will declare that module as importable into a + /// pallet via [`#[import_section]`](`import_section`). + /// + /// Note that sections are imported by their module name/ident, and should be referred to + /// by their _full path_ from the perspective of the target pallet. Do not attempt to make + /// use of `use` statements to bring pallet sections into scope, as this will not work + /// (unless you do so as part of a wildcard import, in which case it will work). + /// + /// ## Naming Logistics + /// + /// Also note that because of how `#[pallet_section]` works, pallet section names must be + /// globally unique _within the crate in which they are defined_. For more information on + /// why this must be the case, see macro_magic's + /// [`#[export_tokens]`](https://docs.rs/macro_magic/latest/macro_magic/attr.export_tokens.html) macro. + /// + /// Optionally, you may provide an argument to `#[pallet_section]` such as + /// `#[pallet_section(some_ident)]`, in the event that there is another pallet section in + /// same crate with the same ident/name. The ident you specify can then be used instead of + /// the module's ident name when you go to import it via + /// [`#[import_section]`](`import_section`). + pub use frame_support_procedural::pallet_section; /// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. /// From 4ff3cbd09f3e836b0d58459fcd95e97065bc5c1b Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:34:32 +1100 Subject: [PATCH 33/57] move storage_prefix docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 22 +++------------ substrate/frame/support/src/lib.rs | 27 ++++++++++++++++++- 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 48c9f018422e..cfe14b11c5c0 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1001,26 +1001,12 @@ pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define the -/// storage prefix to use. This is helpful if you wish to rename the storage field but don't -/// want to perform a migration. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::storage_prefix = "foo"] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap; -/// ``` +#[rustfmt::skip] /// -/// or +/// --- /// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap<_, Blake2_128Concat, u32, u32>; -/// ``` +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// [`frame_support::pallet_macros::storage_prefix`](../frame_support/pallet_macros/attr.storage_prefix.html). #[proc_macro_attribute] pub fn storage_prefix(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 031f57768998..46df2e530e81 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1028,7 +1028,32 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - pub use frame_support_procedural::{storage_prefix, unbounded, weight, whitelist_storage}; + pub use frame_support_procedural::{unbounded, weight, whitelist_storage}; + + /// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define + /// what storage prefix to use for a storage item when building the trie. This is helpful + /// if you wish to rename the storage field but don't want to perform a migration. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::storage_prefix = "foo"] + /// #[pallet::getter(fn my_getter_fn_name)] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::storage_prefix; /// Can be attached to a module. Doing so will declare that module as importable into a /// pallet via [`#[import_section]`](`import_section`). From 3dbddc1066116b815c07cd0b05198fdb4844d568 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:37:16 +1100 Subject: [PATCH 34/57] move unbounded docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 9 +++--- substrate/frame/support/src/lib.rs | 29 +++++++++++++++++-- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index cfe14b11c5c0..3ef665207acb 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1012,10 +1012,11 @@ pub fn storage_prefix(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::unbounded]` declares the storage as unbounded. When -/// implementating the storage info (when `#[pallet::generate_storage_info]` is specified on -/// the pallet struct placeholder), the size of the storage will be declared as unbounded. This -/// can be useful for storage which can never go into PoV (Proof of Validity). +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::unbounded`. #[proc_macro_attribute] pub fn unbounded(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 46df2e530e81..2f5c4a1e463a 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1028,7 +1028,33 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - pub use frame_support_procedural::{unbounded, weight, whitelist_storage}; + pub use frame_support_procedural::{weight, whitelist_storage}; + + /// The optional attribute `#[pallet::unbounded]` declares a storage item as unbounded. + /// When implementating the storage info (when `#[pallet::generate_storage_info]` is + /// specified on the pallet struct placeholder), the size of the storage will be declared + /// as unbounded. This can be useful for storage which can never go into PoV (Proof of + /// Validity). + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::unbounded] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::unbounded; /// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define /// what storage prefix to use for a storage item when building the trie. This is helpful @@ -1046,7 +1072,6 @@ pub mod pallet_macros { /// /// #[pallet::storage] /// #[pallet::storage_prefix = "foo"] - /// #[pallet::getter(fn my_getter_fn_name)] /// pub type MyStorage = StorageValue<_, u32>; /// /// #[pallet::config] From d064bae1f8375dc4a578079615dae1ddcd7a73f7 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Tue, 27 Feb 2024 20:48:35 +1100 Subject: [PATCH 35/57] move pallet::weight docs to frame_support --- substrate/frame/support/procedural/src/lib.rs | 7 ++-- substrate/frame/support/src/lib.rs | 34 ++++++++++++++++++- 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 3ef665207acb..97ad8e927d96 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -885,8 +885,11 @@ pub fn hooks(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// Each dispatchable needs to define a weight with `#[pallet::weight($expr)]` attribute, the -/// first argument must be `origin: OriginFor`. +/// +/// --- +/// +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::weight`. #[proc_macro_attribute] pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 2f5c4a1e463a..ff7b33fe62f1 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1028,7 +1028,39 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - pub use frame_support_procedural::{weight, whitelist_storage}; + pub use frame_support_procedural::whitelist_storage; + + /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` + /// attribute. The first argument must be `origin: OriginFor`. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::call] + /// impl Pallet { + /// #[pallet::weight({0})] // <- set actual weight here + /// #[pallet::call_index(0)] + /// pub fn something( + /// _: OriginFor, + /// foo: u32, + /// ) -> DispatchResult { + /// unimplemented!() + /// } + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::weight; /// The optional attribute `#[pallet::unbounded]` declares a storage item as unbounded. /// When implementating the storage info (when `#[pallet::generate_storage_info]` is From b5b7dfbe72042393c34b4c609c93eee156c46e37 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 10:57:50 +1100 Subject: [PATCH 36/57] move pallet::whitelist_storage to frame_support --- substrate/frame/support/procedural/src/lib.rs | 19 ++---------- substrate/frame/support/src/lib.rs | 30 +++++++++++++++++++ 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 97ad8e927d96..f39a1ae16563 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1025,24 +1025,11 @@ pub fn unbounded(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::whitelist_storage]` will declare the -/// storage as whitelisted from benchmarking. Doing so will exclude reads of -/// that value's storage key from counting towards weight calculations during -/// benchmarking. /// -/// This attribute should only be attached to storages that are known to be -/// read/used in every block. This will result in a more accurate benchmarking weight. -/// -/// ### Example -/// ```ignore -/// #[pallet::storage] -/// #[pallet::whitelist_storage] -/// pub(super) type Number = StorageValue<_, frame_system::pallet_prelude::BlockNumberFor::, ValueQuery>; -/// ``` +/// --- /// -/// NOTE: As with all `pallet::*` attributes, this one _must_ be written as -/// `#[pallet::whitelist_storage]` and can only be placed inside a `pallet` module in order for -/// it to work properly. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::whitelist_storage`. #[proc_macro_attribute] pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index ff7b33fe62f1..c20ac2da4d54 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1028,6 +1028,36 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { + + /// The optional attribute `#[pallet::whitelist_storage]` will declare the + /// storage as whitelisted from benchmarking. Doing so will exclude reads of + /// that value's storage key from counting towards weight calculations during + /// benchmarking. + /// + /// This attribute should only be attached to storages that are known to be + /// read/used in every block. This will result in a more accurate benchmarking weight. + /// + /// ### Example + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::whitelist_storage] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// NOTE: As with all `pallet::*` attributes, this one _must_ be written as + /// `#[pallet::whitelist_storage]` and can only be placed inside a `pallet` module in order + /// for it to work properly. pub use frame_support_procedural::whitelist_storage; /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` From 21011667e01e77f38eb47f7e83370a11006f0bcf Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:06:55 +1100 Subject: [PATCH 37/57] remove links from proc macro comments --- substrate/frame/support/procedural/src/lib.rs | 42 +++++++++---------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index f39a1ae16563..dd3b8492c518 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -191,7 +191,7 @@ pub fn construct_runtime(input: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet`](../frame_support/attr.pallet.html). +/// `frame_support::pallet`. #[proc_macro_attribute] pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream { pallet::pallet(attr, item) @@ -299,7 +299,7 @@ pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStre /// Derive [`Clone`] but do not bound any generic. /// -/// Docs at [`frame_support::CloneNoBound`](../frame_support/derive.CloneNoBound.html). +/// Docs at `frame_support::CloneNoBound`. #[proc_macro_derive(CloneNoBound)] pub fn derive_clone_no_bound(input: TokenStream) -> TokenStream { no_bound::clone::derive_clone_no_bound(input) @@ -307,7 +307,7 @@ pub fn derive_clone_no_bound(input: TokenStream) -> TokenStream { /// Derive [`Debug`] but do not bound any generics. /// -/// Docs at [`frame_support::DebugNoBound`](../frame_support/derive.DebugNoBound.html). +/// Docs at `frame_support::DebugNoBound`. #[proc_macro_derive(DebugNoBound)] pub fn derive_debug_no_bound(input: TokenStream) -> TokenStream { no_bound::debug::derive_debug_no_bound(input) @@ -344,7 +344,7 @@ pub fn derive_runtime_debug_no_bound(input: TokenStream) -> TokenStream { /// Derive [`PartialEq`] but do not bound any generic. /// -/// Docs at [`frame_support::PartialEqNoBound`](../frame_support/derive.PartialEqNoBound.html). +/// Docs at `frame_support::PartialEqNoBound`. #[proc_macro_derive(PartialEqNoBound)] pub fn derive_partial_eq_no_bound(input: TokenStream) -> TokenStream { no_bound::partial_eq::derive_partial_eq_no_bound(input) @@ -352,7 +352,7 @@ pub fn derive_partial_eq_no_bound(input: TokenStream) -> TokenStream { /// DeriveEq but do no bound any generic. /// -/// Docs at [`frame_support::EqNoBound`](../frame_support/derive.EqNoBound.html). +/// Docs at `frame_support::EqNoBound`. #[proc_macro_derive(EqNoBound)] pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { let input: syn::DeriveInput = match syn::parse(input) { @@ -373,7 +373,7 @@ pub fn derive_eq_no_bound(input: TokenStream) -> TokenStream { /// derive `Default` but do no bound any generic. Docs are at `frame_support::DefaultNoBound`. /// -/// Docs at [`frame_support::DefaultNoBound`](../frame_support/derive.PartialEqNoBound.html). +/// Docs at `frame_support::DefaultNoBound`. #[proc_macro_derive(DefaultNoBound, attributes(default))] pub fn derive_default_no_bound(input: TokenStream) -> TokenStream { no_bound::default::derive_default_no_bound(input) @@ -998,7 +998,7 @@ pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::getter`](../frame_support/pallet_macros/attr.getter.html). +/// `frame_support::pallet_macros::getter`. #[proc_macro_attribute] pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1009,7 +1009,7 @@ pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::storage_prefix`](../frame_support/pallet_macros/attr.storage_prefix.html). +/// `frame_support::pallet_macros::storage_prefix`. #[proc_macro_attribute] pub fn storage_prefix(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1040,7 +1040,7 @@ pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::type_value`](../frame_support/pallet_macros/attr.type_value.html). +/// `frame_support::pallet_macros::type_value`. #[proc_macro_attribute] pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1051,7 +1051,7 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_config`](../frame_support/pallet_macros/attr.genesis_config.html). +/// `frame_support::pallet_macros::genesis_config`. #[proc_macro_attribute] pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1062,7 +1062,7 @@ pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::genesis_build`](../frame_support/pallet_macros/attr.genesis_build.html). +/// `frame_support::pallet_macros::genesis_build`. #[proc_macro_attribute] pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1073,7 +1073,7 @@ pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::inherent`](../frame_support/pallet_macros/attr.inherent.html). +/// `frame_support::pallet_macros::inherent`. #[proc_macro_attribute] pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1084,7 +1084,7 @@ pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::validate_unsigned`](../frame_support/pallet_macros/attr.validate_unsigned.html). +/// `frame_support::pallet_macros::validate_unsigned`. #[proc_macro_attribute] pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1095,7 +1095,7 @@ pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::origin`](../frame_support/pallet_macros/attr.origin.html). +/// `frame_support::pallet_macros::origin`. #[proc_macro_attribute] pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1106,7 +1106,7 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::composite_enum`](../frame_support/pallet_macros/attr.composite_enum.html). +/// `frame_support::pallet_macros::composite_enum`. #[proc_macro_attribute] pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1117,7 +1117,7 @@ pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::tasks_experimental`](../frame_support/pallet_macros/attr.tasks_experimental.html). +/// `frame_support::pallet_macros::tasks_experimental`. #[proc_macro_attribute] pub fn tasks_experimental(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1128,7 +1128,7 @@ pub fn tasks_experimental(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::task_list`](../frame_support/pallet_macros/attr.task_list.html). +/// `frame_support::pallet_macros::task_list`. #[proc_macro_attribute] pub fn task_list(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1140,7 +1140,6 @@ pub fn task_list(_: TokenStream, _: TokenStream) -> TokenStream { /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::task_condition`. -/// [`frame_support::pallet_macros::task_condition`](../frame_support/pallet_macros/attr.task_condition.html). #[proc_macro_attribute] pub fn task_condition(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1152,7 +1151,6 @@ pub fn task_condition(_: TokenStream, _: TokenStream) -> TokenStream { /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::task_weight`. -/// [`frame_support::pallet_macros::task_weight`](../frame_support/pallet_macros/attr.task_weight.html). #[proc_macro_attribute] pub fn task_weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1163,7 +1161,7 @@ pub fn task_weight(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::task_index`](../frame_support/pallet_macros/attr.task_index.html). +/// `frame_support::pallet_macros::task_index`. #[proc_macro_attribute] pub fn task_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -1174,7 +1172,7 @@ pub fn task_index(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in -/// [`frame_support::pallet_macros::pallet_section`](../frame_support/pallet_macros/attr.pallet_section.html). +/// `frame_support::pallet_macros::pallet_section`. #[proc_macro_attribute] pub fn pallet_section(attr: TokenStream, tokens: TokenStream) -> TokenStream { let tokens_clone = tokens.clone(); @@ -1194,7 +1192,7 @@ pub fn pallet_section(attr: TokenStream, tokens: TokenStream) -> TokenStream { /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::import_section`. -/// [`frame_support::pallet_macros::import_section`](../frame_support/pallet_macros/attr.import_section.html). +/// `frame_support::pallet_macros::import_section`. #[import_tokens_attr { format!( "{}::macro_magic", From 6cb90e0e86ef1db43308fcb78636243994e556be Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:10:05 +1100 Subject: [PATCH 38/57] finish removing links --- substrate/frame/support/procedural/src/lib.rs | 69 +++++-------------- 1 file changed, 19 insertions(+), 50 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index dd3b8492c518..0bce42f23ce0 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -186,7 +186,6 @@ pub fn construct_runtime(input: TokenStream) -> TokenStream { construct_runtime::construct_runtime(input) } -#[rustfmt::skip] /// /// --- /// @@ -200,7 +199,7 @@ pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as a benchmarking module. /// -/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. +/// See `frame_benchmarking::v2`. #[proc_macro_attribute] pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, false) { @@ -212,7 +211,7 @@ pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as an instance benchmarking module. /// -/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. +/// See `frame_benchmarking::v2`. #[proc_macro_attribute] pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, true) { @@ -225,7 +224,7 @@ pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStrea /// attached to a function definition containing an `#[extrinsic_call]` or `#[block]` /// attribute. /// -/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. +/// See `frame_benchmarking::v2`. #[proc_macro_attribute] pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -238,7 +237,7 @@ pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { /// used as a boundary designating where the benchmark setup code ends, and the benchmark /// verification code begins. /// -/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. +/// See `frame_benchmarking::v2`. #[proc_macro_attribute] pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -251,7 +250,7 @@ pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream /// enclosing benchmark function, This attribute is also used as a boundary designating where /// the benchmark setup code ends, and the benchmark verification code begins. /// -/// See [`frame_benchmarking::v2`](../../frame_benchmarking/v2/index.html) for more info. +/// See `frame_benchmarking::v2`. #[proc_macro_attribute] pub fn block(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -285,12 +284,11 @@ pub fn transactional(attr: TokenStream, input: TokenStream) -> TokenStream { transactional::transactional(attr, input).unwrap_or_else(|e| e.to_compile_error().into()) } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::require_transactional`](../frame_support/attr.require_transactional.html). +/// `frame_support::require_transactional`. #[proc_macro_attribute] pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStream { transactional::require_transactional(attr, input) @@ -441,12 +439,11 @@ pub fn __create_tt_macro(input: TokenStream) -> TokenStream { tt_macro::create_tt_return_macro(input) } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::storage_alias`](../frame_support/attr.storage_alias.html). +/// `frame_support::storage_alias`. #[proc_macro_attribute] pub fn storage_alias(attributes: TokenStream, input: TokenStream) -> TokenStream { storage_alias::storage_alias(attributes.into(), input.into()) @@ -677,23 +674,21 @@ pub fn derive_impl(attrs: TokenStream, input: TokenStream) -> TokenStream { .into() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::no_default`](../frame_support/pallet_macros/attr.no_default.html). +/// `frame_support::pallet_macros::no_default`. #[proc_macro_attribute] pub fn no_default(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::no_default_bounds`](../frame_support/pallet_macros/attr.no_default_bounds.html). +/// `frame_support::pallet_macros::no_default_bounds`. #[proc_macro_attribute] pub fn no_default_bounds(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -773,12 +768,11 @@ pub fn register_default_impl(attrs: TokenStream, tokens: TokenStream) -> TokenSt } } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_prelude::inject_runtime_type`](../frame_support/pallet_prelude/attr.inject_runtime_type.html). +/// `frame_support::pallet_prelude::inject_runtime_type`. #[proc_macro_attribute] pub fn inject_runtime_type(_: TokenStream, tokens: TokenStream) -> TokenStream { let item = tokens.clone(); @@ -825,51 +819,47 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::constant`](../frame_support/pallet_macros/attr.constant.html). +/// `frame_support::pallet_macros::constant`. #[proc_macro_attribute] pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::constant_name`](../frame_support/pallet_macros/attr.constant_name.html). +/// `frame_support::pallet_macros::constant_name`. #[proc_macro_attribute] pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::disable_frame_system_supertrait_check`](../frame_support/pallet_macros/attr.disable_frame_system_supertrait_check.html). +/// `frame_support::pallet_macros::disable_frame_system_supertrait_check`. #[proc_macro_attribute] pub fn disable_frame_system_supertrait_check(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::generate_store`](../frame_support/pallet_macros/attr.generate_store.html). +/// `frame_support::pallet_macros::generate_store`. #[proc_macro_attribute] pub fn generate_store(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::storage_version`](../frame_support/pallet_macros/attr.storage_version.html). +/// `frame_support::pallet_macros::storage_version`. #[proc_macro_attribute] pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -915,38 +905,35 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// Each dispatchable may also be annotated with the `#[pallet::call_index($idx)]` attribute, /// which explicitly defines the codec index for the dispatchable function in the `Call` enum. /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::call_index`](../frame_support/pallet_macros/attr.call_index.html). +/// `frame_support::pallet_macros::call_index`. #[proc_macro_attribute] pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at /// -/// [`frame_support::pallet_macros::feeless_if`](../frame_support/pallet_macros/attr.feeless_if.html). +/// `frame_support::pallet_macros::feeless_if`. #[proc_macro_attribute] pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at /// -/// [`frame_support::pallet_macros::extra_constants`](../frame_support/pallet_macros/attr.extra_constants.html). +/// `frame_support::pallet_macros::extra_constants`. #[proc_macro_attribute] pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -972,12 +959,11 @@ pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::generate_deposit`](../frame_support/pallet_macros/attr.generate_deposit.html). +/// `frame_support::pallet_macros::generate_deposit`. #[proc_macro_attribute] pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -993,7 +979,6 @@ pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1004,7 +989,6 @@ pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1035,7 +1019,6 @@ pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1046,7 +1029,6 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1057,7 +1039,6 @@ pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1068,7 +1049,6 @@ pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1079,7 +1059,6 @@ pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1090,7 +1069,6 @@ pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1101,7 +1079,6 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1112,7 +1089,6 @@ pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1123,7 +1099,6 @@ pub fn tasks_experimental(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1134,7 +1109,6 @@ pub fn task_list(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1145,7 +1119,6 @@ pub fn task_condition(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1156,7 +1129,6 @@ pub fn task_weight(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1167,7 +1139,6 @@ pub fn task_index(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -#[rustfmt::skip] /// /// --- /// @@ -1186,13 +1157,11 @@ pub fn pallet_section(attr: TokenStream, tokens: TokenStream) -> TokenStream { } } -#[rustfmt::skip] /// /// --- /// /// **Rust-Analyzer users**: See the documentation of the Rust item in /// `frame_support::pallet_macros::import_section`. -/// `frame_support::pallet_macros::import_section`. #[import_tokens_attr { format!( "{}::macro_magic", From e2bb8b27edb278d0007a31d4a46084c593303c14 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:11:35 +1100 Subject: [PATCH 39/57] fix comment --- substrate/frame/support/procedural/src/lib.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 0bce42f23ce0..940c18d19e05 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -199,7 +199,7 @@ pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as a benchmarking module. /// -/// See `frame_benchmarking::v2`. +/// See `frame_benchmarking::v2` for more info. #[proc_macro_attribute] pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, false) { @@ -211,7 +211,7 @@ pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { /// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will /// designate that module as an instance benchmarking module. /// -/// See `frame_benchmarking::v2`. +/// See `frame_benchmarking::v2` for more info. #[proc_macro_attribute] pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream { match benchmark::benchmarks(attr, tokens, true) { @@ -224,7 +224,7 @@ pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStrea /// attached to a function definition containing an `#[extrinsic_call]` or `#[block]` /// attribute. /// -/// See `frame_benchmarking::v2`. +/// See `frame_benchmarking::v2` for more info. #[proc_macro_attribute] pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -237,7 +237,7 @@ pub fn benchmark(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { /// used as a boundary designating where the benchmark setup code ends, and the benchmark /// verification code begins. /// -/// See `frame_benchmarking::v2`. +/// See `frame_benchmarking::v2` for more info. #[proc_macro_attribute] pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( @@ -250,7 +250,7 @@ pub fn extrinsic_call(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream /// enclosing benchmark function, This attribute is also used as a boundary designating where /// the benchmark setup code ends, and the benchmark verification code begins. /// -/// See `frame_benchmarking::v2`. +/// See `frame_benchmarking::v2` for more info. #[proc_macro_attribute] pub fn block(_attrs: TokenStream, _tokens: TokenStream) -> TokenStream { quote!(compile_error!( From 6b4362f0aae28a6047fc0daf7b5577acd46e9543 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:13:36 +1100 Subject: [PATCH 40/57] fix comment --- substrate/frame/support/procedural/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 940c18d19e05..55e581d0ee39 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -809,7 +809,7 @@ fn pallet_macro_stub() -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::config`](../frame_support/pallet_macros/attr.config.html). +/// `frame_support::pallet_macros::config`. #[proc_macro_attribute] pub fn config(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() From c3b0f8640ed7600a2fb56b022333044d2babfa93 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:15:15 +1100 Subject: [PATCH 41/57] remove links --- substrate/frame/support/procedural/src/lib.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 55e581d0ee39..7507e051c906 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -869,7 +869,7 @@ pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::hooks`](../frame_support/pallet_macros/attr.hooks.html). +/// `frame_support::pallet_macros::hooks`. #[proc_macro_attribute] pub fn hooks(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -889,7 +889,7 @@ pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::compact`](../frame_support/pallet_macros/attr.compact.html). +/// `frame_support::pallet_macros::compact`. #[proc_macro_attribute] pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -899,7 +899,7 @@ pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::call`](../frame_support/pallet_macros/attr.call.html). +/// `frame_support::pallet_macros::call`. #[proc_macro_attribute] pub fn call(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -943,7 +943,7 @@ pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::error`](../frame_support/pallet_macros/attr.error.html). +/// `frame_support::pallet_macros::error`. #[proc_macro_attribute] pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -953,7 +953,7 @@ pub fn error(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::event`](../frame_support/pallet_macros/attr.event.html). +/// `frame_support::pallet_macros::event`. #[proc_macro_attribute] pub fn event(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() @@ -973,7 +973,7 @@ pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream { /// --- /// /// Rust-Analyzer Users: Documentation for this macro can be found at -/// [`frame_support::pallet_macros::storage`](../frame_support/pallet_macros/attr.storage.html). +/// `frame_support::pallet_macros::storage`. #[proc_macro_attribute] pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() From 85a3984f8958cd300da00c0ac371356c52cbbea0 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Wed, 28 Feb 2024 11:20:06 +1100 Subject: [PATCH 42/57] fix --- substrate/frame/support/src/lib.rs | 312 ++++++++++++++--------------- 1 file changed, 156 insertions(+), 156 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index c20ac2da4d54..9d7325a009d6 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1029,141 +1029,6 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - /// The optional attribute `#[pallet::whitelist_storage]` will declare the - /// storage as whitelisted from benchmarking. Doing so will exclude reads of - /// that value's storage key from counting towards weight calculations during - /// benchmarking. - /// - /// This attribute should only be attached to storages that are known to be - /// read/used in every block. This will result in a more accurate benchmarking weight. - /// - /// ### Example - /// ``` - /// #[frame_support::pallet] - /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// - /// #[pallet::pallet] - /// pub struct Pallet(_); - /// - /// #[pallet::storage] - /// #[pallet::whitelist_storage] - /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} - /// } - /// ``` - /// - /// NOTE: As with all `pallet::*` attributes, this one _must_ be written as - /// `#[pallet::whitelist_storage]` and can only be placed inside a `pallet` module in order - /// for it to work properly. - pub use frame_support_procedural::whitelist_storage; - - /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` - /// attribute. The first argument must be `origin: OriginFor`. - /// - /// ## Example - /// - /// ``` - /// #[frame_support::pallet] - /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; - /// - /// #[pallet::pallet] - /// pub struct Pallet(_); - /// - /// #[pallet::call] - /// impl Pallet { - /// #[pallet::weight({0})] // <- set actual weight here - /// #[pallet::call_index(0)] - /// pub fn something( - /// _: OriginFor, - /// foo: u32, - /// ) -> DispatchResult { - /// unimplemented!() - /// } - /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} - /// } - /// ``` - pub use frame_support_procedural::weight; - - /// The optional attribute `#[pallet::unbounded]` declares a storage item as unbounded. - /// When implementating the storage info (when `#[pallet::generate_storage_info]` is - /// specified on the pallet struct placeholder), the size of the storage will be declared - /// as unbounded. This can be useful for storage which can never go into PoV (Proof of - /// Validity). - /// - /// ## Example - /// - /// ``` - /// #[frame_support::pallet] - /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// - /// #[pallet::pallet] - /// pub struct Pallet(_); - /// - /// #[pallet::storage] - /// #[pallet::unbounded] - /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} - /// } - /// ``` - pub use frame_support_procedural::unbounded; - - /// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define - /// what storage prefix to use for a storage item when building the trie. This is helpful - /// if you wish to rename the storage field but don't want to perform a migration. - /// - /// ## Example - /// - /// ``` - /// #[frame_support::pallet] - /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// - /// #[pallet::pallet] - /// pub struct Pallet(_); - /// - /// #[pallet::storage] - /// #[pallet::storage_prefix = "foo"] - /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} - /// } - /// ``` - pub use frame_support_procedural::storage_prefix; - - /// Can be attached to a module. Doing so will declare that module as importable into a - /// pallet via [`#[import_section]`](`import_section`). - /// - /// Note that sections are imported by their module name/ident, and should be referred to - /// by their _full path_ from the perspective of the target pallet. Do not attempt to make - /// use of `use` statements to bring pallet sections into scope, as this will not work - /// (unless you do so as part of a wildcard import, in which case it will work). - /// - /// ## Naming Logistics - /// - /// Also note that because of how `#[pallet_section]` works, pallet section names must be - /// globally unique _within the crate in which they are defined_. For more information on - /// why this must be the case, see macro_magic's - /// [`#[export_tokens]`](https://docs.rs/macro_magic/latest/macro_magic/attr.export_tokens.html) macro. - /// - /// Optionally, you may provide an argument to `#[pallet_section]` such as - /// `#[pallet_section(some_ident)]`, in the event that there is another pallet section in - /// same crate with the same ident/name. The ident you specify can then be used instead of - /// the module's ident name when you go to import it via - /// [`#[import_section]`](`import_section`). - pub use frame_support_procedural::pallet_section; - /// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. /// /// Item must be either a type alias, an enum, or a struct. It needs to be public. @@ -1203,27 +1068,6 @@ pub mod pallet_macros { /// Docs](../../polkadot_sdk_docs/reference_docs/frame_origin/index.html). pub use frame_support_procedural::origin; - /// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items - /// within a `Config` trait impl that has - /// [`#[pallet::config(with_default)]`](`config`) attached. - /// - /// Attaching this attribute to a trait item ensures that the generated trait - /// `DefaultConfig` will not have any bounds for this trait item. - /// - /// As an example, if you have a trait item `type AccountId: SomeTrait;` in your `Config` - /// trait, the generated `DefaultConfig` will only have `type AccountId;` with no trait - /// bound. - pub use frame_support_procedural::no_default_bounds; - - /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a - /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) - /// attached. - /// - /// Attaching this attribute to a trait item ensures that that trait item will not be used - /// as a default with the [`#[derive_impl(..)]`](`frame_support::derive_impl`) attribute - /// macro. - pub use frame_support_procedural::no_default; - /// The `#[pallet::inherent]` attribute allows the pallet to provide /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). /// An inherent is some piece of data that is inserted by a block authoring node at block @@ -2410,6 +2254,162 @@ pub mod pallet_macros { /// Now, this can be executed as follows: #[doc = docify::embed!("src/tests/tasks.rs", tasks_work)] pub use frame_support_procedural::tasks_experimental; + + /// The optional attribute `#[pallet::whitelist_storage]` will declare the + /// storage as whitelisted from benchmarking. Doing so will exclude reads of + /// that value's storage key from counting towards weight calculations during + /// benchmarking. + /// + /// This attribute should only be attached to storages that are known to be + /// read/used in every block. This will result in a more accurate benchmarking weight. + /// + /// ### Example + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::whitelist_storage] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + /// + /// NOTE: As with all `pallet::*` attributes, this one _must_ be written as + /// `#[pallet::whitelist_storage]` and can only be placed inside a `pallet` module in order + /// for it to work properly. + pub use frame_support_procedural::whitelist_storage; + + /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` + /// attribute. The first argument must be `origin: OriginFor`. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::call] + /// impl Pallet { + /// #[pallet::weight({0})] // <- set actual weight here + /// #[pallet::call_index(0)] + /// pub fn something( + /// _: OriginFor, + /// foo: u32, + /// ) -> DispatchResult { + /// unimplemented!() + /// } + /// } + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::weight; + + /// The optional attribute `#[pallet::unbounded]` declares a storage item as unbounded. + /// When implementating the storage info (when `#[pallet::generate_storage_info]` is + /// specified on the pallet struct placeholder), the size of the storage will be declared + /// as unbounded. This can be useful for storage which can never go into PoV (Proof of + /// Validity). + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::unbounded] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::unbounded; + + /// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define + /// what storage prefix to use for a storage item when building the trie. This is helpful + /// if you wish to rename the storage field but don't want to perform a migration. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// use frame_support::pallet_prelude::*; + /// + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::storage_prefix = "foo"] + /// pub type MyStorage = StorageValue<_, u32>; + /// + /// #[pallet::config] + /// pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::storage_prefix; + + /// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items + /// within a `Config` trait impl that has + /// [`#[pallet::config(with_default)]`](`config`) attached. + /// + /// Attaching this attribute to a trait item ensures that the generated trait + /// `DefaultConfig` will not have any bounds for this trait item. + /// + /// As an example, if you have a trait item `type AccountId: SomeTrait;` in your `Config` + /// trait, the generated `DefaultConfig` will only have `type AccountId;` with no trait + /// bound. + pub use frame_support_procedural::no_default_bounds; + + /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a + /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) + /// attached. + /// + /// Attaching this attribute to a trait item ensures that that trait item will not be used + /// as a default with the [`#[derive_impl(..)]`](`frame_support::derive_impl`) attribute + /// macro. + pub use frame_support_procedural::no_default; + + /// Can be attached to a module. Doing so will declare that module as importable into a + /// pallet via [`#[import_section]`](`import_section`). + /// + /// Note that sections are imported by their module name/ident, and should be referred to + /// by their _full path_ from the perspective of the target pallet. Do not attempt to make + /// use of `use` statements to bring pallet sections into scope, as this will not work + /// (unless you do so as part of a wildcard import, in which case it will work). + /// + /// ## Naming Logistics + /// + /// Also note that because of how `#[pallet_section]` works, pallet section names must be + /// globally unique _within the crate in which they are defined_. For more information on + /// why this must be the case, see macro_magic's + /// [`#[export_tokens]`](https://docs.rs/macro_magic/latest/macro_magic/attr.export_tokens.html) macro. + /// + /// Optionally, you may provide an argument to `#[pallet_section]` such as + /// `#[pallet_section(some_ident)]`, in the event that there is another pallet section in + /// same crate with the same ident/name. The ident you specify can then be used instead of + /// the module's ident name when you go to import it via + /// [`#[import_section]`](`import_section`). + pub use frame_support_procedural::pallet_section; } #[deprecated(note = "Will be removed after July 2023; Use `sp_runtime::traits` directly instead.")] From 0921fa6b6c621cdea2547da13aeebd43f65d01da Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 11:01:03 +1100 Subject: [PATCH 43/57] Update substrate/frame/support/src/lib.rs Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com> --- substrate/frame/support/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 9d7325a009d6..a7f89124ccbf 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1274,7 +1274,7 @@ pub mod pallet_macros { /// /// #[pallet::config] /// #[pallet::disable_frame_system_supertrait_check] - /// pub trait Config: frame_system::Config {} + /// pub trait Config: OtherTrait {} /// } /// ``` /// From 8d39b1ad8a9cb5e40495e987d85f2b1161d91c8d Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 11:02:04 +1100 Subject: [PATCH 44/57] Update substrate/frame/support/src/lib.rs Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com> --- substrate/frame/support/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index a7f89124ccbf..3ccee6ee6500 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1534,7 +1534,7 @@ pub mod pallet_macros { /// If not present, the current storage version is set to the default value. pub use frame_support_procedural::storage_version; - /// The `#[pallet::hooks]` attribute allows you to specify a `Hooks` implementation for + /// The `#[pallet::hooks]` attribute allows you to specify a [`frame_support::traits::Hooks`] implementation for /// `Pallet` that specifies pallet-specific logic. /// /// The item the attribute attaches to must be defined as follows: From 372006227b5e7f1b41ab9966ea021b9b854c60ef Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 16:17:41 +1100 Subject: [PATCH 45/57] address comments --- substrate/frame/support/src/lib.rs | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 9d7325a009d6..1243b7a0c173 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1223,9 +1223,6 @@ pub mod pallet_macros { /// /// Thus when defining a storage named `Foo`, it can later be accessed from `Pallet` using /// `::Foo`. - /// - /// NOTE: this attribute is only valid when applied _directly_ to your `Pallet` struct - /// definition. pub use frame_support_procedural::generate_store; /// Allows you to define some extra constants to be added into constant metadata. @@ -1462,8 +1459,8 @@ pub mod pallet_macros { /// [`ValidateUnsigned`](frame_support::pallet_prelude::ValidateUnsigned) for /// type `Pallet`, and some optional where clause. /// - /// NOTE: There is also the `sp_runtime::traits::SignedExtension` trait that can be used to - /// add some specific logic for transaction validation. + /// NOTE: There is also the [`sp_runtime::traits::SignedExtension`] trait that can be used + /// to add some specific logic for transaction validation. /// /// ## Macro expansion /// @@ -2280,10 +2277,6 @@ pub mod pallet_macros { /// pub trait Config: frame_system::Config {} /// } /// ``` - /// - /// NOTE: As with all `pallet::*` attributes, this one _must_ be written as - /// `#[pallet::whitelist_storage]` and can only be placed inside a `pallet` module in order - /// for it to work properly. pub use frame_support_procedural::whitelist_storage; /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` From b4eb09f7bb7cacd4677fbb2343bfaa4b9ee8f07e Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 17:20:53 +1100 Subject: [PATCH 46/57] improve doc summary paras and make doctests more concise --- substrate/frame/support/src/lib.rs | 343 ++++++++++++++++------------- 1 file changed, 191 insertions(+), 152 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 1a7c0543cfd8..ba22e952374e 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1038,8 +1038,8 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1051,9 +1051,9 @@ pub mod pallet_macros { /// /// AnotherOrigin doc. /// AnotherOrigin, /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1070,6 +1070,7 @@ pub mod pallet_macros { /// The `#[pallet::inherent]` attribute allows the pallet to provide /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). + /// /// An inherent is some piece of data that is inserted by a block authoring node at block /// creation time and can either be accepted or rejected by validators based on whether the /// data falls within an acceptable range. @@ -1083,11 +1084,11 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_support::inherent::IsFatalError; - /// use sp_timestamp::InherentError; - /// use sp_std::result; - /// + /// # use frame_support::pallet_prelude::*; + /// # use frame_support::inherent::IsFatalError; + /// # use sp_timestamp::InherentError; + /// # use sp_std::result; + /// # /// // Example inherent identifier /// pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"timstap0"; /// @@ -1115,9 +1116,9 @@ pub mod pallet_macros { /// unimplemented!() /// } /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1130,15 +1131,17 @@ pub mod pallet_macros { /// in the future to give information directly to `construct_runtime`. pub use frame_support_procedural::inherent; + /// Allows breaking writing a pallet in multiple parts. + /// /// An attribute macro that can be attached to a module declaration. Doing so will /// import the contents of the specified external pallet section that is defined /// elsewhere using [`#[pallet_section]`](`pallet_section`). /// /// ## Example /// ``` - /// use frame_support::pallet_macros::pallet_section; - /// use frame_support::pallet_macros::import_section; - /// + /// # use frame_support::pallet_macros::pallet_section; + /// # use frame_support::pallet_macros::import_section; + /// # /// /// A [`pallet_section`] that defines the events for a pallet. /// /// This can later be imported into the pallet using [`import_section`]. /// #[pallet_section] @@ -1155,15 +1158,15 @@ pub mod pallet_macros { /// #[import_section(events)] /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config { - /// type RuntimeEvent: From> + IsType<::RuntimeEvent>; - /// } + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config { + /// # type RuntimeEvent: From> + IsType<::RuntimeEvent>; + /// # } /// } /// ``` /// @@ -1182,31 +1185,32 @@ pub mod pallet_macros { /// by their _full path_ from the perspective of the target pallet. pub use frame_support_procedural::import_section; - /// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define - /// a getter function on `Pallet` storage. + /// Allows defining getter functions on `Pallet` storage. /// /// ## Example /// /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// /// #[pallet::storage] /// #[pallet::getter(fn my_getter_fn_name)] /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// /// See [`pallet::storage`](`frame_support::pallet_macros::storage`) for more info. pub use frame_support_procedural::getter; + /// Allows generating the `Store` trait for all storages. + /// /// DEPRECATED: Will be removed, do not use. /// See for more details. /// @@ -1232,15 +1236,14 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// - /// #[pallet::config] - /// #[pallet::disable_frame_system_supertrait_check] - /// pub trait Config: frame_system::Config {} - /// + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// # /// #[pallet::extra_constants] /// impl Pallet // $optional_where_clause /// { @@ -1258,13 +1261,21 @@ pub mod pallet_macros { pub use frame_support_procedural::extra_constants; #[rustfmt::skip] + /// Allows bypassing the `frame_system::Config` supertrait check. + /// /// To bypass the `frame_system::Config` supertrait check, use the attribute /// `pallet::disable_frame_system_supertrait_check`, e.g.: /// - /// ``` + /// TODO: Fix the doctest + /// + /// ```ignore + /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; /// #[frame_support::pallet] /// mod pallet { /// use frame_support::pallet_prelude::*; + /// use frame_system::pallet_prelude::*; + /// trait OtherTrait {} /// /// #[pallet::pallet] /// pub struct Pallet(_); @@ -1283,16 +1294,15 @@ pub mod pallet_macros { /// reference doc. pub use frame_support_procedural::disable_frame_system_supertrait_check; - /// The mandatory attribute `#[pallet::config]` defines the configurable options for the - /// pallet. + /// The mandatory attribute allowing definition of configurable types for the pallet. /// /// Item must be defined as: /// /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1326,11 +1336,11 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; - /// use core::fmt::Debug; - /// use frame_support::traits::Contains; - /// + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; + /// # use core::fmt::Debug; + /// # use frame_support::traits::Contains; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1378,6 +1388,8 @@ pub mod pallet_macros { /// For more information, see [`frame_support::derive_impl`]. pub use frame_support_procedural::config; + /// Allows defining an enum that gets composed as an aggregate enum by `construct_runtime`. + /// /// The `#[pallet::composite_enum]` attribute allows you to define an enum that gets /// composed as an aggregate enum by `construct_runtime`. This is similar in principle with /// [frame_support_procedural::event] and [frame_support_procedural::error]. @@ -1408,8 +1420,8 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1421,22 +1433,21 @@ pub mod pallet_macros { /// #[codec(index = 1)] /// SomeOtherHoldReason, /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } pub use frame_support_procedural::composite_enum; - /// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some - /// unsigned transaction: + /// Allows the pallet to validate unsigned transactions. /// /// Item must be defined as: /// /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1449,9 +1460,9 @@ pub mod pallet_macros { /// unimplemented!() /// } /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1468,9 +1479,10 @@ pub mod pallet_macros { /// in the future to give information directly to [`frame_support::construct_runtime`]. pub use frame_support_procedural::validate_unsigned; - /// The `#[pallet::type_value]` attribute lets you define a struct implementing the - /// [`Get`](frame_support::traits::Get) trait to ease the use of storage types. This - /// attribute is meant to be used alongside [`#[pallet::storage]`](`storage`) to + /// Allows defining a struct implementing the [`Get`](frame_support::traits::Get) trait to + /// ease the use of storage types. + /// + /// This attribute is meant to be used alongside [`#[pallet::storage]`](`storage`) to /// define a storage's default value. This attribute can be used multiple times. /// /// Item must be defined as: @@ -1478,9 +1490,9 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use sp_runtime::FixedU128; - /// use frame_support::pallet_prelude::*; - /// + /// # use sp_runtime::FixedU128; + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1493,9 +1505,9 @@ pub mod pallet_macros { /// pub fn DefaultForSomeValue() -> FixedU128 { /// FixedU128::from_u32(1) /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1506,6 +1518,8 @@ pub mod pallet_macros { /// calling the user defined function. pub use frame_support_procedural::type_value; + /// Allows defining a storage version for the pallet. + /// /// Because the `pallet::pallet` macro implements /// [`GetStorageVersion`](frame_support::traits::GetStorageVersion), the current storage /// version needs to be communicated to the macro. This can be done by using the @@ -1514,34 +1528,35 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::StorageVersion; - /// use frame_support::traits::GetStorageVersion; - /// + /// # use frame_support::pallet_prelude::StorageVersion; + /// # use frame_support::traits::GetStorageVersion; + /// # /// const STORAGE_VERSION: StorageVersion = StorageVersion::new(5); /// /// #[pallet::pallet] /// #[pallet::storage_version(STORAGE_VERSION)] /// pub struct Pallet(_); - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// /// If not present, the current storage version is set to the default value. pub use frame_support_procedural::storage_version; - /// The `#[pallet::hooks]` attribute allows you to specify a [`frame_support::traits::Hooks`] implementation for - /// `Pallet` that specifies pallet-specific logic. + /// The `#[pallet::hooks]` attribute allows you to specify a + /// [`frame_support::traits::Hooks`] implementation for `Pallet` that specifies + /// pallet-specific logic. /// /// The item the attribute attaches to must be defined as follows: /// /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1549,9 +1564,9 @@ pub mod pallet_macros { /// impl Hooks> for Pallet { /// // Implement hooks here /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait @@ -1577,8 +1592,7 @@ pub mod pallet_macros { /// following hooks emit traces: `on_initialize`, `on_finalize` and `on_runtime_upgrade`. pub use frame_support_procedural::hooks; - /// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a - /// helper function on `Pallet` that handles deposit events. + /// Generates a helper function on `Pallet` that handles deposit events. /// /// NOTE: For instantiable pallets, the event must be generic over `T` and `I`. /// @@ -1600,6 +1614,8 @@ pub mod pallet_macros { /// deposit_event` on `Pallet`. pub use frame_support_procedural::generate_deposit; + /// Allows defining logic to make an extrinsic call feeless. + /// /// Each dispatchable may be annotated with the `#[pallet::feeless_if($closure)]` /// attribute, which explicitly defines the condition for the dispatchable to be feeless. /// @@ -1613,9 +1629,9 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet(dev_mode)] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1633,9 +1649,9 @@ pub mod pallet_macros { /// unimplemented!() /// } /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// @@ -1653,9 +1669,10 @@ pub mod pallet_macros { /// [`pallet_skip_feeless_payment::CheckIfFeeless`]: ../../pallet_skip_feeless_payment/struct.SkipCheckIfFeeless.html pub use frame_support_procedural::feeless_if; - /// The `#[pallet::error]` attribute allows you to define an error enum that will be - /// returned from the dispatchable when an error occurs. The information for this error - /// type is then stored in metadata. + /// Allows defining an error enum that will be returned from the dispatchable when an error + /// occurs. + /// + /// The information for this error type is then stored in runtime metadata. /// /// Item must be defined as so: /// @@ -1672,9 +1689,9 @@ pub mod pallet_macros { /// /// SomeVariantWithOneField doc /// SomeVariantWithOneField(u32), /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` /// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field @@ -1708,17 +1725,18 @@ pub mod pallet_macros { /// `DispatchError`. pub use frame_support_procedural::error; - /// The `#[pallet::event]` attribute allows you to define pallet events. Pallet events are - /// stored under the `system` / `events` key when the block is applied (and then replaced - /// when the next block writes it's events). + /// Allows defining pallet events. + /// + /// Pallet events are stored under the `system` / `events` key when the block is applied + /// (and then replaced when the next block writes it's events). /// /// The Event enum can be defined as follows: /// /// ``` /// #[frame_support::pallet(dev_mode)] /// mod pallet { - /// use frame_support::pallet_prelude::IsType; - /// + /// # use frame_support::pallet_prelude::IsType; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -1748,8 +1766,10 @@ pub mod pallet_macros { /// `Member`, available in `frame_support::pallet_prelude`. pub use frame_support_procedural::event; - /// Allows a pallet to declare a set of functions as a *dispatchable extrinsic*. In - /// slightly simplified terms, this macro declares the set of "transactions" of a pallet. + /// Allows a pallet to declare a set of functions as a *dispatchable extrinsic*. + /// + /// In slightly simplified terms, this macro declares the set of "transactions" of a + /// pallet. /// /// > The exact definition of **extrinsic** can be found in /// > [`sp_runtime::generic::UncheckedExtrinsic`]. @@ -1866,8 +1886,9 @@ pub mod pallet_macros { /// ``` pub use frame_support_procedural::call; - /// Enforce the index of a variant in the generated `enum Call`. See [`call`] for more - /// information. + /// Enforce the index of a variant in the generated `enum Call`. + /// + /// See [`call`] for more information. /// /// All call indexes start from 0, until it encounters a dispatchable function with a /// defined call index. The dispatchable function that lexically follows the function with @@ -1877,7 +1898,9 @@ pub mod pallet_macros { pub use frame_support_procedural::call_index; /// Declares the arguments of a [`call`] function to be encoded using - /// [`codec::Compact`]. This will results in smaller extrinsic encoding. + /// [`codec::Compact`]. + /// + /// This will results in smaller extrinsic encoding. /// /// A common example of `compact` is for numeric values that are often times far far away /// from their theoretical maximum. For example, in the context of a crypto-currency, the @@ -1973,8 +1996,8 @@ pub mod pallet_macros { /// ``` pub use frame_support_procedural::genesis_build; - /// The `#[pallet::constant]` attribute can be used to add an associated type trait bounded - /// by [`Get`](frame_support::pallet_prelude::Get) from [`pallet::config`](`macro@config`) + /// Allows adding an associated type trait bounded by + /// [`Get`](frame_support::pallet_prelude::Get) from [`pallet::config`](`macro@config`) /// into metadata. /// /// ## Example @@ -1995,9 +2018,10 @@ pub mod pallet_macros { /// ``` pub use frame_support_procedural::constant; - /// Declares a type alias as a storage item. Storage items are pointers to data stored - /// on-chain (the *blockchain state*), under a specific key. The exact key is dependent on - /// the type of the storage. + /// Declares a type alias as a storage item. + /// + /// Storage items are pointers to data stored on-chain (the *blockchain state*), under a + /// specific key. The exact key is dependent on the type of the storage. /// /// > From the perspective of this pallet, the entire blockchain state is abstracted behind /// > a key-value api, namely [`sp_io::storage`]. @@ -2196,6 +2220,9 @@ pub mod pallet_macros { /// } /// ``` pub use frame_support_procedural::storage; + + /// Allows defining conditions for a task to run. + /// /// This attribute is attached to a function inside an `impl` block annoated with /// [`pallet::tasks_experimental`](`tasks_experimental`) to define the conditions for a /// given work item to be valid. @@ -2204,6 +2231,9 @@ pub mod pallet_macros { /// should have the same signature as the function it is attached to, except that it should /// return a `bool` instead. pub use frame_support_procedural::task_condition; + + /// Allows defining an index for a task. + /// /// This attribute is attached to a function inside an `impl` block annoated with /// [`pallet::tasks_experimental`](`tasks_experimental`) to define the index of a given /// work item. @@ -2211,22 +2241,29 @@ pub mod pallet_macros { /// It takes an integer literal as input, which is then used to define the index. This /// index should be unique for each function in the `impl` block. pub use frame_support_procedural::task_index; + + /// Allows defining an iterator over available work items for a task. + /// /// This attribute is attached to a function inside an `impl` block annoated with - /// [`pallet::tasks_experimental`](`tasks_experimental`) to define an iterator over the - /// available work items for a task. + /// [`pallet::tasks_experimental`](`tasks_experimental`). /// /// It takes an iterator as input that yields a tuple with same types as the function /// arguments. pub use frame_support_procedural::task_list; + + /// Allows defining the weight of a task. + /// /// This attribute is attached to a function inside an `impl` block annoated with /// [`pallet::tasks_experimental`](`tasks_experimental`) define the weight of a given work /// item. /// /// It takes a closure as input, which should return a `Weight` value. pub use frame_support_procedural::task_weight; + /// Allows you to define some service work that can be recognized by a script or an - /// off-chain worker. Such a script can then create and submit all such work items at any - /// given time. + /// off-chain worker. + /// + /// Such a script can then create and submit all such work items at any given time. /// /// These work items are defined as instances of the [`Task`](frame_support::traits::Task) /// trait. [`pallet:tasks_experimental`](`tasks_experimental`) when attached to an `impl` @@ -2252,10 +2289,10 @@ pub mod pallet_macros { #[doc = docify::embed!("src/tests/tasks.rs", tasks_work)] pub use frame_support_procedural::tasks_experimental; - /// The optional attribute `#[pallet::whitelist_storage]` will declare the - /// storage as whitelisted from benchmarking. Doing so will exclude reads of - /// that value's storage key from counting towards weight calculations during - /// benchmarking. + /// Declare the storage as whitelisted from benchmarking. + /// + /// Doing so will exclude reads of that value's storage key from counting towards weight + /// calculations during benchmarking. /// /// This attribute should only be attached to storages that are known to be /// read/used in every block. This will result in a more accurate benchmarking weight. @@ -2264,21 +2301,23 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// /// #[pallet::storage] /// #[pallet::whitelist_storage] /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` pub use frame_support_procedural::whitelist_storage; + /// Allows specifying the weight of a call. + /// /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` /// attribute. The first argument must be `origin: OriginFor`. /// @@ -2287,9 +2326,9 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// @@ -2304,14 +2343,15 @@ pub mod pallet_macros { /// unimplemented!() /// } /// } - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` pub use frame_support_procedural::weight; - /// The optional attribute `#[pallet::unbounded]` declares a storage item as unbounded. + /// Declares a storage as unbounded in potential size. + /// /// When implementating the storage info (when `#[pallet::generate_storage_info]` is /// specified on the pallet struct placeholder), the size of the storage will be declared /// as unbounded. This can be useful for storage which can never go into PoV (Proof of @@ -2322,48 +2362,48 @@ pub mod pallet_macros { /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// /// #[pallet::storage] /// #[pallet::unbounded] /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` pub use frame_support_procedural::unbounded; - /// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define - /// what storage prefix to use for a storage item when building the trie. This is helpful - /// if you wish to rename the storage field but don't want to perform a migration. + /// Allow defining what storage prefix to use for a storage item when building the trie. + /// + /// This is helpful if you wish to rename the storage field but don't want to perform a + /// migration. /// /// ## Example /// /// ``` /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// + /// # use frame_support::pallet_prelude::*; + /// # /// #[pallet::pallet] /// pub struct Pallet(_); /// /// #[pallet::storage] /// #[pallet::storage_prefix = "foo"] /// pub type MyStorage = StorageValue<_, u32>; - /// - /// #[pallet::config] - /// pub trait Config: frame_system::Config {} + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} /// } /// ``` pub use frame_support_procedural::storage_prefix; - /// The optional attribute `#[pallet::no_default_bounds]` can be attached to trait items - /// within a `Config` trait impl that has - /// [`#[pallet::config(with_default)]`](`config`) attached. + /// Allows ensuring that the generated `DefaultConfig` will not have any bounds for that + /// trait item. /// /// Attaching this attribute to a trait item ensures that the generated trait /// `DefaultConfig` will not have any bounds for this trait item. @@ -2373,17 +2413,16 @@ pub mod pallet_macros { /// bound. pub use frame_support_procedural::no_default_bounds; + /// Allows ensuring that the trait item will not be used as a default with the + /// `#[derive_impl(..)]` attribute macro. + /// /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) /// attached. - /// - /// Attaching this attribute to a trait item ensures that that trait item will not be used - /// as a default with the [`#[derive_impl(..)]`](`frame_support::derive_impl`) attribute - /// macro. pub use frame_support_procedural::no_default; - /// Can be attached to a module. Doing so will declare that module as importable into a - /// pallet via [`#[import_section]`](`import_section`). + /// Allows declaring a module as importable into a pallet via + /// [`#[import_section]`](`import_section`). /// /// Note that sections are imported by their module name/ident, and should be referred to /// by their _full path_ from the perspective of the target pallet. Do not attempt to make From 4d8a3472ac4621dff30fea420915bcbf32c866b7 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 17:23:56 +1100 Subject: [PATCH 47/57] unignore failing doctest to not forget about it --- substrate/frame/support/src/lib.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index ba22e952374e..f253f2369d1f 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1266,9 +1266,7 @@ pub mod pallet_macros { /// To bypass the `frame_system::Config` supertrait check, use the attribute /// `pallet::disable_frame_system_supertrait_check`, e.g.: /// - /// TODO: Fix the doctest - /// - /// ```ignore + /// ``` /// use frame_support::pallet_prelude::*; /// use frame_system::pallet_prelude::*; /// #[frame_support::pallet] From a3a73bb299bd063aa20de98d86b63209a4e0666c Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Thu, 29 Feb 2024 17:36:36 +1100 Subject: [PATCH 48/57] add more backlinks to 'your first pallet' guide --- docs/sdk/src/guides/your_first_pallet/mod.rs | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 24eada44a83a..c52a33637455 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -250,14 +250,16 @@ // of event is probably not the best. //! //! With the explanation out of the way, let's see how these components can be added. Both follow a -//! fairly familiar syntax: normal Rust enums, with an extra `#[frame::event/error]` attribute -//! attached. +//! fairly familiar syntax: normal Rust enums, with extra +//! [`#[frame::event]`](frame::pallet_macros::event) and +//! [`#[frame::error]`](frame::pallet_macros::error) attributes attached. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", Event)] #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", Error)] //! -//! One slightly custom part of this is the `#[pallet::generate_deposit(pub(super) fn -//! deposit_event)]` part. Without going into too much detail, in order for a pallet to emit events -//! to the rest of the system, it needs to do two things: +//! One slightly custom part of this is the [`#[pallet::generate_deposit(pub(super) fn +//! deposit_event)]`](frame::pallet_macros::generate_deposit) part. Without going into too +//! much detail, in order for a pallet to emit events to the rest of the system, it needs to do two +//! things: //! //! 1. Declare a type in its `Config` that refers to the overarching event type of the runtime. In //! short, by doing this, the pallet is expressing an important bound: `type RuntimeEvent: @@ -266,7 +268,8 @@ //! store it where needed. //! //! 2. But, doing this conversion and storing is too much to expect each pallet to define. FRAME -//! provides a default way of storing events, and this is what `pallet::generate_deposit` is doing. +//! provides a default way of storing events, and this is what +//! [`pallet::generate_deposit`](frame::pallet_macros::generate_deposit) is doing. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", config_v2)] //! //! > These `Runtime*` types are better explained in @@ -280,8 +283,9 @@ #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", runtime_v2)] //! //! In this snippet, the actual `RuntimeEvent` type (right hand side of `type RuntimeEvent = -//! RuntimeEvent`) is generated by `construct_runtime`. An interesting way to inspect this type is -//! to see its definition in rust-docs: +//! RuntimeEvent`) is generated by +//! [`construct_runtime`](frame::runtime::prelude::construct_runtime). An interesting way to inspect +//! this type is to see its definition in rust-docs: //! [`crate::guides::your_first_pallet::pallet_v2::tests::runtime_v2::RuntimeEvent`]. //! //! From a3d57a407e31e355ccc42850f0589a72e303ee8c Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 10:39:33 +1100 Subject: [PATCH 49/57] update cargo.lock --- Cargo.lock | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Cargo.lock b/Cargo.lock index 3838ed0e94a1..6ba78973f12a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5750,6 +5750,7 @@ dependencies = [ "sp-staking", "sp-state-machine", "sp-std 14.0.0", + "sp-timestamp", "sp-tracing 16.0.0", "sp-weights", "static_assertions", @@ -13526,6 +13527,7 @@ version = "7.0.0" dependencies = [ "assert_matches", "async-trait", + "bitvec", "env_logger 0.9.3", "frame-benchmarking", "frame-benchmarking-cli", From 5d05227053b4f4a415817a342689419624f44439 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 10:46:40 +1100 Subject: [PATCH 50/57] fix merge --- substrate/frame/support/procedural/src/lib.rs | 37 ++-------------- substrate/frame/support/src/lib.rs | 42 ++----------------- 2 files changed, 6 insertions(+), 73 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 9ecf0ccb8abf..406a6829f9ea 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -448,42 +448,11 @@ pub fn __create_tt_macro(input: TokenStream) -> TokenStream { tt_macro::create_tt_return_macro(input) } -/// Allows accessing on-chain pallet storage that is no longer accessible via the pallet. /// -/// This is especially useful when writing storage migrations, when types of storage items are -/// modified or outright removed, but the previous definition is required to perform the migration. -/// -/// ## Example -/// -/// Imagine a pallet with the following storage definition: -/// ```ignore -/// #[pallet::storage] -/// pub type Value = StorageValue<_, u32>; -/// ``` -/// `Value` can be accessed by calling `Value::::get()`. -/// -/// Now imagine the definition of `Value` is updated to a `(u32, u32)`: -/// ```ignore -/// #[pallet::storage] -/// pub type Value = StorageValue<_, (u32, u32)>; -/// ``` -/// The on-chain value of `Value` is `u32`, but `Value::::get()` expects it to be `(u32, u32)`. -/// -/// In this instance the developer must write a storage migration to reading the old value of -/// `Value` and writing it back to storage in the new format, so that the on-chain storage layout is -/// consistent with what is defined in the pallet. -/// -/// We can read the old v0 value of `Value` in the migration by creating a `storage_alias`: -/// ```ignore -/// pub(crate) mod v0 { -/// use super::*; -/// -/// #[storage_alias] -/// pub type Value = StorageValue, u32>; -/// } -/// ``` +/// --- /// -/// The developer can now access the old value of `Value` by calling `v0::Value::::get()`. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::storage_alias`. #[proc_macro_attribute] pub fn storage_alias(attributes: TokenStream, input: TokenStream) -> TokenStream { storage_alias::storage_alias(attributes.into(), input.into()) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 473927eecbc5..b3b58f85529e 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1670,45 +1670,6 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { - /// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. - /// - /// Item must be either a type alias, an enum, or a struct. It needs to be public. - /// - /// ## Example - /// - /// ``` - /// #[frame_support::pallet] - /// mod pallet { - /// # use frame_support::pallet_prelude::*; - /// # - /// #[pallet::pallet] - /// pub struct Pallet(_); - /// - /// #[derive(PartialEq, Eq, Clone, MaxEncodedLen, Encode, Decode, TypeInfo, RuntimeDebug)] - /// #[pallet::origin] - /// pub enum Origin { - /// /// SomeOrigin doc. - /// SomeOrigin, - /// /// AnotherOrigin doc. - /// AnotherOrigin, - /// } - /// # - /// # #[pallet::config] - /// # pub trait Config: frame_system::Config {} - /// } - /// ``` - /// - /// **WARNING**: modifying origin changes the outer runtime origin. This outer runtime - /// origin can be stored on-chain (e.g. in - /// [`pallet_scheduler`](../../pallet_scheduler/index.html), thus any change must be - /// done with care as it might require some migration. - /// - /// NOTE: for instantiable pallets, the origin must be generic over `T` and `I`. - /// - /// Read more about origins at the [Origin Reference - /// Docs](../../polkadot_sdk_docs/reference_docs/frame_origin/index.html). - pub use frame_support_procedural::origin; - /// The `#[pallet::inherent]` attribute allows the pallet to provide /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). /// @@ -2984,6 +2945,9 @@ pub mod pallet_macros { /// /// Modifying any pallet's origin type will cause the runtime level origin type to also /// change in encoding. If stored anywhere on-chain, this will require a data migration. + /// + /// Read more about origins at the [Origin Reference + /// Docs](../../polkadot_sdk_docs/reference_docs/frame_origin/index.html). pub use frame_support_procedural::origin; } From 3dd9bff406a3a5fba1451af5b9c7a5b21c201d49 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 11:31:52 +1100 Subject: [PATCH 51/57] disable compiling supertrait example --- substrate/frame/support/src/lib.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index b3b58f85529e..7f8375476166 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1868,13 +1868,11 @@ pub mod pallet_macros { /// To bypass the `frame_system::Config` supertrait check, use the attribute /// `pallet::disable_frame_system_supertrait_check`, e.g.: /// - /// ``` - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; + /// ```ignore /// #[frame_support::pallet] /// mod pallet { - /// use frame_support::pallet_prelude::*; - /// use frame_system::pallet_prelude::*; + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; /// trait OtherTrait {} /// /// #[pallet::pallet] From eef3555dbe7eabd34854a78e264d4271ccad4a74 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 11:39:03 +1100 Subject: [PATCH 52/57] fix merge --- substrate/frame/support/src/lib.rs | 650 ----------------------------- 1 file changed, 650 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 7f8375476166..583224cb7f21 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -947,103 +947,6 @@ pub mod pallet_prelude { /// } /// ``` /// -/// # pallet::* Attributes -/// -/// The `pallet` macro will parse any items within your `pallet` module that are annotated with -/// `#[pallet::*]` attributes. Some of these attributes are mandatory and some are optional, -/// and they can attach to different types of items within your pallet depending on the -/// attribute in question. The full list of `#[pallet::*]` attributes is shown below in the -/// order in which they are mentioned in this document: -/// -/// * [`pallet::pallet`](#pallet-struct-placeholder-palletpallet-mandatory) -/// * [`pallet::config`](#config-trait-palletconfig-mandatory) -/// * [`pallet::constant`](#palletconstant) -/// * [`pallet::disable_frame_system_supertrait_check`](#disable_supertrait_check) -/// * [`pallet::generate_store($vis trait Store)`](#palletgenerate_storevis-trait-store) -/// * [`pallet::storage_version`](#palletstorage_version) -/// * [`pallet::hooks`](#hooks-pallethooks-optional) -/// * [`pallet::call`](#call-palletcall-optional) -/// * [`pallet::weight($expr)`](#palletweightexpr) -/// * [`pallet::compact`](#palletcompact-some_arg-some_type) -/// * [`pallet::call_index($idx)`](#palletcall_indexidx) -/// * [`pallet::extra_constants`](#extra-constants-palletextra_constants-optional) -/// * [`pallet::error`](#error-palleterror-optional) -/// * [`pallet::event`](#event-palletevent-optional) -/// * [`pallet::generate_deposit($visibility fn -/// deposit_event)`](#palletgenerate_depositvisibility-fn-deposit_event) -/// * [`pallet::storage`](#storage-palletstorage-optional) -/// * [`pallet::getter(fn $my_getter_fn_name)`](#palletgetterfn-my_getter_fn_name-optional) -/// * [`pallet::storage_prefix = "SomeName"`](#palletstorage_prefix--somename-optional) -/// * [`pallet::unbounded`](#palletunbounded-optional) -/// * [`pallet::whitelist_storage`](#palletwhitelist_storage-optional) -/// * [`pallet::disable_try_decode_storage`](#palletdisable_try_decode_storage-optional) -/// * [`cfg(..)`](#cfg-for-storage) (on storage items) -/// * [`pallet::type_value`](#type-value-pallettype_value-optional) -/// * [`pallet::genesis_config`](#genesis-config-palletgenesis_config-optional) -/// * [`pallet::genesis_build`](#genesis-build-palletgenesis_build-optional) -/// * [`pallet::inherent`](#inherent-palletinherent-optional) -/// * [`pallet::validate_unsigned`](#validate-unsigned-palletvalidate_unsigned-optional) -/// * [`pallet::origin`](#origin-palletorigin-optional) -/// * [`pallet::composite_enum`](#composite-enum-palletcomposite_enum-optional) -/// -/// Note that at compile-time, the `#[pallet]` macro will analyze and expand all of these -/// attributes, ultimately removing their AST nodes before they can be parsed as real -/// attribute macro calls. This means that technically we do not need attribute macro -/// definitions for any of these attributes, however, for consistency and discoverability -/// reasons, we still maintain stub attribute macro definitions for all of these attributes in -/// the [`pallet_macros`] module which is automatically included in all pallets as part of the -/// pallet prelude. The actual "work" for all of these attribute macros can be found in the -/// macro expansion for `#[pallet]`. -/// -/// Also note that in this document, pallet attributes are explained using the syntax of -/// non-instantiable pallets. For an example of an instantiable pallet, see [this -/// example](#example-of-an-instantiable-pallet). -/// -/// # Dev Mode (`#[pallet(dev_mode)]`) -/// -/// Specifying the argument `dev_mode` on the `#[pallet]` or `#[frame_support::pallet]` -/// attribute attached to your pallet module will allow you to enable dev mode for a pallet. -/// The aim of dev mode is to loosen some of the restrictions and requirements placed on -/// production pallets for easy tinkering and development. Dev mode pallets should not be used -/// in production. Enabling dev mode has the following effects: -/// -/// * Weights no longer need to be specified on every `#[pallet::call]` declaration. By -/// default, dev mode pallets will assume a weight of zero (`0`) if a weight is not -/// specified. This is equivalent to specifying `#[weight(0)]` on all calls that do not -/// specify a weight. -/// * Call indices no longer need to be specified on every `#[pallet::call]` declaration. By -/// default, dev mode pallets will assume a call index based on the order of the call. -/// * All storages are marked as unbounded, meaning you do not need to implement -/// `MaxEncodedLen` on storage types. This is equivalent to specifying `#[pallet::unbounded]` -/// on all storage type definitions. -/// * Storage hashers no longer need to be specified and can be replaced by `_`. In dev mode, -/// these will be replaced by `Blake2_128Concat`. In case of explicit key-binding, `Hasher` -/// can simply be ignored when in `dev_mode`. -/// -/// Note that the `dev_mode` argument can only be supplied to the `#[pallet]` or -/// `#[frame_support::pallet]` attribute macro that encloses your pallet module. This argument -/// cannot be specified anywhere else, including but not limited to the `#[pallet::pallet]` -/// attribute macro. -/// -/// 
-/// WARNING:
-/// You should not deploy or use dev mode pallets in production. Doing so can break your chain
-/// and therefore should never be done. Once you are done tinkering, you should remove the
-/// 'dev_mode' argument from your #[pallet] declaration and fix any compile errors before
-/// attempting to use your pallet in a production scenario.
-///
-/// -/// # Pallet struct placeholder: `#[pallet::pallet]` (mandatory) -/// -/// The pallet struct placeholder `#[pallet::pallet]` is mandatory and allows you to specify -/// pallet information. -/// -/// The struct must be defined as follows: -/// ```ignore -/// #[pallet::pallet] -/// pub struct Pallet(_); -/// ``` /// I.e. a regular struct definition named `Pallet`, with generic T and no where clause. /// /// ## Macro expansion: @@ -1071,9 +974,6 @@ pub mod pallet_prelude { /// It implements [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) on `Pallet` /// which give information about all storages. /// -/// If the attribute [`generate_store`](frame_support::pallet_macros::generate_store) is -/// set then the macro creates the trait `Store` and implements it on `Pallet`. -/// /// If the attribute `set_storage_max_encoded_len` is set then the macro calls /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for each storage in the /// implementation of [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the @@ -1115,556 +1015,6 @@ pub mod pallet_prelude { /// remove the 'dev_mode' argument from your #[pallet] declaration and fix any compile /// errors before attempting to use your pallet in a production scenario. /// -/// -/// ## Runtime Metadata Documentation -/// -/// The documentation added to this pallet is included in the runtime metadata. -/// -/// The documentation can be defined in the following ways: -/// -/// ```ignore -/// #[pallet::pallet] -/// #[pallet::storage_version(STORAGE_VERSION)] -/// pub struct Pallet(_); -/// ``` -/// -/// If not present, the in-code storage version is set to the default value. -/// -/// Also see [`pallet::storage_version`](`frame_support::pallet_macros::storage_version`) -/// -/// # Hooks: `#[pallet::hooks]` (optional) -/// -/// The `pallet::hooks` attribute allows you to specify a `Hooks` implementation for `Pallet` -/// that specifies pallet-specific logic. -/// -/// The item the attribute attaches to must be defined as follows: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet $optional_where_clause { -/// ... -/// } -/// ``` -/// I.e. a regular trait implementation with generic bound: `T: Config`, for the trait -/// `Hooks>` (they are defined in preludes), for the type `Pallet` and -/// with an optional where clause. -/// -/// If no `#[pallet::hooks]` exists, then the following default implementation is -/// automatically generated: -/// ```ignore -/// #[pallet::hooks] -/// impl Hooks> for Pallet {} -/// ``` -/// -/// Also see [`pallet::hooks`](`frame_support::pallet_macros::hooks`) -/// -/// # Call: `#[pallet::call]` (optional) -/// -/// Implementation of pallet dispatchables. -/// -/// Item must be defined as: -/// ```ignore -/// #[pallet::call] -/// impl Pallet { -/// /// $some_doc -/// #[pallet::weight($ExpressionResultingInWeight)] -/// pub fn $fn_name( -/// origin: OriginFor, -/// $some_arg: $some_type, -/// // or with compact attribute: #[pallet::compact] $some_arg: $some_type, -/// ... -/// ) -> DispatchResultWithPostInfo { // or `-> DispatchResult` -/// ... -/// } -/// ... -/// } -/// ``` -/// I.e. a regular type implementation, with generic `T: Config`, on type `Pallet`, with -/// an optional where clause. -/// -/// ## `#[pallet::weight($expr)]` -/// -/// Each dispatchable needs to define a weight with `#[pallet::weight($expr)]` attribute, the -/// first argument must be `origin: OriginFor`. -/// -/// Also see [`pallet::weight`](`frame_support::pallet_macros::weight`) -/// -/// ### `#[pallet::compact] $some_arg: $some_type` -/// -/// Compact encoding for arguments can be achieved via `#[pallet::compact]`. The function must -/// return a `DispatchResultWithPostInfo` or `DispatchResult`. -/// -/// Also see [`pallet::compact`](`frame_support::pallet_macros::compact`) -/// -/// ## `#[pallet::call_index($idx)]` -/// -/// Each dispatchable may also be annotated with the `#[pallet::call_index($idx)]` attribute, -/// which explicitly defines the codec index for the dispatchable function in the `Call` enum. -/// -/// All call indexes start from 0, until it encounters a dispatchable function with a defined -/// call index. The dispatchable function that lexically follows the function with a defined -/// call index will have that call index, but incremented by 1, e.g. if there are 3 -/// dispatchable functions `fn foo`, `fn bar` and `fn qux` in that order, and only `fn bar` -/// has a call index of 10, then `fn qux` will have an index of 11, instead of 1. -/// -/// **WARNING**: modifying dispatchables, changing their order, removing some, etc., must be -/// done with care. Indeed this will change the outer runtime call type (which is an enum with -/// one variant per pallet), this outer runtime call can be stored on-chain (e.g. in -/// `pallet-scheduler`). Thus migration might be needed. To mitigate against some of this, the -/// `#[pallet::call_index($idx)]` attribute can be used to fix the order of the dispatchable so -/// that the `Call` enum encoding does not change after modification. As a general rule of -/// thumb, it is therefore adventageous to always add new calls to the end so you can maintain -/// the existing order of calls. -/// -/// Also see [`pallet::call_index`](`frame_support::pallet_macros::call_index`) -/// -/// # Extra constants: `#[pallet::extra_constants]` (optional) -/// -/// Allows you to define some extra constants to be added into constant metadata. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::extra_constants] -/// impl Pallet where $optional_where_clause { -/// /// $some_doc -/// $vis fn $fn_name() -> $some_return_type { -/// ... -/// } -/// ... -/// } -/// ``` -/// I.e. a regular rust `impl` block with some optional where clause and functions with 0 args, -/// 0 generics, and some return type. -/// -/// ## Macro expansion -/// -/// The macro add some extra constants to pallet constant metadata. -/// -/// Also see: [`pallet::extra_constants`](`frame_support::pallet_macros::extra_constants`) -/// -/// # Error: `#[pallet::error]` (optional) -/// -/// The `#[pallet::error]` attribute allows you to define an error enum that will be returned -/// from the dispatchable when an error occurs. The information for this error type is then -/// stored in metadata. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::error] -/// pub enum Error { -/// /// $some_optional_doc -/// $SomeFieldLessVariant, -/// /// $some_more_optional_doc -/// $SomeVariantWithOneField(FieldType), -/// ... -/// } -/// ``` -/// I.e. a regular enum named `Error`, with generic `T` and fieldless or multiple-field -/// variants. -/// -/// Any field type in the enum variants must implement [`scale_info::TypeInfo`] in order to be -/// properly used in the metadata, and its encoded size should be as small as possible, -/// preferably 1 byte in size in order to reduce storage size. The error enum itself has an -/// absolute maximum encoded size specified by [`MAX_MODULE_ERROR_ENCODED_SIZE`]. -/// -/// (1 byte can still be 256 different errors. The more specific the error, the easier it is to -/// diagnose problems and give a better experience to the user. Don't skimp on having lots of -/// individual error conditions.) -/// -/// Field types in enum variants must also implement [`PalletError`](traits::PalletError), -/// otherwise the pallet will fail to compile. Rust primitive types have already implemented -/// the [`PalletError`](traits::PalletError) trait along with some commonly used stdlib types -/// such as [`Option`] and -/// [`PhantomData`](`frame_support::__private::sp_std::marker::PhantomData`), and hence in most -/// use cases, a manual implementation is not necessary and is discouraged. -/// -/// The generic `T` must not bound anything and a `where` clause is not allowed. That said, -/// bounds and/or a where clause should not needed for any use-case. -/// -/// Also see: [`pallet::error`](`frame_support::pallet_macros::error`) -/// -/// # Event: `#[pallet::event]` (optional) -/// -/// Allows you to define pallet events. Pallet events are stored under the `system` / `events` -/// key when the block is applied (and then replaced when the next block writes it's events). -/// -/// The Event enum must be defined as follows: -/// -/// ```ignore -/// #[pallet::event] -/// #[pallet::generate_deposit($visibility fn deposit_event)] // Optional -/// pub enum Event<$some_generic> $optional_where_clause { -/// /// Some doc -/// $SomeName($SomeType, $YetanotherType, ...), -/// ... -/// } -/// ``` -/// -/// I.e. an enum (with named or unnamed fields variant), named `Event`, with generic: none or -/// `T` or `T: Config`, and optional w here clause. -/// -/// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], [`Encode`], [`Decode`], and -/// [`Debug`] (on std only). For ease of use, bound by the trait -/// [`Member`](`frame_support::pallet_prelude::Member`), available in -/// frame_support::pallet_prelude. -/// -/// Also see [`pallet::event`](`frame_support::pallet_macros::event`) -/// -/// ## `#[pallet::generate_deposit($visibility fn deposit_event)]` -/// -/// The attribute `#[pallet::generate_deposit($visibility fn deposit_event)]` generates a -/// helper function on `Pallet` that handles deposit events. -/// -/// NOTE: For instantiable pallets, the event must be generic over `T` and `I`. -/// -/// Also see [`pallet::generate_deposit`](`frame_support::pallet_macros::generate_deposit`) -/// -/// # Storage: `#[pallet::storage]` (optional) -/// -/// The `#[pallet::storage]` attribute lets you define some abstract storage inside of runtime -/// storage and also set its metadata. This attribute can be used multiple times. -/// -/// Item should be defined as: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn $getter_name)] // optional -/// $vis type $StorageName<$some_generic> $optional_where_clause -/// = $StorageType<$generic_name = $some_generics, $other_name = $some_other, ...>; -/// ``` -/// -/// or with unnamed generic: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn $getter_name)] // optional -/// $vis type $StorageName<$some_generic> $optional_where_clause -/// = $StorageType<_, $some_generics, ...>; -/// ``` -/// -/// I.e. it must be a type alias, with generics: `T` or `T: Config`. The aliased type must be -/// one of [`StorageValue`](`pallet_prelude::StorageValue`), -/// [`StorageMap`](`pallet_prelude::StorageMap`) or -/// [`StorageDoubleMap`](`pallet_prelude::StorageDoubleMap`). The generic arguments of the -/// storage type can be given in two manners: named and unnamed. For named generic arguments, -/// the name for each argument should match the name defined for it on the storage struct: -/// * [`StorageValue`](`pallet_prelude::StorageValue`) expects `Value` and optionally -/// `QueryKind` and `OnEmpty`, -/// * [`StorageMap`](`pallet_prelude::StorageMap`) expects `Hasher`, `Key`, `Value` and -/// optionally `QueryKind` and `OnEmpty`, -/// * [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`) expects `Hasher`, `Key`, -/// `Value` and optionally `QueryKind` and `OnEmpty`, -/// * [`StorageDoubleMap`](`pallet_prelude::StorageDoubleMap`) expects `Hasher1`, `Key1`, -/// `Hasher2`, `Key2`, `Value` and optionally `QueryKind` and `OnEmpty`. -/// -/// For unnamed generic arguments: Their first generic must be `_` as it is replaced by the -/// macro and other generic must declared as a normal generic type declaration. -/// -/// The `Prefix` generic written by the macro is generated using -/// `PalletInfo::name::>()` and the name of the storage type. E.g. if runtime names -/// the pallet "MyExample" then the storage `type Foo = ...` should use the prefix: -/// `Twox128(b"MyExample") ++ Twox128(b"Foo")`. -/// -/// For the [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`) variant, the `Prefix` -/// also implements -/// [`CountedStorageMapInstance`](`frame_support::storage::types::CountedStorageMapInstance`). -/// It also associates a [`CounterPrefix`](`pallet_prelude::CounterPrefix'), which is -/// implemented the same as above, but the storage prefix is prepend with `"CounterFor"`. E.g. -/// if runtime names the pallet "MyExample" then the storage `type Foo = -/// CountedStorageaMap<...>` will store its counter at the prefix: `Twox128(b"MyExample") ++ -/// Twox128(b"CounterForFoo")`. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::storage] -/// pub(super) type MyStorage = StorageMap; -/// ``` -/// -/// In this case the final prefix used by the map is `Twox128(b"MyExample") ++ -/// Twox128(b"OtherName")`. -/// -/// Also see [`pallet::storage`](`frame_support::pallet_macros::storage`) -/// -/// ## `#[pallet::getter(fn $my_getter_fn_name)]` (optional) -/// -/// The optional attribute `#[pallet::getter(fn $my_getter_fn_name)]` allows you to define a -/// getter function on `Pallet`. -/// -/// Also see [`pallet::getter`](`frame_support::pallet_macros::getter`) -/// -/// ## `#[pallet::storage_prefix = "SomeName"]` (optional) -/// -/// The optional attribute `#[pallet::storage_prefix = "SomeName"]` allows you to define the -/// storage prefix to use, see how `Prefix` generic is implemented above. This is helpful if -/// you wish to rename the storage field but don't want to perform a migration. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::storage_prefix = "foo"] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap; -/// ``` -/// -/// or -/// -/// ```ignore -/// #[pallet::storage] -/// #[pallet::getter(fn my_storage)] -/// pub(super) type MyStorage = StorageMap<_, Blake2_128Concat, u32, u32>; -/// ``` -/// -/// The runtime metadata for this pallet contains the following -/// - "Documentation for pallet 1" (captured from `///`) -/// - "Documentation for pallet 2" (captured from `#[doc]`) -/// - content of ../README.md (captured from `#[doc]` with `include_str!`) -/// - content of "../doc1.md" (captured from `pallet_doc`) -/// - content of "../doc2.md" (captured from `pallet_doc`) -/// -/// ### `doc` attribute -/// -/// The optional attribute `#[pallet::unbounded]` declares the storage as unbounded. When -/// implementating the storage info (when `#[pallet::generate_storage_info]` is specified on -/// the pallet struct placeholder), the size of the storage will be declared as unbounded. This -/// can be useful for storage which can never go into PoV (Proof of Validity). -/// -/// Also see [`pallet::unbounded`](`frame_support::pallet_macros::unbounded`) -/// -/// ## `#[pallet::whitelist_storage]` (optional) -/// -/// The optional attribute `#[pallet::whitelist_storage]` will declare the storage as -/// whitelisted from benchmarking. -/// -/// See -/// [`pallet::whitelist_storage`](frame_support::pallet_macros::whitelist_storage) -/// for more info. -/// -/// ## `#[pallet::disable_try_decode_storage]` (optional) -/// -/// The optional attribute `#[pallet::disable_try_decode_storage]` will declare the storage as -/// whitelisted state decoding during try-runtime logic. -/// -/// See -/// [`pallet::disable_try_decode_storage`](frame_support::pallet_macros::disable_try_decode_storage) -/// for more info. -/// -/// ## `#[cfg(..)]` (for storage) -/// The optional attributes `#[cfg(..)]` allow conditional compilation for the storage. -/// -/// E.g: -/// -/// ```ignore -/// #[cfg(feature = "my-feature")] -/// #[pallet::storage] -/// pub(super) type MyStorage = StorageValue; -/// ``` -/// -/// All the `cfg` attributes are automatically copied to the items generated for the storage, -/// i.e. the getter, storage prefix, and the metadata element etc. -/// -/// Any type placed as the `QueryKind` parameter must implement -/// [`frame_support::storage::types::QueryKindTrait`]. There are 3 implementations of this -/// trait by default: -/// -/// 1. [`OptionQuery`](`frame_support::storage::types::OptionQuery`), the default `QueryKind` -/// used when this type parameter is omitted. Specifying this as the `QueryKind` would cause -/// storage map APIs that return a `QueryKind` to instead return an [`Option`], returning -/// `Some` when a value does exist under a specified storage key, and `None` otherwise. -/// 2. [`ValueQuery`](`frame_support::storage::types::ValueQuery`) causes storage map APIs that -/// return a `QueryKind` to instead return the value type. In cases where a value does not -/// exist under a specified storage key, the `OnEmpty` type parameter on `QueryKindTrait` is -/// used to return an appropriate value. -/// 3. [`ResultQuery`](`frame_support::storage::types::ResultQuery`) causes storage map APIs -/// that return a `QueryKind` to instead return a `Result`, with `T` being the value -/// type and `E` being the pallet error type specified by the `#[pallet::error]` attribute. -/// In cases where a value does not exist under a specified storage key, an `Err` with the -/// specified pallet error variant is returned. -/// -/// NOTE: If the `QueryKind` generic parameter is still generic at this stage or is using some -/// type alias then the generation of the getter might fail. In this case the getter can be -/// implemented manually. -/// -/// NOTE: The generic `Hasher` must implement the [`StorageHasher`] trait (or the type is not -/// usable at all). We use [`StorageHasher::METADATA`] for the metadata of the hasher of the -/// storage item. Thus generic hasher is supported. -/// -/// ## Macro expansion -/// -/// For each storage item the macro generates a struct named -/// `_GeneratedPrefixForStorage$NameOfStorage`, and implements -/// [`StorageInstance`](traits::StorageInstance) on it using the pallet and storage name. It -/// then uses it as the first generic of the aliased type. For -/// [`CountedStorageMap`](`pallet_prelude::CountedStorageMap`), -/// [`CountedStorageMapInstance`](`frame_support::storage::types::CountedStorageMapInstance`) -/// is implemented, and another similar struct is generated. -/// -/// For a named generic, the macro will reorder the generics, and remove the names. -/// -/// The macro implements the function `storage_metadata` on the `Pallet` implementing the -/// metadata for all storage items based on their kind: -/// * for a storage value, the type of the value is copied into the metadata -/// * for a storage map, the type of the values and the key's type is copied into the metadata -/// * for a storage double map, the type of the values, and the types of `key1` and `key2` are -/// copied into the metadata. -/// -/// # Type value: `#[pallet::type_value]` (optional) -/// -/// The `#[pallet::type_value]` attribute lets you define a struct implementing the -/// [`Get`](crate::traits::Get) trait to ease use of storage types. This attribute is meant to -/// be used alongside [`#[pallet::storage]`](#storage-palletstorage-optional) to define a -/// storage's default value. This attribute can be used multiple times. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } -/// ``` -/// -/// I.e.: a function definition with generics none or `T: Config` and a returned type. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn MyDefault() -> T::Balance { 3.into() } -/// ``` -/// -/// Also see [`pallet::type_value`](`frame_support::pallet_macros::type_value`) -/// -/// # Genesis config: `#[pallet::genesis_config]` (optional) -/// -/// The `#[pallet::genesis_config]` attribute allows you to define the genesis configuration -/// for the pallet. -/// -/// Item is defined as either an enum or a struct. It needs to be public and implement the -/// trait [`BuildGenesisConfig`](`traits::BuildGenesisConfig`) with -/// [`#[pallet::genesis_build]`](#genesis-build-palletgenesis_build-optional). The type -/// generics are constrained to be either none, or `T` or `T: Config`. -/// -/// E.g: -/// -/// ```ignore -/// #[pallet::genesis_config] -/// pub struct GenesisConfig { -/// _myfield: BalanceOf, -/// } -/// ``` -/// -/// Also see [`pallet::genesis_config`](`frame_support::pallet_macros::genesis_config`) -/// -/// # Genesis build: `#[pallet::genesis_build]` (optional) -/// -/// The `#[pallet::genesis_build]` attribute allows you to define how `genesis_configuration` -/// is built. This takes as input the `GenesisConfig` type (as `self`) and constructs the -/// pallet's initial state. -/// -/// The impl must be defined as: -/// -/// ```ignore -/// #[pallet::genesis_build] -/// impl GenesisBuild for GenesisConfig<$maybe_generics> { -/// fn build(&self) { $expr } -/// } -/// ``` -/// -/// I.e. a trait implementation with generic `T: Config`, of trait `GenesisBuild` on -/// type `GenesisConfig` with generics none or `T`. -/// -/// E.g.: -/// -/// ```ignore -/// #[pallet::genesis_build] -/// impl GenesisBuild for GenesisConfig { -/// fn build(&self) {} -/// } -/// ``` -/// -/// Also see [`pallet::genesis_build`](`frame_support::pallet_macros::genesis_build`) -/// -/// # Inherent: `#[pallet::inherent]` (optional) -/// -/// The `#[pallet::inherent]` attribute allows the pallet to provide some -/// [inherent](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). -/// An inherent is some piece of data that is inserted by a block authoring node at block -/// creation time and can either be accepted or rejected by validators based on whether the -/// data falls within an acceptable range. -/// -/// The most common inherent is the `timestamp` that is inserted into every block. Since there -/// is no way to validate timestamps, validators simply check that the timestamp reported by -/// the block authoring node falls within an acceptable range. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::inherent] -/// impl ProvideInherent for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait -/// [`ProvideInherent`](`pallet_prelude::ProvideInherent`) for type `Pallet`, and some -/// optional where clause. -/// -/// Also see [`pallet::inherent`](`frame_support::pallet_macros::inherent`) -/// -/// # Validate unsigned: `#[pallet::validate_unsigned]` (optional) -/// -/// The `#[pallet::validate_unsigned]` attribute allows the pallet to validate some unsigned -/// transaction: -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::validate_unsigned] -/// impl ValidateUnsigned for Pallet { -/// // ... regular trait implementation -/// } -/// ``` -/// -/// I.e. a trait implementation with bound `T: Config`, of trait -/// [`ValidateUnsigned`](`pallet_prelude::ValidateUnsigned`) for type `Pallet`, and some -/// optional where clause. -/// -/// NOTE: There is also the [`sp_runtime::traits::SignedExtension`] trait that can be used to -/// add some specific logic for transaction validation. -/// -/// Also see [`pallet::validate_unsigned`](`frame_support::pallet_macros::validate_unsigned`) -/// -/// # Origin: `#[pallet::origin]` (optional) -/// -/// The `#[pallet::origin]` attribute allows you to define some origin for the pallet. -/// -/// Item must be either a type alias, an enum, or a struct. It needs to be public. -/// -/// E.g.: -/// -/// ```ignore -/// /// Documentation for pallet 1 -/// /// Documentation for pallet 2 -/// /// Content of README.md -/// pub mod pallet {} -/// ``` -/// -/// If you want to specify the file from which the documentation is loaded, you can use the -/// `include_str` macro. However, if you only want the documentation to be included in the -/// runtime metadata, use the `pallet_doc` attribute. -/// -/// ### `pallet_doc` attribute -/// -/// Unlike the `doc` attribute, the documentation provided to the `pallet_doc` attribute is -/// not inserted on the module. -/// -/// The `pallet_doc` attribute can only be provided with one argument, -/// which is the file path that holds the documentation to be added to the metadata. -/// -/// This approach is beneficial when you use the `include_str` macro at the beginning of -/// the file and want that documentation to extend to the runtime metadata, without -/// reiterating the documentation on the pallet module itself. pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros From a1a25919db45b862afc38536cab5793361f9f7e1 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 12:17:27 +1100 Subject: [PATCH 53/57] fix bad merge --- substrate/frame/support/procedural/src/lib.rs | 35 +--- substrate/frame/support/src/lib.rs | 180 +++++++++++++++++- 2 files changed, 184 insertions(+), 31 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 406a6829f9ea..8bc2c3ba23fd 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -1029,38 +1029,16 @@ pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The optional attribute `#[pallet::disable_try_decode_storage]` will declare the -/// storage as whitelisted from decoding during try-runtime checks. This should only be -/// attached to transient storage which cannot be migrated during runtime upgrades. /// -/// ### Example -/// ```ignore -/// #[pallet::storage] -/// #[pallet::disable_try_decode_storage] -/// pub(super) type Events = StorageValue<_, Vec>>, ValueQuery>; -/// ``` +/// --- /// -/// NOTE: As with all `pallet::*` attributes, this one _must_ be written as -/// `#[pallet::disable_try_decode_storage]` and can only be placed inside a `pallet` module in order -/// for it to work properly. +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::disable_try_decode_storage`. #[proc_macro_attribute] pub fn disable_try_decode_storage(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() } -/// The `#[pallet::type_value]` attribute lets you define a struct implementing the `Get` trait -/// to ease the use of storage types. This attribute is meant to be used alongside -/// [`#[pallet::storage]`](`macro@storage`) to define a storage's default value. This attribute -/// can be used multiple times. -/// -/// Item must be defined as: -/// -/// ```ignore -/// #[pallet::type_value] -/// fn $MyDefaultName<$some_generic>() -> $default_type $optional_where_clause { $expr } -/// ``` -/// -/// I.e.: a function definition with generics none or `T: Config` and a returned type. /// /// --- /// @@ -1124,11 +1102,8 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream { /// /// --- /// -/// For ease of usage, when no `#[derive]` attributes are found for the enum under -/// `#[pallet::composite_enum]`, the aforementioned traits are automatically derived for it. The -/// inverse is also true: if there are any `#[derive]` attributes found for the enum, then no traits -/// will automatically be derived for it (this implies that you need to provide the -/// `frame_support::traits::VariantCount` implementation). +/// Rust-Analyzer Users: Documentation for this macro can be found at +/// `frame_support::pallet_macros::composite_enum`. #[proc_macro_attribute] pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream { pallet_macro_stub() diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 583224cb7f21..e68860de54aa 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1019,6 +1019,184 @@ pub use frame_support_procedural::pallet; /// Contains macro stubs for all of the `pallet::` macros pub mod pallet_macros { + /// Declare the storage as whitelisted from benchmarking. + /// + /// Doing so will exclude reads of that value's storage key from counting towards weight + /// calculations during benchmarking. + /// + /// This attribute should only be attached to storages that are known to be + /// read/used in every block. This will result in a more accurate benchmarking weight. + /// + /// ### Example + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// # use frame_support::pallet_prelude::*; + /// # + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::whitelist_storage] + /// pub type MyStorage = StorageValue<_, u32>; + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::whitelist_storage; + + /// Allows specifying the weight of a call. + /// + /// Each dispatchable needs to define a weight with the `#[pallet::weight($expr)]` + /// attribute. The first argument must be `origin: OriginFor`. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// # use frame_support::pallet_prelude::*; + /// # use frame_system::pallet_prelude::*; + /// # + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::call] + /// impl Pallet { + /// #[pallet::weight({0})] // <- set actual weight here + /// #[pallet::call_index(0)] + /// pub fn something( + /// _: OriginFor, + /// foo: u32, + /// ) -> DispatchResult { + /// unimplemented!() + /// } + /// } + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::weight; + + /// Allows whitelisting a storage item from decoding during try-runtime checks. + /// + /// The optional attribute `#[pallet::disable_try_decode_storage]` will declare the + /// storage as whitelisted from decoding during try-runtime checks. This should only be + /// attached to transient storage which cannot be migrated during runtime upgrades. + /// + /// ### Example + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// # use frame_support::pallet_prelude::*; + /// # + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::disable_try_decode_storage] + /// pub type MyStorage = StorageValue<_, u32>; + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::disable_try_decode_storage; + + /// Declares a storage as unbounded in potential size. + /// + /// When implementating the storage info (when `#[pallet::generate_storage_info]` is + /// specified on the pallet struct placeholder), the size of the storage will be declared + /// as unbounded. This can be useful for storage which can never go into PoV (Proof of + /// Validity). + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// # use frame_support::pallet_prelude::*; + /// # + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::unbounded] + /// pub type MyStorage = StorageValue<_, u32>; + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::unbounded; + + /// Allow defining what storage prefix to use for a storage item when building the trie. + /// + /// This is helpful if you wish to rename the storage field but don't want to perform a + /// migration. + /// + /// ## Example + /// + /// ``` + /// #[frame_support::pallet] + /// mod pallet { + /// # use frame_support::pallet_prelude::*; + /// # + /// #[pallet::pallet] + /// pub struct Pallet(_); + /// + /// #[pallet::storage] + /// #[pallet::storage_prefix = "foo"] + /// pub type MyStorage = StorageValue<_, u32>; + /// # + /// # #[pallet::config] + /// # pub trait Config: frame_system::Config {} + /// } + /// ``` + pub use frame_support_procedural::storage_prefix; + + /// Allows ensuring that the generated `DefaultConfig` will not have any bounds for that + /// trait item. + /// + /// Attaching this attribute to a trait item ensures that the generated trait + /// `DefaultConfig` will not have any bounds for this trait item. + /// + /// As an example, if you have a trait item `type AccountId: SomeTrait;` in your `Config` + /// trait, the generated `DefaultConfig` will only have `type AccountId;` with no trait + /// bound. + pub use frame_support_procedural::no_default_bounds; + + /// Allows ensuring that the trait item will not be used as a default with the + /// `#[derive_impl(..)]` attribute macro. + /// + /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a + /// `Config` trait impl that has [`#[pallet::config(with_default)]`](`config`) + /// attached. + pub use frame_support_procedural::no_default; + + /// Allows declaring a module as importable into a pallet via + /// [`#[import_section]`](`import_section`). + /// + /// Note that sections are imported by their module name/ident, and should be referred to + /// by their _full path_ from the perspective of the target pallet. Do not attempt to make + /// use of `use` statements to bring pallet sections into scope, as this will not work + /// (unless you do so as part of a wildcard import, in which case it will work). + /// + /// ## Naming Logistics + /// + /// Also note that because of how `#[pallet_section]` works, pallet section names must be + /// globally unique _within the crate in which they are defined_. For more information on + /// why this must be the case, see macro_magic's + /// [`#[export_tokens]`](https://docs.rs/macro_magic/latest/macro_magic/attr.export_tokens.html) macro. + /// + /// Optionally, you may provide an argument to `#[pallet_section]` such as + /// `#[pallet_section(some_ident)]`, in the event that there is another pallet section in + /// same crate with the same ident/name. The ident you specify can then be used instead of + /// the module's ident name when you go to import it via + /// [`#[import_section]`](`import_section`). + pub use frame_support_procedural::pallet_section; /// The `#[pallet::inherent]` attribute allows the pallet to provide /// [inherents](https://docs.substrate.io/fundamentals/transaction-types/#inherent-transactions). @@ -2268,7 +2446,7 @@ pub mod pallet_macros { /// } /// ``` /// - /// Or, more commonly used:/ + /// Or, more commonly used: /// /// ``` /// #[frame_support::pallet] From d6a3c326795641d2c7c77dfe6b6ad89da5c2839b Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Fri, 1 Mar 2024 12:23:15 +1100 Subject: [PATCH 54/57] Update substrate/frame/support/procedural/src/lib.rs --- substrate/frame/support/procedural/src/lib.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/substrate/frame/support/procedural/src/lib.rs b/substrate/frame/support/procedural/src/lib.rs index 8bc2c3ba23fd..ca33039567b7 100644 --- a/substrate/frame/support/procedural/src/lib.rs +++ b/substrate/frame/support/procedural/src/lib.rs @@ -379,8 +379,6 @@ pub fn derive_ord_no_bound(input: TokenStream) -> TokenStream { } /// derive `Default` but do no bound any generic. Docs are at `frame_support::DefaultNoBound`. -/// -/// Docs at `frame_support::DefaultNoBound`. #[proc_macro_derive(DefaultNoBound, attributes(default))] pub fn derive_default_no_bound(input: TokenStream) -> TokenStream { no_bound::default::derive_default_no_bound(input) From 3faf4dc8a23c95da6b48534a0ca2d1d460c75ba8 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Sun, 3 Mar 2024 18:18:47 +1100 Subject: [PATCH 55/57] address comments --- substrate/frame/support/src/lib.rs | 41 +++++++++++++++--------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index e68860de54aa..3766d2d97481 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -907,8 +907,9 @@ pub mod pallet_prelude { /// `construct_runtime`. /// /// Attaching this attribute to such an item ensures that the combined impl generated via - /// [`#[derive_impl(..)]`](`frame_support::derive_impl`) will use the correct type - /// auto-generated by `construct_runtime!`. + /// [`#[derive_impl(..)]`](`frame_support::derive_impl`) will use the correct + /// type auto-generated by + /// `construct_runtime!`. #[doc = docify::embed!("src/tests/inject_runtime_type.rs", derive_impl_works_with_runtime_type_injection)] /// /// However, if `no_aggregated_types` is specified while using @@ -960,19 +961,18 @@ pub mod pallet_prelude { /// frame_support::RuntimeDebugNoBound, /// )] /// ``` -/// and replaces the type `_` with `PhantomData`. It also implements on the pallet: +/// and replaces the type `_` with `PhantomData`. +/// +/// It also implements on the pallet: +/// /// * [`GetStorageVersion`](frame_support::traits::GetStorageVersion) /// * [`OnGenesis`](frame_support::traits::OnGenesis): contains some logic to write the pallet /// version into storage. -/// -/// It declares `type Module` type alias for `Pallet`, used by `construct_runtime`. -/// -/// It implements [`PalletInfoAccess`](frame_support::traits::PalletInfoAccess) on `Pallet` -/// to ease access to pallet information given by [`frame_support::traits::PalletInfo`]. -/// (The implementation uses the associated type [`frame_support::traits::PalletInfo`]). -/// -/// It implements [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) on `Pallet` -/// which give information about all storages. +/// * [`PalletInfoAccess`](frame_support::traits::PalletInfoAccess) to ease access to pallet +/// information given by [`frame_support::traits::PalletInfo`]. (The implementation uses the +/// associated type [`frame_support::traits::PalletInfo`]). +/// * [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) to give information about +/// storages. /// /// If the attribute `set_storage_max_encoded_len` is set then the macro calls /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for each storage in the @@ -1132,7 +1132,7 @@ pub mod pallet_macros { /// ``` pub use frame_support_procedural::unbounded; - /// Allow defining what storage prefix to use for a storage item when building the trie. + /// Defines what storage prefix to use for a storage item when building the trie. /// /// This is helpful if you wish to rename the storage field but don't want to perform a /// migration. @@ -1157,8 +1157,8 @@ pub mod pallet_macros { /// ``` pub use frame_support_procedural::storage_prefix; - /// Allows ensuring that the generated `DefaultConfig` will not have any bounds for that - /// trait item. + /// Ensures the generated `DefaultConfig` will not have any bounds for + /// that trait item. /// /// Attaching this attribute to a trait item ensures that the generated trait /// `DefaultConfig` will not have any bounds for this trait item. @@ -1168,7 +1168,7 @@ pub mod pallet_macros { /// bound. pub use frame_support_procedural::no_default_bounds; - /// Allows ensuring that the trait item will not be used as a default with the + /// Ensures the trait item will not be used as a default with the /// `#[derive_impl(..)]` attribute macro. /// /// The optional attribute `#[pallet::no_default]` can be attached to trait items within a @@ -1176,7 +1176,7 @@ pub mod pallet_macros { /// attached. pub use frame_support_procedural::no_default; - /// Allows declaring a module as importable into a pallet via + /// Declares a module as importable into a pallet via /// [`#[import_section]`](`import_section`). /// /// Note that sections are imported by their module name/ident, and should be referred to @@ -1261,7 +1261,7 @@ pub mod pallet_macros { /// in the future to give information directly to `construct_runtime`. pub use frame_support_procedural::inherent; - /// Allows breaking writing a pallet in multiple parts. + /// Splits a pallet declaration into multiple parts. /// /// An attribute macro that can be attached to a module declaration. Doing so will /// import the contents of the specified external pallet section that is defined @@ -1359,7 +1359,8 @@ pub mod pallet_macros { /// `::Foo`. pub use frame_support_procedural::generate_store; - /// Allows you to define some extra constants to be added into constant metadata. + /// Defines constants that are added to the constant field of + /// [`PalletMetadata`](frame_metadata::v15::PalletMetadata) struct for this pallet. /// /// Must be defined like: /// @@ -1889,7 +1890,7 @@ pub mod pallet_macros { /// /// Each field must implement [`Clone`], [`Eq`], [`PartialEq`], [`codec::Encode`], /// [`codec::Decode`], and [`Debug`] (on std only). For ease of use, bound by the trait - /// `Member`, available in `frame_support::pallet_prelude`. + /// `Member`, available in [`frame_support::pallet_prelude`]. pub use frame_support_procedural::event; /// Allows a pallet to declare a set of functions as a *dispatchable extrinsic*. From 16b9d929d9c04c43303efc5c469f914b49e77f51 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Sun, 3 Mar 2024 18:41:55 +1100 Subject: [PATCH 56/57] update disable_frame_system_supertrait_check doc --- substrate/frame/support/src/lib.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 3766d2d97481..caf9457d6668 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1394,15 +1394,23 @@ pub mod pallet_macros { #[rustfmt::skip] /// Allows bypassing the `frame_system::Config` supertrait check. /// - /// To bypass the `frame_system::Config` supertrait check, use the attribute - /// `pallet::disable_frame_system_supertrait_check`, e.g.: + /// To bypass the syntactic `frame_system::Config` supertrait check, use the attribute + /// `pallet::disable_frame_system_supertrait_check`. /// - /// ```ignore + /// Note this bypass is purely syntactic, and does not actually remove the requirement that your + /// pallet implements `frame_system::Config`. When using this check, your config is still required to implement + /// `frame_system::Config` either via + /// - Implementing a trait that itself implements `frame_system::Config` + /// - Tightly coupling it with another pallet which itself implements `frame_system::Config` + /// + /// e.g. + /// + /// ``` /// #[frame_support::pallet] /// mod pallet { /// # use frame_support::pallet_prelude::*; /// # use frame_system::pallet_prelude::*; - /// trait OtherTrait {} + /// trait OtherTrait: frame_system::Config {} /// /// #[pallet::pallet] /// pub struct Pallet(_); @@ -1413,9 +1421,6 @@ pub mod pallet_macros { /// } /// ``` /// - /// Bypassing the `frame_system::Config` supertrait check is typically desirable when - /// you want to write an alternative to the `frame_system` pallet. - /// /// To learn more about supertraits, see the /// [trait_based_programming](../../polkadot_sdk_docs/reference_docs/trait_based_programming/index.html) /// reference doc. From fed90fce3d6de744686b8ecfd74bba54e4c7a2c6 Mon Sep 17 00:00:00 2001 From: Liam Aharon Date: Sun, 3 Mar 2024 19:03:28 +1100 Subject: [PATCH 57/57] zepter --- substrate/frame/support/Cargo.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/substrate/frame/support/Cargo.toml b/substrate/frame/support/Cargo.toml index fcd486fa0d1c..fb9cb3d45119 100644 --- a/substrate/frame/support/Cargo.toml +++ b/substrate/frame/support/Cargo.toml @@ -97,6 +97,7 @@ std = [ "sp-std/std", "sp-tracing/std", "sp-weights/std", + "sp-timestamp/std" ] runtime-benchmarks = [ "frame-system/runtime-benchmarks",