docs: add a few more docs to ControlFlow (#3603)

crates/consensus/beacon/src/engine/mod.rs

@@ -1306,7 +1306,7 @@ where
 
                 // update the canon chain if continuous is enabled
                 if self.sync.run_pipeline_continuously() {
-                    let max_block = ctrl.progress().unwrap_or_default();
+                    let max_block = ctrl.block_number().unwrap_or_default();
                     let max_header = match self.blockchain.sealed_header(max_block) {
                         Ok(header) => match header {
                             Some(header) => header,
@@ -1371,7 +1371,7 @@ where
                     // If both are Some, we perform another distance check and return the desired
                     // pipeline target
                     let pipeline_target = if let (Some(progress), Some(finalized_number)) =
-                        (ctrl.progress(), newest_finalized)
+                        (ctrl.block_number(), newest_finalized)
                     {
                         // Determines whether or not we should run the pipeline again, in case the
                         // new gap is large enough to warrant running the pipeline.

crates/stages/src/pipeline/ctrl.rs

@@ -1,6 +1,8 @@
 use reth_primitives::{BlockNumber, SealedHeader};
 
 /// Determines the control flow during pipeline execution.
+///
+/// See [Pipeline::run_loop](crate::Pipeline::run_loop) for more information.
 #[derive(Debug, Eq, PartialEq)]
 pub enum ControlFlow {
     /// An unwind was requested and must be performed before continuing.
@@ -10,7 +12,7 @@ pub enum ControlFlow {
         /// The block that caused the unwind.
         bad_block: SealedHeader,
     },
-    /// The pipeline is allowed to continue executing stages.
+    /// The pipeline made progress.
     Continue {
         /// Block number reached by the stage.
         block_number: BlockNumber,
@@ -33,8 +35,8 @@ impl ControlFlow {
         matches!(self, ControlFlow::Unwind { .. })
     }
 
-    /// Returns the pipeline progress, if the state is not `Unwind`.
-    pub fn progress(&self) -> Option<BlockNumber> {
+    /// Returns the pipeline block number the stage reached, if the state is not `Unwind`.
+    pub fn block_number(&self) -> Option<BlockNumber> {
         match self {
             ControlFlow::Unwind { .. } => None,
             ControlFlow::Continue { block_number } => Some(*block_number),

crates/stages/src/pipeline/mod.rs

@@ -206,6 +206,11 @@ where
     /// If any stage is unsuccessful at execution, we proceed to
     /// unwind. This will undo the progress across the entire pipeline
     /// up to the block that caused the error.
+    ///
+    /// Returns the control flow after it ran the pipeline.
+    /// This will be [ControlFlow::Continue] or [ControlFlow::NoProgress] of the _last_ stage in the
+    /// pipeline (for example the `Finish` stage). Or [ControlFlow::Unwind] of the stage that caused
+    /// the unwind.
     pub async fn run_loop(&mut self) -> Result<ControlFlow, PipelineError> {
         let mut previous_stage = None;
         for stage_index in 0..self.stages.len() {