From 54deef92f86a16d413f98a6f68418d11c8142a25 Mon Sep 17 00:00:00 2001
From: Nathaniel Bajo <73991674+Nathy-bajo@users.noreply.github.com>
Date: Sat, 15 Feb 2025 13:48:15 +0100
Subject: [PATCH] Documentation update for weight. #7354 (#7376)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
resolves #7354
Polkadot address: 121HJWZtD13GJQPD82oEj3gSeHqsRYm1mFgRALu4L96kfPD1
---------
Co-authored-by: Guillaume Thiolliere <guillaume.thiolliere@parity.io>
Co-authored-by: Bastian Köcher <git@kchr.de>
---
prdoc/pr_7376.prdoc | 13 ++++
substrate/frame/support/src/lib.rs | 121 +++++++++++++++++++++++++----
2 files changed, 117 insertions(+), 17 deletions(-)
create mode 100644 prdoc/pr_7376.prdoc
diff --git a/prdoc/pr_7376.prdoc b/prdoc/pr_7376.prdoc
new file mode 100644
index 00000000000..73076ed4c8d
--- /dev/null
+++ b/prdoc/pr_7376.prdoc
@@ -0,0 +1,13 @@
+title: Documentation update for weight.
+
+doc:
+- audience: Runtime Dev
+ description: |-
+ Document the usage of `#[pallet::call(weight = <T as Config>::WeightInfo)]` within FRAME macros.
+ This update enhances the documentation for `#[pallet::call]` and `#[pallet::weight]`, providing
+ examples and clarifying weight specifications for dispatchable functions, ensuring consistency
+ with existing guidelines.
+
+crates:
+ - name: frame-support
+ bump: patch
\ No newline at end of file
diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs
index 6dbd0605a52..825628fb01e 100644
--- a/substrate/frame/support/src/lib.rs
+++ b/substrate/frame/support/src/lib.rs
@@ -1099,34 +1099,61 @@ pub mod pallet_macros {
/// 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<T>`.
+ /// Each dispatchable needs to define a weight.
+ /// This attribute allows to define a weight using the expression:
+ /// `#[pallet::weight($expr)]` Note that argument of the call are available inside the
+ /// expression.
+ ///
+ /// If not defined explicitly, the weight can be implicitly inferred from the weight info
+ /// defined in the attribute `pallet::call`: `#[pallet::call(weight = $WeightInfo)]`.
+ /// Or it can be simply ignored when the pallet is in `dev_mode`.
///
/// ## Example
///
/// ```
/// #[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<T>(_);
///
- /// #[pallet::call]
+ /// #[pallet::config]
+ /// pub trait Config: frame_system::Config {
+ /// /// Type for specifying dispatchable weights.
+ /// type WeightInfo: WeightInfo;
+ /// }
+ ///
+ /// #[pallet::call(weight = <T as Config>::WeightInfo)]
/// impl<T: Config> Pallet<T> {
- /// #[pallet::weight({0})] // <- set actual weight here
+ /// // Explicit weight definition
+ /// #[pallet::weight(<T as Config>::WeightInfo::do_something())]
/// #[pallet::call_index(0)]
- /// pub fn something(
- /// _: OriginFor<T>,
+ /// pub fn do_something(
+ /// origin: OriginFor<T>,
/// foo: u32,
/// ) -> DispatchResult {
- /// unimplemented!()
+ /// Ok(())
/// }
- /// }
- /// #
- /// # #[pallet::config]
- /// # pub trait Config: frame_system::Config {}
+ ///
+ /// // Implicit weight definition, the macro looks up to the weight info defined in
+ /// // `#[pallet::call(weight = $WeightInfo)]` attribute. Then use
+ /// // `$WeightInfo::do_something_else` as the weight function.
+ /// #[pallet::call_index(1)]
+ /// pub fn do_something_else(
+ /// origin: OriginFor<T>,
+ /// bar: u64,
+ /// ) -> DispatchResult {
+ /// Ok(())
+ /// }
+ /// }
+ ///
+ /// /// The `WeightInfo` trait defines weight functions for dispatchable calls.
+ /// pub trait WeightInfo {
+ /// fn do_something() -> Weight;
+ /// fn do_something_else() -> Weight;
+ /// }
/// }
/// ```
pub use frame_support_procedural::weight;
@@ -2182,9 +2209,69 @@ pub mod pallet_macros {
/// [`crate::dispatch::DispatchResultWithPostInfo`]).
///
/// **WARNING**: modifying dispatchables, changing their order (i.e. using [`call_index`]),
- /// removing some, etc., must be done with care. This will change the encoding of the , and
- /// the call can be stored on-chain (e.g. in `pallet-scheduler`). Thus, migration might be
- /// needed. This is why the use of `call_index` is mandatory by default in FRAME.
+ /// removing some, etc., must be done with care. This will change the encoding of the call,
+ /// and the call can be stored on-chain (e.g. in `pallet-scheduler`). Thus, migration
+ /// might be needed. This is why the use of `call_index` is mandatory by default in FRAME.
+ ///
+ /// ## Weight info
+ ///
+ /// Each call needs to define a weight.
+ /// * The weight can be defined explicitly using the attribute `#[pallet::weight($expr)]`
+ /// (Note that argument of the call are available inside the expression).
+ /// * Or it can be defined implicitly, the weight info for the calls needs to be specified
+ /// in the call attribute: `#[pallet::call(weight = $WeightInfo)]`, then each call that
+ /// doesn't have explicit weight will use `$WeightInfo::$call_name` as the weight.
+ ///
+ /// * Or it can be simply ignored when the pallet is in `dev_mode`.
+ ///
+ /// ```
+ /// #[frame_support::pallet]
+ /// mod pallet {
+ /// use frame_support::pallet_prelude::*;
+ /// use frame_system::pallet_prelude::*;
+ ///
+ /// #[pallet::pallet]
+ /// pub struct Pallet<T>(_);
+ ///
+ /// #[pallet::config]
+ /// pub trait Config: frame_system::Config {
+ /// /// Type for specifying dispatchable weights.
+ /// type WeightInfo: WeightInfo;
+ /// }
+ ///
+ /// /// The `WeightInfo` trait defines weight functions for dispatchable calls.
+ /// pub trait WeightInfo {
+ /// fn do_something() -> Weight;
+ /// fn do_something_else() -> Weight;
+ /// }
+ ///
+ /// #[pallet::call(weight = <T as Config>::WeightInfo)]
+ /// impl<T: Config> Pallet<T> {
+ /// // Explicit weight definition using `#[pallet::weight(...)]`
+ /// #[pallet::weight(<T as Config>::WeightInfo::do_something())]
+ /// #[pallet::call_index(0)]
+ /// pub fn do_something(
+ /// origin: OriginFor<T>,
+ /// foo: u32,
+ /// ) -> DispatchResult {
+ /// // Function logic here
+ /// Ok(())
+ /// }
+ ///
+ /// // Implicit weight definition, the macro looks up to the weight info defined in
+ /// // `#[pallet::call(weight = $WeightInfo)]` attribute. Then use
+ /// // `$WeightInfo::do_something_else` as the weight function.
+ /// #[pallet::call_index(1)]
+ /// pub fn do_something_else(
+ /// origin: OriginFor<T>,
+ /// bar: u64,
+ /// ) -> DispatchResult {
+ /// // Function logic here
+ /// Ok(())
+ /// }
+ /// }
+ /// }
+ /// ```
///
/// ## Default Behavior
///
--
GitLab