docs: consistency improvements

lib/array_list.h

@@ -27,24 +27,36 @@ struct array_list* array_list_initialization();
 
 /**
  * @brief Adds an element to the end of the array list.
+ *
+ * @param list
+ * @param element
  * @since v1.2.0
  */
 void array_list_add(struct array_list* list, void* element);
 
 /**
  * @brief Removes an element from the array list.
+ *
+ * @param list
+ * @param index
  * @since v1.2.0
  */
 void array_list_remove(struct array_list* list, size_t index);
 
 /**
  * @brief Gets an element from the array list.
+ *
+ * @param list
+ * @param index
+ * @return void*
  * @since v1.2.0
  */
 void* array_list_get(struct array_list* list, size_t index);
 
 /**
  * @brief Frees the array list.
+ *
+ * @param list
  * @since v3.0.0
  */
 void array_list_free(struct array_list* list);

lib/character.h

@@ -47,7 +47,9 @@ char character_to_lower(const char character);
 /**
  * @brief Check if the character is a digit ('0', '1', '2', '3', '4', '5', '6', '7, '8' or '9').
  *
- * @return true if the character is a digit, false otherwise
+ * @param character
+ * @return true
+ * @return false
  * @since v1.0.0
  */
 bool character_get_is_digit(const char character);
@@ -57,6 +59,7 @@ bool character_get_is_digit(const char character);
  * Return 0 if the character is not a letter.
  *
  * @param character
+ * @return unsigned char
  * @since v1.0.0
  */
 unsigned char character_get_alphabet_position(const char character);

lib/convert.h

@@ -15,6 +15,7 @@
  * @brief Convert a character to a string.
  *
  * @param character
+ * @return string_t
  * @since v1.0.0
  */
 string_t convert_character_to_string(const char character);
@@ -23,6 +24,7 @@ string_t convert_character_to_string(const char character);
  * @brief Convert a character to a digit.
  *
  * @param character
+ * @return char
  * @since v1.0.0
  */
 char convert_character_to_digit(const char character);
@@ -31,6 +33,7 @@ char convert_character_to_digit(const char character);
  * @brief Convert a digit to a character.
  *
  * @param digit
+ * @return char
  * @since v1.0.0
  */
 char convert_digit_to_character(const char digit);
@@ -39,6 +42,7 @@ char convert_digit_to_character(const char digit);
  * @brief Convert a string to a number.
  *
  * @param string
+ * @return long long
  * @since v1.0.0
  */
 long long convert_string_to_number(const string_t string);
@@ -47,6 +51,7 @@ long long convert_string_to_number(const string_t string);
  * @brief Convert a number to a string.
  *
  * @param integer
+ * @return string_t
  * @since v1.0.0
  */
 string_t convert_number_to_string(const long long integer);
@@ -56,6 +61,7 @@ string_t convert_number_to_string(const long long integer);
  *
  * @param number
  * @param base
+ * @return string_t
  * @since v1.0.0
  */
 string_t convert_number_from_base_10_to_base(unsigned long long number, unsigned int base);
@@ -65,6 +71,7 @@ string_t convert_number_from_base_10_to_base(unsigned long long number, unsigned
  *
  * @param number
  * @param base
+ * @return int
  * @since v1.0.0
  */
 int convert_number_from_base_to_base_10(string_t number, unsigned int base);
@@ -75,6 +82,7 @@ int convert_number_from_base_to_base_10(string_t number, unsigned int base);
  * @param number
  * @param base_from
  * @param base_target
+ * @return string_t
  * @since v1.0.0
  */
 string_t convert_number_from_base_to_another(string_t number, int base_from, int base_target);

lib/filesystem.h

@@ -18,9 +18,10 @@
  *
  * @param path
  * @param file_content
- * @param file_size
+ * @param file_size The size of the file that was read (mutated by the function).
  * @retval -1 if the file does not exist or if there is an error.
  * @retval 0 for success.
+ * @return int
  * @since v1.0.0
  */
 int filesystem_read(string_t path, byte_t **file_content, off_t *file_size);
@@ -33,6 +34,7 @@ int filesystem_read(string_t path, byte_t **file_content, off_t *file_size);
  * @param file_size
  * @retval -1 if there is an error.
  * @retval 0 for success.
+ * @return int
  * @since v1.0.0
  */
 int filesystem_write(string_t path, byte_t *file_content, off_t file_size);
@@ -41,8 +43,8 @@ int filesystem_write(string_t path, byte_t *file_content, off_t file_size);
  * @brief Check if a path exists.
  *
  * @param path
- * @retval true if the path exists.
- * @retval false if the path does not exist.
+ * @return true
+ * @return false
  * @since v3.1.0
  */
 bool filesystem_exists(string_t path);
@@ -54,6 +56,7 @@ bool filesystem_exists(string_t path);
  * @return int
  * @retval -1 if there is an error.
  * @retval 0 for success.
+ * @return int
  * @since v3.1.0
  */
 int filesystem_remove(string_t path);
@@ -64,6 +67,7 @@ int filesystem_remove(string_t path);
  * @param path
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
  * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+ * @return string_t
  * @since v1.0.0
  */
 string_t filesystem_get_mimetype(string_t path);

lib/hash_map.h

@@ -35,22 +35,27 @@ struct hash_map_item {
 
 /**
  * @brief Hash function (using SipHash 1-3 algorithm).
- * @param key
- * @param capacity
  * @see https://en.wikipedia.org/wiki/SipHash
  * @see https://github.com/veorq/SipHash
+ *
+ * @param key
+ * @param capacity
+ * @return uint64_t
  * @since v2.0.0
  */
 uint64_t hash(string_t key, size_t capacity);
 
 /**
  * @brief Hash map initialization.
+ *
+ * @return struct hash_map*
  * @since v2.0.0
  */
 struct hash_map *hash_map_initialization();
 
 /**
  * @brief Add an item to the hash map.
+ *
  * @param hash_map
  * @param key
  * @param data
@@ -70,14 +75,18 @@ void hash_map_remove(struct hash_map *hash_map, string_t key);
  * @brief Get an item from the hash map.
  * @param hash_map
  * @param key
+ * @return void*
  * @since v2.0.0
  */
 void *hash_map_get(struct hash_map *hash_map, string_t key);
 
 /**
  * @brief Check if the hash map contains a key.
+ *
  * @param hash_map
  * @param key
+ * @return true
+ * @return false
  * @since v2.0.0
  */
 bool hash_map_contains_key(struct hash_map *hash_map, string_t key);
@@ -86,12 +95,15 @@ bool hash_map_contains_key(struct hash_map *hash_map, string_t key);
  * @brief Get the hash map keys.
  *
  * @param hash_map
+ * @return string_t*
  * @since v2.0.0
  */
 string_t *hash_map_get_keys(struct hash_map *hash_map);
 
 /**
  * @brief Frees the hash map.
+ *
+ * @param hash_map
  * @since v3.0.0
  */
 void hash_map_free(struct hash_map *hash_map);

lib/linked_list.h

@@ -14,7 +14,6 @@
  */
 struct linked_list {
   struct linked_list_node *head;
-
   size_t length;
 };
 
@@ -29,42 +28,61 @@ struct linked_list_node {
 
 /**
  * @brief Linked list initialization.
+ *
+ * @return struct linked_list*
  * @since v1.0.0
  */
 struct linked_list *linked_list_initialization();
 
 /**
  * @brief Add a new node in the head of the linked list.
+ *
+ * @param list
+ * @param new_value
+ * @return struct linked_list_node*
  * @since v1.0.0
  */
 struct linked_list_node *linked_list_add_in_head(struct linked_list *list, void *new_value);
 
 /**
  * @brief Delete node in the head of the linked list.
+ *
+ * @param list
  * @since v1.0.0
  */
 void linked_list_delete_in_head(struct linked_list *list);
 
 /**
  * @brief Add a new node in the tail of the linked list.
+ *
+ * @param list
+ * @param new_data
+ * @return struct linked_list_node*
  * @since v1.0.0
  */
 struct linked_list_node *linked_list_add_after_last(struct linked_list *list, void *new_data);
 
 /**
  * @brief Reverse the linked list by creating a new one.
+ *
+ * @param list
+ * @return struct linked_list*
  * @since v1.0.0
  */
 struct linked_list *linked_list_reverse(struct linked_list *list);
 
 /**
  * @brief Reverse the linked list by mutating it.
+ *
+ * @param list
  * @since v1.0.0
  */
 void linked_list_reverse_mutate(struct linked_list *list);
 
 /**
  * @brief Frees the linked list.
+ *
+ * @param list
  * @since v3.0.0
  */
 void linked_list_free(struct linked_list *list);

lib/mathematics.h

@@ -13,6 +13,8 @@
  *
  * @param number1
  * @param number2
+ * @return true
+ * @return false
  * @since v1.0.0
  */
 bool mathematics_equals(const float number1, const float number2);
@@ -21,6 +23,7 @@ bool mathematics_equals(const float number1, const float number2);
  * @brief Get the absolute value of a number.
  *
  * @param number
+ * @return unsigned long long
  * @since v1.0.0
  */
 unsigned long long mathematics_absolute_value(const long long number);
@@ -30,15 +33,17 @@ unsigned long long mathematics_absolute_value(const long long number);
  *
  * @param base
  * @param exponent
+ * @return unsigned long long
  * @since v1.0.0
  */
 unsigned long long mathematics_pow(unsigned long long base, unsigned long long exponent);
 
 /**
- * @brief Calculates the nth root of a number using Heron's method.
+ * @brief Calculates the nth root of a number.
  *
  * @param number
  * @param nth_root
+ * @return float
  * @since v1.0.0
  */
 float mathematics_root(float number, unsigned int nth_root);
@@ -47,6 +52,7 @@ float mathematics_root(float number, unsigned int nth_root);
  * @brief Calculates the square root of a number using Heron's method.
  *
  * @param number
+ * @return float
  * @since v1.0.0
  */
 float mathematics_square_root(float number);
@@ -55,6 +61,7 @@ float mathematics_square_root(float number);
  * @brief Calculates the factorial of a number.
  *
  * @param number
+ * @return unsigned long long
  * @since v1.0.0
  */
 unsigned long long mathematics_factorial(unsigned long long number);

lib/queue.h

@@ -27,24 +27,34 @@ struct queue_node {
 
 /**
  * @brief Queue initialization.
+ *
+ * @return struct queue*
  * @since v1.0.0
  */
 struct queue *queue_initialization();
 
 /**
  * @brief Push data to queue.
+ *
+ * @param queue
+ * @param data
  * @since v1.0.0
  */
 void queue_push(struct queue *queue, void *data);
 
 /**
  * @brief Pop data from queue.
+ *
+ * @param queue
+ * @return void*
  * @since v1.0.0
  */
 void *queue_pop(struct queue *queue);
 
 /**
  * @brief Frees the queue.
+ *
+ * @param queue
  * @since v3.0.0
  */
 void queue_free(struct queue *queue);