pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 06:27:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve doc for pallet macro and config macro (#4146)

Browse Source 
Improve doc:

* the pallet macro is actually referring to 2 places, for the module and
for the struct placeholder but doesn't really clarify it (I should have
named the latter just `pallet_struct` or something but it is a bit late)

* The doc of `with_default` is a bit confusing too IMO.

CC @kianenigma

---------

Co-authored-by: Liam Aharon <liam.aharon@hotmail.com>
This commit is contained in:
gui
2024-04-18 00:22:46 +09:00
committed by GitHub
parent 4e10d3b0a6
commit ca7c01c8d8
1 changed files with 103 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/frame/support/src/lib.rs
+103 -38
View File
@@ -936,6 +936,83 @@ pub mod pallet_prelude {
pub use sp_weights::Weight;
}
/// The pallet macro has 2 purposes:
///
/// * [For declaring a pallet as a rust module](#1---pallet-module-declaration)
/// * [For declaring the `struct` placeholder of a
/// pallet](#2---pallet-struct-placeholder-declaration)
///
/// # 1 - Pallet module declaration
///
/// The module to declare a pallet is organized as follow:
/// ```
/// #[frame_support::pallet] // <- the macro
/// mod pallet {
/// #[pallet::pallet]
/// pub struct Pallet<T>(_);
///
/// #[pallet::config]
/// pub trait Config: frame_system::Config {}
///
/// #[pallet::call]
/// impl<T: Config> Pallet<T> {
/// }
///
/// /* ... */
/// }
/// ```
///
/// The documentation for each individual part can be found at [frame_support::pallet_macros]
///
/// ## Dev Mode (`#[pallet(dev_mode)]`)
///
/// Syntax:
///
/// ```
/// #[frame_support::pallet(dev_mode)]
/// mod pallet {
/// # #[pallet::pallet]
/// # pub struct Pallet<T>(_);
/// # #[pallet::config]
/// # pub trait Config: frame_system::Config {}
/// /* ... */
/// }
/// ```
///
/// 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`](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`.
///
/// 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.
///
/// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail"
/// style="white-space:normal;font:inherit;">
/// <strong>WARNING</strong>:
/// You should never deploy or use dev mode pallets in production. Doing so can break your
/// chain. 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.
/// </pre></div>
///
/// # 2 - Pallet struct placeholder declaration
///
/// The pallet struct placeholder `#[pallet::pallet]` is mandatory and allows you to
/// specify pallet information.
///
@@ -984,40 +1061,6 @@ pub mod pallet_prelude {
/// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the pallet using the
/// [`PartialStorageInfoTrait`](frame_support::traits::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`](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`.
///
/// 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.
///
/// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail"
/// style="white-space:normal;font:inherit;">
/// <strong>WARNING</strong>:
/// 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.
/// </pre></div>
pub use frame_support_procedural::pallet;
/// Contains macro stubs for all of the `pallet::` macros
@@ -1456,16 +1499,24 @@ pub mod pallet_macros {
/// # use core::fmt::Debug;
/// # use frame_support::traits::Contains;
/// #
/// # pub trait SomeMoreComplexBound {}
/// #
/// #[pallet::pallet]
/// pub struct Pallet<T>(_);
///
/// #[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
/// #[pallet::no_default_bounds] // Default with bounds is not supported for RuntimeEvent
/// type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
///
/// // ...other config items get default
/// /// A more complex type.
/// #[pallet::no_default] // Example of type where no default should be provided
/// type MoreComplexType: SomeMoreComplexBound;
///
/// /// A simple type.
/// // Default with bounds is supported for simple types
/// type SimpleType: From<u32>;
/// }
///
/// #[pallet::event]
@@ -1475,12 +1526,23 @@ pub mod pallet_macros {
/// }
/// ```
///
/// As shown above, you may also attach the [`#[pallet::no_default]`](`no_default`)
/// As shown above:
/// * you may 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`).
/// * you may attach the [`#[pallet::no_default_bounds]`](`no_default_bounds`)
/// attribute to specify that a particular trait item can be used as a default when a
/// test `Config` is derived using the [`#[derive_impl(..)]`](`frame_support::derive_impl`)
/// attribute macro. But its bounds cannot be enforced at this point and should be
/// discarded when generating the default config trait.
/// * you may not specify any attribute to generate a trait item in the default config
/// trait.
///
/// In case origin of error is not clear it is recommended to disable all default with
/// [`#[pallet::no_default]`](`no_default`) and enable them one by one.
///
/// ### `DefaultConfig` Caveats
///
@@ -1500,7 +1562,10 @@ pub mod pallet_macros {
/// the `DefaultConfig` trait, and therefore any impl of `DefaultConfig` doesn't need to
/// implement such items.
///
/// For more information, see [`frame_support::derive_impl`].
/// For more information, see:
/// * [`frame_support::derive_impl`].
/// * [`#[pallet::no_default]`](`no_default`)
/// * [`#[pallet::no_default_bounds]`](`no_default_bounds`)
pub use frame_support_procedural::config;
/// Allows defining an enum that gets composed as an aggregate enum by `construct_runtime`.