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);

lib/stack.h

@@ -27,24 +27,34 @@ struct stack_node {
 
 /**
  * @brief Stack initialization.
+ *
+ * @return struct stack*
  * @since v1.0.0
  */
 struct stack *stack_initialization();
 
 /**
  * @brief Push data to stack.
+ *
+ * @param stack
+ * @param data
  * @since v1.0.0
  */
 void stack_push(struct stack *stack, void *data);
 
 /**
  * @brief Pop data from stack.
+ *
+ * @param stack
+ * @return void*
  * @since v1.0.0
  */
 void *stack_pop(struct stack *stack);
 
 /**
  * @brief Frees the stack.
+ *
+ * @param stack
  * @since v3.0.0
  */
 void stack_free(struct stack *stack);

lib/string.h

@@ -15,6 +15,7 @@
  * @brief Return the length of a string (excluding '\0').
  *
  * @param string
+ * @return size_t
  * @since v1.0.0
  */
 size_t string_get_length(const string_t string);
@@ -96,6 +97,7 @@ void string_trim(string_t string, char character);
  * @brief Return the copy of a string.
  *
  * @param string
+ * @return string_t
  * @since v1.0.0
  */
 string_t string_copy(const string_t string);
@@ -115,6 +117,7 @@ void string_capitalize(string_t string);
  *
  * @param string
  * @param character
+ * @return size_t
  * @since v1.0.0
  */
 size_t string_total_occurrences_of_character(string_t string, char character);
@@ -134,16 +137,18 @@ void string_reverse(const string_t string);
  *
  * @param string1
  * @param string2
- * @return true if the strings are equals, false otherwise.
+ * @return true if the strings are equals.
+ * @return false if the strings are not equals.
  * @since v1.0.0
  */
 bool string_equals(const string_t string1, const string_t string2);
 
 /**
- * @brief Check if the string is a integer.
+ * @brief Check if the string is an integer.
  *
  * @param string
- * @return true if the string is a integer, false otherwise.
+ * @return true if the string is an integer.
+ * @return false if the string is not an integer.
  * @since v1.0.0
  */
 bool string_get_is_integer(const string_t string);
@@ -154,6 +159,7 @@ bool string_get_is_integer(const string_t string);
  * @param string
  * @param separator
  * @param result_size
+ * @return string_t*
  * @since v1.0.0
  */
 string_t* string_split(const string_t string, char separator, size_t* result_size);
@@ -164,6 +170,7 @@ string_t* string_split(const string_t string, char separator, size_t* result_siz
  * @param array
  * @param separator
  * @param array_length
+ * @return string_t
  * @since v1.0.0
  */
 string_t string_join(string_t* array, const char separator, size_t array_length);
@@ -183,7 +190,8 @@ void string_concatenate(string_t* destination, string_t source);
  * @brief Check if a string contains only unique characters.
  *
  * @param string
- * @return true if string contains only unique characters, false otherwise.
+ * @return true if string contains only unique characters.
+ * @return false if string contains duplicate characters.
  * @since v1.0.0
  */
 bool string_get_has_unique_characters(const string_t string);
@@ -194,6 +202,7 @@ bool string_get_has_unique_characters(const string_t string);
  * @param string
  * @param index_start
  * @param index_end
+ * @return string_t
  * @since v1.0.0
  */
 string_t string_substring(const string_t string, size_t index_start, size_t index_end);
@@ -203,7 +212,8 @@ string_t string_substring(const string_t string, size_t index_start, size_t inde
  *
  * @param string
  * @param substring
- * @return true if the string contains the substring, false otherwise.
+ * @return true if the string contains the substring.
+ * @return false if the string does not contain the substring.
  * @since v1.0.0
  */
 bool string_get_is_substring(const string_t string, const string_t substring);
@@ -213,11 +223,12 @@ bool string_get_is_substring(const string_t string, const string_t substring);
  *
  * @param number
  * @param separator
- * @since v1.0.0
+ * @return string_t
  * @code
  * string_get_formatted_number(1000, " ") // "1 000"
  * string_get_formatted_number(1000, ",") // "1,000"
  * @endcode
+ * @since v1.0.0
  */
 string_t string_get_formatted_number(const long long number, string_t separator);
 
@@ -226,6 +237,7 @@ string_t string_get_formatted_number(const long long number, string_t separator)
  *
  * @param string
  * @param character
+ * @return string_t
  * @since v1.0.0
  */
 string_t string_get_last_occurence_of_character(const string_t string, char character);
@@ -235,7 +247,8 @@ string_t string_get_last_occurence_of_character(const string_t string, char char
  *
  * @param string
  * @param prefix
- * @return true if the string starts with the substring, false otherwise.
+ * @return true if the string starts with the substring.
+ * @return false if the string does not start with the substring.
  * @since v1.0.0
  */
 bool string_starts_with(const string_t string, const string_t prefix);
@@ -245,7 +258,8 @@ bool string_starts_with(const string_t string, const string_t prefix);
  *
  * @param string
  * @param prefix
- * @return true if the string ends with the substring, false otherwise.
+ * @return true if the string ends with the substring.
+ * @return false if the string does not end with the substring.
  * @since v1.0.0
  */
 bool string_ends_with(const string_t string, const string_t prefix);

lib/terminal.h

@@ -17,6 +17,8 @@
 
 /**
  * @brief Read a line from stdin.
+ *
+ * @return string_t
  * @since v1.0.0
  */
 string_t terminal_input();
@@ -111,7 +113,7 @@ void terminal_print_hash_map(struct hash_map* hash_map, void (*print_element)(vo
 /**
  * @brief Print an array list.
  *
- * @param array_list
+ * @param list
  * @param print_element
  * @since v3.0.0
  */

set_version.c

@@ -16,6 +16,7 @@ int main(int argc, char** argv) {
   int result = filesystem_write("./version.h", (byte_t*)content, string_get_length(content));
   if (result == -1) {
     fprintf(stderr, "Error: Could not write to file.\n");
+    perror("Error (set_version)");
     return EXIT_FAILURE;
   }
   printf("Success: Version set to %s.\n", argv[1]);