Refactor user management functions and improve memory handling in addPersonToList

include/users.h

@@ -17,7 +17,7 @@ typedef struct person
     time_t last_time_event;
     uint32_t total;
 
-    pthread_mutex_t lock; 
+    pthread_mutex_t lock;
 } person_t;
 
 typedef struct node
@@ -26,14 +26,41 @@ typedef struct node
     struct node *next;
 } node_t;
 
-uint16_t generateUUID(node_t * _head);
+uint16_t generateUUID(node_t *_head);
 
-uint16_t searchUUIDByName(node_t * _head);
+uint16_t searchUUIDByName(node_t *_head);
 
-node_t * searchPersonByUUID(node_t * _head);
+node_t *searchPersonByUUID(node_t *_head);
 
-void addPersonToList(node_t * _head, char * _name, char * _surname, uint32_t _department);
+/**
+ * @brief Adds a new person to the linked list.
+ *
+ * This function creates a new person and appends it to the end of the linked list.
+ * It dynamically allocates memory for the new person and initializes their details.
+ * If memory allocation fails or the input parameters are invalid, the function returns an error.
+ *
+ * @param _head Pointer to the head of the linked list (node_t **).
+ * @param _name Pointer to a string containing the person's first name.
+ * @param _surname Pointer to a string containing the person's last name.
+ * @param _department The department number to which the person belongs.
+ * 
+ * @return int Returns 1 if the person was successfully added, otherwise 0 on failure.
+ *
+ * @note Memory for the name and surname is dynamically allocated. It is the caller's
+ *       responsibility to free the memory for the entire list to avoid memory leaks.
+ *
+ * @example
+ * ```c
+ * node_t *head = NULL;
+ * if (addPersonToList(&head, "John", "Doe", 101)) {
+ *     printf("Person successfully added.\n");
+ * } else {
+ *     printf("Error adding person.\n");
+ * }
+ * ```
+ */
+int addPersonToList(node_t **_head, char *_name, char *_surname, uint32_t _department);
 
-void addTimeEvent(node_t * _person);
+int addTimeEvent(node_t *_person);
 
 #endif