doc: create list module documentation

hozlucas28 · hozlucas28 · commit a94abcc63774 · 2025-02-14T15:19:31.000-03:00
diff --git a/libs/list/main.c b/libs/list/main.c
@@ -4,10 +4,12 @@
 
 Node* __getElementAt(List* _list, const size_t index);
 
-// Constructor
+/* ------------------------------- Constructor ------------------------------ */
+
 void newList(List* list) { *list = NULL; }
 
-// Destroyer
+/* ------------------------------- Destructor ------------------------------- */
+
 void destroyList(List* _list) {
     Node* nextNode;
 
@@ -20,7 +22,8 @@ void destroyList(List* _list) {
     }
 }
 
-// Getters
+/* --------------------------------- Getters -------------------------------- */
+
 Node* __getElementAt(List* _list, const size_t index) {
     size_t length = 0;
 
@@ -32,14 +35,6 @@ Node* __getElementAt(List* _list, const size_t index) {
     return *_list;
 }
 
-unsigned char getHead(const List* _list, void* store, const size_t sizeOfStore) {
-    if ((*_list) == NULL) return 0;
-
-    memcpy(store, (*_list)->__data, MIN(sizeOfStore, (*_list)->__sizeOfData));
-
-    return 1;
-}
-
 unsigned char getElement(const List* _list, void* store, const size_t sizeOfStore,
                          const size_t index) {
     size_t length = 0;
@@ -56,6 +51,25 @@ unsigned char getElement(const List* _list, void* store, const size_t sizeOfStor
     return 0;
 }
 
+size_t getLength(List* _list) {
+    size_t length = 0;
+
+    while ((*_list) != NULL) {
+        length++;
+        _list = &(*_list)->__next;
+    }
+
+    return length;
+}
+
+unsigned char getHead(const List* _list, void* store, const size_t sizeOfStore) {
+    if ((*_list) == NULL) return 0;
+
+    memcpy(store, (*_list)->__data, MIN(sizeOfStore, (*_list)->__sizeOfData));
+
+    return 1;
+}
+
 unsigned char isListEmpty(List* _list) { return (*_list) == NULL; }
 
 unsigned char isListFull(List* _list, const size_t sizeOfStore) {
@@ -71,18 +85,25 @@ unsigned char isListFull(List* _list, const size_t sizeOfStore) {
     return ((newNode == NULL) || (newNodeData == NULL));
 }
 
-size_t getLength(List* _list) {
-    size_t length = 0;
+/* --------------------------------- Methods -------------------------------- */
 
-    while ((*_list) != NULL) {
-        length++;
+unsigned char popElement(List* _list, void* store, const size_t sizeOfStore) {
+    if ((*_list) == NULL) {
+        return 0;
+    }
+
+    while ((*_list)->__next != NULL) {
         _list = &(*_list)->__next;
     }
 
-    return length;
+    memcpy(store, (*_list)->__data, MIN(sizeOfStore, (*_list)->__sizeOfData));
+    free((*_list)->__data);
+    free(*_list);
+    *_list = NULL;
+
+    return 1;
 }
 
-// Methods
 unsigned char pushElement(List* _list, void* data, const size_t sizeOfData) {
     Node* newNode;
 
@@ -104,49 +125,11 @@ unsigned char pushElement(List* _list, void* data, const size_t sizeOfData) {
     return 1;
 }
 
-unsigned char popElement(List* _list, void* store, const size_t sizeOfStore) {
-    if ((*_list) == NULL) {
-        return 0;
-    }
-
-    while ((*_list)->__next != NULL) {
-        _list = &(*_list)->__next;
-    }
-
-    memcpy(store, (*_list)->__data, MIN(sizeOfStore, (*_list)->__sizeOfData));
-    free((*_list)->__data);
-    free(*_list);
-    *_list = NULL;
-
-    return 1;
-}
-
-void selectionSort(List* _list, int (*cmp)(const void* a, const void* b)) {
-    void* aux;
-    unsigned tam;
-    List *minor, *iterator;
-
-    if (!(*_list)) return;
-
-    while ((*_list)->__next) {
-        iterator = &(*_list)->__next;
-        minor = _list;
-        while (*iterator) {
-            if (cmp((*minor)->__data, (*iterator)->__data) > 0) minor = iterator;
-            iterator = &(*iterator)->__next;
-        }
-        if (*minor != *_list) {
-            aux = (*_list)->__data;
-            tam = (*_list)->__sizeOfData;
-
-            (*_list)->__data = (*minor)->__data;
-            (*_list)->__sizeOfData = (*minor)->__sizeOfData;
-
-            (*minor)->__data = aux;
-            (*minor)->__sizeOfData = tam;
-        }
+void map(List* _list, void (*callback)(void* element)) {
+    while (*_list) {
+        callback((*_list)->__data);
         _list = &(*_list)->__next;
-    }
+    };
 }
 
 void randomSort(List* _list) {
@@ -203,9 +186,30 @@ void randomSort(List* _list) {
     }
 }
 
-void map(List* _list, action _action, void* punt) {
-    while (*_list) {
-        _action((*_list)->__data, punt);
+void selectionSort(List* _list, int (*cmp)(const void* a, const void* b)) {
+    void* aux;
+    unsigned tam;
+    List *minor, *iterator;
+
+    if (!(*_list)) return;
+
+    while ((*_list)->__next) {
+        iterator = &(*_list)->__next;
+        minor = _list;
+        while (*iterator) {
+            if (cmp((*minor)->__data, (*iterator)->__data) > 0) minor = iterator;
+            iterator = &(*iterator)->__next;
+        }
+        if (*minor != *_list) {
+            aux = (*_list)->__data;
+            tam = (*_list)->__sizeOfData;
+
+            (*_list)->__data = (*minor)->__data;
+            (*_list)->__sizeOfData = (*minor)->__sizeOfData;
+
+            (*minor)->__data = aux;
+            (*minor)->__sizeOfData = tam;
+        }
         _list = &(*_list)->__next;
-    };
-}
+    }
+}
diff --git a/libs/list/main.h b/libs/list/main.h
@@ -6,39 +6,160 @@
 
 #include "../structs.h"
 
-/* ---------- List ---------- */
+typedef Node* List; /** Singly linked list */
 
-typedef Node* List;
+/* ------------------------------- Constructor ------------------------------ */
 
-// Constructor
+/**
+ * @brief Initializes a new singly linked list.
+ *
+ * This function sets the given singly linked list to `NULL`.
+ *
+ * @param list Singly linked list structure to be initialized.
+ */
 void newList(List* list);
 
-// Destroyer
-void destroyList(List* _list);
+/* ------------------------------- Destructor ------------------------------- */
 
-// Getters
-unsigned char getHead(const List* _list, void* store, const size_t sizeOfStore);
+/**
+ * @brief Destroys a singly linked list.
+ *
+ * This function deallocates all the memory used by the nodes in the singly linked list,
+ * effectively destroying the list and setting the list pointer to `NULL`.
+ *
+ * @param _list Singly linked list to be destroyed.
+ */
+void destroyList(List* _list);
 
+/* --------------------------------- Getters -------------------------------- */
+
+/**
+ * @brief Retrieves a copy of the data at a specific index in the singly linked list.
+ *
+ * This function copies the data from the node at the specified index in the singly linked list
+ * into the provided storage.
+ *
+ * @param _list Singly linked list.
+ * @param store Storage where the data from the specified index will be copied.
+ * @param sizeOfStore Size in bytes of the storage.
+ * @param index Index of data to be copied.
+ *
+ * @return 0 if the data was successfully copied, 1 otherwise.
+ *
+ * @warning Ensure that the storage provided is large enough to hold the data from the specified
+ * index.
+ */
 unsigned char getElement(const List* _list, void* store, const size_t sizeOfStore,
                          const size_t index);
 
-unsigned char isListEmpty(List* _list);
+/**
+ * @brief Retrieves the length of the singly linked list.
+ *
+ * @param _list Singly linked list whose length is to be determined.
+ *
+ * @return Length of the singly linked list.
+ */
+size_t getLength(List* _list);
 
-unsigned char isListFull(List* _list, const size_t sizeOfStore);
+/**
+ * @brief Retrieves a copy of the top data inside the singly linked list.
+ *
+ * This function copies the data from the top of the singly linked list into the provided
+ * storage.
+ *
+ * @param _list Singly linked list.
+ * @param store Storage where the data from the top will be copied.
+ * @param sizeOfStore Size in bytes of the storage.
+ *
+ * @return 1 if the data was successfully copied, 0 otherwise.
+ *
+ * @warning Ensure that the storage provided is large enough to hold the top data.
+ */
+unsigned char getHead(const List* _list, void* store, const size_t sizeOfStore);
 
-size_t getLength(List* _list);
+/**
+ * @brief Checks if the singly linked list is empty.
+ *
+ * @param _list Singly linked list to be checked.
+ *
+ * @return 1 if the list is empty, 0 otherwise.
+ */
+unsigned char isListEmpty(List* _list);
 
-// Methods
-unsigned char pushElement(List* _list, void* data, const size_t sizeOfData);
+/**
+ * @brief Checks if the singly linked list can accommodate more data.
+ *
+ * This function attempts to allocate memory for a new data to determine if the list
+ * can accommodate more data. If either allocation fails, the list is considered full.
+ *
+ * @param _list Singly linked list to be checked.
+ * @param sizeOfStore Size in bytes of the data to be stored.
+ *
+ * @return 1 if the list is full, 0 otherwise.
+ *
+ * @warning This function temporarily allocates memory to check for fullness and immediately frees
+ * it.
+ */
+unsigned char isListFull(List* _list, const size_t sizeOfStore);
 
+/* --------------------------------- Methods -------------------------------- */
+
+/**
+ * @brief Removes the last data from the singly linked list and copies its data.
+ *
+ * This function removes the last data from the singly linked list and copies its data into the
+ * provided storage.
+ *
+ * @param _list Singly linked list from which the last data will be removed.
+ * @param store Storage where the data will be copied.
+ * @param sizeOfStore Size in bytes of the storage.
+ *
+ * @return 1 if the data was successfully copied to the store, 0 otherwise.
+ *
+ * @warning Ensure that the storage provided is large enough to hold data.
+ */
 unsigned char popElement(List* _list, void* store, const size_t sizeOfStore);
 
-void selectionSort(List* _list, int (*cmp)(const void* a, const void* b));
+/**
+ * @brief Adds a new data to the end of the singly linked list.
+ *
+ * @param _list Singly linked list where the new data will be added.
+ * @param data Data to be stored at the end of the singly linked list.
+ * @param sizeOfData Size in bytes of the data to be stored.
+ *
+ * @return 1 if the data was successfully added, 0 otherwise.
+ */
+unsigned char pushElement(List* _list, void* data, const size_t sizeOfData);
 
+/**
+ * @brief Applies a callback function to each data in the singly linked list.
+ *
+ * This function iterates through each data in the singly linked list and applies the provided
+ * callback function to the data.
+ *
+ * @param _list Singly linked list whose data will be processed.
+ * @param callback Function that will be applied to each data.
+ */
+void map(List* _list, void (*callback)(void* element));
+
+/**
+ * @brief Randomly shuffles the data of the singly linked list.
+ *
+ * @param _list Singly linked list to be shuffled.
+ */
 void randomSort(List* _list);
 
-typedef void (*action)(void* data, void* data2);
-
-void map(List* _list, action _action, void* punt);
+/**
+ * @brief Sorts the singly linked list using the selection sort algorithm.
+ *
+ * This function sorts the data of the singly linked list in ascending order
+ * based on the comparison function provided. The selection sort algorithm repeatedly
+ * selects the smallest data from the unsorted portion of the list and swaps it
+ * with the first unsorted data.
+ *
+ * @param _list Singly linked list to be sorted.
+ * @param cmp Comparison function.
+ */
+void selectionSort(List* _list, int (*cmp)(const void* a, const void* b));
 
 #endif  // LIBS__LIST_H_INCLUDED
