Repository: paritytech/substrate
File: frame/scheduler/src/lib.rs (Rust)

Code before:
//! This Pallet executes all scheduled runtime calls in the
//! [`frame_support::traits::Hooks::on_initialize`] hook.
//!
//! **Do NOT schedule runtime calls if they satisfy any of the following points:**
//!
//! * [ ] Runtime call does not need to be executed at a specific block (not a hard requirement).
//! 	Use [`frame_support::traits::Hooks::on_idle`] hook for runtime calls that can be executed
//!   after some block but do not need to be executed at a specific block.
//! * [ ] No unbounded iterations.
//! * [ ] Runtime call weight exceeds configured [`Config::MaximumWeight`].
//! 	If you are scheduling a heavy weight runtime call, make sure to set the `MaximumWeight` type
//! according to your chain's needs. You can find the weight conversions to real time from these
//! [`sp_weights::constants`].
//!
//! Please be aware that any scheduled runtime calls executed in a future block may __fail__ or may
//! result in __undefined behavior__ since the runtime could have upgraded between the time of
//! scheduling and execution. For example, the runtime upgrade could have:
//!
//! * Modified the implementation of the runtime call (runtime specification upgrade).
//!     * 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 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;
pub mod migration;
#[cfg(test)]
mod mock;
#[cfg(test)]
mod tests;
pub mod weights;

use codec::{Decode, Encode, MaxEncodedLen};
use frame_support::{
	dispatch::{
		DispatchError, DispatchResult, Dispatchable, GetDispatchInfo, Parameter, RawOrigin,
	},
	ensure,
	traits::{

Review comment (suggestion):
I think what you saying here is more a property of `on_initialize` than this pallet. I would phrase is as this sequence: 

1. This pallet uses `on_initialize`
2. `on_initialize` has a mandatory property to it (which you can make sure is documented in the `Hooks` trait), and should only be used for _really_ mandatory stuff. There, you can also mention `on_idle`
4. Therefore, this pallet is also suitable for scheduling _really mandatory_ stuff. 


In other words, I don't think scheduler and `on_idle` are apples to apples. 

Code after:
//! will not be used when dispatching the schedule runtime call.
//!
//! ### 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)]

//!
//! ## 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
//!
//! This Pallet executes all scheduled runtime calls in the [`on_initialize`] hook. Do not execute
//! any runtime calls which should not be considered mandatory.
//!
//! Please be aware that any scheduled runtime calls executed in a future block may __fail__ or may
//! result in __undefined behavior__ since the runtime could have upgraded between the time of
//! scheduling and execution. For example, the runtime upgrade could have:
//!
//! * Modified the implementation of the runtime call (runtime specification upgrade).
//!     * 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 undefined behavior, such as executing another runtime call with the same
//!       index.
//!
//! [`on_initialize`]: frame_support::traits::Hooks::on_initialize

// Ensure we're `no_std` when compiling for Wasm.
#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(feature = "runtime-benchmarks")]
mod benchmarking;
pub mod migration;
#[cfg(test)]
mod mock;
#[cfg(test)]
mod tests;
pub mod weights;

use codec::{Decode, Encode, MaxEncodedLen};
use frame_support::{
	dispatch::{
		DispatchError, DispatchResult, Dispatchable, GetDispatchInfo, Parameter, RawOrigin,
	},