Document code for the marks

3 files changed, 97 insertions, 3 deletions

diff --git a/src/02/04/hash.c b/src/02/04/hash.c
index cc0089d..f7cc5ec 100644
--- a/src/02/04/hash.c
+++ b/src/02/04/hash.c
@@ -4,6 +4,12 @@
 #include <stdlib.h>
 #include <string.h>
 
+/**
+ * Initialize a new hash table.
+ *
+ * @param size The number of buckets to allocate for the chash table.
+ * @return Returns the hash table.
+ */
 Hash *hash_init(int size) {
   Hash *hash = malloc(sizeof(Hash));
   hash->size = size;
@@ -11,8 +17,26 @@ Hash *hash_init(int size) {
   return hash;
 }
 
-unsigned int hash_index(Hash *hash, int key) { return key % hash->size; }
+/**
+ * Computes a hash code for the given key.
+ *
+ * @param hash The hash table that the key is used in.
+ * @param key The key to produce a hash code for
+ * @return Returns a hash code for the given key.
+ */
+unsigned int hash_code(Hash *hash, int key) { return key % hash->size; }
 
+/**
+ * A function to search for a specific key in a linked list.
+ * This performs a O(n) search to find the matching key.
+ * A possible optimization would be to convert this to do a binary
+ * search for the given key using a binary search tree instead of a linked
+ * list.
+ *
+ * @param list The linked list to search for the given key
+ * @param key The key to search for in the linked list
+ * @return Returns the data associated with the given key.
+ */
 void *search(Node *list, int key) {
   Node *current = list;
 
@@ -26,14 +50,30 @@ void *search(Node *list, int key) {
   return NULL;
 }
 
+/**
+ * A function to fetch a specify value from a hash table by key.
+ *
+ * @param hash The hash table to search.
+ * @param key The key associated with the value to return
+ * @return Returns the data associated with the key or NULL if the key is not
+ * found.
+ */
 void *hash_get(Hash *hash, int key) {
-  unsigned int bucket = hash_index(hash, key);
+  unsigned int bucket = hash_code(hash, key);
   Node *n = hash->buckets + bucket;
   return (n->data) ? search(n, key) : NULL;
 }
 
+/**
+ * A function to set the value associated with a key
+ * in a hash table.
+ *
+ * @param hash The hash table to insert the key/value pair into
+ * @param key The key associated with the value to insert.
+ * @param value The value associated with the key to insert.
+ */
 void hash_set(Hash *hash, int key, void *value) {
-  unsigned int bucket = hash_index(hash, key);
+  unsigned int bucket = hash_code(hash, key);
   Tuple *tuple = tuple_initialize(key, value);
   Node *n = hash->buckets + bucket;
 
@@ -43,6 +83,11 @@ void hash_set(Hash *hash, int key, void *value) {
     hash->buckets[bucket] = *list_initialize(tuple);
 }
 
+/**
+ * A function that pretty prints a key/value pair.
+ *
+ * @param data The Tuple to print.
+ */
 void print_tuple(void *data) {
   Tuple *t = data;
 
@@ -52,6 +97,11 @@ void print_tuple(void *data) {
     printf("(nil)");
 }
 
+/**
+ * Prints a visual representation of a hash table.
+ *
+ * @param hash The hash table to inspect
+ */
 void hash_inspect(Hash *hash) {
   for (int i = 0; i < hash->size; i++) {
     printf("%2d: ", i);
diff --git a/src/02/04/list.c b/src/02/04/list.c
index cfc3b2c..1de7a03 100644
--- a/src/02/04/list.c
+++ b/src/02/04/list.c
@@ -2,6 +2,12 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/**
+ * Initializes a new node for a linked list.
+ *
+ * @param data The data to bind to the new node in the list.
+ * @return Returns a new linked list node
+ */
 Node *list_initialize(void *data) {
   Node *node = malloc(sizeof(Node));
   node->data = data;
@@ -9,6 +15,13 @@ Node *list_initialize(void *data) {
   return node;
 }
 
+/**
+ * Adds a new item to the tail of a linked list
+ *
+ * @param head The head of a linked list
+ * @param data The data to add to the tail of a linked list
+ * @return Returns the new node tail node
+ */
 Node *list_add(Node *head, void *data) {
   Node *tail;
   Node *tmp = head;
@@ -23,6 +36,13 @@ Node *list_add(Node *head, void *data) {
   return tail->next;
 }
 
+/**
+ * Returns a specific node by zero based index in a linked list.
+ *
+ * @param self the head of the linked list
+ * @param index the offset from the head of the node to return
+ * @return Returns the node at the specified offset or NULL.
+ */
 Node *list_get(Node *self, int index) {
   if (!self || index < 0)
     return NULL;
@@ -34,6 +54,12 @@ Node *list_get(Node *self, int index) {
   return self;
 }
 
+/**
+ * Returns the total number of nodes in a linked list.
+ *
+ * @param head The head of a linked list
+ * @returns Returns the # of items in the list.
+ */
 int list_size(Node *head) {
   int i = 0;
   for (Node *tmp = head; tmp && tmp != NULL; tmp = tmp->next)
@@ -41,6 +67,12 @@ int list_size(Node *head) {
   return i;
 }
 
+/**
+ * Prints a visual representation of a linked list.
+ *
+ * @param self The head of the linked list
+ * @param printer A callback function to invoke to print each item.
+ */
 void list_inspect(Node *self, Printer printer) {
   if (!self)
     return;
diff --git a/src/02/04/tuple.c b/src/02/04/tuple.c
index 9e31975..f7ff327 100644
--- a/src/02/04/tuple.c
+++ b/src/02/04/tuple.c
@@ -1,6 +1,13 @@
 #include "tuple.h"
 #include "stdlib.h"
 
+/**
+ * Initializes a new tuple bound to a key/value pair.
+ *
+ * @param key The key to bind to
+ * @param value The value to bind to
+ * @return Returns a new Tuple
+ */
 Tuple *tuple_initialize(int key, void *value) {
   Tuple *tuple = malloc(sizeof(Tuple));
   tuple->key = key;
@@ -8,4 +15,9 @@ Tuple *tuple_initialize(int key, void *value) {
   return tuple;
 }
 
+/**
+ * A destructor for a Tuple
+ *
+ * @param tuple The tuple to free
+ */
 void tuple_destroy(Tuple *tuple) { return free(tuple); }