From f37cfefc5a12be33315611cddbd64fa8ee70c6d8 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Sat, 2 Dec 2006 23:02:34 +0000 Subject: [PATCH] fix the doxygen comments to produce proper docs --- include/QF/hash.h | 156 ++++++++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 54 deletions(-) diff --git a/include/QF/hash.h b/include/QF/hash.h index 21ae14b64..a2d01ca08 100644 --- a/include/QF/hash.h +++ b/include/QF/hash.h @@ -38,22 +38,22 @@ typedef struct hashtab_s hashtab_t; -/** create a new hash table: - tsize: table size. larger values will give better distribution, but +/** create a new hash table. + \param tsize table size. larger values will give better distribution, but use more memory. - gk: a function that returns a string to be used as the key for + \param gk a function that returns a string to be used as the key for inserting or finding the element. First parameter is a pointer to the element from which to extract the key, the second is the user data pointer. - f: a function to free the element. Only ever called from + \param f a function to free the element. Only ever called from Hash_FlushTable and Hash_DelTable. The first parameter is the element to be freed and the second is the user data pointer. - ud: user data pointer. set to whatever you want, it will be passed + \param ud user data pointer. set to whatever you want, it will be passed to the get key and free functions as the second parameter. - returns a pointer to the hash table (to be passed to the other functions) - or 0 on error. + \return pointer to the hash table (to be passed to the other functions) + or 0 on error. - Hash_Add, Hash_Find, Hash_FindList and Hash_Del use gk and strcmp. + Hash_Add(), Hash_Find(), Hash_FindList() and Hash_Del() use gk and strcmp. multiple inserions of the same key are fine; later insertions override previous ones until the later one is removed (Hash_Del). @@ -70,94 +70,142 @@ hashtab_t *Hash_NewTable (int tsize, const char *(*gk)(void*,void*), be mixed with the non-element functions, but by default the results will be undefined. - gh takes the same parameters as gk above - cmp is element 1, element 2, userdata + \param gh takes the same parameters as gk in Hash_NewTable + \param cmp is element 1, element 2, userdata */ void Hash_SetHashCompare (hashtab_t *tab, unsigned long (*gh)(void*,void*), int (*cmp)(void*,void*,void*)); -/** delete a hash table: - tab: the table to be deleted +/** delete a hash table. + \param tab the table to be deleted */ void Hash_DelTable (hashtab_t *tab); -/** clean out all the entries from a hash table, starting over again: - tab: the table to be cleared +/** clean out all the entries from a hash table, starting over again. + \param tab the table to be cleared */ void Hash_FlushTable (hashtab_t *tab); -//@{ -/** add an entry to a hash table: - tab: the table to be added to - ele: the element to add to the table - returns 0 for success, -1 for error. +/** add an entry to a hash table. + \param tab the table to be added to + \param ele the element to add to the table + \return 0 for success, -1 for error. */ int Hash_Add (hashtab_t *tab, void *ele); -int Hash_AddElement (hashtab_t *tab, void *ele); -//@} -//@{ -/** find an element within a hash table: - tab: the table to search - key: the key string identifying the element being searched for - returns a pointer to the element if found, otherwise 0. +/** add an entry to a hash table. + \param tab the table to be added to + \param ele the element to add to the table + \return 0 for success, -1 for error. +*/ +int Hash_AddElement (hashtab_t *tab, void *ele); + +/** find an element within a hash table. + \param tab the table to search + \param key the key string identifying the element being searched for + \param ele element with info identifying the element being searched for + \return pointer to the element if found, otherwise 0. */ void *Hash_Find (hashtab_t *tab, const char *key); -void *Hash_FindElement (hashtab_t *tab, void *ele); -//@} -//@{ -/** find a list of elements within a hash table: - tab: the table to search - key: the key string identifying the elements being searched for - returns a null terminated list of element pointers if at least one found, - otherwise 0. returned list is guaranteed to be in reverse order of - insertion. ie, deleting items from the list in list order will delete the - correct items. +/** find an element within a hash table. + \param tab the table to search + \param key the key string identifying the element being searched for + \param ele element with info identifying the element being searched for + \return pointer to the element if found, otherwise 0. +*/ +void *Hash_FindElement (hashtab_t *tab, void *ele); + +/** find a list of elements within a hash table. + \param tab the table to search + \param key the key string identifying the elements being searched for + \return a null terminated list of element pointers if at least one + found, otherwise 0. + \note it is the caller's responsibilty to free() the list. + + returned list is guaranteed to be in reverse order of insertion. ie, + deleting items from the list in list order will delete the correct items. */ void **Hash_FindList (hashtab_t *tab, const char *key); -void **Hash_FindElementList (hashtab_t *tab, void *ele); -//@} -//@{ -/** delete an element from a hash table: - tab: the table to remove the element from - key: the key string identifying the element to be deleted - returns a pointer to the element on success, 0 if the element could not - be found. - Does /NOT/ call the free element function. That is the caller's +/** find a list of elements within a hash table. + \param tab the table to search + \param ele element with info identifying the elements being searched for + \return a null terminated list of element pointers if at least one + found, otherwise 0. + \note it is the caller's responsibilty to free() the list. + + returned list is guaranteed to be in reverse order of insertion. ie, + deleting items from the list in list order will delete the correct items. +*/ +void **Hash_FindElementList (hashtab_t *tab, void *ele); + +/** delete an element from a hash table. + \param tab the table to remove the element from + \param key the key string identifying the element to be deleted + \return a pointer to the element on success, 0 if the element could not + be found. + + Does \em NOT call the free element function. That is the caller's responsibility. */ void *Hash_Del (hashtab_t *tab, const char *key); + +/** delete an element from a hash table. + \param tab the table to remove the element from + \param ele element with info identifying the element to be deleted + \return a pointer to the element on success, 0 if the element could not + be found. + + Does \em NOT call the free element function. That is the caller's + responsibility. +*/ void *Hash_DelElement (hashtab_t *tab, void *ele); -//@} /** calls the free element function for the supplied ele - eg: - Hash_Free (tab, Hash_Del (tab, key)); + \param tab the table associated with the element (for the free function) + \param ele the element to be freed + + eg: Hash_Free (tab, Hash_Del (tab, key)); */ void Hash_Free (hashtab_t *tab, void *ele); -/** returh the hash value of a string. this is the same function as used - internally. +/** hash a string. + \param str the string to hash + \return the hash value of the string. + + this is the same function as used internally. */ unsigned long Hash_String (const char *str); -/** returh the hash value of a buffer. +/** hash a buffer. + \param buf the buffer to hash + \param len the size of the buffer + \return the hash value of the string. */ unsigned long Hash_Buffer (const void *buf, int len); -/** return the number of elements in the table. +/** get the size of the table + \param tab the table in question + \return the number of elements in the table. */ size_t Hash_NumElements (hashtab_t *tab); -/** return a list of all elements in the table. it is the caller's - responsibilty to free() the array. Null terminated. +/** list of all elements in the table. + \param tab the table to list + \return a null terminated list of element pointers for all elements + in the table + \note it is the caller's responsibilty to free() the list. + + returned list is guaranteed to be in reverse order of insertion for + elements with the same key. ie, deleting items from the list in list order + will delete the correct items. */ void **Hash_GetList (hashtab_t *tab); /** dump statistics about the hash table + \param tab the table to dump */ void Hash_Stats (hashtab_t *tab);