1
1
mirror of https://github.com/theoludwig/libcproject.git synced 2024-11-08 22:31:31 +01:00

docs: consistency improvements

This commit is contained in:
Théo LUDWIG 2023-08-09 21:08:15 +02:00
parent 7ef38fa993
commit b9ba3fbff4
Signed by: theoludwig
GPG Key ID: ADFE5A563D718F3B
12 changed files with 118 additions and 17 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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
*/

View File

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