From 12f3f4c4dbb3da369dcde1e67807f5b24e406b61 Mon Sep 17 00:00:00 2001
From: Ranadeep Biswas <mail@rnbguy.at>
Date: Fri, 3 May 2024 15:45:14 +0200
Subject: [PATCH] update comments

---
 basecoin/store/src/avl/tree.rs | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/basecoin/store/src/avl/tree.rs b/basecoin/store/src/avl/tree.rs
index 1f4960c8..2427da0c 100644
--- a/basecoin/store/src/avl/tree.rs
+++ b/basecoin/store/src/avl/tree.rs
@@ -93,6 +93,15 @@ impl<K: Ord + AsBytes, V: Borrow<[u8]>> AvlTree<K, V> {
     }
 
     /// Removes the top node in the tree, if it exists.
+    ///
+    /// Since we are removing the current node, we need to replace it with a new node.
+    /// The new node is chosen as follows:
+    /// - If the current node has no children, the new node is `None`.
+    /// - If the current node has only one child, the new node is the child.
+    /// - If the current node has both children.
+    ///   - If left child is shorter: the new node is the leftmost node in the right subtree.
+    ///     Also, the current node's children are set to the new node's children.
+    ///   - If right child is shorter, vice versa.
     fn remove_top(node_ref: &mut NodeRef<K, V>) -> NodeRef<K, V> {
         let node = node_ref.as_deref_mut()?;
 
@@ -114,7 +123,7 @@ impl<K: Ord + AsBytes, V: Borrow<[u8]>> AvlTree<K, V> {
             // leftmost_node_ref.right <- node_ref.right
             // leftmost_node_ref.left <- node_ref.left
             if let Some(leftmost_node) = leftmost_node_ref.as_mut() {
-                // removed leftmost node must be a leaf; not asserting, as it is an invariant.
+                // removed leftmost node must be a leaf; it is an invariant.
                 // assert!(leftmost_node.right.is_none() && leftmost_node.left.is_none());
 
                 leftmost_node.right = node.right.take();
@@ -133,7 +142,7 @@ impl<K: Ord + AsBytes, V: Borrow<[u8]>> AvlTree<K, V> {
             // rightmost_node_ref.right <- node_ref.right
             // rightmost_node_ref.left <- node_ref.left
             if let Some(rightmost_node) = rightmost_node_ref.as_mut() {
-                // removed rightmost node must be a leaf; not asserting, as it is an invariant.
+                // removed rightmost node must be a leaf; it is an invariant.
                 // assert!(rightmost_node.right.is_none() && rightmost_node.left.is_none());
 
                 rightmost_node.right = node.right.take();