From 5ce5ee07d827c72808e8fddd33a594e9a80032f9 Mon Sep 17 00:00:00 2001
From: a bellenir <a@bellenir.com>
Date: Fri, 15 Aug 2014 03:42:57 +0000
Subject: [PATCH] +comments

---
 source/rbt/rbt.h | 69 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 3 deletions(-)

diff --git a/source/rbt/rbt.h b/source/rbt/rbt.h
index 3e1add0..5ee3416 100644
--- a/source/rbt/rbt.h
+++ b/source/rbt/rbt.h
@@ -5,34 +5,97 @@
 extern "C" {
 #endif
 
+/** node colors */
 typedef enum {
 	RED = 0,
 	BLACK
 } rbt_color_t;
  
+/** a function pointer for comparing node contents
+should return -1, 0, or 1 if a is <, ==, or > b, respectively */
 typedef int (*comparator_t)(void* p_a, void* p_b);
 
+/** a red-black tree node */
 typedef struct rbt_node_t {
+	/** pointers to immediate relatives */
 	struct rbt_node_t* left;
 	struct rbt_node_t* right;
 	struct rbt_node_t* parent;
+	/** node color */
 	rbt_color_t color;
+	/** pointer to node contents */
 	void* contents;
 } rbt_node_t;
 
+/** a red-black tree */
 typedef struct {
+	/** pointer to the root of the tree */
 	rbt_node_t* root;
+	/** function pointer for comparing node contents */
 	comparator_t comp;
 } rbt_t;
 
+
+/**
+ * @brief creates a new red-black tree
+ *
+ * @param comparator pointer to the comparator function
+ *
+ * @return pointer to newly created tree
+ */
 rbt_t* rbt_new(comparator_t comparator);
+
+
+/**
+ * @brief creates a new node for a red-black tree
+ *
+ * @param contents pointer to the contents of the node
+ *
+ * @return pointer to newly created node
+ */
 rbt_node_t* rbt_node_new(void* contents);
-rbt_color_t rbt_node_color(rbt_node_t* ndoe);
+
+
+/**
+ * @brief get the color of a given node
+ *
+ * @param node the node to get the color of
+ *
+ * @return RED or BLACK. BLACK if node is NULL (a leaf)
+ */
+rbt_color_t rbt_node_color(rbt_node_t* node);
+
+
+/**
+ * @brief find a value in an red-black tree
+ *
+ * @param tree  pointer to the tree on which to operate
+ * @param value pointer to the data to find
+ *
+ * @return pointer to the node containing the given value
+ *         NULL if the value is present in the tree
+ */
 rbt_node_t* rbt_lookup(rbt_t* tree, void* value);
-//returns a pointer to the new node
+
+
+/**
+ * @brief insert a value into a red-black tree
+ *
+ * @param tree  pointer to the tree on which to operate
+ * @param value pointer to the value to be inserted
+ *
+ * @return a pointer to the new node
+ */
 rbt_node_t* rbt_insert(rbt_t* tree, void* value);
+
+
+/**
+ * @brief removes a value from a red-black tree
+ *
+ * @param tree  pointer to the tree on which to operate
+ * @param value pointer to the value to be removed
+ */
 void rbt_delete(rbt_t* tree, void* value);
-//look up a node in the tree with the given value
 
 #ifdef __cplusplus
 }
-- 
2.52.0