From be5850488cc2f9893f6fad70a63465926b9d1b3c Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Fri, 26 May 2023 14:24:27 +0200
Subject: [PATCH] docs: a few additional tree docs (#2852)

---
 crates/blockchain-tree/src/blockchain_tree.rs |  6 +++---
 crates/storage/provider/src/chain.rs          | 17 +++++++++--------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/crates/blockchain-tree/src/blockchain_tree.rs b/crates/blockchain-tree/src/blockchain_tree.rs
index e97309074a..d55df46035 100644
--- a/crates/blockchain-tree/src/blockchain_tree.rs
+++ b/crates/blockchain-tree/src/blockchain_tree.rs
@@ -800,7 +800,7 @@ impl<DB: Database, C: Consensus, EF: ExecutorFactory> BlockchainTree<DB, C, EF>
             }
             ChainSplit::NoSplitCanonical(canonical) => canonical,
             ChainSplit::NoSplitPending(_) => {
-                panic!("Should not happen as block indices guarantee structure of blocks")
+                unreachable!("Should not happen as block indices guarantee structure of blocks")
             }
         }
     }
@@ -835,7 +835,7 @@ impl<DB: Database, C: Consensus, EF: ExecutorFactory> BlockchainTree<DB, C, EF>
         self.find_canonical_header(hash).map(|header| header.is_some())
     }
 
-    /// Make a block and its parent(s) part of the canonical chain.
+    /// Make a block and its parent(s) part of the canonical chain and commit them to the database
     ///
     /// # Note
     ///
@@ -872,7 +872,7 @@ impl<DB: Database, C: Consensus, EF: ExecutorFactory> BlockchainTree<DB, C, EF>
         };
         let chain = self.chains.remove(&chain_id).expect("To be present");
 
-        // we are splitting chain as there is possibility that only part of chain get canonicalized.
+        // we are splitting chain at the block hash that we want to make canonical
         let canonical = self.split_chain(chain_id, chain, SplitAt::Hash(*block_hash));
 
         let mut block_fork = canonical.fork_block();
diff --git a/crates/storage/provider/src/chain.rs b/crates/storage/provider/src/chain.rs
index 4a18bd7438..6c2bb01235 100644
--- a/crates/storage/provider/src/chain.rs
+++ b/crates/storage/provider/src/chain.rs
@@ -288,24 +288,25 @@ pub enum SplitAt {
     Hash(BlockHash),
 }
 
-/// Result of spliting chain.
+/// Result of a split chain.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum ChainSplit {
-    /// Chain is not splited. Pending chain is returned.
+    /// Chain is not split. Pending chain is returned.
     /// Given block split is higher than last block.
     /// Or in case of split by hash when hash is unknown.
     NoSplitPending(Chain),
-    /// Chain is not splited. Canonical chain is returned.
+    /// Chain is not split. Canonical chain is returned.
     /// Given block split is lower than first block.
     NoSplitCanonical(Chain),
-    /// Chain is splited in two.
+    /// Chain is split into two.
     /// Given block split is contained in first chain.
     Split {
-        /// Left contains lower block number that get canonicalized.
-        /// And substate is empty and not usable.
+        /// Left contains lower block numbers that get are considered canonicalized. It ends with
+        /// the [SplitAt] block. The substate of this chain is now empty and not usable.
         canonical: Chain,
-        /// Right contains higher block number, that is still pending.
-        /// And substate from original chain is moved here.
+        /// Right contains all subsequent blocks after the [SplitAt], that are still pending.
+        ///
+        /// The substate of the original chain is moved here.
         pending: Chain,
     },
 }