feat: add back comments to scanner start functions

Author: LeoPatOZ

src/event_scanner/modes/historic.rs

@@ -114,11 +114,14 @@ impl<N: Network> HistoricEventScanner<N> {
         ReceiverStream::new(receiver)
     }
 
-    /// Calls stream historical
+    /// Starts the scanner in historical mode.
+    ///
+    /// Scans from `from_block` to `to_block` (inclusive), emitting block ranges
+    /// and matching logs to registered listeners.
     ///
     /// # Errors
     ///
-    /// * `EventScannerMessage::ServiceShutdown` - if the service is already shutting down.
+    /// - `EventScannerMessage::ServiceShutdown` if the service is already shutting down.
     pub async fn start(self) -> Result<(), EventScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.stream_historical(self.config.from_block, self.config.to_block).await?;

src/event_scanner/modes/latest.rs

@@ -135,11 +135,21 @@ impl<N: Network> LatestEventScanner<N> {
         ReceiverStream::new(receiver)
     }
 
-    /// Calls stream latest
+    /// Scans a block range and collects the latest `count` matching events per registered listener.
+    ///
+    /// Emits a single message per listener with up to `count` logs, ordered oldest→newest.
+    ///
+    /// # Reorg behavior
+    ///
+    /// Performs a reverse-ordered rewind over the range, periodically checking the tip hash. If a
+    /// reorg is detected, emits [`ScannerStatus::ReorgDetected`], resets the rewind start to the
+    /// updated tip, and resumes until completion. Final log delivery preserves chronological order.
     ///
     /// # Errors
     ///
-    /// * `EventScannerMessage::ServiceShutdown` - if the service is already shutting down.
+    /// - Returns `EventScannerError` if the scanner fails to start or fetching logs fails.
+    ///
+    /// [`ScannerStatus::ReorgDetected`]: crate::types::ScannerStatus::ReorgDetected
     pub async fn start(self) -> Result<(), EventScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.rewind(self.config.from_block, self.config.to_block).await?;

src/event_scanner/modes/live.rs

@@ -104,11 +104,19 @@ impl<N: Network> LiveEventScanner<N> {
         ReceiverStream::new(receiver)
     }
 
-    /// Calls stream live
+    /// Starts the scanner in live mode.
+    ///
+    /// Streams new blocks as they are produced, applying the configured
+    /// `block_confirmations` to mitigate reorgs.
+    ///
+    /// # Reorg behavior
+    ///
+    /// - Emits [`ScannerStatus::ReorgDetected`] and adjusts the next confirmed
+    ///   range using `block_confirmations` to re-emit the confirmed portion.
     ///
     /// # Errors
     ///
-    /// * `EventScannerMessage::ServiceShutdown` - if the service is already shutting down.
+    /// - `EventScannerMessage::ServiceShutdown` if the service is already shutting down.
     pub async fn start(self) -> Result<(), EventScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.stream_live(self.config.block_confirmations).await?;

src/event_scanner/modes/sync.rs

@@ -114,11 +114,19 @@ impl<N: Network> SyncEventScanner<N> {
         ReceiverStream::new(receiver)
     }
 
-    /// Calls stream from
+    /// Starts the scanner in sync (historical → live) mode.
+    ///
+    /// Streams from `from_block` up to the current confirmed tip using the configured
+    /// `block_confirmations`, then continues streaming new confirmed ranges live.
+    ///
+    /// # Reorg behavior
+    ///
+    /// - In live mode, emits [`ScannerStatus::ReorgDetected`] and adjusts the next confirmed range
+    ///   using `block_confirmations` to re-emit the confirmed portion.
     ///
     /// # Errors
     ///
-    /// * `EventScannerMessage::ServiceShutdown` - if the service is already shutting down.
+    /// - `EventScannerMessage::ServiceShutdown` if the service is already shutting down.
     pub async fn start(self) -> Result<(), EventScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream =