Add documentation around pallet coupling (#3542)

substrate.io deprecation companion: polkadot-developers/substrate-docs#2139 pba-content companion: Polkadot-Blockchain-Academy/pba-content#978 partially inspired by: #3535 --------- Co-authored-by: Ankan <[email protected]>
paritytech · Mar 7, 2024 · c07bc5c · c07bc5c
1 parent 2b63e79
commit c07bc5c
Show file tree

Hide file tree

Showing 6 changed files with 374 additions and 77 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml
@@ -65,6 +65,7 @@ pallet-aura = { path = "../../substrate/frame/aura", default-features = false }
 # Pallets and FRAME internals
 pallet-timestamp = { path = "../../substrate/frame/timestamp" }
 pallet-balances = { path = "../../substrate/frame/balances" }
+pallet-assets = { path = "../../substrate/frame/assets" }
 pallet-transaction-payment = { path = "../../substrate/frame/transaction-payment" }
 pallet-utility = { path = "../../substrate/frame/utility" }
 pallet-multisig = { path = "../../substrate/frame/multisig" }

diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs
@@ -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;
-		}
+		/// 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>);
+	/// 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> {}
+	/// 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>;
+	/// 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(())
-			}
+	/// 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,
-			}
-		);
+/// 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::*};
 
-		// 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>;
+	// The major macro that amalgamates pallets into `enum Runtime`
+	construct_runtime!(
+		pub enum Runtime {
+			System: frame_system,
+			Example: pallet_example,
 		}
+	);
 
-		impl pallet_example::Config for Runtime {
-			type RuntimeEvent = RuntimeEvent;
-			type ValueParameter = ConstU32<42>;
-			const ANOTHER_VALUE_PARAMETER: u32 = 42;
-		}
+	// 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;
 	}
 }