Add code comments

1 files changed, 70 insertions, 20 deletions

diff --git a/src/01/02b/doubly_linked_list.c b/src/01/02b/doubly_linked_list.c
index 24e1734..4a46fcf 100644
--- a/src/01/02b/doubly_linked_list.c
+++ b/src/01/02b/doubly_linked_list.c
@@ -2,6 +2,13 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/**
+ * The equivalent of a constructor
+ * to initialize a new node in a doubly linked list.
+ *
+ * @param data The data to initialize the head node with.
+ * @return new Node bound to the data specified
+ */
 Node *initialize(int data) {
   Node *node = malloc(sizeof(Node));
   node->data = data;
@@ -10,21 +17,43 @@ Node *initialize(int data) {
   return node;
 }
 
-Node *add(Node *head, int data) {
-  Node *tail;
+/**
+ * Returns the tail of the list.
+ *
+ * @param head The head of the linked list
+ * @return The tail of the linked list
+ */
+Node *tail(Node *head) {
   Node *tmp = head;
-
   while (tmp) {
     if (!tmp->next)
       break;
     tmp = tmp->next;
   }
-  tail = tmp;
-  tail->next = initialize(data);
-  tail->next->prev = tail;
-  return tail->next;
+  return tmp;
+}
+
+/**
+ * Adds data to the tail of a doubly linked list.
+ *
+ * @param head The head of the doubly linked list
+ * @param data The data to append to the list
+ * @return Returns the new node.
+ */
+Node *add(Node *head, int data) {
+  Node *t = tail(head);
+  t->next = initialize(data);
+  t->next->prev = t;
+  return t->next;
 }
 
+/**
+ * Returns a specific node in the list by index starting from 0.
+ *
+ * @param from The node to start scanning from.
+ * @param index The zero based index of the node to retrieve.
+ * @return The node at the specified index.
+ */
 Node *get(Node *from, int index) {
   if (!from || index < 0)
     return NULL;
@@ -36,6 +65,12 @@ Node *get(Node *from, int index) {
   return from;
 }
 
+/**
+ * Returns the number of items in the linked list.
+ *
+ * @param head The head of the linked list
+ * @return The number of items in the list.
+ */
 static int size(Node *head) {
   int i = 0;
   for (Node *tmp = head; tmp && tmp != NULL; tmp = tmp->next)
@@ -43,6 +78,12 @@ static int size(Node *head) {
   return i;
 }
 
+/**
+ * Assigns the next pointer of a node.
+ *
+ * @param self The node struct to alter.
+ * @param other The other node to point to.
+ */
 static void assign_next(Node *self, Node *other) {
   if (self)
     self->next = other;
@@ -51,6 +92,12 @@ static void assign_next(Node *self, Node *other) {
     other->prev = self;
 }
 
+/**
+ * Assigns the previous pointer of a node.
+ *
+ * @param self The node struct to alter.
+ * @param other The other node to point to.
+ */
 static void assign_prev(Node *self, Node *other) {
   if (self)
     self->prev = other;
@@ -59,6 +106,12 @@ static void assign_prev(Node *self, Node *other) {
     other->next = self;
 }
 
+/**
+ * Swaps two different nodes in the same linked list.
+ *
+ * @param x A node to swap
+ * @param y Another node to swap
+ */
 void swap(Node *x, Node *y) {
   if (x == y)
     return;
@@ -82,19 +135,11 @@ void swap(Node *x, Node *y) {
   }
 }
 
-Node *reverse(Node *head) {
-  Node *tmp = NULL;
-  Node *current = head;
-
-  while (current != NULL) {
-    tmp = current->prev;
-    current->prev = current->next;
-    current->next = tmp;
-    current = current->prev;
-  }
-  return tmp ? tmp->prev : head;
-}
-
+/**
+ * Prints the previous, data and next pointers for a node
+ *
+ * @param node The node to print
+ */
 static void print(Node *node) {
   if (node->prev && node->next)
     printf("(%d<%d>%d)", node->prev->data, node->data, node->next->data);
@@ -104,6 +149,11 @@ static void print(Node *node) {
     printf("(%d<%d>nil)", node->prev->data, node->data);
 }
 
+/**
+ * Renders a visual output of a full linked list.
+ *
+ * @param node The head of the linked list
+ */
 void inspect(Node *node) {
   if (!node)
     return;