Add doxygen comments

2 files changed, 93 insertions, 27 deletions

diff --git a/src/01/01a/README.md b/src/01/01a/README.md
index 10a799a..b3bf3e1 100644
--- a/src/01/01a/README.md
+++ b/src/01/01a/README.md
@@ -48,7 +48,15 @@ Running "test" (8 tests)...
 Completed "test": 17 passes in 5ms.
 ```
 
-The test cases include
+The test cases include:
+
+* add a node to an empty queue
+* remove a node from the head of the queue
+* removing a node from an empty queue
+* removing the last node
+* adding nodes out of order
+
+Please see [`priority_queue_test.c`](./priority_queue_test.c) for more details.
 
 ## Sample Input and Output
 
diff --git a/src/01/01a/priority_queue.c b/src/01/01a/priority_queue.c
index 83a3e09..4d7fc21 100644
--- a/src/01/01a/priority_queue.c
+++ b/src/01/01a/priority_queue.c
@@ -2,13 +2,23 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/**
+ * The equivalent of a constructor to create a PriorityQueue.
+ */
 PriorityQueue *initialize() {
-  PriorityQueue *queue = malloc(sizeof(PriorityQueue));
-  queue->size = 0;
-  queue->head = NULL;
-  return queue;
+  PriorityQueue *self = malloc(sizeof(PriorityQueue));
+  self->size = 0;
+  self->head = NULL;
+  return self;
 }
 
+/**
+ * A function used to construct a Node for a singly linked list.
+ *
+ * @param priority the priority for the data
+ * @param data the data to store in the queue
+ * @return The Node to add to a singly linked list.
+ */
 static Node *create_node(int priority, int data) {
   Node *node = malloc(sizeof(Node));
   node->priority = priority;
@@ -17,14 +27,37 @@ static Node *create_node(int priority, int data) {
   return node;
 }
 
-int size(PriorityQueue *queue) {
-  return queue->size;
+/**
+ * Determines the number of items stored in a queue.
+ *
+ * @param self The queue to investigate
+ * @return The total number of items stored in the queue.
+ */
+int size(PriorityQueue *self) {
+  return self->size;
 }
 
+/**
+ * Compares two integers and returns:
+ * 1 if x is greater than y.
+ * 0 if x is equal to y.
+ * -1 if x is less than to y.
+ *
+ *  @param x the integer to compare
+ *  @param y the other integer to compare
+ *  @return 1,0,-1 depending on the comparison of x and y
+ */
 static int compare(const int x, const int y) {
   return x == y ? 0 : x > y ? 1 : -1;
 }
 
+/**
+ * Inserts a node into the queue in the best position based on the priority.
+ *
+ * @param self The head of the queue.
+ * @param priority The priority of the data.
+ * @param data the data to store.
+ */
 void enqueue(Node *self, int priority, int data) {
   if (self->next == NULL) {
     self->next = create_node(priority, data);
@@ -45,38 +78,57 @@ void enqueue(Node *self, int priority, int data) {
   self->next->next = tmp;
 }
 
-void add(PriorityQueue *queue, int priority, int data) {
-  queue->size++;
-
-  if (!queue->head) {
-    queue->head = create_node(priority, data);
+/**
+ * Adds data with a specific priority to the queue
+ *
+ * @param self The queue to add data to
+ * @param priority The priority for the data
+ * @param data The data to store
+ */
+void add(PriorityQueue *self, int priority, int data) {
+  self->size++;
+
+  if (!self->head) {
+    self->head = create_node(priority, data);
     return;
   }
 
-  if (compare(queue->head->priority, priority) <= 0)
-    return enqueue(queue->head, priority, data);
+  if (compare(self->head->priority, priority) <= 0)
+    return enqueue(self->head, priority, data);
 
   Node *node = create_node(priority, data);
-  node->next = queue->head;
-  queue->head = node;
+  node->next = self->head;
+  self->head = node;
 }
 
-int delete_min(PriorityQueue *queue) {
-  if (queue->head) {
-    Node *tmp = queue->head;
+/**
+ * Removes the next item in the queue with the lowest priority.
+ *
+ * @param self The queue
+ * @return The data associated with the lowest priority in the queue
+ */
+int delete_min(PriorityQueue *self) {
+  if (self->head) {
+    Node *tmp = self->head;
     int data = tmp->data;
-    queue->head = tmp->next;
-    queue->size--;
+    self->head = tmp->next;
+    self->size--;
     free(tmp);
     return data;
   }
   return 0;
 }
 
-void inspect(PriorityQueue *queue) {
-  Node *tmp = queue->head;
+/**
+ * A helper function used to print a queue.
+ * This is useful for debugging.
+ *
+ * @param self The queue to print
+ */
+void inspect(PriorityQueue *self) {
+  Node *tmp = self->head;
 
-  printf("Items (%d): [ ", size(queue));
+  printf("Items (%d): [ ", size(self));
   while(tmp) {
     printf("(%d,%d) ", tmp->priority, tmp->data);
     tmp = tmp->next;
@@ -84,8 +136,14 @@ void inspect(PriorityQueue *queue) {
   printf("]\n");
 }
 
-void destroy(PriorityQueue *queue) {
-  Node *current = queue->head;
+/**
+ * The equivalent of a destructor function.
+ * This function frees any memory associated with a queue
+ *
+ * @param self The queue to free
+ */
+void destroy(PriorityQueue *self) {
+  Node *current = self->head;
   Node *tmp;
 
   while(current) {
@@ -93,5 +151,5 @@ void destroy(PriorityQueue *queue) {
 
     if (tmp) free(tmp);
   }
-  free(queue);
+  free(self);
 }