Repository: paritytech/substrate
File: frame/support/src/traits/hooks.rs (Rust)

Code before:
	///
	/// 1. is called after [`on_initialize`] of all pallets is done executing,
	/// 2. execution on *each block* is not guaranteed
	///
	/// The latter point is usually correlated with the block resources being available, for example
	/// `Weight` leftover.
	fn poll(_n: BlockNumber) -> Weight {
		Weight::zero()
	}

	/// Block finalization hook. This is called at the very end of block execution.
	///
	/// Note that this has nothing to do with finality in the "consensus" sense.
	///
	/// Note that the non-negotiable weight for this has must have already been returned by
	/// [`OnInitialize`]. It usage along is not permitted.
	///
	/// Similar to [`OnInitialize`] it should only be used when execution is absolutely necessary.
	fn on_finalize(_n: BlockNumber) {}

	/// Hook to consume a block's idle time. This will run when the block is being finalized (before
	/// [`on_finalize`]).
	///
	/// Given that all dispatchables are already executed and noted, and the weight for
	/// [`on_finalize`], which comes next, is also already accounted for (via `on_initialize`), this
	/// hook consumes anything that is leftover.
	///
	/// Each pallet's `on_idle` is chosen to be the first to execute in a round-robin fashion
	/// indexed by the block number.
	///
	/// Return the weight used, the caller will use this to calculate the remaining weight and then
	/// call the next pallet `on_idle` hook if there is still weight left.
	///
	/// Any implementation should always respect `_remaining_weight` and never consume (and
	/// therefore return) more than this amount.
	fn on_idle(_n: BlockNumber, _remaining_weight: Weight) -> Weight {
		Weight::zero()
	}

	/// Hook executed when a code change (aka. a "runtime upgrade") is detected by FRAME.
	///
	/// Be aware that this is called before [`on_initialize`] of any pallet, therefore a lot of the
	/// critical storage items such as `block_number` in system pallet might not been set.
	///
	/// Vert similar to [`on_initialize`], any code in this block is mandatory and MUST execute. Use
	/// with care.
	///
	/// ## Implementation Note: Versioning
	///
	/// 1. An implementation of this should typically follow a pattern where the version of the
	/// pallet is checked against the onchain version, and a decision is made about what needs to be

Review comment (suggestion):
I get confused with many commas, maybe something like this?

```suggestion
	/// Given that all dispatchables are already executed and noted (and the weight for
	/// [`on_finalize`], which comes next, is also already accounted for via `on_initialize`), this
	/// hook consumes anything that is leftover.
```

Code after:
/// 	Extrinsic1
/// 	Extrinsic2
///
/// 	Inherent1 --> Inherent2
/// 	Inherent2 --> Extrinsic1
/// 	Extrinsic1 --> Extrinsic2
/// end
///
/// subgraph AfterExtrinsics
/// 	OnIdle
/// 	OnFinalize
///
/// 	OnIdle --> OnFinalize
/// end
/// ```
///
/// * `OnRuntimeUpgrade` is only executed before everything else if a code
/// * `OnRuntimeUpgrade` is mandatorily at the beginning of the block body (extrinsics) being
///   processed. change is detected.
/// * Extrinsics start with inherents, and continue with other signed or unsigned extrinsics.
/// * `OnIdle` optionally comes after extrinsics.
/// `OnFinalize` mandatorily comes after `OnIdle`.
///
/// > `OffchainWorker` is not part of this flow, as it is not really part of the consensus/main
/// > block import path, and is called optionally, and in other circumstances. See
/// > [`crate::traits::misc::OffchainWorker`] for more information.
///
/// To learn more about the execution of hooks see `frame-executive` as this component is is charge
/// of dispatching extrinsics and placing the hooks in the correct order.
pub trait Hooks<BlockNumber> {
	/// Block initialization hook. This is called at the very beginning of block execution.
	///
	/// Must return the non-negotiable weight of both itself and whatever [`Hooks::on_finalize`]
	/// wishes to consume.
	///
	/// The weight returned by this is treated as `DispatchClass::Mandatory`, meaning that
	/// it MUST BE EXECUTED. If this is not the case, consider using [`Hooks::on_idle`] instead.
	///
	/// NOTE: This function is called BEFORE ANY extrinsic in a block is applied, including inherent
	/// extrinsics. Hence for instance, if you runtime includes `pallet-timestamp`, the `timestamp`
	/// is not yet up to date at this point.
	fn on_initialize(_n: BlockNumber) -> Weight {
		Weight::zero()
	}

	/// Block finalization hook. This is called at the very end of block execution.
	///
	/// Note that this has nothing to do with finality in the "consensus" sense.
	///
	/// Note that the non-negotiable weight for this has must have already been returned by
	/// [`Hooks::on_initialize`]. It usage alone is not permitted.