Improve documentation for fast-unstake pallet

frame/fast-unstake/Cargo.toml

@@ -27,6 +27,8 @@ frame-election-provider-support = { default-features = false, path = "../electio
 
 frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" }
 
+docify = "0.1.1"
+
 [dev-dependencies]
 pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" }
 sp-core = { version = "7.0.0", default-features = false, path = "../../primitives/core" }

frame/fast-unstake/src/lib.rs

@@ -15,6 +15,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! # Fast Unstake Pallet
+//!
+//! ## Overview
+//!
 //! A pallet that's designed to JUST do the following:
 //!
 //! If a nominator is not exposed in any `ErasStakers` (i.e. "has not actively backed any
@@ -27,16 +31,16 @@
 //! Nominator" role explained in the
 //! [February Staking Update](https://polkadot.network/blog/staking-update-february-2022/).
 //!
-//! This pallet works off the basis of `on_idle`, meaning that it provides no guarantee about when
-//! it will succeed, if at all. Moreover, the queue implementation is unordered. In case of
-//! congestion, no FIFO ordering is provided.
+//! This pallet works off the basis of `on_idle`, meaning that it
+//! provides no guarantee about when it will succeed, if at all. Moreover, the queue implementation
+//! is unordered. In case of congestion, no FIFO ordering is provided.
 //!
 //! Stakers who are certain about NOT being exposed can register themselves with
-//! [`Call::register_fast_unstake`]. This will chill, and fully unbond the staker, and place them in
-//! the queue to be checked.
+//! [`Pallet::register_fast_unstake`]. This will chill, and fully unbond the staker, and place them
+//! in the queue to be checked.
 //!
 //! Once queued, but not being actively processed, stakers can withdraw their request via
-//! [`Call::deregister`].
+//! [`Pallet::deregister`].
 //!
 //! Once queued, a staker wishing to unbond can perform no further action in pallet-staking. This is
 //! to prevent them from accidentally exposing themselves behind a validator etc.
@@ -46,16 +50,29 @@
 //!
 //! If unsuccessful, meaning that the staker was exposed sometime in the last `BondingDuration` eras
 //! they will end up being slashed for the amount of wasted work they have inflicted on the chian.
+//!
+//! ## Details
+//!
+//! See [`pallet`] module for more information.
+//!
+//! ## Examples
+//!
+//! 1. Fast-unstake with multiple participants in the queue.
+#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", successful_multi_queue)]
+//!
+//! 2. Fast unstake failing because a nominator is exposed.
+#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake)]
+//!
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use pallet::*;
 
 #[cfg(test)]
-mod mock;
+pub mod mock;
 
 #[cfg(test)]
-mod tests;
+pub mod tests;
 
 // NOTE: enable benchmarking in tests as well.
 #[cfg(feature = "runtime-benchmarks")]
@@ -91,16 +108,6 @@ pub mod pallet {
 	use sp_std::{prelude::*, vec::Vec};
 	pub use weights::WeightInfo;
 
-	#[derive(scale_info::TypeInfo, codec::Encode, codec::Decode, codec::MaxEncodedLen)]
-	#[codec(mel_bound(T: Config))]
-	#[scale_info(skip_type_params(T))]
-	pub struct MaxChecking<T: Config>(sp_std::marker::PhantomData<T>);
-	impl<T: Config> frame_support::traits::Get<u32> for MaxChecking<T> {
-		fn get() -> u32 {
-			T::Staking::bonding_duration() + 1
-		}
-	}
-
 	const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
 
 	#[pallet::pallet]
@@ -122,7 +129,7 @@ pub mod pallet {
 		#[pallet::constant]
 		type Deposit: Get<BalanceOf<Self>>;
 
-		/// The origin that can control this pallet.
+		/// The origin that can control this pallet, in other words invoke [`Pallet::control`].
 		type ControlOrigin: frame_support::traits::EnsureOrigin<Self::RuntimeOrigin>;
 
 		/// Batch size.
@@ -133,40 +140,44 @@ pub mod pallet {
 		/// The access to staking functionality.
 		type Staking: StakingInterface<Balance = BalanceOf<Self>, AccountId = Self::AccountId>;
 
+		/// Maximum value for `ErasToCheckPerBlock`, checked in [`Pallet::control`].
+		///
+		/// This should be as close as possible, but more than the actual value, in order to have
+		/// accurate benchmarks.
+		type MaxErasToCheckPerBlock: Get<u32>;
+
 		/// The weight information of this pallet.
 		type WeightInfo: WeightInfo;
 
-		/// Maximum value for `ErasToCheckPerBlock`. This should be as close as possible, but more
-		/// than the actual value, in order to have accurate benchmarks.
-		type MaxErasToCheckPerBlock: Get<u32>;
-
 		/// Use only for benchmarking.
 		#[cfg(feature = "runtime-benchmarks")]
 		type MaxBackersPerValidator: Get<u32>;
 	}
 
 	/// The current "head of the queue" being unstaked.
+	///
+	/// The head in itself can be a batch of up to [`Config::BatchSize`] stakers.
 	#[pallet::storage]
 	pub type Head<T: Config> = StorageValue<_, UnstakeRequest<T>, OptionQuery>;
 
 	/// The map of all accounts wishing to be unstaked.
 	///
 	/// Keeps track of `AccountId` wishing to unstake and it's corresponding deposit.
-	///
-	/// TWOX-NOTE: SAFE since `AccountId` is a secure hash.
+	// Hasher: Twox safe since `AccountId` is a secure hash.
 	#[pallet::storage]
 	pub type Queue<T: Config> = CountedStorageMap<_, Twox64Concat, T::AccountId, BalanceOf<T>>;
 
 	/// Number of eras to check per block.
 	///
-	/// If set to 0, this pallet does absolutely nothing.
+	/// If set to 0, this pallet does absolutely nothing. Cannot be set to more than
+	/// [`Config::MaxErasToCheckPerBlock`].
 	///
-	/// Based on the amount of weight available at `on_idle`, up to this many eras of a single
-	/// nominator might be checked.
+	/// Based on the amount of weight available at [`Pallet::on_idle`], up to this many eras of a
+	/// [`UnstakeRequest`], stored in [`Head`] might be checked.
 	#[pallet::storage]
+	#[pallet::getter(fn eras_to_check_per_block)]
 	pub type ErasToCheckPerBlock<T: Config> = StorageValue<_, u32, ValueQuery>;
 
-	/// The events of this pallet.
 	#[pallet::event]
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config> {
@@ -244,8 +255,13 @@ pub mod pallet {
 	impl<T: Config> Pallet<T> {
 		/// Register oneself for fast-unstake.
 		///
-		/// The dispatch origin of this call must be signed by the controller account, similar to
-		/// `staking::unbond`.
+		///
+		/// ## Dispatch Origin
+		///
+		/// The dispatch origin of this call must be *signed* by the whoever is permitted by to call
+		/// unbond funds by the staking system. See [`Config::Staking`].
+		///
+		/// ## Details
 		///
 		/// The stash associated with the origin must have no ongoing unlocking chunks. If
 		/// successful, this will fully unbond and chill the stash. Then, it will enqueue the stash
@@ -285,11 +301,18 @@ pub mod pallet {
 
 		/// Deregister oneself from the fast-unstake.
 		///
+		/// ## Dispatch Origin
+		///
+		/// The dispatch origin of this call must be *signed* by the whoever is permitted by to call
+		/// unbond funds by the staking system. See [`Config::Staking`].
+		///
+		/// ## Details
+		///
 		/// This is useful if one is registered, they are still waiting, and they change their mind.
 		///
 		/// Note that the associated stash is still fully unbonded and chilled as a consequence of
-		/// calling `register_fast_unstake`. This should probably be followed by a call to
-		/// `Staking::rebond`.
+		/// calling [`Pallet::register_fast_unstake`]. THerefore, this should probably be followed
+		/// by a call to `rebond` in the staking system.
 		#[pallet::call_index(1)]
 		#[pallet::weight(<T as Config>::WeightInfo::deregister())]
 		pub fn deregister(origin: OriginFor<T>) -> DispatchResult {
@@ -315,7 +338,13 @@ pub mod pallet {
 
 		/// Control the operation of this pallet.
 		///
-		/// Dispatch origin must be signed by the [`Config::ControlOrigin`].
+		/// ## Dispatch Origin
+		///
+		/// The dispatch origin of this call must be [`Config::ControlOrigin`].
+		///
+		/// ## Details
+		///
+		/// Can set the number of eras to check per block, and potentially other admin work.
 		#[pallet::call_index(2)]
 		#[pallet::weight(<T as Config>::WeightInfo::control())]
 		pub fn control(origin: OriginFor<T>, eras_to_check: EraIndex) -> DispatchResult {

frame/fast-unstake/src/tests.rs

@@ -303,6 +303,7 @@ mod on_idle {
 		});
 	}
 
+	#[docify::export]
 	#[test]
 	fn successful_multi_queue() {
 		ExtBuilder::default().build_and_execute(|| {
@@ -356,6 +357,7 @@ mod on_idle {
 		});
 	}
 
+	#[docify::export]
 	#[test]
 	fn successful_unstake() {
 		ExtBuilder::default().build_and_execute(|| {
@@ -694,6 +696,7 @@ mod on_idle {
 	}
 
 	#[test]
+	#[docify::export]
 	fn exposed_nominator_cannot_unstake() {
 		ExtBuilder::default().build_and_execute(|| {
 			ErasToCheckPerBlock::<T>::put(1);

frame/fast-unstake/src/types.rs

@@ -17,7 +17,7 @@
 
 //! Types used in the Fast Unstake pallet.
 
-use crate::{Config, MaxChecking};
+use crate::Config;
 use codec::{Decode, Encode, MaxEncodedLen};
 use frame_support::{
 	traits::Currency, BoundedVec, EqNoBound, PartialEqNoBound, RuntimeDebugNoBound,
@@ -26,16 +26,32 @@ use scale_info::TypeInfo;
 use sp_staking::EraIndex;
 use sp_std::prelude::*;
 
-pub type BalanceOf<T> =
+/// Maximum number of eras that we might check for a single staker.
+///
+/// In effect, it is the bonding duration, coming from [`Config::Staking`], plus one.
+#[derive(scale_info::TypeInfo, codec::Encode, codec::Decode, codec::MaxEncodedLen)]
+#[codec(mel_bound(T: Config))]
+#[scale_info(skip_type_params(T))]
+pub struct MaxChecking<T: Config>(sp_std::marker::PhantomData<T>);
+impl<T: Config> frame_support::traits::Get<u32> for MaxChecking<T> {
+	fn get() -> u32 {
+		T::Staking::bonding_duration() + 1
+	}
+}
+
+pub(crate) type BalanceOf<T> =
 	<<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
 /// An unstake request.
+///
+/// This is stored in [`crate::Head`] storage item and points to the current unstake request that is
+/// being processed.
 #[derive(
 	Encode, Decode, EqNoBound, PartialEqNoBound, Clone, TypeInfo, RuntimeDebugNoBound, MaxEncodedLen,
 )]
 #[scale_info(skip_type_params(T))]
 pub struct UnstakeRequest<T: Config> {
-	/// This list of stashes being processed in this request, and their corresponding deposit.
-	pub(crate) stashes: BoundedVec<(T::AccountId, BalanceOf<T>), T::BatchSize>,
+	/// This list of stashes are being processed in this request, and their corresponding deposit.
+	pub stashes: BoundedVec<(T::AccountId, BalanceOf<T>), T::BatchSize>,
 	/// The list of eras for which they have been checked.
-	pub(crate) checked: BoundedVec<EraIndex, MaxChecking<T>>,
+	pub checked: BoundedVec<EraIndex, MaxChecking<T>>,
 }

frame/support/procedural/src/pallet/expand/call.rs

@@ -113,7 +113,13 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 	}
 	debug_assert_eq!(fn_weight.len(), methods.len());
 
-	let fn_doc = methods.iter().map(|method| &method.docs).collect::<Vec<_>>();
+	let fn_doc = methods
+		.iter()
+		.map(|method| {
+			let reference = format!("See [`Pallet::{}`].", method.name);
+			quote!(#reference)
+		})
+		.collect::<Vec<_>>();
 
 	let args_name = methods
 		.iter()
@@ -175,9 +181,8 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 			.collect::<Vec<_>>()
 	});
 
-	let default_docs = [syn::parse_quote!(
-		r"Contains one variant per dispatchable that can be called by an extrinsic."
-	)];
+	let default_docs =
+		[syn::parse_quote!(r"Contains a variant per dispatchable extrinsic that this pallet has.")];
 	let docs = if docs.is_empty() { &default_docs[..] } else { &docs[..] };
 
 	let maybe_compile_error = if def.call.is_none() {
@@ -274,7 +279,7 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
 				#frame_support::Never,
 			),
 			#(
-				#( #[doc = #fn_doc] )*
+				#[doc = #fn_doc]
 				#[codec(index = #call_index)]
 				#fn_name {
 					#(