From 936b2835b28082d83f9716ffc2470ae0621ab52a Mon Sep 17 00:00:00 2001
From: Danila Fedorin <danila.fedorin@gmail.com>
Date: Wed, 28 Dec 2016 19:29:51 -0800
Subject: [PATCH] Add more comments and a new comparison function.

---
 include/ht.h    | 41 +++++++++++++++++++++++++++++++++++++----
 include/libds.h |  7 +++++++
 include/ll.h    | 15 +++++++++++++++
 include/vec.h   |  9 +++++++++
 src/libds.c     |  1 +
 5 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/include/ht.h b/include/ht.h
index c1ac404..b9cec4b 100644
--- a/include/ht.h
+++ b/include/ht.h
@@ -11,8 +11,17 @@
  * data as to avoid conflicting hash functions.
  */
 struct ht_node_s {
+  /**
+   * A copy of the key used to store this node's data.
+   */
   void* key;
+  /**
+   * The data stored in this node.
+   */
   void* data;
+  /**
+   * The next linked list node with the same hash.
+   */
   struct ht_node_s* next;
 };
 
@@ -27,11 +36,35 @@ struct ht_node_s {
  * hash table to know something went wrong.
  */
 struct ht_s {
+  /**
+   * The buckets in this hash table.
+   */
   struct ht_node_s* data[LIBDS_HT_SIZE];
-  unsigned int (*hash_func)(void*);
-  int (*cmp_func)(void*, void*);
-  void* (*copy_func)(void*);
-  void (*free_func)(void*);
+  /**
+   * Hash function used to store data.
+   * @param input the data being hashed.
+   * @return the data's hash.
+   */
+  unsigned int (*hash_func)(void* input);
+  /**
+   * Function to compare two keys.
+   * @param given_key the key being used to retrieve data
+   * @param current_key the key of a hash table node
+   * @return nonzero value if the keys match.
+   */
+  int (*cmp_func)(void* given_key, void* current_key);
+  /**
+   * Function used to duplicate the given key and
+   * store it in a node.
+   * @param key the key to copy
+   * @return pointer to a new key.
+   */
+  void* (*copy_func)(void* key);
+  /**
+   * Function used to free a previously copied key.
+   * @param key the key to free.
+   */
+  void (*free_func)(void* key);
 };
 
 typedef struct ht_node_s ht_node;
diff --git a/include/libds.h b/include/libds.h
index 391aa29..0c9b566 100644
--- a/include/libds.h
+++ b/include/libds.h
@@ -30,5 +30,12 @@ typedef int (*foreach_func)(void*, va_list);
  * @return always true, i.e 1
  */
 int compare_always(void* a, void* b);
+/**
+ * A compare_func implementation that compares two pointers using ==.
+ * @param a the first piece of data being compared
+ * @param b the second piece of data being compared
+ * @return true if a and b are the same value.
+ */
+int compare_pointer(void* a, void* b);
 
 #endif
diff --git a/include/ll.h b/include/ll.h
index 641ab8b..0bcfee6 100644
--- a/include/ll.h
+++ b/include/ll.h
@@ -7,8 +7,17 @@
  * A simple linked list node, doubly-linked.
  */
 struct ll_node_s {
+    /**
+     * The next node in the linked list
+     */
     struct ll_node_s* next;
+    /**
+     * The previous node in the linked list.
+     */
     struct ll_node_s* prev;
+    /**
+     * The data of the linked list node.
+     */
     void* data;
 };
 
@@ -16,7 +25,13 @@ struct ll_node_s {
  * A linked list struct, containing pointers to the head and tail node.
  */
 struct ll_s {
+    /**
+     * The head of the linked list.
+     */
     struct ll_node_s* head;
+    /**
+     * The tail of the linked list.
+     */
     struct ll_node_s* tail;
 };
 
diff --git a/include/vec.h b/include/vec.h
index 1a61210..7f887c2 100644
--- a/include/vec.h
+++ b/include/vec.h
@@ -11,8 +11,17 @@
  * Whenever the size limit is reached, the vector allocates a new array that is two times bigger.
  */
 struct vec_s {
+  /**
+   * The data array of the vector.
+   */
   void* data;
+  /**
+   * The maximum size of the vector.
+   */
   int capacity;
+  /**
+   * The current number of items in the vector.
+   */
   int size;
 };
 
diff --git a/src/libds.c b/src/libds.c
index e2bc17b..6b07d43 100644
--- a/src/libds.c
+++ b/src/libds.c
@@ -1,3 +1,4 @@
 #include "libds.h"
 
 int compare_always(void* a, void* b) { return 1; }
+int compare_pointer(void* a, void* b) { return a == b; }