From: Michael D. Lowis Date: Wed, 3 Sep 2014 16:36:59 +0000 (-0400) Subject: Fix documentation X-Git-Url: https://git.mdlowis.com/?a=commitdiff_plain;h=6f50e3eb40a26824cb3274baba63870c3ebb3279;p=projs%2Flibcds.git Fix documentation --- diff --git a/source/buffer/buf.c b/source/buffer/buf.c index eae75cc..5efeaeb 100644 --- a/source/buffer/buf.c +++ b/source/buffer/buf.c @@ -1,8 +1,6 @@ /** @file buf.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "buf.h" diff --git a/source/buffer/buf.h b/source/buffer/buf.h index 2c15e85..b7866a5 100644 --- a/source/buffer/buf.h +++ b/source/buffer/buf.h @@ -1,8 +1,6 @@ /** @file buf.h @brief Implementation of a circular buffer. - $Revision$ - $HeadURL$ */ #ifndef BUF_H #define BUF_H diff --git a/source/exn/exn.c b/source/exn/exn.c index 3cb3dc2..f0b533e 100755 --- a/source/exn/exn.c +++ b/source/exn/exn.c @@ -1,8 +1,6 @@ /** @file exn.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "exn.h" #include diff --git a/source/exn/exn.h b/source/exn/exn.h index 3c7febb..93ad5f6 100755 --- a/source/exn/exn.h +++ b/source/exn/exn.h @@ -1,8 +1,6 @@ /** @file exn.h @brief An implementation of exception handling in pure ANSI C. - $Revision$ - $HeadURL$ */ #ifndef EXN_H #define EXN_H diff --git a/source/list/list.c b/source/list/list.c index 317d7ad..d669599 100644 --- a/source/list/list.c +++ b/source/list/list.c @@ -1,8 +1,6 @@ /** @file list.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "list.h" diff --git a/source/list/list.h b/source/list/list.h index b9ae7ad..1801352 100644 --- a/source/list/list.h +++ b/source/list/list.h @@ -1,3 +1,7 @@ +/** + @file list.h + @brief An Implementation of a doubly linked list. + */ #ifndef LIST_H #define LIST_H @@ -7,226 +11,226 @@ extern "C" { #include "rt.h" -/** A linked list node. */ -typedef struct list_node_t -{ - /** Pointer to the contents the node */ - void* contents; - /** Pointer to next node in the list */ - struct list_node_t* next; - /** pointer to prev node in the list */ - struct list_node_t* prev; -} list_node_t; - -/** A doubly linked list */ -typedef struct list_t -{ - /** Pointer to the first element in the list */ - list_node_t* head; - /** Pointer to the last element in the list */ - list_node_t* tail; -} list_t; - -/** - * @brief Creates a new empty linked list. - * - * @return A pointer to the newly created list. - **/ -list_t* list_new(void); - -/** - * @brief Creates a new node with given contents. - * - * @param contents Pointer to the contents of this node. - * - * @return Pointer to newly created node. - */ -list_node_t* list_new_node(void* contents); - -/** - * @brief Returns pointer to first node in the list - * - * @param list The list from which to retrieve elements. - * - * @return Pointer to the first element in the list. - */ -list_node_t* list_front( list_t* list ); - -/** - * @brief Returns pointer to the last element in the list. - * - * @param The list from which to retrieve elements. - * - * @return Pointer to the last element in the list. - */ -list_node_t* list_back( list_t* list ); - -/** - * @brief Returns the number of elements in the list. - * - * This function loops through the supplied list and returns a count of the - * number of elements contained in the list. - * - * @param list The list to be counted. - * - * @return The number of elements in the list. - **/ -size_t list_size(list_t* list); - -/** - * @brief Returns whether the list is empty or not. - * - * @param list The list to operate on. - * - * @return Whether the list is empty, 1 for true and 0 for false. - */ -bool list_empty(list_t* list); - -/** !!this function is unnecessary now that list is doubly linked. - * @brief Find the node before the given one in the specified list. - * - * @param list The list to search thru - * @param node The node to search for - * - * @return Pointer to the node before the given node or - * NULL if given node is NULL, is the head of list - */ -list_node_t* list_prev(list_t* list, list_node_t* node); - -/** - * @brief Return the node at the specified index in a linked list. - * - * This function loops through the linked list and returns the node in the list - * at the specified index. Returns NULL if the index is out of range. - * - * @param list The list to search for the supplied index. - * @param index The index of the node to return. - * - * @return A pointer to the node at the supplied index, NULL if out of range. - **/ -list_node_t* list_at(list_t* list, size_t index); - -/** - * @brief Return the index of the specified node in a linked list. - * - * This function loops through the linked list and returns the index in the list - * that matches the specified node. Returns -1 if the node is not found. - * Note: since NULL is implicitly at the end of every list, calling this - * with NULL for the node is equivalent to list_size - * - * @param list The list to search thru - * @param node The node to look for - * - * @return The int index of the supplied node, -1 if not found. - **/ -int list_index_of(list_t* list, list_node_t* node); - -/** - * @brief Adds a new node to the front of an existing linked list. - * - * This function creates a new node and pushes it to the beginning of the given - * list. The newly created node becomes the new head of the list. - * - * @param list The list to operate on. - * @param contents The contents of the new node. - * - * @return Pointer to the newly added node. - **/ -list_node_t* list_push_front( list_t* list, void* contents ); - -/** - * @brief Adds a new node to the end of an existing linked list. - * - * This function creates a new node and pushes it to the end of the given list. - * The newly created node becomes the new tail of the list. - * - * @param list The list to operate on. - * @param contents The contents of the new node. - * - * @return Pointer to the newly added node. - **/ -list_node_t* list_push_back( list_t* list, void* contents ); - -/** - * @brief Removes and returns a pointer to the first element of the list. - * - * This function removes the first node from the list and frees it's associated - * memory. - * - * @param list The lsit to operate on. - * - * @return Pointer to the newly added node. - **/ -list_node_t* list_pop_front( list_t* list ); - -/** - * @brief Removes and returns a pointer to the last element of the list. - * - * This function removes the last node from the list and frees it's associated - * memory. - * - * @param list The list to operate on. - * - * @return Pointer to the newly added node. - **/ -list_node_t* list_pop_back( list_t* list ); - -/** - * @brief Inserts a new node in a linked list at the specified index. - * - * This function traverses the list to the desired index and inserts a new node - * with the given contents at that position. The node previously at the desired - * index becomes the child of the new node. - * - * @param list The list to operate on. - * @param index The index where the new node will be inserted. - * @param contents The contents of the new node. - * - * @return Pointer to the newly inserted node, NULL if index is out of range. - **/ -list_node_t* list_insert( list_t* list, size_t index, void* contents); - -/** - * @brief Inserts a new node in a linked list after the specified node - * - * @param list The list to operate on. - * @param node The node after which the item should be inserted. - * if node is NULL, will insert at the beginning of the list - * @param contents The contents of the new node. - * - * @return Pointer to the newly inserted node - **/ -list_node_t* list_insert_after( list_t* list, list_node_t* node, void* contents); - -/** - * @brief Deletes a node from the supplied list. - * - * This function traverses the list to the desired index and frees the memory - * allocated for that node. If the deleted node has a child then the child is - * reattached to the deleted node's parent. - * - * @param list The list to operate on. - * @param index The index of the node to delete. - **/ -void list_delete(list_t* list, size_t index); - -/** - * @brief Delete a node from the supplied list. - * - * This function differs from the above list_delete in that it is given a - * pointer to a node to be deleted instead of an index. - * - * @param list The list to operate on. - * @param node A pointer to the node to delete. - */ -void list_delete_node(list_t* list, list_node_t* node); - -/** - * @brief Deletes all elements in the provided list - * - * @param list The list to be cleared - */ -void list_clear(list_t* list); + /** A linked list node. */ + typedef struct list_node_t + { + /** Pointer to the contents the node */ + void* contents; + /** Pointer to next node in the list */ + struct list_node_t* next; + /** pointer to prev node in the list */ + struct list_node_t* prev; + } list_node_t; + + /** A doubly linked list */ + typedef struct list_t + { + /** Pointer to the first element in the list */ + list_node_t* head; + /** Pointer to the last element in the list */ + list_node_t* tail; + } list_t; + + /** + * @brief Creates a new empty linked list. + * + * @return A pointer to the newly created list. + **/ + list_t* list_new(void); + + /** + * @brief Creates a new node with given contents. + * + * @param contents Pointer to the contents of this node. + * + * @return Pointer to newly created node. + */ + list_node_t* list_new_node(void* contents); + + /** + * @brief Returns pointer to first node in the list + * + * @param list The list from which to retrieve elements. + * + * @return Pointer to the first element in the list. + */ + list_node_t* list_front( list_t* list ); + + /** + * @brief Returns pointer to the last element in the list. + * + * @param The list from which to retrieve elements. + * + * @return Pointer to the last element in the list. + */ + list_node_t* list_back( list_t* list ); + + /** + * @brief Returns the number of elements in the list. + * + * This function loops through the supplied list and returns a count of the + * number of elements contained in the list. + * + * @param list The list to be counted. + * + * @return The number of elements in the list. + **/ + size_t list_size(list_t* list); + + /** + * @brief Returns whether the list is empty or not. + * + * @param list The list to operate on. + * + * @return Whether the list is empty, 1 for true and 0 for false. + */ + bool list_empty(list_t* list); + + /** !!this function is unnecessary now that list is doubly linked. + * @brief Find the node before the given one in the specified list. + * + * @param list The list to search thru + * @param node The node to search for + * + * @return Pointer to the node before the given node or + * NULL if given node is NULL, is the head of list + */ + list_node_t* list_prev(list_t* list, list_node_t* node); + + /** + * @brief Return the node at the specified index in a linked list. + * + * This function loops through the linked list and returns the node in the list + * at the specified index. Returns NULL if the index is out of range. + * + * @param list The list to search for the supplied index. + * @param index The index of the node to return. + * + * @return A pointer to the node at the supplied index, NULL if out of range. + **/ + list_node_t* list_at(list_t* list, size_t index); + + /** + * @brief Return the index of the specified node in a linked list. + * + * This function loops through the linked list and returns the index in the list + * that matches the specified node. Returns -1 if the node is not found. + * Note: since NULL is implicitly at the end of every list, calling this + * with NULL for the node is equivalent to list_size + * + * @param list The list to search thru + * @param node The node to look for + * + * @return The int index of the supplied node, -1 if not found. + **/ + int list_index_of(list_t* list, list_node_t* node); + + /** + * @brief Adds a new node to the front of an existing linked list. + * + * This function creates a new node and pushes it to the beginning of the given + * list. The newly created node becomes the new head of the list. + * + * @param list The list to operate on. + * @param contents The contents of the new node. + * + * @return Pointer to the newly added node. + **/ + list_node_t* list_push_front( list_t* list, void* contents ); + + /** + * @brief Adds a new node to the end of an existing linked list. + * + * This function creates a new node and pushes it to the end of the given list. + * The newly created node becomes the new tail of the list. + * + * @param list The list to operate on. + * @param contents The contents of the new node. + * + * @return Pointer to the newly added node. + **/ + list_node_t* list_push_back( list_t* list, void* contents ); + + /** + * @brief Removes and returns a pointer to the first element of the list. + * + * This function removes the first node from the list and frees it's associated + * memory. + * + * @param list The lsit to operate on. + * + * @return Pointer to the newly added node. + **/ + list_node_t* list_pop_front( list_t* list ); + + /** + * @brief Removes and returns a pointer to the last element of the list. + * + * This function removes the last node from the list and frees it's associated + * memory. + * + * @param list The list to operate on. + * + * @return Pointer to the newly added node. + **/ + list_node_t* list_pop_back( list_t* list ); + + /** + * @brief Inserts a new node in a linked list at the specified index. + * + * This function traverses the list to the desired index and inserts a new node + * with the given contents at that position. The node previously at the desired + * index becomes the child of the new node. + * + * @param list The list to operate on. + * @param index The index where the new node will be inserted. + * @param contents The contents of the new node. + * + * @return Pointer to the newly inserted node, NULL if index is out of range. + **/ + list_node_t* list_insert( list_t* list, size_t index, void* contents); + + /** + * @brief Inserts a new node in a linked list after the specified node + * + * @param list The list to operate on. + * @param node The node after which the item should be inserted. + * if node is NULL, will insert at the beginning of the list + * @param contents The contents of the new node. + * + * @return Pointer to the newly inserted node + **/ + list_node_t* list_insert_after( list_t* list, list_node_t* node, void* contents); + + /** + * @brief Deletes a node from the supplied list. + * + * This function traverses the list to the desired index and frees the memory + * allocated for that node. If the deleted node has a child then the child is + * reattached to the deleted node's parent. + * + * @param list The list to operate on. + * @param index The index of the node to delete. + **/ + void list_delete(list_t* list, size_t index); + + /** + * @brief Delete a node from the supplied list. + * + * This function differs from the above list_delete in that it is given a + * pointer to a node to be deleted instead of an index. + * + * @param list The list to operate on. + * @param node A pointer to the node to delete. + */ + void list_delete_node(list_t* list, list_node_t* node); + + /** + * @brief Deletes all elements in the provided list + * + * @param list The list to be cleared + */ + void list_clear(list_t* list); #ifdef __cplusplus } diff --git a/source/mem/mem.c b/source/mem/mem.c index a0d8731..6e47265 100644 --- a/source/mem/mem.c +++ b/source/mem/mem.c @@ -1,3 +1,7 @@ +/** + @file mem.c + @brief See header for details + */ #include "mem.h" #ifdef LEAK_DETECT_LEVEL #include @@ -40,7 +44,7 @@ size_t Num_Allocations = 0; static #endif void summarize_leaks(void) { - #if (LEAK_DETECT_LEVEL == 2) +#if (LEAK_DETECT_LEVEL == 2) bool leak_detected = false; block_t* p_curr = Live_Blocks; /* Print out all the live blocks and where they were allocated from */ @@ -48,22 +52,22 @@ void summarize_leaks(void) { { block_t* to_be_freed = p_curr; printf("%p %s (line %d): %d references to object\n", - p_curr->p_obj, - p_curr->p_file, - p_curr->line, - mem_num_references(p_curr->p_obj)); + p_curr->p_obj, + p_curr->p_file, + p_curr->line, + mem_num_references(p_curr->p_obj)); p_curr = p_curr->p_next; free(to_be_freed); leak_detected = true; } if(leak_detected) puts("Memory leak(s) detected!"); - #elif (LEAK_DETECT_LEVEL == 1) +#elif (LEAK_DETECT_LEVEL == 1) if(Num_Allocations > 0) { puts("Warning: Memory leak(s) detected!"); printf("\nFor more details set the LEAK_DETECT_LEVEL build option to 2 or run the executable in valgrind.\n"); } - #endif +#endif } #if (LEAK_DETECT_LEVEL == 2) @@ -125,7 +129,7 @@ void* mem_allocate(size_t size, destructor_t p_destruct_fn) obj_t* p_obj = (obj_t*)malloc(sizeof(obj_t) + size); p_obj->refcount = 1; p_obj->p_finalize = p_destruct_fn; - #if (LEAK_DETECT_LEVEL == 1) +#if (LEAK_DETECT_LEVEL == 1) Num_Allocations++; /* If we haven't already, register an exit handler that will printout the * unfreed objects before the program quits */ @@ -134,7 +138,7 @@ void* mem_allocate(size_t size, destructor_t p_destruct_fn) atexit(summarize_leaks); Handler_Registered = true; } - #endif +#endif return (void*)(p_obj+1); } @@ -163,11 +167,11 @@ void mem_release(void* p_obj) p_hdr->refcount -= 1; if(p_hdr->refcount < 1) { - #if (LEAK_DETECT_LEVEL == 2) +#if (LEAK_DETECT_LEVEL == 2) deregister_block(p_obj); - #elif (LEAK_DETECT_LEVEL == 1) +#elif (LEAK_DETECT_LEVEL == 1) Num_Allocations--; - #endif +#endif if(p_hdr->p_finalize) { p_hdr->p_finalize(p_obj); diff --git a/source/mem/mem.h b/source/mem/mem.h index fcdfb4d..78f084f 100644 --- a/source/mem/mem.h +++ b/source/mem/mem.h @@ -1,8 +1,6 @@ /** @file mem.h @brief Implements reference counting routines for C. - $Revision$ - $HeadURL$ */ #ifndef MEM_H #define MEM_H diff --git a/source/rbt/rbt.c b/source/rbt/rbt.c index 1cc3dbd..843d456 100644 --- a/source/rbt/rbt.c +++ b/source/rbt/rbt.c @@ -1,8 +1,6 @@ /** @file rbt.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "rbt.h" diff --git a/source/rbt/rbt.h b/source/rbt/rbt.h index 3da093e..512d1ca 100644 --- a/source/rbt/rbt.h +++ b/source/rbt/rbt.h @@ -1,5 +1,9 @@ -#ifndef RB_H -#define RB_H +/** + @file rbt.h + @brief Implementation of a Red-Black tree. + */ +#ifndef RBT_H +#define RBT_H #ifdef __cplusplus extern "C" { @@ -7,90 +11,90 @@ extern "C" { #include "rt.h" -/** node colors */ -typedef enum { - RED = 0, - BLACK -} rbt_color_t; - -/** a function pointer for comparing node contents -should return -1, 0, or 1 if a is <, ==, or > b, respectively */ -typedef int (*comparator_t)(void* p_a, void* p_b); - -/** a red-black tree node */ -typedef struct rbt_node_t { - /** pointers to immediate relatives */ - struct rbt_node_t* left; - struct rbt_node_t* right; - struct rbt_node_t* parent; - /** node color */ - rbt_color_t color; - /** pointer to node contents */ - void* contents; -} rbt_node_t; - -/** a red-black tree */ -typedef struct { - /** pointer to the root of the tree */ - rbt_node_t* root; - /** function pointer for comparing node contents */ - comparator_t comp; -} rbt_t; - - -/** - * @brief creates a new red-black tree - * - * @param comparator pointer to the comparator function - * - * @return pointer to newly created tree - */ -rbt_t* rbt_new(comparator_t comparator); - - -/** - * @brief find a value in a red-black tree - * - * @param tree pointer to the tree on which to operate - * @param value pointer to the data to find - * - * @return pointer to the node containing the given value - * NULL if the value is present in the tree - */ -rbt_node_t* rbt_lookup(rbt_t* tree, void* value); - - -/** - * @brief count the number of nodes in a red-black tree - * - * @param tree pointer to the tree on which to operate - * - * @return the number of nodes present in the tree - */ -int rbt_size(rbt_t* tree); - -/** - * @brief insert a value into a red-black tree - * - * @param tree pointer to the tree on which to operate - * @param value pointer to the value to be inserted - * - * @return a pointer to the new node - */ -rbt_node_t* rbt_insert(rbt_t* tree, void* value); - - -/** - * @brief removes a value from a red-black tree - * - * @param tree pointer to the tree on which to operate - * @param value pointer to the value to be removed - */ -void rbt_delete(rbt_t* tree, void* value); + /** node colors */ + typedef enum { + RED = 0, + BLACK + } rbt_color_t; + + /** a function pointer for comparing node contents + should return -1, 0, or 1 if a is <, ==, or > b, respectively */ + typedef int (*comparator_t)(void* p_a, void* p_b); + + /** a red-black tree node */ + typedef struct rbt_node_t { + /** pointers to immediate relatives */ + struct rbt_node_t* left; + struct rbt_node_t* right; + struct rbt_node_t* parent; + /** node color */ + rbt_color_t color; + /** pointer to node contents */ + void* contents; + } rbt_node_t; + + /** a red-black tree */ + typedef struct { + /** pointer to the root of the tree */ + rbt_node_t* root; + /** function pointer for comparing node contents */ + comparator_t comp; + } rbt_t; + + + /** + * @brief creates a new red-black tree + * + * @param comparator pointer to the comparator function + * + * @return pointer to newly created tree + */ + rbt_t* rbt_new(comparator_t comparator); + + + /** + * @brief find a value in a red-black tree + * + * @param tree pointer to the tree on which to operate + * @param value pointer to the data to find + * + * @return pointer to the node containing the given value + * NULL if the value is present in the tree + */ + rbt_node_t* rbt_lookup(rbt_t* tree, void* value); + + + /** + * @brief count the number of nodes in a red-black tree + * + * @param tree pointer to the tree on which to operate + * + * @return the number of nodes present in the tree + */ + int rbt_size(rbt_t* tree); + + /** + * @brief insert a value into a red-black tree + * + * @param tree pointer to the tree on which to operate + * @param value pointer to the value to be inserted + * + * @return a pointer to the new node + */ + rbt_node_t* rbt_insert(rbt_t* tree, void* value); + + + /** + * @brief removes a value from a red-black tree + * + * @param tree pointer to the tree on which to operate + * @param value pointer to the value to be removed + */ + void rbt_delete(rbt_t* tree, void* value); #ifdef __cplusplus } #endif -#endif /* RB_H */ +#endif /* RBT_H */ diff --git a/source/rt.h b/source/rt.h index bed0c74..9bea95a 100755 --- a/source/rt.h +++ b/source/rt.h @@ -1,12 +1,10 @@ /** - @file hdr.h + @file rt.h @brief A helper file with runtime specific includes used by all files in the library. - $Revision$ - $HeadURL$ */ -#ifndef HDR_H -#define HDR_H +#ifndef RT_H +#define RT_H #include #include @@ -17,4 +15,4 @@ #include "exn.h" #include "mem.h" -#endif /* HDR_H */ +#endif /* RT_H */ diff --git a/source/string/str.c b/source/string/str.c index 6b64233..a0b55c7 100644 --- a/source/string/str.c +++ b/source/string/str.c @@ -1,8 +1,6 @@ /** @file str.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "str.h" diff --git a/source/string/str.h b/source/string/str.h index 1a6a15a..9115342 100644 --- a/source/string/str.h +++ b/source/string/str.h @@ -1,8 +1,6 @@ /** @file str.h @brief An updated string type for C. - $Revision$ - $HeadURL$ */ #ifndef STR_H #define STR_H diff --git a/source/vector/vec.c b/source/vector/vec.c index 4573725..61d8c94 100644 --- a/source/vector/vec.c +++ b/source/vector/vec.c @@ -1,8 +1,6 @@ /** @file vec.c @brief See header for details - $Revision$ - $HeadURL$ */ #include "vec.h" diff --git a/source/vector/vec.h b/source/vector/vec.h index 2ec79ca..54e70ed 100644 --- a/source/vector/vec.h +++ b/source/vector/vec.h @@ -1,8 +1,6 @@ /** @file vec.h @brief A vector implementation. - $Revision$ - $HeadURL$ */ #ifndef VEC_H #define VEC_H