1 files changed, 122 insertions, 20 deletions

diff --git a/src/linked_list.h b/src/linked_list.h
index 4e6dadf..0da0c25 100644
--- a/src/linked_list.h
+++ b/src/linked_list.h
@@ -1,50 +1,152 @@
+/**
+ * @file linked_list.h
+ * @brief Doubly-linked list implementation.
+ * @details This module provides a generic doubly-linked list data structure
+ *          that can store pointers to any data type. The list maintains both
+ *          head and tail pointers for efficient operations at both ends.
+ */
+
 #ifndef LINKED_LIST_H
 #define LINKED_LIST_H
 
-// A linked list containing any type of pointer.
-// The linked list does _not_ own its elements.
-
+/**
+ * @struct LinkedList
+ * @brief A doubly-linked list container.
+ * @details Maintains references to the first and last nodes in the list,
+ *          as well as the current number of elements.
+ */
 typedef struct LinkedList LinkedList;
+
+/**
+ * @struct LinkedListNode
+ * @brief A node within a doubly-linked list.
+ * @details Each node contains pointers to the next and previous nodes,
+ *          allowing bidirectional traversal, and a generic data pointer.
+ */
 typedef struct LinkedListNode LinkedListNode;
 
+/**
+ * @struct LinkedList
+ * @brief A doubly-linked list container structure.
+ */
 struct LinkedList {
+    /**
+     * @brief Pointer to the first node in the list.
+     * @details NULL if the list is empty.
+     */
     LinkedListNode *head;
+
+    /**
+     * @brief Pointer to the last node in the list.
+     * @details NULL if the list is empty.
+     */
     LinkedListNode *tail;
+
+    /**
+     * @brief The number of nodes currently in the list.
+     * @details Updated whenever nodes are added or removed.
+     */
     int size;
 };
 
+/**
+ * @struct LinkedListNode
+ * @brief A single node in a doubly-linked list structure.
+ */
 struct LinkedListNode {
+    /**
+     * @brief Pointer to the next node in the list.
+     * @details NULL if this is the last node.
+     */
     LinkedListNode *next;
+
+    /**
+     * @brief Pointer to the previous node in the list.
+     * @details NULL if this is the first node (head).
+     */
     LinkedListNode *prev;
+
+    /**
+     * @brief Generic pointer to the node's data.
+     * @details The caller is responsible for managing the memory
+     *          pointed to by this pointer. This pointer can store any
+     *          data type (int*, char*, struct*, etc.).
+     */
     void *data;
 };
 
-// Allocate and initialize an empty linked list.
-// Returns: a pointer to the new linked list, or NULL on error.
-// Post: the caller owns the linked list.
+/**
+ * @brief Allocates and initializes an empty linked list.
+ *
+ * @return A pointer to the newly created linked list, or NULL if memory
+ *         allocation fails.
+ *
+ * @note The caller is responsible for freeing the returned linked list
+ *       using linked_list_delete().
+ */
 LinkedList *linked_list_new();
 
-// Deallocate the given linked list, including all nodes
-// (but _not_ the data they point to, the user owns that).
+/**
+ * @brief Deallocates the given linked list and all its nodes.
+ *
+ * @param ll Pointer to the linked list to delete. If NULL, this function
+ *           does nothing.
+ *
+ * @note This function deallocates only the list structure and nodes, not
+ *       the data they point to. The caller retains ownership of the data.
+ */
 void linked_list_delete(LinkedList *ll);
 
-// Append a the given element to the list.
-// The linked list does _not_ take ownership over the element
-// (only the linked list node).
-// Returns: a pointer to the node with the new element, or NULL on error.
+/**
+ * @brief Appends an element to the end of the linked list.
+ *
+ * @param ll Pointer to the linked list.
+ * @param elem Pointer to the element to append.
+ *
+ * @return A pointer to the newly created node containing the element,
+ *         or NULL if memory allocation fails.
+ *
+ * @note The linked list does not take ownership of the element itself,
+ *       only the node structure. The caller retains ownership of the
+ *       data.
+ */
 LinkedListNode *linked_list_append(LinkedList *ll, void *elem);
 
-// Remove and return the first element from the given list.
-// Pre: ll->size != 0
+/**
+ * @brief Removes and returns the first element from the linked list.
+ *
+ * @param ll Pointer to the linked list.
+ *
+ * @return The data pointer of the removed first element.
+ *
+ * @pre The list must not be empty (ll->size != 0).
+ */
 void *linked_list_popfront(LinkedList *ll);
 
-// Find the linked list node containing the given element.
-// Returns: a pointer to the found node, or NULL if the element was not found.
+/**
+ * @brief Finds the linked list node containing the given element.
+ *
+ * @param ll Pointer to the linked list.
+ * @param elem Pointer to the element to search for.
+ *
+ * @return A pointer to the node containing the element, or NULL if the
+ *         element was not found in the list.
+ */
 LinkedListNode *linked_list_find(LinkedList *ll, void *elem);
 
-// Remove the given node from the given linked list (and deallocate it).
-// Pre: node must belong to ll
-// Returns: node->data
+/**
+ * @brief Removes the given node from the linked list and deallocates it.
+ *
+ * @param ll Pointer to the linked list.
+ * @param node Pointer to the node to remove.
+ *
+ * @return The data pointer stored in the removed node.
+ *
+ * @pre The node must belong to the linked list ll.
+ *
+ * @note The node structure is deallocated, but the data is not. The
+ *       caller retains ownership of the returned data.
+ */
 void *linked_list_remove(LinkedList *ll, LinkedListNode *node);
 
-#endif // LINKED_LIST_H
+#endif // !LINKED_LIST_H