fix(cardano-chain-follower): comments

Signed-off-by: bkioshn <[email protected]>

Author: bkioshn

rust/cardano-chain-follower/src/chain_sync.rs

@@ -40,7 +40,7 @@ use crate::{
 const MAX_NODE_CONNECT_TIME_SECS: u64 = 2;
 
 /// The maximum number of times we wait for a nodeChainUpdate to connect.
-/// Currently set to never give up.
+/// Currently set to maximum of 5 retries.
 const MAX_NODE_CONNECT_RETRIES: u64 = 5;
 
 /// Try and connect to a node, in a robust and quick way.
@@ -120,7 +120,7 @@ async fn resync_live_tip(client: &mut PeerClient, chain: Network) -> Result<Poin
     Ok(sync_to_point)
 }
 
-/// Fetch a single block from the Peer, and Decode it.
+/// Fetch a single block from the Peer, and decode it.
 async fn fetch_block_from_peer(
     peer: &mut PeerClient, chain: Network, point: Point, previous_point: Point, fork: Fork,
 ) -> anyhow::Result<MultiEraBlock> {

rust/cardano-chain-follower/src/chain_sync_config.rs

@@ -22,12 +22,13 @@ use crate::{
 /// Default Follower block buffer size.
 const DEFAULT_CHAIN_UPDATE_BUFFER_SIZE: usize = 32;
 
-/// How many slots back from TIP is considered Immutable in the absence of a mithril
-/// snapshot.
+/// How many window (in slot) back from TIP is considered Immutable in the 
+/// absence of a mithril snapshot.
 const DEFAULT_IMMUTABLE_SLOT_WINDOW: u64 = 12 * 60 * 60;
 
 /// Type we use to manage the Sync Task handle map.
 type SyncMap = DashMap<Network, Mutex<Option<JoinHandle<()>>>>;
+
 /// Handle to the mithril sync thread. One for each Network ONLY.
 static SYNC_JOIN_HANDLE_MAP: LazyLock<SyncMap> = LazyLock::new(|| {
     let map = DashMap::new();
@@ -68,7 +69,7 @@ impl ChainSyncConfig {
         }
     }
 
-    /// Sets the relay to use for Chain Sync.
+    /// Sets the relay address to use for Chain Sync.
     ///
     /// # Arguments
     ///
@@ -101,12 +102,11 @@ impl ChainSyncConfig {
         self
     }
 
-    /// Sets the the Mithril snapshot Config the `ChainSync` will use.
+    /// Sets the Mithril snapshot Config the `ChainSync` will use.
     ///
     /// # Arguments
     ///
-    /// * `path`: Mithril snapshot path.
-    /// * `update`: Auto-update this path with the latest mithril snapshot as it changes.
+    /// * `cfg`: Mithril snapshot configuration.
     #[must_use]
     pub fn mithril_cfg(mut self, cfg: MithrilSnapshotConfig) -> Self {
         self.mithril_cfg = cfg;
@@ -117,10 +117,6 @@ impl ChainSyncConfig {
     ///
     /// Must be done BEFORE the chain can be followed.
     ///
-    /// # Arguments
-    ///
-    /// * `chain`: The chain to follow.
-    ///
     /// # Returns
     ///
     /// `Result<()>`: On success.

rust/cardano-chain-follower/src/chain_sync_live_chains.rs

@@ -21,7 +21,7 @@ use crate::{
 /// Type we use to manage the Sync Task handle map.
 type LiveChainBlockList = SkipMap<Point, MultiEraBlock>;
 
-/// Because we have multi-entry relationships in the live-chain protect it with a
+/// Because we have multi-entry relationships in the live-chain, it need to protect it with a
 /// `read/write lock`. The underlying `SkipMap` is still capable of multiple simultaneous
 /// reads from multiple threads which is the most common access.
 #[derive(Clone)]
@@ -50,7 +50,8 @@ fn update_peer_tip(chain: Network, tip: Point) {
     PEER_TIP.insert(chain, tip);
 }
 
-/// Set the last TIP received from the peer.
+/// Get the last TIP received from the peer.
+/// If the peer tip doesn't exist, get the UNKNOWN point.
 pub(crate) fn get_peer_tip(chain: Network) -> Point {
     (*PEER_TIP.get_or_insert(chain, Point::UNKNOWN).value()).clone()
 }
@@ -117,7 +118,7 @@ impl ProtectedLiveChainBlockList {
         Ok(check_first_live_block.point())
     }
 
-    /// Get the point of the first known block in the Live Chain.
+    /// Get the point of the last known block in the Live Chain.
     fn get_last_live_point(live_chain: &LiveChainBlockList) -> Point {
         let Some(check_last_live_entry) = live_chain.back() else {
             // Its not an error if we can't get a latest block because the chain is empty,
@@ -151,7 +152,7 @@ impl ProtectedLiveChainBlockList {
             )));
         }
 
-        // Get the current Oldest block in the live chain.
+        // Get the current oldest block in the live chain.
         let check_first_live_point = Self::get_first_live_point(&live_chain)?;
 
         let last_backfill_block = blocks
@@ -160,7 +161,7 @@ impl ProtectedLiveChainBlockList {
             .clone();
         let last_backfill_point = last_backfill_block.point();
 
-        // Make sure the backfill will properly connect the partial Live chain to the Mithril
+        // Make sure the backfill will properly connect the partial live chain to the Mithril
         // chain.
         if !last_backfill_point.strict_eq(&check_first_live_point) {
             return Err(Error::LiveSync(format!(
@@ -179,8 +180,8 @@ impl ProtectedLiveChainBlockList {
         Ok(())
     }
 
-    /// Check if the given point is strictly in the live-chain.  This means the slot and
-    /// Hash MUST be present.
+    /// Check if the given point is strictly in the live-chain. This means the slot and
+    /// block hash MUST be present.
     fn strict_block_lookup(live_chain: &LiveChainBlockList, point: &Point) -> bool {
         if let Some(found_block) = live_chain.get(point) {
             return found_block.value().point().strict_eq(point);
@@ -451,7 +452,7 @@ pub(crate) fn get_live_block(
     live_chain.get_block(point, advance, strict)
 }
 
-/// Get the fill tp point for a chain.
+/// Get the fill to point for a chain.
 ///
 /// Returns the Point of the block we are filling up-to, and it's fork count.
 ///
@@ -493,7 +494,7 @@ pub(crate) fn live_chain_length(chain: Network) -> usize {
     live_chain.len()
 }
 
-/// On an immutable update, purge the live-chain up to the new immutable tip.
+/// On an immutable update, purge the live chain up to the new immutable tip.
 /// Will error if the point is not in the Live chain.
 pub(crate) fn purge_live_chain(chain: Network, point: &Point) -> Result<()> {
     let live_chain = get_live_chain(chain);

rust/cardano-chain-follower/src/chain_update.rs

@@ -40,7 +40,7 @@ impl ChainUpdate {
         &self.data
     }
 
-    /// Gets the chain update's block data.
+    /// Is the chain update immutable?
     #[must_use]
     pub fn immutable(&self) -> bool {
         self.data.immutable()

rust/cardano-chain-follower/src/error.rs

@@ -21,7 +21,7 @@ pub enum Error {
     /// Chainsync protocol error.
     #[error("Chainsync error: {0:?}")]
     Chainsync(chainsync::ClientError),
-    /// Backfill Synch error.
+    /// Backfill Sync error.
     #[error("Backfill Sync error: {0}")]
     BackfillSync(String),
     /// Live Sync error.
@@ -48,7 +48,7 @@ pub enum Error {
     /// Mithril snapshot traversal error.
     #[error("Failed to traverse block(s) from Mithril snapshot")]
     MithrilSnapshotTraverse(pallas::ledger::traverse::Error),
-    /// Failed to parse
+    /// Failed to parse network error.
     #[error("Failed to parse network")]
     ParseNetwork,
     /// Mithril Snapshot path is not a directory

rust/cardano-chain-follower/src/follow.rs

@@ -23,9 +23,9 @@ pub struct ChainFollower {
     chain: Network,
     /// Where we end following.
     end: Point,
-    /// Block we processed most recently.
+    /// Point we processed most recently.
     previous: Point,
-    /// Where we are currently in the following process.
+    /// Point we are currently in the following process.
     current: Point,
     /// What fork were we last on
     fork: Fork,
@@ -134,7 +134,7 @@ impl ChainFollower {
         None
     }
 
-    /// If we can, get the next update from the mithril snapshot.
+    /// If we can, get the next update from the live chain.
     async fn next_from_live_chain(&mut self) -> Option<ChainUpdate> {
         let mut next_block: Option<MultiEraBlock> = None;
         let mut update_type = chain_update::Kind::Block;
@@ -208,7 +208,7 @@ impl ChainFollower {
         None
     }
 
-    /// Update the current Point, and return `false` if this fails.
+    /// Update the current Point, return `false` if this fails.
     fn update_current(&mut self, update: &Option<ChainUpdate>) -> bool {
         if let Some(update) = update {
             let decoded = update.block_data().decode();
@@ -323,7 +323,7 @@ impl ChainFollower {
     ///
     /// # Arguments
     ///
-    /// * `chain` - The blockchain to post the transaction on.
+    /// * `chain` - The blockchain network to post the transaction on.
     /// * `txn` - The transaction to be posted.
     ///
     /// # Returns

rust/cardano-chain-follower/src/mithril_snapshot.rs

@@ -33,7 +33,7 @@ impl MithrilSnapshot {
     /// Checks if the snapshot contains a given point.
     ///
     /// # Arguments
-    /// * `network`: The network that this function should check against.
+    /// 
     /// * `point`: The point to be checked for existence within the specified Mithril
     ///   snapshot.
     ///

rust/cardano-chain-follower/src/mithril_snapshot_config.rs

@@ -29,6 +29,7 @@ use crate::{
 
 /// Type we use to manage the Sync Task handle map.
 type SyncMap = DashMap<Network, Mutex<Option<JoinHandle<()>>>>;
+
 /// Handle to the mithril sync thread. One for each Network ONLY.
 static SYNC_JOIN_HANDLE_MAP: LazyLock<SyncMap> = LazyLock::new(|| {
     let map = DashMap::new();
@@ -294,7 +295,7 @@ impl MithrilSnapshotConfig {
         snapshot_path
     }
 
-    /// Check if the Mithril Snapshot Path is valid an usable.
+    /// Check if the Mithril Snapshot Path is valid and usable.
     async fn validate_path(&self) -> Result<()> {
         let path = self.path.clone();
         debug!(