docs: minor reorg-related updates + fix doc link + dashes to stars (#235)

Author: 0xNeshi

src/event_scanner/scanner/common.rs

@@ -35,8 +35,8 @@ pub enum ConsumerMode {
 ///
 /// Log consumers are tightly coupled with the `ConsumerMode` because the mode dictates their
 /// entire lifecycle and behavior:
-/// - `Stream` mode: consumers forward logs immediately as they arrive
-/// - `CollectLatest` mode: consumers accumulate logs and send them only at the end
+/// * `Stream` mode: consumers forward logs immediately as they arrive
+/// * `CollectLatest` mode: consumers accumulate logs and send them only at the end
 ///
 /// This tight coupling means consumers cannot be reused across different modes. For example,
 /// the "sync from latest" scanning strategy needs to run two modes sequentially (first

src/event_scanner/scanner/mod.rs

@@ -130,12 +130,14 @@ impl EventScannerBuilder<Unspecified> {
     ///
     /// # Key behaviors
     ///
-    /// - **Continuous streaming**: Events are delivered in multiple messages as they are fetched
-    /// - **Chronological order**: Events are always delivered oldest to newest
-    /// - **Default range**: By default, scans from `Earliest` to `Latest` block
-    /// - **Batch control**: Use `.max_block_range(n)` to control how many blocks are queried per
+    /// * **Continuous streaming**: Events are delivered in multiple messages as they are fetched
+    /// * **Chronological order**: Events are always delivered oldest to newest
+    /// * **Default range**: By default, scans from `Earliest` to `Latest` block
+    /// * **Batch control**: Use `.max_block_range(n)` to control how many blocks are queried per
     ///   RPC call
-    /// - **Completion**: The scanner completes when the entire range has been processed
+    /// * **Reorg handling**: Performs reorg checks when streaming events from non-finalized blocks;
+    ///   if a reorg is detected, streams events from the reorged blocks
+    /// * **Completion**: The scanner completes when the entire range has been processed.
     #[must_use]
     pub fn historic() -> EventScannerBuilder<Historic> {
         EventScannerBuilder::default()
@@ -190,11 +192,11 @@ impl EventScannerBuilder<Unspecified> {
     ///
     /// # Key behaviors
     ///
-    /// - **Real-time streaming**: Events are delivered as new blocks are confirmed
-    /// - **Reorg protection**: Waits for configured confirmations before emitting events
-    /// - **Continuous operation**: Runs indefinitely until the scanner is dropped or encounters an
+    /// * **Real-time streaming**: Events are delivered as new blocks are confirmed
+    /// * **Reorg protection**: Waits for configured confirmations before emitting events
+    /// * **Continuous operation**: Runs indefinitely until the scanner is dropped or encounters an
     ///   error
-    /// - **Default confirmations**: By default, waits for 12 block confirmations
+    /// * **Default confirmations**: By default, waits for 12 block confirmations
     ///
     /// # Reorg behavior
     ///
@@ -222,8 +224,8 @@ impl EventScannerBuilder<Unspecified> {
     /// EventScannerBuilder::sync().from_latest(10);
     /// ```
     ///
-    /// See [`from_block`](EventScannerBuilder::from_block) and
-    /// [`from_latest`](EventScannerBuilder::from_latest) for details on each mode.
+    /// See [`from_block`](crate::EventScannerBuilder#method.from_block-2) and
+    /// [`from_latest`](crate::EventScannerBuilder#method.from_latest) for details on each mode.
     #[must_use]
     pub fn sync() -> EventScannerBuilder<Synchronize> {
         EventScannerBuilder::default()
@@ -290,20 +292,20 @@ impl EventScannerBuilder<Unspecified> {
     ///
     /// # Key behaviors
     ///
-    /// - **Single delivery**: Each registered stream receives at most `count` logs in a single
+    /// * **Single delivery**: Each registered stream receives at most `count` logs in a single
     ///   message, chronologically ordered
-    /// - **One-shot operation**: The scanner completes after delivering messages; it does not
+    /// * **One-shot operation**: The scanner completes after delivering messages; it does not
     ///   continue streaming
-    /// - **Flexible count**: If fewer than `count` events exist in the range, returns all available
+    /// * **Flexible count**: If fewer than `count` events exist in the range, returns all available
     ///   events
-    /// - **Default range**: By default, scans from `Earliest` to `Latest` block
-    /// - **Reorg handling**: Periodically checks the tip to detect reorgs during the scan
+    /// * **Default range**: By default, scans from `Earliest` to `Latest` block
+    /// * **Reorg handling**: Periodically checks the tip to detect reorgs during the scan
     ///
     /// # Notifications
     ///
     /// The scanner emits the following notification before delivering log data:
     ///
-    /// - **[`Notification::NoPastLogsFound`][no_logs]**: Emitted when no matching logs are found in
+    /// * **[`Notification::NoPastLogsFound`][no_logs]**: Emitted when no matching logs are found in
     ///   the scanned range.
     ///
     /// # Arguments
@@ -392,10 +394,10 @@ impl<M> EventScannerBuilder<M> {
     /// # Example
     ///
     /// If scanning events from blocks 1000–1099 (100 blocks total) with `max_block_range(30)`:
-    /// - Batch 1: blocks 1000–1029 (30 blocks)
-    /// - Batch 2: blocks 1030–1059 (30 blocks)
-    /// - Batch 3: blocks 1060–1089 (30 blocks)
-    /// - Batch 4: blocks 1090–1099 (10 blocks)
+    /// * Batch 1: blocks 1000–1029 (30 blocks)
+    /// * Batch 2: blocks 1030–1059 (30 blocks)
+    /// * Batch 3: blocks 1060–1089 (30 blocks)
+    /// * Batch 4: blocks 1090–1099 (10 blocks)
     #[must_use]
     pub fn max_block_range(mut self, max_block_range: u64) -> Self {
         self.block_range_scanner.max_block_range = max_block_range;

src/event_scanner/scanner/sync/mod.rs

@@ -71,20 +71,20 @@ impl EventScannerBuilder<Synchronize> {
     ///
     /// # Key behaviors
     ///
-    /// - **No duplicates**: Events are not delivered twice across the phase transition
-    /// - **Flexible count**: If fewer than `count` events exist, returns all available events
-    /// - **Reorg handling**: Both phases handle reorgs appropriately:
+    /// * **No duplicates**: Events are not delivered twice across the phase transition
+    /// * **Flexible count**: If fewer than `count` events exist, returns all available events
+    /// * **Reorg handling**: Both phases handle reorgs appropriately:
     ///   - Latest events phase: resets and rescans on reorg detection
     ///   - Live phase: resets stream to the first post-reorg block that satisfies the configured
     ///     block confirmations
-    /// - **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
+    /// * **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
     ///
     /// # Notifications
     ///
     /// During the **latest events phase**, the scanner can emit the following notification
     /// before transitioning to live mode:
     ///
-    /// - **[`Notification::NoPastLogsFound`][no_logs]**: Emitted when no matching logs are found in
+    /// * **[`Notification::NoPastLogsFound`][no_logs]**: Emitted when no matching logs are found in
     ///   the scanned range
     ///
     /// After the latest events phase completes, [`Notification::SwitchingToLive`][switch_to_live]
@@ -97,15 +97,15 @@ impl EventScannerBuilder<Synchronize> {
     ///
     /// # Important notes
     ///
-    /// - The live phase continues indefinitely until the scanner is dropped or encounters an error
+    /// * The live phase continues indefinitely until the scanner is dropped or encounters an error
     ///
     /// # Detailed reorg behavior
     ///
-    /// - **Latest events phase**: Restart the scanner. On detecting a reorg, emits
+    /// * **Latest events phase**: Restart the scanner. On detecting a reorg, emits
     ///   [`Notification::ReorgDetected`][reorg], resets the rewind start to the new tip, and
     ///   continues until collectors accumulate `count` logs. Final delivery to listeners preserves
     ///   chronological order.
-    /// - **Live streaming phase**: Starts from `latest_block + 1` and respects the configured block
+    /// * **Live streaming phase**: Starts from `latest_block + 1` and respects the configured block
     ///   confirmations. On reorg, emits [`Notification::ReorgDetected`][reorg], adjusts the next
     ///   confirmed window (possibly re-emitting confirmed portions), and continues streaming.
     ///
@@ -203,7 +203,7 @@ impl EventScannerBuilder<Synchronize> {
     /// * **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
     /// * **Reorg detection**: When a reorg is detected, [`Notification::ReorgDetected`][reorg] is
     ///   emitted, the next confirmed window is adjusted to stream the reorged blocks, and continues
-    ///   streaming.
+    ///   streaming. While syncing, reorg checks are only performed for non-finalized blocks.
     ///
     /// # Arguments
     ///