Add documentation around pallet coupling (#3542)

substrate.io deprecation companion: https://github.com/substrate-developer-hub/substrate-docs/pull/2139 pba-content companion: https://github.com/Polkadot-Blockchain-Academy/pba-content/pull/978 partially inspired by: https://github.com/paritytech/polkadot-sdk/issues/3535 --------- Co-authored-by: Ankan <10196091+Ank4n@users.noreply.github.com>
2026-07-24 05:25:48 +00:00 · 2024-03-07 11:40:30 +00:00
parent 30c32e3d84
commit 50cc1c2f7e
6 changed files with 378 additions and 81 deletions
@@ -87,93 +87,89 @@
 //! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template).
 //! * writing a runtime in AssemblyScript,as explored in [this project](https://github.com/LimeChain/subsembly).

-#[cfg(test)]
-mod tests {
-	use frame::prelude::*;
+use frame::prelude::*;

-	/// A FRAME based pallet. This `mod` is the entry point for everything else. All
-	/// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
-	/// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
-	/// more.
-	#[docify::export]
-	#[frame::pallet(dev_mode)]
-	pub mod pallet {
-		use super::*;
+/// A FRAME based pallet. This `mod` is the entry point for everything else. All
+/// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
+/// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
+/// more.
+#[docify::export]
+#[frame::pallet(dev_mode)]
+pub mod pallet {
+	use super::*;

-		/// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
-		/// later point from the runtime that wishes to contain it. It allows the pallet to be
-		/// parameterized over both types and values.
-		#[pallet::config]
-		pub trait Config: frame_system::Config {
-			/// A type that is not known now, but the runtime that will contain this pallet will
-			/// know it later, therefore we define it here as an associated type.
-			type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent>
-				+ From<Event<Self>>;
+	/// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
+	/// later point from the runtime that wishes to contain it. It allows the pallet to be
+	/// parameterized over both types and values.
+	#[pallet::config]
+	pub trait Config: frame_system::Config {
+		/// A type that is not known now, but the runtime that will contain this pallet will
+		/// know it later, therefore we define it here as an associated type.
+		type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent> + From<Event<Self>>;

-			/// A parameterize-able value that we receive later via the `Get<_>` trait.
-			type ValueParameter: Get<u32>;
+		/// A parameterize-able value that we receive later via the `Get<_>` trait.
+		type ValueParameter: Get<u32>;

-			/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
-			/// equal, but offer different tradeoffs.
-			const ANOTHER_VALUE_PARAMETER: u32;
-		}
-
-		/// A mandatory struct in each pallet. All functions callable by external users (aka.
-		/// transactions) must be attached to this type (see [`frame::pallet_macros::call`]). For
-		/// convenience, internal (private) functions can also be attached to this type.
-		#[pallet::pallet]
-		pub struct Pallet<T>(PhantomData<T>);
-
-		/// The events tha this pallet can emit.
-		#[pallet::event]
-		pub enum Event<T: Config> {}
-
-		/// A storage item that this pallet contains. This will be part of the state root trie/root
-		/// of the blockchain.
-		#[pallet::storage]
-		pub type Value<T> = StorageValue<Value = u32>;
-
-		/// All *dispatchable* call functions (aka. transactions) are attached to `Pallet` in a
-		/// `impl` block.
-		#[pallet::call]
-		impl<T: Config> Pallet<T> {
-			/// This will be callable by external users, and has two u32s as a parameter.
-			pub fn some_dispatchable(
-				_origin: OriginFor<T>,
-				_param: u32,
-				_other_para: u32,
-			) -> DispatchResult {
-				Ok(())
-			}
-		}
+		/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
+		/// equal, but offer different tradeoffs.
+		const ANOTHER_VALUE_PARAMETER: u32;
 	}

-	/// A simple runtime that contains the above pallet and `frame_system`, the mandatory pallet of
-	/// all runtimes. This runtime is for testing, but it shares a lot of similarities with a *real*
-	/// runtime.
-	#[docify::export]
-	pub mod runtime {
-		use super::pallet as pallet_example;
-		use frame::{prelude::*, testing_prelude::*};
+	/// A mandatory struct in each pallet. All functions callable by external users (aka.
+	/// transactions) must be attached to this type (see [`frame::pallet_macros::call`]). For
+	/// convenience, internal (private) functions can also be attached to this type.
+	#[pallet::pallet]
+	pub struct Pallet<T>(PhantomData<T>);

-		// The major macro that amalgamates pallets into `enum Runtime`
-		construct_runtime!(
-			pub enum Runtime {
-				System: frame_system,
-				Example: pallet_example,
-			}
-		);
+	/// The events tha this pallet can emit.
+	#[pallet::event]
+	pub enum Event<T: Config> {}

-		// These `impl` blocks specify the parameters of each pallet's `trait Config`.
-		#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
-		impl frame_system::Config for Runtime {
-			type Block = MockBlock<Self>;
-		}
+	/// A storage item that this pallet contains. This will be part of the state root trie/root
+	/// of the blockchain.
+	#[pallet::storage]
+	pub type Value<T> = StorageValue<Value = u32>;

-		impl pallet_example::Config for Runtime {
-			type RuntimeEvent = RuntimeEvent;
-			type ValueParameter = ConstU32<42>;
-			const ANOTHER_VALUE_PARAMETER: u32 = 42;
+	/// All *dispatchable* call functions (aka. transactions) are attached to `Pallet` in a
+	/// `impl` block.
+	#[pallet::call]
+	impl<T: Config> Pallet<T> {
+		/// This will be callable by external users, and has two u32s as a parameter.
+		pub fn some_dispatchable(
+			_origin: OriginFor<T>,
+			_param: u32,
+			_other_para: u32,
+		) -> DispatchResult {
+			Ok(())
 		}
 	}
 }
+
+/// A simple runtime that contains the above pallet and `frame_system`, the mandatory pallet of
+/// all runtimes. This runtime is for testing, but it shares a lot of similarities with a *real*
+/// runtime.
+#[docify::export]
+pub mod runtime {
+	use super::pallet as pallet_example;
+	use frame::{prelude::*, testing_prelude::*};
+
+	// The major macro that amalgamates pallets into `enum Runtime`
+	construct_runtime!(
+		pub enum Runtime {
+			System: frame_system,
+			Example: pallet_example,
+		}
+	);
+
+	// These `impl` blocks specify the parameters of each pallet's `trait Config`.
+	#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
+	impl frame_system::Config for Runtime {
+		type Block = MockBlock<Self>;
+	}
+
+	impl pallet_example::Config for Runtime {
+		type RuntimeEvent = RuntimeEvent;
+		type ValueParameter = ConstU32<42>;
+		const ANOTHER_VALUE_PARAMETER: u32 = 42;
+	}
+}