Co-authored-by: Keith Yeung <kungfukeith11@gmail.com>

Ammend comments related to documentation

frame/scheduler/src/lib.rs

@@ -15,29 +15,49 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! > Made with *Substrate*, for *Polkadot*.
+//!
+//! [![github]](https://github.com/paritytech/substrate/frame/fast-unstake) -
+//! [![polkadot]](https://polkadot.network)
+//!
+//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
+//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
+//!
 //! # Scheduler Pallet
 //!
 //! A Pallet for scheduling runtime calls.
 //!
 //! ## Overview
 //!
-//! This Pallet exposes capabilities for scheduling runtime calls to occur at a
-//! specified block number or at a specified period. These scheduled runtime calls
-//! may be named or anonymous and may be canceled.
+//! This Pallet exposes capabilities for scheduling runtime calls to occur at a specified block
+//! number or at a specified period. These scheduled runtime calls may be named or anonymous and may
+//! be canceled.
 //!
-//! **NOTE:** Instead of the filter contained in the origin used to call `fn schedule`, scheduled runtime calls will be 
-//! dispatched with the default filter for the origin: namely `frame_system::Config::BaseCallFilter` for all origin
-//! types (except root which will get no filter).
+//! **NOTE:** Instead of the filter contained in the origin used to call `fn schedule`, scheduled
+//! runtime calls will be dispatched with the default filter for the origin: namely
+//! `frame_system::Config::BaseCallFilter` for all origin types (except root which will get no
+//! filter).
+//!
+//! If a call is scheduled using proxy or whatever mecanism which adds filter, then those filter
+//! will not be used when dispatching the schedule runtime call.
+//!
+//! ### Examples
 //!
-//! If a call is scheduled using proxy or whatever mecanism which adds filter,
-//! then those filter will not be used when dispatching the schedule runtime call.
+//! 1. Scheduling a runtime call at a specific block.
+#![doc = docify::embed!("src/tests.rs", basic_scheduling_works)]
+//!
+//! 2. Scheduling a preimage hash of a runtime call at a specifc block
+#![doc = docify::embed!("src/tests.rs", scheduling_with_preimages_works)]
+// Ensure we're `no_std` when compiling for Wasm.
+#![cfg_attr(not(feature = "std"), no_std)]
 //!
 //! ## Pallet API
 //!
 //! See the [`pallet`] module for more information about the interfaces this pallet exposes,
 //! including its configuration trait, dispatchables, storage items, events and errors.
 //!
-//! ### Warning
+//!
+//! ## Warning
 //!
 //! This Pallet executes all scheduled runtime calls in the
 //! [`frame_support::traits::Hooks::on_initialize`] hook.
@@ -61,18 +81,8 @@
 //!     * Could lead to undefined behavior.
 //! * Removed or changed the ordering/index of the runtime call.
 //!     * Could fail due to the runtime call index not being part of the `Call`.
-//!     * Could lead to unintended behavior, such as executing another runtime call with the same
+//!     * Could lead to undefined behavior, such as executing another runtime call with the same
 //!       index.
-//!
-//! ### Examples
-//!
-//! 1. Scheduling a runtime call at a specific block
-#![doc = docify::embed!("src/tests.rs", basic_scheduling_works)]
-//!
-//! 2. Scheduling a preimage hash of a runtime call at a specifc block
-#![doc = docify::embed!("src/tests.rs", scheduling_with_preimages_works)]
-// Ensure we're `no_std` when compiling for Wasm.
-#![cfg_attr(not(feature = "std"), no_std)]
 
 #[cfg(feature = "runtime-benchmarks")]
 mod benchmarking;

frame/scheduler/src/tests.rs

@@ -33,20 +33,31 @@ use substrate_test_utils::assert_eq_uvec;
 #[docify::export]
 fn basic_scheduling_works() {
 	new_test_ext().execute_with(|| {
+		// Call to schedule
 		let call =
 			RuntimeCall::Logger(LoggerCall::log { i: 42, weight: Weight::from_parts(10, 0) });
+
+		// BaseCallFilter should be implemented to accept `Logger::log` runtime call which is
+		// implemented for `BaseFilter` in the mock runtime
 		assert!(!<Test as frame_system::Config>::BaseCallFilter::contains(&call));
+
+		// Schedule call to be executed at the the 4th block
 		assert_ok!(Scheduler::do_schedule(
 			DispatchTime::At(4),
 			None,
 			127,
 			root(),
 			Preimage::bound(call).unwrap()
 		));
+
+		// `log` runtime call should not have executed yet
 		run_to_block(3);
 		assert!(logger::log().is_empty());
+
 		run_to_block(4);
+		// `log` runtime call should have executed at block 4
 		assert_eq!(logger::log(), vec![(root(), 42u32)]);
+
 		run_to_block(100);
 		assert_eq!(logger::log(), vec![(root(), 42u32)]);
 	});
@@ -56,21 +67,35 @@ fn basic_scheduling_works() {
 #[docify::export]
 fn scheduling_with_preimages_works() {
 	new_test_ext().execute_with(|| {
+		// Call to schedule
 		let call =
 			RuntimeCall::Logger(LoggerCall::log { i: 42, weight: Weight::from_parts(10, 0) });
+
 		let hash = <Test as frame_system::Config>::Hashing::hash_of(&call);
 		let len = call.using_encoded(|x| x.len()) as u32;
-		// Important to use here `Bounded::Lookup` to ensure that we request the hash.
+
+		// Important to use here `Bounded::Lookup` to ensure that that the Scheduler can request the
+		// hash from PreImage to dispatch the call
 		let hashed = Bounded::Lookup { hash, len };
+
+		// Schedule call to be executed at block 4 with the PreImage hash
 		assert_ok!(Scheduler::do_schedule(DispatchTime::At(4), None, 127, root(), hashed));
+
+		// Register preimage on chain
 		assert_ok!(Preimage::note_preimage(RuntimeOrigin::signed(0), call.encode()));
 		assert!(Preimage::is_requested(&hash));
+
+		// `log` runtime call should not have executed yet
 		run_to_block(3);
 		assert!(logger::log().is_empty());
+
 		run_to_block(4);
+		// preimage should no have been removed when executed by the scheduler
 		assert!(!Preimage::len(&hash).is_some());
 		assert!(!Preimage::is_requested(&hash));
+		// `log` runtime call should have executed at block 4
 		assert_eq!(logger::log(), vec![(root(), 42u32)]);
+
 		run_to_block(100);
 		assert_eq!(logger::log(), vec![(root(), 42u32)]);
 	});