Add doxygen comments

1 files changed, 86 insertions, 32 deletions

diff --git a/src/01/01b/stack.c b/src/01/01b/stack.c
index beffd64..9c08795 100644
--- a/src/01/01b/stack.c
+++ b/src/01/01b/stack.c
@@ -2,19 +2,35 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-static Queue *newQueue(){
+/**
+ * Constructs a new instance of a queue
+ *
+ * @return A Queue struct
+ */
+static Queue *newQueue(void){
   Queue *queue = malloc(sizeof(Queue));
   queue->size = 0;
   queue->head = NULL;
   return queue;
 }
 
-Stack *initialize() {
+/**
+ * Constructs an instance of a Stack.
+ *
+ * @return A Stack struct.
+ */
+Stack *initialize(void) {
   Stack *stack = malloc(sizeof(Stack));
   stack->q1 = newQueue();
   return stack;
 }
 
+/**
+ * Constructs a new singly linked list Node to push onto the Stack.
+ *
+ * @param data The data to store on the stack.
+ * @return A Node struct
+ */
 Node *newNode(int data) {
   Node *node = malloc(sizeof(Node));
   node->data = data;
@@ -22,14 +38,20 @@ Node *newNode(int data) {
   return node;
 }
 
-void enqueue(Queue *q, int data) {
+/**
+ * Enqueues a new item onto a Queue
+ *
+ * @param self The queue to add the data to
+ * @param data The data to add to the queue
+ */
+void enqueue(Queue *self, int data) {
   Node *node = newNode(data);
-  q->size++;
+  self->size++;
 
-  if (q->head == NULL) {
-    q->head = node;
+  if (self->head == NULL) {
+    self->head = node;
   } else {
-    Node *tail = q->head;
+    Node *tail = self->head;
 
     while (tail->next != NULL)
       tail = tail->next;
@@ -37,60 +59,92 @@ void enqueue(Queue *q, int data) {
   }
 }
 
-int dequeue(Queue *q) {
-  if (q->head == NULL) return -1;
+/**
+ * Dequeues the next item from the queue
+ *
+ * @param self The queue to dequeue from
+ * @return The data for the next it to remove from the Queue
+ */
+int dequeue(Queue *self) {
+  if (self->head == NULL) return -1;
 
-  Node *node = q->head;
+  Node *node = self->head;
   int data = node->data;
 
-  q->head = node->next;
+  self->head = node->next;
   free(node);
   return data;
 }
 
-// The running time is linear time.
-void push(Stack *stack, int data) {
-  enqueue(stack->q1, data);
+/**
+ * Pushes an item on to the top of a stack.
+ *
+ * @param self The stack to push the data on to
+ * @param data The data to push on to the stack
+ */
+void push(Stack *self, int data) {
+  enqueue(self->q1, data);
 }
 
-// The running time is linear time.
-int pop(Stack *stack) {
-  int count = stack->q1->size - 1;
+/**
+ * Pops off the last item pushed onto the stack.
+ *
+ * @param self The stack to pop an item off of
+ * @return The data associated with the item to pop off the stack
+ */
+int pop(Stack *self) {
+  int count = self->q1->size - 1;
   Queue *tmp = newQueue();
 
   for (int i = 0; i < count; i++)
-    enqueue(tmp, dequeue(stack->q1));
+    enqueue(tmp, dequeue(self->q1));
 
-  int data = dequeue(stack->q1);
-  free(stack->q1);
-  stack->q1 = tmp;
+  int data = dequeue(self->q1);
+  free(self->q1);
+  self->q1 = tmp;
   return data;
 }
 
-int size(Stack *stack) {
-  return stack->q1->size;
+/**
+ * Returns the number of items on the stack
+ *
+ * @param self The stack to investigate
+ * @return The count of items on the stack.
+ */
+int size(Stack *self) {
+  return self->q1->size;
 }
 
-void destroy(Stack *stack) {
-  int count = size(stack);
+/**
+ * The equivalent of a destructor to free any memory associated with a Stack.
+ *
+ * @param self The stack to clean up
+ */
+void destroy(Stack *self) {
+  int count = size(self);
 
   for (int i = 0; i < count; i++)
-    pop(stack);
+    pop(self);
 
-  free(stack->q1);
-  free(stack);
+  free(self->q1);
+  free(self);
 }
 
-static void inspect(Queue *q) {
-  Node *tmp = q->head;
+/**
+ * A helper method used to print the items in a queue
+ *
+ * @param self the queue to print
+ */
+static void inspect(Queue *self) {
+  Node *tmp = self->head;
 
-  if (q->size == 0) {
+  if (self->size == 0) {
     printf("[]\n");
     return;
   }
 
   printf("[");
-  for (int i = 0; i < q->size; i++) {
+  for (int i = 0; i < self->size; i++) {
     printf("%d,", tmp->data);
     tmp = tmp->next;
   }