From 424f1e9a63b64bc79d4b8837052adfbf9d4cf078 Mon Sep 17 00:00:00 2001
From: donnaskiez <lachiehodges7785@gmail.com>
Date: Sun, 16 Jun 2024 20:31:06 +1000
Subject: [PATCH] comments + fixes

---
 driver/containers/tree.c | 67 +++++++++++++++++++++++++++++++++-------
 1 file changed, 56 insertions(+), 11 deletions(-)

diff --git a/driver/containers/tree.c b/driver/containers/tree.c
index 34449cd..2781fc2 100644
--- a/driver/containers/tree.c
+++ b/driver/containers/tree.c
@@ -1,12 +1,53 @@
 #include "tree.h"
 
 /*
- * Basic red-black tree implementation. Currently the enumeration routines are
- * recursive which maybe isnt the best idea given the environment this is meant
+ * Basic red-black tree implementation. Currently, the enumeration routines are
+ * recursive, which may not be the best idea given the environment this is meant
  * for (kernel mode). We can always fix that up later though :).
- * 
+ *
+ * Example of a Red-Black Tree:
+ *
+ *                grandparent(B)
+ *                       |
+ *              +--------+--------+
+ *              |                 |
+ *            parent(R)          uncle(R)
+ *              |
+ *        +-----+-----+
+ *        |           |
+ *      Node(R)      sibling(B)
+ *                    |
+ *                    +-----+
+ *                    |     |
+ *                  child  ...
+ *
+ * Legend:
+ * - 'B' represents a Black node
+ * - 'R' represents a Red node
+ *
+ * Labels for components during insert and delete fix-up:
+ *
+ * - Node: The newly inserted node that may cause a violation.
+ * - Parent: The parent of the newly inserted node.
+ * - Grandparent: The grandparent of the newly inserted node.
+ * - Uncle: The sibling of the parent node.
+ * - Sibling: The sibling of the node to be deleted or fixed.
+ * - Child: The child of the node to be deleted or fixed.
+ *
+ * In this example:
+ * - Each 'B' is a black node.
+ * - Each 'R' is a red node.
+ * - The labels illustrate a typical structure that might be encountered during
+ *   the insertion or deletion process, where the new node, its parent,
+ * grandparent, uncle, sibling, and child are involved in the rebalancing
+ * operations.
+ *
+ * Resources used:
  * https://www.kernel.org/doc/Documentation/rbtree.txt
  * https://github.com/torvalds/linux/blob/master/lib/rbtree.c
+ * https://www.osronline.com/article.cfm%5Earticle=516.htm
+ * https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-_rtl_avl_table (for structure ideas)
+ * 
  */
 
 /**
@@ -357,9 +398,9 @@ RtlpRbTreeFixupDelete(_In_ PRB_TREE Tree, _In_ PRB_TREE_NODE Node)
             else {
                 if (sibling &&
                     (!sibling->right || sibling->right->colour == black)) {
-                    if (sibling->left) {
+                    if (sibling->left)
                         sibling->left->colour = black;
-                    }
+
                     sibling->colour = red;
                     RtlpRbTreeRotateRight(Tree, sibling);
                     sibling = Node->parent->right;
@@ -368,11 +409,13 @@ RtlpRbTreeFixupDelete(_In_ PRB_TREE Tree, _In_ PRB_TREE_NODE Node)
                 if (sibling) {
                     sibling->colour      = Node->parent->colour;
                     Node->parent->colour = black;
-                    if (sibling->right) {
+
+                    if (sibling->right)
                         sibling->right->colour = black;
-                    }
+
                     RtlpRbTreeRotateLeft(Tree, Node->parent);
                 }
+
                 Node = Tree->root;
             }
         }
@@ -395,9 +438,9 @@ RtlpRbTreeFixupDelete(_In_ PRB_TREE Tree, _In_ PRB_TREE_NODE Node)
             else {
                 if (sibling &&
                     (!sibling->left || sibling->left->colour == black)) {
-                    if (sibling->right) {
+                    if (sibling->right)
                         sibling->right->colour = black;
-                    }
+
                     sibling->colour = red;
                     RtlpRbTreeRotateLeft(Tree, sibling);
                     sibling = Node->parent->left;
@@ -406,11 +449,13 @@ RtlpRbTreeFixupDelete(_In_ PRB_TREE Tree, _In_ PRB_TREE_NODE Node)
                 if (sibling) {
                     sibling->colour      = Node->parent->colour;
                     Node->parent->colour = black;
-                    if (sibling->left) {
+
+                    if (sibling->left)
                         sibling->left->colour = black;
-                    }
+
                     RtlpRbTreeRotateRight(Tree, Node->parent);
                 }
+
                 Node = Tree->root;
             }
         }