Refactor and document queue data structure

Improved code style and consistency in queue.c and queue.h, added detailed documentation for the queue data structure, and clarified comments. Updated main.c build instructions and fixed minor formatting issues. Added include guard for QUEUE_EMPTY in queue.h.

Author: XuhuaHuang

AbstractDataType/main.c

@@ -2,8 +2,13 @@
  * @file main.c
  * @author Xuhua Huang
  * @brief To compile and run the demo, execute the following:
- * $ cd .\AbstractDataTypes\
+ * $ cd .\AbstractDataType\
  * $ mingw32-make all
+ * 
+ * or alternatively with CMake:
+ * $ cd .\AbstractDataType\
+ * $ cmake -S . -B build
+ * $ cmake --build build --config Debug --verbose
  *
  * @version 0.1
  * @date 2022-11-07
@@ -15,10 +20,11 @@
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
+
 #include "queue.h"
 
 int main(void) {
-    queue *q = q_create(5);
+    queue* q = q_create(5);
 
     q_endqueue(q, 23);
     q_endqueue(q, 34);

AbstractDataType/queue.c

@@ -11,37 +11,46 @@
 
 #include "queue.h"
 
+/**
+ * @brief Queue data structure
+ *
+ * @details `values` is a dynamically allocated array that holds the queue entries.
+ * `head` points to the front of the queue, where entries are dequeued.
+ * `tail` points to the end of the queue, where entries are enqueued.
+ * `num_entries` keeps track of the number of entries currently in the queue.
+ * `size` reflects the maximum number of entries that can be stored in the underlying array.
+ */
 typedef struct _queue {
-    int *values;
-    int head, tail;
-    int num_entries, size;
+    int* values;
+    int  head, tail;
+    int  num_entries, size;
 } queue;
 
-queue *q_create(int max_size) {
-    queue *q = malloc(sizeof(queue));
-    q->size = max_size;
-    q->values = malloc(sizeof(int) * q->size);
+queue* q_create(int max_size) {
+    queue* q       = malloc(sizeof(queue));
+    q->size        = max_size;
+    q->values      = malloc(sizeof(int) * q->size);
     q->num_entries = 0; // the queue is empty for now
-    q->head = 0;
-    q->tail = 0;
+    q->head        = 0; // points to the front of the queue
+    q->tail        = 0; // points to the end of the queue
     return q;
 }
 
-void q_destroy(queue *q) {
+void q_destroy(queue* q) {
     free(q->values);
     free(q);
     q = NULL;
 }
 
-bool q_empty(queue *q) {
-    return (q->num_entries == 0);
+bool q_empty(queue* q) {
+    return (bool)(q->num_entries == 0);
 }
 
-bool q_full(queue *q) {
-    return (q->num_entries == q->size);
+bool q_full(queue* q) {
+    return (bool)(q->num_entries == q->size);
 }
 
-bool q_endqueue(queue *q, int value) {
+bool q_endqueue(queue* q, int value) {
     // no more entry space available
     if (q_full(q)) {
         return false;
@@ -53,14 +62,14 @@ bool q_endqueue(queue *q, int value) {
     return true;
 }
 
-int q_dequeue(queue *q) {
+int q_dequeue(queue* q) {
     int result;
 
     if (q_empty(q)) {
         return QUEUE_EMPTY;
     }
 
-    result = q->values[q->head];
+    result  = q->values[q->head];
     q->head = (q->head + 1) % q->size;
     q->num_entries--;
 

AbstractDataType/queue.h

@@ -11,11 +11,13 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+#ifndef QUEUE_EMPTY
 #define QUEUE_EMPTY INT_MIN
+#endif // !QUEUE_EMPTY
 
 /**
  * @brief The compiler will treat "queue"
- * as in incomplete type.
+ * as an incomplete type.
  * queue is an opaque data type.
  */
 typedef struct _queue queue;
@@ -30,4 +32,4 @@ bool   q_full(queue* q);
 bool   q_endqueue(queue* q, int value);
 int    q_dequeue(queue* q);
 
-#endif
+#endif  //!QUEUE_H