From d1b93d1da0b7319f70b4b4cca2a380a4cd53d06f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20LUDWIG?= <contact@theoludwig.fr>
Date: Sat, 24 Jun 2023 21:06:45 +0200
Subject: [PATCH] docs: add `@since` to know when a structure/function was
 added

---
 lib/array_list.h  | 20 ++++++++++++++
 lib/character.h   |  6 +++++
 lib/convert.h     | 59 ++++++++++++++++++++++++++++++++++++++++
 lib/filesystem.h  |  3 +++
 lib/linked_list.h | 32 ++++++++++++++++++++++
 lib/mathematics.h | 37 ++++++++++++++++++++++++++
 lib/queue.h       | 21 ++++++++++++++-
 lib/stack.h       | 21 ++++++++++++++-
 lib/string.h      | 23 ++++++++++++++++
 lib/terminal.h    | 68 +++++++++++++++++++++++++++++++++++++++++++++++
 10 files changed, 288 insertions(+), 2 deletions(-)

diff --git a/lib/array_list.h b/lib/array_list.h
index dd6bb9a..6c64f92 100644
--- a/lib/array_list.h
+++ b/lib/array_list.h
@@ -6,18 +6,38 @@
 
 #define ARRAY_LIST_INITIAL_CAPACITY 10
 
+/**
+ * @brief A dynamic array implementation.
+ * @since v1.2.0
+ */
 struct array_list {
   void** data;
   size_t size;
   size_t capacity;
 };
 
+/**
+ * @brief Initializes a new array list.
+ * @since v1.2.0
+ */
 struct array_list* array_list_initialization();
 
+/**
+ * @brief Adds an element to the end of the array list.
+ * @since v1.2.0
+ */
 void array_list_add(struct array_list* list, void* element);
 
+/**
+ * @brief Removes an element from the array list.
+ * @since v1.2.0
+ */
 void array_list_remove(struct array_list* list, size_t index);
 
+/**
+ * @brief Gets an element from the array list.
+ * @since v1.2.0
+ */
 void* array_list_get(struct array_list* list, size_t index);
 
 #endif
diff --git a/lib/character.h b/lib/character.h
index 2299372..14cf7ce 100644
--- a/lib/character.h
+++ b/lib/character.h
@@ -12,6 +12,7 @@
  *
  * @param string
  * @param character
+ * @since v1.0.0
  */
 void character_append(char* string, char character);
 
@@ -21,6 +22,7 @@ void character_append(char* string, char character);
  * @param string
  * @param character
  * @param index
+ * @since v1.0.0
  */
 void character_append_at(char* string, const char character, const size_t index);
 
@@ -29,6 +31,7 @@ void character_append_at(char* string, const char character, const size_t index)
  *
  * @param character
  * @return const char
+ * @since v1.0.0
  */
 char character_to_upper(const char character);
 
@@ -37,6 +40,7 @@ char character_to_upper(const char character);
  *
  * @param character
  * @return const char
+ * @since v1.0.0
  */
 char character_to_lower(const char character);
 
@@ -46,6 +50,7 @@ char character_to_lower(const char character);
  * @param string1
  * @param string2
  * @return true if the character is a digit, false otherwise
+ * @since v1.0.0
  */
 bool character_get_is_digit(const char character);
 
@@ -55,6 +60,7 @@ bool character_get_is_digit(const char character);
  *
  * @param character
  * @return char
+ * @since v1.0.0
  */
 unsigned char character_get_alphabet_position(const char character);
 
diff --git a/lib/convert.h b/lib/convert.h
index a112af8..251ac25 100644
--- a/lib/convert.h
+++ b/lib/convert.h
@@ -9,20 +9,79 @@
 #include "stdbool.h"
 #include "string.h"
 
+/**
+ * @brief Convert a character to a string.
+ *
+ * @param character
+ * @since v1.0.0
+ */
 char* 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);
 
+/**
+ * @brief Convert a digit to a character.
+ *
+ * @param digit
+ * @return char
+ * @since v1.0.0
+ */
 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 char* string);
 
+/**
+ * @brief Convert a number to a string.
+ *
+ * @param integer
+ * @return char*
+ * @since v1.0.0
+ */
 char* convert_number_to_string(const long long integer);
 
+/**
+ * @brief Convert a number (base 10) to a string with a specific base.
+ *
+ * @param number
+ * @param base
+ * @return char*
+ * @since v1.0.0
+ */
 char* convert_number_from_base_10_to_base(unsigned long long number, unsigned int base);
 
+/**
+ * @brief Convert a number with a specific base to a number base 10.
+ *
+ * @param number
+ * @param base
+ * @return int
+ * @since v1.0.0
+ */
 int convert_number_from_base_to_base_10(char* number, unsigned int base);
 
+/**
+ * @brief Convert a number with a specific base to a number of specific base.
+ *
+ * @param number
+ * @param base_from
+ * @param base_target
+ * @return char*
+ * @since v1.0.0
+ */
 char* convert_number_from_base_to_another(char* number, int base_from, int base_target);
 
 #endif
diff --git a/lib/filesystem.h b/lib/filesystem.h
index de67c56..cab4e48 100644
--- a/lib/filesystem.h
+++ b/lib/filesystem.h
@@ -21,6 +21,7 @@
  * @return int
  * @retval -1 if the file does not exist
  * @retval 0 for success
+ * @since v1.0.0
  */
 int filesystem_read(char *path, char **file_content, off_t *file_size);
 
@@ -33,6 +34,7 @@ int filesystem_read(char *path, char **file_content, off_t *file_size);
  * @return int
  * @retval -1 if errors
  * @retval 0 for success
+ * @since v1.0.0
  */
 int filesystem_write(char *path, char *file_content, off_t file_size);
 
@@ -41,6 +43,7 @@ int filesystem_write(char *path, char *file_content, off_t file_size);
  *
  * @param path
  * @return char*
+ * @since v1.0.0
  */
 char *filesystem_get_mimetype(char *path);
 
diff --git a/lib/linked_list.h b/lib/linked_list.h
index 9bedde4..ff20024 100644
--- a/lib/linked_list.h
+++ b/lib/linked_list.h
@@ -6,27 +6,59 @@
 
 #include "stack.h"
 
+/**
+ * @brief Linked list data structure.
+ * @since v1.0.0
+ */
 struct linked_list {
   struct linked_list_node *head;
 
   size_t length;
 };
 
+/**
+ * @brief Linked list node data structure.
+ * @since v1.0.0
+ */
 struct linked_list_node {
   void *data;
   struct linked_list_node *next;
 };
 
+/**
+ * @brief Linked list initialization.
+ * @since v1.0.0
+ */
 struct linked_list *linked_list_initialization();
 
+/**
+ * @brief Add a new node in the head of the linked list.
+ * @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.
+ * @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.
+ * @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.
+ * @since v1.0.0
+ */
 struct linked_list *linked_list_reverse(struct linked_list *list);
 
+/**
+ * @brief Reverse the linked list by mutating it.
+ * @since v1.0.0
+ */
 void linked_list_reverse_mutate(struct linked_list *list);
 
 #endif
diff --git a/lib/mathematics.h b/lib/mathematics.h
index 3e6c05f..cc426fd 100644
--- a/lib/mathematics.h
+++ b/lib/mathematics.h
@@ -5,10 +5,32 @@
 
 #include <stdbool.h>
 
+/**
+ * @brief Verify that 2 numbers are equal.
+ *
+ * @param number1
+ * @param number2
+ * @since v1.0.0
+ */
 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);
 
+/**
+ * @brief Calculates the power of a 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);
 
 /**
@@ -17,11 +39,26 @@ unsigned long long mathematics_pow(unsigned long long base, unsigned long long e
  * @param number
  * @param nth_root
  * @return float
+ * @since v1.0.0
  */
 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);
 
+/**
+ * @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);
 
 #endif
diff --git a/lib/queue.h b/lib/queue.h
index c1e9185..288fb17 100644
--- a/lib/queue.h
+++ b/lib/queue.h
@@ -4,21 +4,40 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-// FIFO = First In First Out
+/**
+ * @brief Queue structure => FIFO (First In First Out).
+ * @since v1.0.0
+ */
 struct queue {
   struct queue_node *first;
   size_t length;
 };
 
+/**
+ * @brief Queue node structure.
+ * @since v1.0.0
+ */
 struct queue_node {
   void *data;
   struct queue_node *next;
 };
 
+/**
+ * @brief Queue initialization.
+ * @since v1.0.0
+ */
 struct queue *queue_initialization();
 
+/**
+ * @brief Push data to queue.
+ * @since v1.0.0
+ */
 void queue_push(struct queue *queue, void *data);
 
+/**
+ * @brief Pop data from queue.
+ * @since v1.0.0
+ */
 void *queue_pop(struct queue *queue);
 
 #endif
diff --git a/lib/stack.h b/lib/stack.h
index 385552e..3333d43 100644
--- a/lib/stack.h
+++ b/lib/stack.h
@@ -4,21 +4,40 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-// LIFO = Last In First Out
+/**
+ * @brief Stack structure => LIFO (Last In First Out).
+ * @since v1.0.0
+ */
 struct stack {
   struct stack_node *first;
   size_t length;
 };
 
+/**
+ * @brief Stack node structure.
+ * @since v1.0.0
+ */
 struct stack_node {
   void *data;
   struct stack_node *next;
 };
 
+/**
+ * @brief Stack initialization.
+ * @since v1.0.0
+ */
 struct stack *stack_initialization();
 
+/**
+ * @brief Push data to stack.
+ * @since v1.0.0
+ */
 void stack_push(struct stack *stack, void *data);
 
+/**
+ * @brief Pop data from stack.
+ * @since v1.0.0
+ */
 void *stack_pop(struct stack *stack);
 
 #endif
diff --git a/lib/string.h b/lib/string.h
index 57c4d50..9a37cf2 100644
--- a/lib/string.h
+++ b/lib/string.h
@@ -14,6 +14,7 @@
  *
  * @param string
  * @return size_t
+ * @since v1.0.0
  */
 size_t string_get_length(const char* string);
 
@@ -22,6 +23,7 @@ size_t string_get_length(const char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_to_uppercase(char* string);
 
@@ -30,6 +32,7 @@ char* string_to_uppercase(char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_to_lowercase(char* string);
 
@@ -40,6 +43,7 @@ char* string_to_lowercase(char* string);
  * @param search_value A character search value.
  * @param replace_value A character containing the text to replace for match.
  * @return char*
+ * @since v1.0.0
  */
 char* string_replace(char* string, char search, char replace);
 
@@ -48,6 +52,7 @@ char* string_replace(char* string, char search, char replace);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_trim_start(char* string);
 
@@ -56,6 +61,7 @@ char* string_trim_start(char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_trim_end(char* string);
 
@@ -64,6 +70,7 @@ char* string_trim_end(char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_trim(char* string);
 
@@ -72,6 +79,7 @@ char* string_trim(char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_copy(const char* string);
 
@@ -80,6 +88,7 @@ char* string_copy(const char* string);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_capitalize(char* string);
 
@@ -89,6 +98,7 @@ char* string_capitalize(char* string);
  * @param string
  * @param character
  * @return size_t
+ * @since v1.0.0
  */
 size_t string_total_occurrences_of_character(char* string, char character);
 
@@ -97,6 +107,7 @@ size_t string_total_occurrences_of_character(char* string, char character);
  *
  * @param string
  * @return char*
+ * @since v1.0.0
  */
 char* string_reverse(const char* string);
 
@@ -106,6 +117,7 @@ char* string_reverse(const char* string);
  * @param string1
  * @param string2
  * @return true if the strings are equals, false otherwise.
+ * @since v1.0.0
  */
 bool string_equals(const char* string1, const char* string2);
 
@@ -114,6 +126,7 @@ bool string_equals(const char* string1, const char* string2);
  *
  * @param string
  * @return true if the string is a integer, false otherwise.
+ * @since v1.0.0
  */
 bool string_get_is_integer(const char* string);
 
@@ -123,6 +136,7 @@ bool string_get_is_integer(const char* string);
  * @param string
  * @param separator
  * @return char**
+ * @since v1.0.0
  */
 char** string_split(const char* string, char separator, size_t* result_size);
 
@@ -132,6 +146,7 @@ char** string_split(const char* string, char separator, size_t* result_size);
  * @param array
  * @param separator
  * @return char*
+ * @since v1.0.0
  */
 char* string_join(char** array, const char separator, size_t array_length);
 
@@ -141,6 +156,7 @@ char* string_join(char** array, const char separator, size_t array_length);
  * @param string1
  * @param string2
  * @return char*
+ * @since v1.0.0
  */
 char* string_concatenate(char* string1, char* string2);
 
@@ -149,6 +165,7 @@ char* string_concatenate(char* string1, char* string2);
  *
  * @param string
  * @return true if string contains only unique characters, false otherwise.
+ * @since v1.0.0
  */
 bool string_get_has_unique_characters(const char* string);
 
@@ -159,6 +176,7 @@ bool string_get_has_unique_characters(const char* string);
  * @param index_start
  * @param index_end
  * @return char*
+ * @since v1.0.0
  */
 char* string_substring(const char* string, size_t index_start, size_t index_end);
 
@@ -168,6 +186,7 @@ char* string_substring(const char* string, size_t index_start, size_t index_end)
  * @param string
  * @param substring
  * @return true if the string contains the substring, false otherwise.
+ * @since v1.0.0
  */
 bool string_get_is_substring(const char* string, const char* substring);
 
@@ -176,6 +195,7 @@ bool string_get_is_substring(const char* string, const char* substring);
  *
  * @param integer
  * @return char* example: string_get_formatted_number(1000, " ") => "1 000"
+ * @since v1.0.0
  */
 char* string_get_formatted_number(const long long number, char* separator);
 
@@ -185,6 +205,7 @@ char* string_get_formatted_number(const long long number, char* separator);
  * @param string
  * @param character
  * @return char*
+ * @since v1.0.0
  */
 char* string_get_last_occurence_of_character(const char* string, char character);
 
@@ -194,6 +215,7 @@ char* string_get_last_occurence_of_character(const char* string, char character)
  * @param string
  * @param prefix
  * @return true if the string starts with the substring, false otherwise.
+ * @since v1.0.0
  */
 bool string_starts_with(const char* string, const char* prefix);
 
@@ -203,6 +225,7 @@ bool string_starts_with(const char* string, const char* prefix);
  * @param string
  * @param prefix
  * @return true if the string ends with the substring, false otherwise.
+ * @since v1.0.0
  */
 bool string_ends_with(const char* string, const char* prefix);
 
diff --git a/lib/terminal.h b/lib/terminal.h
index bd72a3c..a570f9c 100644
--- a/lib/terminal.h
+++ b/lib/terminal.h
@@ -16,27 +16,95 @@
  * @brief Read a line from stdin.
  *
  * @return char*
+ * @since v1.0.0
  */
 char* terminal_input();
 
+/**
+ * @brief Print an array.
+ *
+ * @param array
+ * @param array_size
+ * @param element_size
+ * @param print_element
+ * @since v1.0.0
+ */
 void terminal_print_array(void* array, size_t array_size, size_t element_size, void (*print_element)(void*));
 
+/**
+ * @brief Print a int.
+ *
+ * @param value
+ * @since v1.0.0
+ */
 void terminal_print_int(void* value);
 
+/**
+ * @brief Print a long.
+ *
+ * @param value
+ * @since v1.0.0
+ */
 void terminal_print_long(void* value);
 
+/**
+ * @brief Print a unsigned long.
+ *
+ * @param value
+ * @since v1.0.0
+ */
 void terminal_print_unsigned_long(void* value);
 
+/**
+ * @brief Print a char.
+ *
+ * @param value
+ * @since v1.0.0
+ */
 void terminal_print_char(void* value);
 
+/**
+ * @brief Print a string.
+ *
+ * @param value
+ * @since v1.0.0
+ */
 void terminal_print_string(void* value);
 
+/**
+ * @brief Print a stack.
+ *
+ * @param stack
+ * @param print_element
+ * @since v1.0.0
+ */
 void terminal_print_stack(struct stack* stack, void (*print_element)(void*));
 
+/**
+ * @brief Print a queue.
+ *
+ * @param queue
+ * @param print_element
+ * @since v1.0.0
+ */
 void terminal_print_queue(struct queue* queue, void (*print_element)(void*));
 
+/**
+ * @brief Print a linked list.
+ *
+ * @param linked_list
+ * @param print_element
+ * @since v1.0.0
+ */
 void terminal_print_linked_list(struct linked_list* linked_list, void (*print_element)(void*));
 
+/**
+ * @brief Print a dictionary.
+ *
+ * @param dictionary
+ * @param print_element
+ * @since v1.0.0
+ */
 void terminal_print_dictionary(struct dictionary* dictionary, void (*print_element)(void*));
 
 #endif