From ce668465e73a4a54c22ef7c0c0462569fc011f29 Mon Sep 17 00:00:00 2001 From: Hammy Date: Tue, 28 Dec 2021 03:04:26 +0000 Subject: [PATCH] Format documentation --- src/list.h | 180 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 121 insertions(+), 59 deletions(-) diff --git a/src/list.h b/src/list.h index b7d1adc..db0e272 100644 --- a/src/list.h +++ b/src/list.h @@ -5,178 +5,240 @@ typedef struct list List; /* - * Function: List_new() + * Description * ---------------------------- - * Return a new list that has been dynamically allocated memory on the heap + * Create a new list that has been dynamically allocated memory on the heap * - * returns: List (Pointer To List) + * Returns + * ---------------------------- + * List (Pointer To List) */ List *List_new(); /* - * Function: List_get(List *list, int index) + * Description * ---------------------------- * Retrieve an element from the list at the given index * - * *list: the list to append onto - * index: the index of the list to retrieve + * Params + * ---------------------------- + * *list the list to append onto + * index the index of the list to retrieve * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_get(List *list, int index); /* - * Function: List_append(List *list, int element) + * Description * ---------------------------- * Append an element onto the end of the list * - * *list: the list to append onto - * element: the element to insert into the list + * Params + * ---------------------------- + * *list the list to append onto + * element the element to insert into the list * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_append(List *list, int element); /* - * Function: List_append_all(List *list, int element_count, ...) + * + * Description * ---------------------------- * Append multiple elements into the given list * - * *list: the list to append onto - * element_count: number of elements to append into the given list - * ...: variable list of integers to append into the given list + * Params + * ---------------------------- + * *list the list to append onto + * element_count number of elements to append into the given list + * ... variable list of integers to append into the given list * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_append_all(List *list, int element_count, ...); /* - * Function: List_insert(List *list, int index, int element) + * + * Description * ---------------------------- * Insert the given element into a valid index of the list * - * *list: the list to insert into - * index: the index to insert the given value - * element: the element to insert into the list + * Params + * ---------------------------- + * *list the list to insert into + * index the index to insert the given value + * element the element to insert into the list * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_insert(List *list, int index, int element); /* - * Function: List_remove(List *list, int element) + * + * Description * ---------------------------- * Remove the first occurrence of the given element from the given list * - * *list: the list to remove given element from - * element: the element to remove from the given list + * Params + * ---------------------------- + * *list the list to remove given element from + * element the element to remove from the given list * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_remove(List *list, int element); /* - * Function: List_sort(List *list, bool reverse) + * + * Description * ---------------------------- * Sort the given list into ascending/descending order - * - * ============================== + * ======================================= * WARNING: This is an in-place operation - * ============================== + * ======================================= * - * *list: the list to sort - * reverse: true if wanting list to be sorted in descending order, false for ascending order + * Params + * ---------------------------- + * *list the list to sort + * reverse true if wanting list to be sorted in descending order, false for ascending order * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_sort(List *list, bool reverse); /* - * Function: List_copy(List *list) + * + * Description * ---------------------------- * Return a shallow copy of the given list * - * *list: the list to copy + * Params + * ---------------------------- + * *list the list to copy * - * returns: List (Pointer to List) + * Returns + * ---------------------------- + * List (Pointer to List) */ List *List_copy(List *list); /* - * Function: List_clear + * + * Description * ---------------------------- * Empty the given list - * * ======================================================================= * WARNING: This does NOT free the allocated memory for elements cleared. * ======================================================================= * - * *list: the list to clear + * Params + * ---------------------------- + * *list the list to clear * - * returns: int (0 for success, Non-0 for error) + * Returns + * ---------------------------- + * int (0 for success, Non-0 for error) */ int List_clear(List *list); /* - * Function: List_slice(List *list, int start_index, int end_index) + * + * Description * ---------------------------- * Return a sublist of the given list according to given indexes * - * *list: the list to slice - * start_index: the starting index to slice from (inclusive) - * end_index: the ending index to slice until (exclusive) + * Params + * ---------------------------- + * *list the list to slice + * start_index the starting index to slice from (inclusive) + * end_index the ending index to slice until (exclusive) * - * ================================= - * E.g + * Example + * ---------------------------- * Given List -> [0, 1, 2, 3, 4, 5] * When List_slice(list, 1, 4); * Then List Returned -> [1, 2, 3] - * ================================= * - * returns: List (Pointer To List) + * Returns + * ---------------------------- + * List (Pointer To List) */ List *List_slice(List *list, int start_index, int end_index); /* - * Function: List_length(List *list) + * + * Description * ---------------------------- * Return the length of the given list * - * *list: the list to get the length of + * Params + * ---------------------------- + * *list the list to get the length of * - * returns: int + * Returns + * ---------------------------- + * int */ int List_length(List *list); /* - * Function: List_max_length(List *list) + * + * Description * ---------------------------- * Return the maxLength (current maximum length allocated in memory) of the given list * - * *list: the list to get the maximum length of + * Params + * ---------------------------- + * *list the list to get the maximum length of * - * returns: int + * Returns + * ---------------------------- + * int */ int List_max_length(List *list); /* - * Function: List_print(List *list) + * + * Description * ---------------------------- * Print out the current elements within the given list * - * *list: the list to print out + * Params + * ---------------------------- + * *list the list to print out * - * returns: void + * Returns + * ---------------------------- + * void */ void List_print(List *list); /* - * Function: List_destroy(List *list) + * + * Description * ---------------------------- * Free the memory allocated to the list * - * **list: a pointer to the list to free in memory + * Params + * ---------------------------- + * **list a pointer to the list to free in memory * - * returns: void + * Returns + * ---------------------------- + * void */ void List_destroy(List **list); \ No newline at end of file