add comments

[ppos.git] / queue / queue.c

diff --git a/queue/queue.c b/queue/queue.c
index 2aed9eb54cae7f70b4021011226bf4b40adeba7c..6a08e90d22045c54aa4d6325fe4f619e35547b27 100644 (file)
--- a/queue/queue.c
+++ b/queue/queue.c
@@ -4,44 +4,61 @@
 
 // Implementação do TAD fila genérica
 
-/* PEDRO HENRIQUE FRIEDRICH RAMOS : GRR20243133 */
+/* PEDRO HENRIQUE FRIEDRICH RAMOS : GRR20243133  */
 
 #include "queue.h"
 #include <stdio.h>
 #include <stdlib.h>
 
+/* -------------------------------------------------------------------------  */
+/* Data types  -------------------------------------------------------------  */
+
+/* Queue element.  */
 struct node_t
 {
-  void *item;
-  struct node_t *next;
+  void *item; /* User provided opaque pointer.  */
+  struct node_t *next; /* Pointer to the next node in the queue.  */
 };
 
+/* -------------------------------------------------------------------------  */
+
+/* Queue.  */
 struct queue_t
 {
-  struct node_t *head;
-  struct node_t *tail;
-  struct node_t *iterator;
-  int size;
+  struct node_t *head; /* Pointer to the first node in the queue.  */
+  struct node_t *tail; /* Pointer to the last node in the queue.  */
+  struct node_t *iterator; /* Pointer to the current node.  */
+  int size; /* Number of nodes in the queue.  */
 };
 
+/* -------------------------------------------------------------------------  */
+/* Internal functions  -----------------------------------------------------  */
+
 static inline struct node_t *
 node_create (void)
 {
   return calloc (1, sizeof (struct node_t));
 }
 
+/* -------------------------------------------------------------------------  */
+
 static inline void
 node_destroy (struct node_t *node)
 {
   free (node);
 }
 
+/* -------------------------------------------------------------------------  */
+/* Exported functions  -----------------------------------------------------  */
+
 struct queue_t *
 queue_create (void)
 {
   return calloc (1, sizeof (struct queue_t));
 }
 
+/* -------------------------------------------------------------------------  */
+
 int
 queue_destroy (struct queue_t *queue)
 {
@@ -54,6 +71,7 @@ queue_destroy (struct queue_t *queue)
 
   while (n)
     {
+      /* Save the next node pointer before destroying the current node.  */
       next = n->next;
       node_destroy (n);
       n = next;
@@ -63,6 +81,8 @@ queue_destroy (struct queue_t *queue)
   return NOERROR;
 }
 
+/* -------------------------------------------------------------------------  */
+
 int
 queue_add (struct queue_t *queue, void *item)
 {
@@ -77,16 +97,20 @@ queue_add (struct queue_t *queue, void *item)
   n->item = item;
   ++queue->size;
 
+  /* Empty queue, this is the first element.  */
   if (!queue->head)
     {
       queue->head = queue->tail = queue->iterator = n;
       return NOERROR;
     }
 
+  /* Append to queue.  */
   queue->tail = queue->tail->next = n;
   return NOERROR;
 }
 
+/* -------------------------------------------------------------------------  */
+
 int
 queue_del (struct queue_t *queue, void *item)
 {
@@ -95,7 +119,7 @@ queue_del (struct queue_t *queue, void *item)
   if (!queue || !item)
     return ERROR;
 
-  if (!(n = queue->head))
+  if (!(n = queue->head)) /* Queue is empty.  */
     return ERROR;
 
   prev = NULL;
@@ -106,18 +130,20 @@ queue_del (struct queue_t *queue, void *item)
       n = n->next;
     }
 
-  if (!n) /* not found */
+  if (!n) /* Not found.  */
     return ERROR;
 
   if (prev)
     prev->next = n->next;
 
+  /* Update boundaries accordingly.  */
   if (queue->head == n)
     queue->head = n->next;
 
   if (queue->tail == n)
     queue->tail = prev;
 
+  /* Advance the iterator if it points to the removed node.  */
   if (queue->iterator == n)
     queue->iterator = n->next;
 
@@ -126,6 +152,8 @@ queue_del (struct queue_t *queue, void *item)
   return NOERROR;
 }
 
+/* -------------------------------------------------------------------------  */
+
 bool
 queue_has (struct queue_t *queue, void *item)
 {
@@ -137,12 +165,15 @@ queue_has (struct queue_t *queue, void *item)
   if (!(n = queue->head))
     return false;
 
+  /* Traverse until the item is found or the end is reached.  */
   while (n->item != item && (n = n->next))
     ;
 
   return n != NULL;
 }
 
+/* -------------------------------------------------------------------------  */
+
 int
 queue_size (struct queue_t *queue)
 {
@@ -152,6 +183,8 @@ queue_size (struct queue_t *queue)
   return queue->size;
 }
 
+/* -------------------------------------------------------------------------  */
+
 void *
 queue_head (struct queue_t *queue)
 {
@@ -163,6 +196,8 @@ queue_head (struct queue_t *queue)
   return queue->head->item;
 }
 
+/* -------------------------------------------------------------------------  */
+
 void *
 queue_next (struct queue_t *queue)
 {
@@ -177,6 +212,8 @@ queue_next (struct queue_t *queue)
   return queue->iterator->item;
 }
 
+/* -------------------------------------------------------------------------  */
+
 void *
 queue_item (struct queue_t *queue)
 {
@@ -186,6 +223,8 @@ queue_item (struct queue_t *queue)
   return queue->iterator->item;
 }
 
+/* -------------------------------------------------------------------------  */
+
 void
 queue_print (char *name, struct queue_t *queue, void (func) (void *))
 {
@@ -217,3 +256,5 @@ queue_print (char *name, struct queue_t *queue, void (func) (void *))
 
   printf ("] (%d items)\n", queue->size);
 }
+
+/* -------------------------------------------------------------------------  */