pallet-grandpa: Improve/Clarify docs of note_stalled (#11623)

substrate/frame/grandpa/src/lib.rs

@@ -231,12 +231,17 @@ pub mod pallet {
 			)
 		}
 
-		/// Note that the current authority set of the GRANDPA finality gadget has
+		/// Note that the current authority set of the GRANDPA finality gadget has stalled.
-		/// stalled. This will trigger a forced authority set change at the beginning
+		///
-		/// of the next session, to be enacted `delay` blocks after that. The delay
+		/// This will trigger a forced authority set change at the beginning of the next session, to
-		/// should be high enough to safely assume that the block signalling the
+		/// be enacted `delay` blocks after that. The `delay` should be high enough to safely assume
-		/// forced change will not be re-orged (e.g. 1000 blocks). The GRANDPA voters
+		/// that the block signalling the forced change will not be re-orged e.g. 1000 blocks.
-		/// will start the new authority set using the given finalized block as base.
+		/// The block production rate (which may be slowed down because of finality lagging) should
+		/// be taken into account when choosing the `delay`. The GRANDPA voters based on the new
+		/// authority will start voting on top of `best_finalized_block_number` for new finalized
+		/// blocks. `best_finalized_block_number` should be the highest of the latest finalized
+		/// block of all validators of the new authority set.
+		///
 		/// Only callable by root.
 		#[pallet::weight(T::WeightInfo::note_stalled())]
 		pub fn note_stalled(