docs: move start-related docs to EventScanner + list specific possible errors

Author: 0xNeshi

src/event_scanner/scanner/historic.rs

@@ -124,19 +124,16 @@ impl EventScannerBuilder<Historic> {
 }
 
 impl<N: Network> EventScanner<Historic, N> {
-    /// Starts the scanner.
+    /// Starts the scanner in [`Historic`] mode.
     ///
-    /// # Important notes
-    ///
-    /// * Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
-    ///   this function.
-    /// * The method returns immediately; events are delivered asynchronously.
+    /// See [`EventScanner`] for general startup notes.
     ///
     /// # Errors
     ///
-    /// Can error out if the service fails to start.
-    ///
-    /// [subscribe]: EventScanner::subscribe
+    /// * [`ScannerError::ServiceShutdown`] - if the internal block-range service cannot be started.
+    /// * [`ScannerError::Timeout`] - if an RPC call required for startup times out.
+    /// * [`ScannerError::RpcError`] - if an RPC call required for startup fails.
+    /// * [`ScannerError::BlockNotFound`] - if `from_block` or `to_block` cannot be resolved.
     pub async fn start(self) -> Result<(), ScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.stream_historical(self.config.from_block, self.config.to_block).await?;

src/event_scanner/scanner/latest.rs

@@ -135,19 +135,16 @@ impl EventScannerBuilder<LatestEvents> {
 }
 
 impl<N: Network> EventScanner<LatestEvents, N> {
-    /// Starts the scanner.
+    /// Starts the scanner in [`LatestEvents`] mode.
     ///
-    /// # Important notes
-    ///
-    /// * Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
-    ///   this function.
-    /// * The method returns immediately; events are delivered asynchronously.
+    /// See [`EventScanner`] for general startup notes.
     ///
     /// # Errors
     ///
-    /// Can error out if the service fails to start.
-    ///
-    /// [subscribe]: EventScanner::subscribe
+    /// * [`ScannerError::ServiceShutdown`] - if the internal block-range service cannot be started.
+    /// * [`ScannerError::Timeout`] - if an RPC call required for startup times out.
+    /// * [`ScannerError::RpcError`] - if an RPC call required for startup fails.
+    /// * [`ScannerError::BlockNotFound`] - if `from_block` or `to_block` cannot be resolved.
     pub async fn start(self) -> Result<(), ScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.rewind(self.config.from_block, self.config.to_block).await?;

src/event_scanner/scanner/live.rs

@@ -59,19 +59,15 @@ impl EventScannerBuilder<Live> {
 }
 
 impl<N: Network> EventScanner<Live, N> {
-    /// Starts the scanner.
+    /// Starts the scanner in [`Live`] mode.
     ///
-    /// # Important notes
-    ///
-    /// * Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
-    ///   this function.
-    /// * The method returns immediately; events are delivered asynchronously.
+    /// See [`EventScanner`] for general startup notes.
     ///
     /// # Errors
     ///
-    /// Can error out if the service fails to start.
-    ///
-    /// [subscribe]: EventScanner::subscribe
+    /// * [`ScannerError::ServiceShutdown`] - if the internal block-range service cannot be started.
+    /// * [`ScannerError::Timeout`] - if an RPC call required for startup times out.
+    /// * [`ScannerError::RpcError`] - if an RPC call required for startup fails.
     pub async fn start(self) -> Result<(), ScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream = client.stream_live(self.config.block_confirmations).await?;

src/event_scanner/scanner/mod.rs

@@ -142,6 +142,18 @@ impl Default for Live {
 ///
 /// Create an instance via [`EventScannerBuilder`], register subscriptions with
 /// [`EventScanner::subscribe`], then start the scanner with the mode-specific `start()` method.
+///
+/// # Starting the scanner
+///
+/// All scanner modes follow the same general startup pattern:
+///
+/// - **Register subscriptions first**: call [`EventScanner::subscribe`] before starting the scanner
+///   with `start()`. The scanner sends events only to subscriptions that have already been
+///   registered.
+/// - **Non-blocking start**: `start()` returns immediately after spawning background tasks.
+///   Subscription streams yield events asynchronously.
+/// - **Errors after startup**: most runtime failures are delivered through subscription streams as
+///   [`ScannerError`] items, rather than being returned from `start()`.
 pub struct EventScanner<M = Unspecified, N: Network = Ethereum> {
     config: M,
     block_range_scanner: ConnectedBlockRangeScanner<N>,

src/event_scanner/scanner/sync/from_block.rs

@@ -66,19 +66,16 @@ impl EventScannerBuilder<SyncFromBlock> {
 }
 
 impl<N: Network> EventScanner<SyncFromBlock, N> {
-    /// Starts the scanner.
+    /// Starts the scanner in [`SyncFromBlock`] mode.
     ///
-    /// # Important notes
-    ///
-    /// * Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
-    ///   this function.
-    /// * The method returns immediately; events are delivered asynchronously.
+    /// See [`EventScanner`] for general startup notes.
     ///
     /// # Errors
     ///
-    /// Can error out if the service fails to start.
-    ///
-    /// [subscribe]: EventScanner::subscribe
+    /// * [`ScannerError::ServiceShutdown`] - if the internal block-range service cannot be started.
+    /// * [`ScannerError::Timeout`] - if an RPC call required for startup times out.
+    /// * [`ScannerError::RpcError`] - if an RPC call required for startup fails.
+    /// * [`ScannerError::BlockNotFound`] - if `from_block` cannot be resolved.
     pub async fn start(self) -> Result<(), ScannerError> {
         let client = self.block_range_scanner.run()?;
         let stream =

src/event_scanner/scanner/sync/from_latest.rs

@@ -67,19 +67,15 @@ impl EventScannerBuilder<SyncFromLatestEvents> {
 }
 
 impl<N: Network> EventScanner<SyncFromLatestEvents, N> {
-    /// Starts the scanner.
+    /// Starts the scanner in [`SyncFromLatestEvents`] mode.
     ///
-    /// # Important notes
-    ///
-    /// * Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
-    ///   this function.
-    /// * The method returns immediately; events are delivered asynchronously.
+    /// See [`EventScanner`] for general startup notes.
     ///
     /// # Errors
     ///
-    /// Can error out if the service fails to start.
-    ///
-    /// [subscribe]: EventScanner::subscribe
+    /// * [`ScannerError::ServiceShutdown`] - if the internal block-range service cannot be started.
+    /// * [`ScannerError::Timeout`] - if an RPC call required for startup times out.
+    /// * [`ScannerError::RpcError`] - if an RPC call required for startup fails.
     #[allow(clippy::missing_panics_doc)]
     pub async fn start(self) -> Result<(), ScannerError> {
         let count = self.config.count;