From 89914f30977925f62b70a51ef62a5f9c25b5ea4d Mon Sep 17 00:00:00 2001 From: rbdpngn Date: Thu, 18 Mar 2004 19:02:23 +0000 Subject: [PATCH] Convert some of the documentation to doxygen. SVN revision: 9393 --- legacy/ecore/src/lib/ecore/ecore_hash.c | 154 ++++++----- legacy/ecore/src/lib/ecore/ecore_list.c | 334 +++++++++++------------- legacy/ecore/src/lib/ecore/ecore_tree.c | 222 +++++++--------- 3 files changed, 316 insertions(+), 394 deletions(-) diff --git a/legacy/ecore/src/lib/ecore/ecore_hash.c b/legacy/ecore/src/lib/ecore/ecore_hash.c index a202c25332..d578094e8c 100644 --- a/legacy/ecore/src/lib/ecore/ecore_hash.c +++ b/legacy/ecore/src/lib/ecore/ecore_hash.c @@ -31,11 +31,10 @@ static int _ecore_hash_node_destroy(Ecore_Hash_Node *node, Ecore_Free_Cb keyd, /** - * ecore_hash_new - create and initialize a new hash - * @hash_func: the function for determining hash position - * @compare: the function for comparing node keys - * - * Returns NULL on error, a new hash on success + * @brief Create and initialize a new hash + * @param hash_func: the function for determining hash position + * @param compare: the function for comparing node keys + * @return Returns NULL on error, a new hash on success */ Ecore_Hash *ecore_hash_new(Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare) { @@ -52,12 +51,11 @@ Ecore_Hash *ecore_hash_new(Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare) } /** - * ecore_hash_init - initialize a hash to some sane starting values - * @hash: the hash table to initialize - * @hash_func: the function for hashing node keys - * @compare: the function for comparing node keys - * - * Returns TRUE on success, FALSE on an error. + * @brief Initialize a hash to some sane starting values + * @param hash: the hash table to initialize + * @param hash_func: the function for hashing node keys + * @param compare: the function for comparing node keys + * @return Returns TRUE on success, FALSE on an error. */ int ecore_hash_init(Ecore_Hash *hash, Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare) { @@ -78,11 +76,10 @@ int ecore_hash_init(Ecore_Hash *hash, Ecore_Hash_Cb hash_func, Ecore_Compare_Cb } /** - * ecore_hash_set_free_key - set the function to destroy the keys of entries - * @hash: the hash that this will affect - * @function: the function that will free the node keys - * - * Returns TRUE on success, FALSE on error + * @brief Set the function to destroy the keys of entries + * @param hash: the hash that this will affect + * @param function: the function that will free the node keys + * @return Returns TRUE on success, FALSE on error */ int ecore_hash_set_free_key(Ecore_Hash *hash, Ecore_Free_Cb function) { @@ -97,11 +94,10 @@ int ecore_hash_set_free_key(Ecore_Hash *hash, Ecore_Free_Cb function) } /** - * ecore_hash_set_free_value - set the function to destroy the value - * @hash: the hash that this will affect - * @function: the function that will free the node values - * - * Returns TRUE on success, FALSE on error + * @brief Set the function to destroy the value + * @param hash: the hash that this will affect + * @param function: the function that will free the node values + * @return Returns TRUE on success, FALSE on error */ int ecore_hash_set_free_value(Ecore_Hash *hash, Ecore_Free_Cb function) { @@ -116,12 +112,11 @@ int ecore_hash_set_free_value(Ecore_Hash *hash, Ecore_Free_Cb function) } /** - * ecore_hash_set - set the key/value pair in the hash table - * @hash: the hash table to set the the value in - * @key: the key for this value pair - * @value: the value corresponding with the key - * - * Returns TRUE if successful, FALSE if not + * @brief Set the key/value pair in the hash table + * @param hash: the hash table to set the the value in + * @param key: the key for this value pair + * @param value: the value corresponding with the key + * @return Returns TRUE if successful, FALSE if not */ int ecore_hash_set(Ecore_Hash *hash, void *key, void *value) { @@ -145,10 +140,10 @@ int ecore_hash_set(Ecore_Hash *hash, void *key, void *value) } /** - * ecore_hash_destroy - free the hash table and the data contained inside it - * @hash: the hash table to destroy + * @brief Free the hash table and the data contained inside it + * @param hash: the hash table to destroy * - * Returns TRUE on success, FALSE on error + * @brief Returns TRUE on success, FALSE on error */ void ecore_hash_destroy(Ecore_Hash *hash) { @@ -176,7 +171,10 @@ void ecore_hash_destroy(Ecore_Hash *hash) } /** - * ecore_hash_for_each - iterate over the entries in the hash table + * @brief Iterate over the entries in the hash table + * @param hash: the hash whose entries are iterated over + * @param for_each_func: the function each entry is passed to + * @return Returns TRUE on success, FALSE otherwise. */ int ecore_hash_for_each_node(Ecore_Hash *hash, Ecore_For_Each for_each_func) { @@ -205,8 +203,8 @@ int ecore_hash_for_each_node(Ecore_Hash *hash, Ecore_For_Each for_each_func) } /** - * ecore_hash_dump_graph - print the distribution of the hash table for graphing - * @hash: the hash table to print + * @brief Print the distribution of the hash table for graphing + * @param hash: the hash table to print * * Returns no value. */ @@ -238,10 +236,10 @@ _ecore_hash_bucket_destroy(Ecore_List *list, Ecore_Free_Cb keyd, Ecore_Free_Cb v } /* - * Description: Add the node to the hash table - * Parameters: 1. hash - the hash table to add the key - * 2. node - the node to add to the hash table - * Returns: FALSE on error, TRUE on success + * @brief Add the node to the hash table + * @param hash: the hash table to add the key + * @param node: the node to add to the hash table + * @return Returns FALSE on error, TRUE on success */ static int _ecore_hash_add_node(Ecore_Hash *hash, Ecore_Hash_Node *node) @@ -275,11 +273,11 @@ _ecore_hash_add_node(Ecore_Hash *hash, Ecore_Hash_Node *node) } /** - * ecore_hash_get - retrieve the value associated with key - * @hash: the hash table to search for the key - * @key: the key to search for in the hash table + * @brief Retrieve the value associated with key + * @param hash: the hash table to search for the key + * @param key: the key to search for in the hash table * - * Returns NULL on error, value corresponding to key on success + * @return Returns NULL on error, value corresponding to key on success */ void *ecore_hash_get(Ecore_Hash *hash, void *key) { @@ -301,11 +299,11 @@ void *ecore_hash_get(Ecore_Hash *hash, void *key) /** - * ecore_hash_remove - remove the value associated with key - * @hash: the hash table to remove the key from - * @key: the key to search for in the hash table + * @brief Remove the value associated with key + * @param hash: the hash table to remove the key from + * @param key: the key to search for in the hash table * - * Returns NULL on error, value corresponding to key on success + * @return Returns NULL on error, value corresponding to key on success */ void *ecore_hash_remove(Ecore_Hash *hash, void *key) { @@ -363,10 +361,10 @@ void *ecore_hash_remove(Ecore_Hash *hash, void *key) } /* - * Description: Retrieve the node associated with key - * Parameters: 1. hash - the hash table to search for the key - * 2. key - the key to search for in the hash table - * Returns: NULL on error, node corresponding to key on success + * @brief Retrieve the node associated with key + * @param hash: the hash table to search for the key + * @param key: the key to search for in the hash table + * @return Returns NULL on error, node corresponding to key on success */ static Ecore_Hash_Node * _ecore_hash_get_node(Ecore_Hash *hash, void *key) @@ -394,11 +392,11 @@ _ecore_hash_get_node(Ecore_Hash *hash, void *key) } /* - * Description: Search the hash bucket for a specified key - * Parameters: 1. hash - the hash table to retrieve the comparison function - * 2. bucket - the list to search for the key - * 3. key - the key to search for in the list - * Returns: NULL on error or not found, the found node on success + * @brief Search the hash bucket for a specified key + * @param hash: the hash table to retrieve the comparison function + * @param bucket: the list to search for the key + * @param key: the key to search for in the list + * @return Returns NULL on error or not found, the found node on success */ inline Ecore_Hash_Node * _ecore_hash_get_bucket(Ecore_Hash *hash, Ecore_List *bucket, void *key) @@ -440,9 +438,9 @@ _ecore_hash_get_bucket(Ecore_Hash *hash, Ecore_List *bucket, void *key) } /* - * Description: Increase the size of the hash table by approx. 2 * current size - * Parameters: 1. hash - the hash table to increase the size of - * Returns: TRUE on success, FALSE on error + * @brief Increase the size of the hash table by approx. 2 * current size + * @param hash: the hash table to increase the size of + * @return Returns TRUE on success, FALSE on error */ static int _ecore_hash_increase(Ecore_Hash *hash) @@ -495,9 +493,9 @@ _ecore_hash_increase(Ecore_Hash *hash) } /* - * Description: Decrease the size of the hash table by < 1/2 * current size - * Parameters: 1. hash - the hash table to decrease the size of - * Returns: TRUE on success, FALSE on error + * @brief Decrease the size of the hash table by < 1/2 * current size + * @param hash: the hash table to decrease the size of + * @return Returns TRUE on success, FALSE on error */ static int _ecore_hash_decrease(Ecore_Hash *hash) @@ -547,10 +545,10 @@ _ecore_hash_decrease(Ecore_Hash *hash) } /* - * Description: Rehash the nodes of a table into the hash table - * Parameters: 1. hash - the hash to place the nodes of the table - * 2. table - the table to remove the nodes from and place in hash - * Returns: TRUE on success, FALSE on success + * @brief Rehash the nodes of a table into the hash table + * @param hash: the hash to place the nodes of the table + * @param table: the table to remove the nodes from and place in hash + * @return Returns TRUE on success, FALSE on success */ inline int _ecore_hash_rehash(Ecore_Hash *hash, Ecore_List **old_table, int old_size) @@ -582,10 +580,10 @@ _ecore_hash_rehash(Ecore_Hash *hash, Ecore_List **old_table, int old_size) } /* - * Description: Create a new hash node for key and value storage - * Parameters: 1. key - the key for this node - * 2. value - the value that the key references - * Returns: NULL on error, a new hash node on success + * @brief Create a new hash node for key and value storage + * @param key: the key for this node + * @param value: the value that the key references + * @return Returns NULL on error, a new hash node on success */ static Ecore_Hash_Node * _ecore_hash_node_new(void *key, void *value) @@ -605,11 +603,11 @@ _ecore_hash_node_new(void *key, void *value) } /* - * Description: Initialize a hash node to some sane default values - * Parameters: 1. node - the node to set the values - * 2. key - the key to reference this node - * 3. value - the value that key refers to - * Returns: TRUE on success, FALSE on error + * @brief Initialize a hash node to some sane default values + * @param node: the node to set the values + * @param key: the key to reference this node + * @param value: the value that key refers to + * @return Returns TRUE on success, FALSE on error */ static int _ecore_hash_node_init(Ecore_Hash_Node *node, void *key, void *value) @@ -624,11 +622,11 @@ _ecore_hash_node_init(Ecore_Hash_Node *node, void *key, void *value) } /* - * Description: Destroy a node and call the specified callbacks to free data - * Parameters: 1. node - the node to be destroyed - * 2. keyd - the function to free the key - * 3. valued - the function to free the value - * Returns: TRUE on success, FALSE on error + * @brief Destroy a node and call the specified callbacks to free data + * @param node: the node to be destroyed + * @param keyd: the function to free the key + * @param valued: the function to free the value + * @return Returns TRUE on success, FALSE on error */ static int _ecore_hash_node_destroy(Ecore_Hash_Node *node, Ecore_Free_Cb keyd, diff --git a/legacy/ecore/src/lib/ecore/ecore_list.c b/legacy/ecore/src/lib/ecore/ecore_list.c index f064445a66..a8a11a80c5 100644 --- a/legacy/ecore/src/lib/ecore/ecore_list.c +++ b/legacy/ecore/src/lib/ecore/ecore_list.c @@ -202,9 +202,8 @@ _ecore_list_find(void *in_list, void *in_item) /* XXX: End deprecated code */ /** - * ecore_list_new - create and initialize a new list. - * - * Returns a new initialized list on success, NULL on failure. + * @brief Create and initialize a new list. + * @return Returns a new initialized list on success, NULL on failure. */ Ecore_List *ecore_list_new() { @@ -223,10 +222,9 @@ Ecore_List *ecore_list_new() } /** - * ecore_list_init - initialize a list to some sane starting values. - * @list: the list to initialize - * - * Returns FALSE if an error occurs, TRUE if successful + * @brief Initialize a list to some sane starting values. + * @param list: the list to initialize + * @return Returns FALSE if an error occurs, TRUE if successful */ int ecore_list_init(Ecore_List *list) { @@ -240,10 +238,9 @@ int ecore_list_init(Ecore_List *list) } /** - * ecore_list_destroy - Free a list and all of it's nodes. - * @list: the list to be freed - * - * Returns no value + * @brief Free a list and all of it's nodes. + * @param list: the list to be freed + * @return Returns no value */ void ecore_list_destroy(Ecore_List * list) { @@ -266,11 +263,10 @@ void ecore_list_destroy(Ecore_List * list) } /** - * ecore_list_set_free_cb - set the function for freeing data - * @list: the list that will use this function when nodes are destroyed. - * @free_func: the function that will free the key data - * - * Returns TRUE on successful set, FALSE otherwise. + * @brief Set the function for freeing data + * @param list: the list that will use this function when nodes are destroyed. + * @param free_func: the function that will free the key data + * @return Returns TRUE on successful set, FALSE otherwise. */ int ecore_list_set_free_cb(Ecore_List * list, Ecore_Free_Cb free_func) { @@ -286,10 +282,9 @@ int ecore_list_set_free_cb(Ecore_List * list, Ecore_Free_Cb free_func) } /** - * ecore_list_is_empty - checks the list for any nodes. - * @list: the list to check for nodes - * - * Returns TRUE if no nodes in list, FALSE if the list contains nodes + * @brief Checks the list for any nodes. + * @param list: the list to check for nodes + * @return Returns TRUE if no nodes in list, FALSE if the list contains nodes */ int ecore_list_is_empty(Ecore_List * list) { @@ -308,10 +303,9 @@ int ecore_list_is_empty(Ecore_List * list) } /** - * ecore_list_index - returns the number of the current node - * @list: the list to return the number of the current node - * - * Returns the number of the current node in the list. + * @brief Returns the number of the current node + * @param list: the list to return the number of the current node + * @return Returns the number of the current node in the list. */ int ecore_list_index(Ecore_List * list) { @@ -329,10 +323,9 @@ int ecore_list_index(Ecore_List * list) } /** - * ecore_list_nodes - find the number of nodes in the list. - * @list: the list to find the number of nodes - * - * Returns the number of nodes in the list. + * @brief Find the number of nodes in the list. + * @param list: the list to find the number of nodes + * @return Returns the number of nodes in the list. */ int ecore_list_nodes(Ecore_List * list) { @@ -350,11 +343,10 @@ int ecore_list_nodes(Ecore_List * list) } /** - * ecore_list_append - append data to the list. - * @list: the list to append @data - * @data: the data to append to @list. - * - * Returns FALSE if an error occurs, TRUE if @data is appended successfully + * @brief Append data to the list. + * @param list: the list to append @data + * @param data: the data to append to @list. + * @return Returns FALSE if an error occurs, TRUE if appended successfully */ inline int ecore_list_append(Ecore_List * list, void *data) { @@ -397,11 +389,10 @@ static int _ecore_list_append_0(Ecore_List * list, Ecore_List_Node *end) } /** - * ecore_list_prepend - prepend data to the beginning of the list - * @list: the list to prepend @data - * @data: the data to prepend to @list - * - * Returns FALSE if an error occurs, TRUE if data prepended successfully + * @brief Prepend data to the beginning of the list + * @param list: the list to prepend @data + * @param data: the data to prepend to @list + * @return Returns FALSE if an error occurs, TRUE if prepended successfully */ inline int ecore_list_prepend(Ecore_List * list, void *data) { @@ -441,11 +432,10 @@ static int _ecore_list_prepend_0(Ecore_List * list, Ecore_List_Node *start) } /** - * ecore_list_insert - insert data at the current point in the list - * @list: the list to hold the inserted @data - * @data: the data to insert into @list - * - * Returns FALSE on an error, TRUE on success + * @brief Insert data at the current point in the list + * @param list: the list to hold the inserted @data + * @param data: the data to insert into @list + * @return Returns FALSE on an error, TRUE on success */ inline int ecore_list_insert(Ecore_List * list, void *data) { @@ -504,10 +494,9 @@ static int _ecore_list_insert(Ecore_List * list, Ecore_List_Node *new_node) } /** - * ecore_list_remove - remove the current item from the list. - * @list: the list to remove the current item - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the current item from the list. + * @param list: the list to remove the current item + * @return Returns a pointer to the removed data on success, NULL on failure. */ inline void *ecore_list_remove(Ecore_List * list) { @@ -567,10 +556,9 @@ static void *_ecore_list_remove_0(Ecore_List * list) } /** - * ecore_list_remove_destroy - remove and free the data in lists current position - * @list: the list to remove and free the current item - * - * Returns TRUE on success, FALSE on error + * @brief Remove and free the data in lists current position + * @param list: the list to remove and free the current item + * @return Returns TRUE on success, FALSE on error */ int ecore_list_remove_destroy(Ecore_List *list) { @@ -589,10 +577,9 @@ int ecore_list_remove_destroy(Ecore_List *list) } /** - * ecore_list_remove_first - remove the first item from the list. - * @list: the list to remove the current item - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the first item from the list. + * @param list: the list to remove the current item + * @return Returns a pointer to the removed data on success, NULL on failure. */ inline void *ecore_list_remove_first(Ecore_List * list) { @@ -648,10 +635,9 @@ static void *_ecore_list_remove_first(Ecore_List * list) } /** - * ecore_list_remove_first - remove the last item from the list. - * @list: the list to remove the last node from - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the last item from the list. + * @param list: the list to remove the last node from + * @return Returns a pointer to the removed data on success, NULL on failure. */ inline void *ecore_list_remove_last(Ecore_List * list) { @@ -712,11 +698,10 @@ static void *_ecore_list_remove_last(Ecore_List * list) } /** - * ecore_list_goto_index - move the current item to the index number - * @list: the list to move the current item - * @index: the position to move the current item - * - * Returns a pointer to the new current item on success, NULL on failure. + * @brief Move the current item to the index number + * @param list: the list to move the current item + * @param index: the position to move the current item + * @return Returns a pointer to new current item on success, NULL on failure. */ inline void *ecore_list_goto_index(Ecore_List * list, int index) { @@ -756,11 +741,11 @@ static void *_ecore_list_goto_index(Ecore_List *list, int index) } /** - * ecore_list_goto - move the current item to the node that contains data - * @list: the list to move the current item in - * @data: the data to find and set the current item to + * @brief Move the current item to the node that contains data + * @param list: the list to move the current item in + * @param data: the data to find and set the current item to * - * Returns a pointer to @data on success, NULL on failure. + * @return Returns a pointer to @a data on success, NULL on failure. */ inline void *ecore_list_goto(Ecore_List * list, void *data) { @@ -814,10 +799,9 @@ static void *_ecore_list_goto(Ecore_List * list, void *data) } /** - * ecore_list_goto_first - move the current pointer to the first item in the list - * @list: the list to move the current pointer in - * - * Returns a pointer to the first item on success, NULL on failure + * @brief Move the current pointer to the first item in the list + * @param list: the list to move the current pointer in + * @return Returns a pointer to the first item on success, NULL on failure */ inline void *ecore_list_goto_first(Ecore_List *list) { @@ -847,10 +831,9 @@ static void *_ecore_list_goto_first(Ecore_List * list) } /** - * ecore_list_goto_last - move the pointer to current to the last item in the list - * @list: the list to move the current pointer in - * - * Returns a pointer to the last item on success, NULL on failure. + * @brief Move the pointer to current to the last item in the list + * @param list: the list to move the current pointer in + * @return Returns a pointer to the last item on success, NULL on failure. */ inline void *ecore_list_goto_last(Ecore_List * list) { @@ -878,11 +861,9 @@ static void *_ecore_list_goto_last(Ecore_List * list) } /** - * ecore_list_current - retrieve the data in the current node - * @list: the list to retrieve the current data from - * - * Returns the data at the current position on success, NULL on failure or if - * no current item set. + * @brief Retrieve the data in the current node + * @param list: the list to retrieve the current data from + * @return Returns the data at current position, can be NULL. */ inline void *ecore_list_current(Ecore_List * list) { @@ -911,10 +892,10 @@ static void *_ecore_list_current(Ecore_List * list) } /** - * ecore_list_next - retrieve the data at the current node and move to the next - * @list: the list to move to the next item + * @brief Retrieve the data at the current node and move to the next + * @param list: the list to move to the next item * - * Returns the current item in the list on success, NULL on failure. + * @return Returns the current item in the list on success, NULL on failure. */ inline void *ecore_list_next(Ecore_List * list) { @@ -955,11 +936,11 @@ static void *_ecore_list_next(Ecore_List * list) } /** - * ecore_list_clear - remove all nodes from the list - * @list: the list that will have it's nodes removed + * @brief Remove all nodes from the list + * @param list: the list that will have it's nodes removed + * @return Returns TRUE on success, FALSE on error. * - * Returns TRUE on success, FALSE on error. The data for each item on the list - * is not freed by ecore_list_clear. + * The data for each item on the list is not freed by ecore_list_clear. */ int ecore_list_clear(Ecore_List * list) { @@ -976,11 +957,11 @@ int ecore_list_clear(Ecore_List * list) } /** - * ecore_list_for_each - execute function for each node in the list. - * @list: the list to retrieve nodes from. - * @function: The function to pass each node from the list to. + * @brief Execute function for each node in the list. + * @param list: the list to retrieve nodes from. + * @param function: The function to pass each node from the list to. * - * Returns TRUE on success, FALSE on failure. + * @return Returns TRUE on success, FALSE on failure. */ int ecore_list_for_each(Ecore_List *list, Ecore_For_Each function) { @@ -1058,9 +1039,8 @@ int ecore_list_node_destroy(Ecore_List_Node * node, Ecore_Free_Cb free_func) } /** - * ecore_dlist_new - create and initialize a new list. - * - * Returns a new initialized list on success, NULL on failure. + * @brief Create and initialize a new list. + * @return Returns a new initialized list on success, NULL on failure. */ Ecore_DList *ecore_dlist_new() { @@ -1079,10 +1059,9 @@ Ecore_DList *ecore_dlist_new() } /** - * ecore_dlist_init - initialize a list to some sane starting values. - * @list: the list to initialize - * - * Returns FALSE if an error occurs, TRUE if successful + * @brief Initialize a list to some sane starting values. + * @param list: the list to initialize + * @return Returns FALSE if an error occurs, TRUE if successful */ int ecore_dlist_init(Ecore_DList *list) { @@ -1096,10 +1075,10 @@ int ecore_dlist_init(Ecore_DList *list) } /** - * ecore_dlist_destroy - free a list and all of it's nodes. - * @list: the list to be freed + * @brief Free a list and all of it's nodes. + * @param list: the list to be freed * - * Returns no value + * @return Returns no value */ void ecore_dlist_destroy(Ecore_DList * list) { @@ -1121,11 +1100,10 @@ void ecore_dlist_destroy(Ecore_DList * list) } /** - * ecore_dlist_set_free_cb - set the function for freeing data - * @list: the list that will use this function when nodes are destroyed. - * @free_func: the function that will free the key data - * - * Returns TRUE on success, FALSE on failure. + * @brief Set the function for freeing data + * @param list: the list that will use this function when nodes are destroyed. + * @param free_func: the function that will free the key data + * @return Returns TRUE on success, FALSE on failure. */ int ecore_dlist_set_free_cb(Ecore_DList * list, Ecore_Free_Cb free_func) { @@ -1135,10 +1113,10 @@ int ecore_dlist_set_free_cb(Ecore_DList * list, Ecore_Free_Cb free_func) } /** - * ecore_dlist_is_empty - checks the list for any nodes. - * @list: the list to check for nodes + * @brief Checks the list for any nodes. + * @param list: the list to check for nodes * - * Returns TRUE if no nodes in list, FALSE if the list contains nodes + * @return Returns TRUE if no nodes in list, FALSE if the list contains nodes */ int ecore_dlist_is_empty(Ecore_DList * list) { @@ -1148,10 +1126,9 @@ int ecore_dlist_is_empty(Ecore_DList * list) } /** - * ecore_dlist_index - returns the number of the current node - * @list: the list to return the number of the current node - * - * Returns the number of the current node in the list. + * @brief Returns the number of the current node + * @param list: the list to return the number of the current node + * @return Returns the number of the current node in the list. */ inline int ecore_dlist_index(Ecore_DList * list) { @@ -1161,11 +1138,11 @@ inline int ecore_dlist_index(Ecore_DList * list) } /** - * ecore_dlist_append - append data to the list. - * @list: the list to append @data - * @data: the data to append to @list + * @brief Append data to the list. + * @param list: the list to append @data + * @param data: the data to append to @list * - * Returns FALSE if an error occurs, TRUE if the data is appended successfully + * @return Returns FALSE if an error occurs, TRUE if appended successfully */ int ecore_dlist_append(Ecore_DList * list, void *data) { @@ -1192,11 +1169,10 @@ int ecore_dlist_append(Ecore_DList * list, void *data) } /** - * ecore_dlist_prepend - prepend data to the beginning of the list - * @list: the list to prepend @data - * @data: the data to prepend to @list - * - * Returns FALSE if an error occurs, TRUE if data prepended successfully + * @brief Prepend data to the beginning of the list + * @param list: the list to prepend @data + * @param data: the data to prepend to @list + * @return Returns FALSE if an error occurs, TRUE if prepended successfully */ int ecore_dlist_prepend(Ecore_DList * list, void *data) { @@ -1222,11 +1198,10 @@ int ecore_dlist_prepend(Ecore_DList * list, void *data) } /** - * ecore_dlist_insert - insert data at the current point in the list - * @list: the list to hold the inserted @data - * @data: the data to insert into @list - * - * Returns FALSE on an error, TRUE on success + * @brief Insert data at the current point in the list + * @param list: the list to hold the inserted @data + * @param data: the data to insert into @list + * @return Returns FALSE on an error, TRUE on success */ int ecore_dlist_insert(Ecore_DList * list, void *data) { @@ -1266,10 +1241,9 @@ int ecore_dlist_insert(Ecore_DList * list, void *data) } /** - * ecore_dlist_remove - remove the current item from the list. - * @list: the list to remove the current item - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the current item from the list. + * @param list: the list to remove the current item + * @return Returns a pointer to the removed data on success, NULL on failure. */ void *ecore_dlist_remove(Ecore_DList * list) { @@ -1293,10 +1267,9 @@ void *ecore_dlist_remove(Ecore_DList * list) } /** - * ecore_dlist_remove_first - remove the first item from the list. - * @list: the list to remove the current item - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the first item from the list. + * @param list: the list to remove the current item + * @return Returns a pointer to the removed data on success, NULL on failure. */ void *ecore_dlist_remove_first(Ecore_DList * list) { @@ -1312,10 +1285,10 @@ void *ecore_dlist_remove_first(Ecore_DList * list) } /** - * ecore_dlist_remove_destroy - remove and free the data at the current position - * @list: the list to remove the data from + * @brief Remove and free the data at the current position + * @param list: the list to remove the data from * - * Returns TRUE on success, FALSE on error + * @return Returns TRUE on success, FALSE on error */ int ecore_dlist_remove_destroy(Ecore_DList *list) { @@ -1339,10 +1312,9 @@ static void *_ecore_dlist_remove_first(Ecore_DList *list) } /** - * ecore_dlist_remove_last - remove the last item from the list - * @list: the list to remove the last node from - * - * Returns a pointer to the removed data on success, NULL on failure. + * @brief Remove the last item from the list + * @param list: the list to remove the last node from + * @return Returns a pointer to the removed data on success, NULL on failure. */ void *ecore_dlist_remove_last(Ecore_DList * list) { @@ -1358,11 +1330,10 @@ void *ecore_dlist_remove_last(Ecore_DList * list) } /** - * ecore_dlist_goto_index - move the current item to the index number - * @list: the list to move the current item - * @index: the position to move the current item - * - * Returns node at specified index on success, NULL on error + * @brief Move the current item to the index number + * @param list: the list to move the current item + * @param index: the position to move the current item + * @return Returns node at specified index on success, NULL on error */ void *ecore_dlist_goto_index(Ecore_DList * list, int index) { @@ -1411,11 +1382,11 @@ static void *_ecore_dlist_goto_index(Ecore_DList *list, int index) } /** - * ecore_dlist_goto - move the current item to the node that contains data - * @list: the list to move the current item in - * @data: the data to find and set the current item to + * @brief Move the current item to the node that contains data + * @param list: the list to move the current item in + * @param data: the data to find and set the current item to * - * Returns specified data on success, NULL on error + * @return Returns specified data on success, NULL on error */ void *ecore_dlist_goto(Ecore_DList * list, void *data) { @@ -1431,10 +1402,10 @@ void *ecore_dlist_goto(Ecore_DList * list, void *data) } /** - * ecore_dlist_goto_first - move the current pointer to the first item in the list - * @list: the list to change the current to the first item + * @brief Move the current pointer to the first item in the list + * @param list: the list to change the current to the first item * - * Returns a pointer to the first item on success, NULL on failure. + * @return Returns a pointer to the first item on success, NULL on failure. */ void *ecore_dlist_goto_first(Ecore_DList *list) { @@ -1450,10 +1421,9 @@ void *ecore_dlist_goto_first(Ecore_DList *list) } /** - * ecore_dlist_goto_last - move the pointer to the current item to the last item - * @list: the list to move the current item pointer to the last - * - * Returns a pointer to the last item in the list on success, NULL on failure. + * @brief Move the pointer to the current item to the last item + * @param list: the list to move the current item pointer to the last + * @return Returns a pointer to the last item in the list , NULL if empty. */ void *ecore_dlist_goto_last(Ecore_DList * list) { @@ -1469,10 +1439,9 @@ void *ecore_dlist_goto_last(Ecore_DList * list) } /** - * ecore_dlist_current - return the data in the current list item - * @list: the list to the return the current data - * - * Returns value of the current data item, NULL if no current item + * @brief Return the data in the current list item + * @param list: the list to the return the current data + * @return Returns value of the current data item, NULL if no current item */ void *ecore_dlist_current(Ecore_DList * list) { @@ -1486,10 +1455,9 @@ void *ecore_dlist_current(Ecore_DList * list) } /** - * ecore_dlist_next - move to the next item in the list and return current item - * @list: the list to move to the next item in. - * - * Returns data in the current list node, or NULL on error + * @brief Move to the next item in the list and return current item + * @param list: the list to move to the next item in. + * @return Returns data in the current list node, or NULL on error */ void *ecore_dlist_next(Ecore_DList * list) { @@ -1503,10 +1471,9 @@ void *ecore_dlist_next(Ecore_DList * list) } /** - * ecore_dlist_previous - move to the previous item and return current item - * @list: the list to move to the previous item in. - * - * Returns data in the current list node, or NULL on error + * @brief Move to the previous item and return current item + * @param list: the list to move to the previous item in. + * @return Returns data in the current list node, or NULL on error */ void *ecore_dlist_previous(Ecore_DList * list) { @@ -1539,10 +1506,10 @@ static void *_ecore_dlist_previous(Ecore_DList * list) } /** - * ecore_dlist_clear - remove all nodes from the list. - * @list: the list to remove all nodes from + * @brief Remove all nodes from the list. + * @param list: the list to remove all nodes from * - * Returns TRUE on success, FALSE on errors + * @return Returns TRUE on success, FALSE on errors */ int ecore_dlist_clear(Ecore_DList * list) { @@ -1554,9 +1521,9 @@ int ecore_dlist_clear(Ecore_DList * list) } /* - * Description: Initialize a node to sane starting values - * Parameters: 1. node - the node to initialize - * Returns: TRUE on success, FALSE on errors + * @brief Initialize a node to sane starting values + * @param node: the node to initialize + * @return Returns TRUE on success, FALSE on errors */ int ecore_dlist_node_init(Ecore_DList_Node * node) { @@ -1572,9 +1539,8 @@ int ecore_dlist_node_init(Ecore_DList_Node * node) } /* - * Description: Allocate and initialize a new list node - * Parameters: None - * Returns: NULL on error, new list node on success + * @brief Allocate and initialize a new list node + * @return Returns NULL on error, new list node on success */ Ecore_DList_Node *ecore_dlist_node_new() { @@ -1594,10 +1560,10 @@ Ecore_DList_Node *ecore_dlist_node_new() } /* - * Description: Call the data's free callback function, then free the node - * Parameters: 1. node - the node to be freed - * 2. free_func - the callback function to execute on the data - * Returns: TRUE on success, FALSE on error + * @brief Call the data's free callback function, then free the node + * @param node: the node to be freed + * @param free_func: the callback function to execute on the data + * @return Returns TRUE on success, FALSE on error */ int ecore_dlist_node_destroy(Ecore_DList_Node * node, Ecore_Free_Cb free_func) { diff --git a/legacy/ecore/src/lib/ecore/ecore_tree.c b/legacy/ecore/src/lib/ecore/ecore_tree.c index b2a6e095bc..6b18c2eb2e 100644 --- a/legacy/ecore/src/lib/ecore/ecore_tree.c +++ b/legacy/ecore/src/lib/ecore/ecore_tree.c @@ -1,28 +1,3 @@ -/* ecore_tree.c - -Copyright (C) 2001 Nathan Ingersoll - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to -deal in the Software without restriction, including without limitation the -rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies of the Software and its documentation and acknowledgment shall be -given in the documentation and software packages that this Software was -used. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER -IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - #include /* A macro for determining the highest node at given branch */ @@ -45,10 +20,9 @@ int tree_for_each_node_value(Ecore_Tree_Node * node, Ecore_For_Each for_each_func); /** - * ecore_tree_new - allocate a new tree structure. - * @compare_func: function used to compare the two values - * - * Returns NULL if the operation fails, otherwise a pointer to the new tree + * @brief Allocate a new tree structure. + * @param compare_func: function used to compare the two values + * @return Returns NULL if the operation fails, otherwise the new tree */ Ecore_Tree *ecore_tree_new(Ecore_Compare_Cb compare_func) { @@ -67,11 +41,10 @@ Ecore_Tree *ecore_tree_new(Ecore_Compare_Cb compare_func) } /** - * ecore_tree_init - initialize a tree structure to some sane initial values - * @new_tree: the new tree structure to be initialized - * @compare_func: the function used to compare node keys - * - * Returns TRUE on successful initialization, FALSE on an error + * @brief Initialize a tree structure to some sane initial values + * @param new_tree: the new tree structure to be initialized + * @param compare_func: the function used to compare node keys + * @return Returns TRUE on successful initialization, FALSE on an error */ int ecore_tree_init(Ecore_Tree * new_tree, Ecore_Compare_Cb compare_func) { @@ -90,11 +63,10 @@ int ecore_tree_init(Ecore_Tree * new_tree, Ecore_Compare_Cb compare_func) } /* - * ecore_tree_set_free_cb - add a function to be called at node destroy time - * @tree: the tree that will use this function when nodes are destroyed - * @free_func - the function that will be passed the node being freed - * - * Returns TRUE on successful set, FALSE otherwise. + * @brief Add a function to be called at node destroy time + * @param tree: the tree that will use this function when nodes are destroyed + * @param free_func: the function that will be passed the node being freed + * @return Returns TRUE on successful set, FALSE otherwise. */ int ecore_tree_set_free_cb(Ecore_Tree * tree, Ecore_Free_Cb free_func) { @@ -108,9 +80,8 @@ int ecore_tree_set_free_cb(Ecore_Tree * tree, Ecore_Free_Cb free_func) } /* - * ecore_tree_node_init - initialize a new tree node - * - * Returns FALSE if the operation fails, otherwise TRUE + * @brief Initialize a new tree node + * @return Returns FALSE if the operation fails, otherwise TRUE */ int ecore_tree_node_init(Ecore_Tree_Node * new_node) { @@ -131,9 +102,8 @@ int ecore_tree_node_init(Ecore_Tree_Node * new_node) } /* - * Description: Allocate a new tree node - * Parameters: None. - * Returns: NULL if the operation fails, otherwise a pointer to the new node. + * @brief Allocate a new tree node + * @return Returns NULL if the operation fails, otherwise the new node. */ Ecore_Tree_Node *ecore_tree_node_new() { @@ -152,11 +122,12 @@ Ecore_Tree_Node *ecore_tree_node_new() } /* - * Description: Free a tree node and it's children. If you don't want the - * children free'd then you need to remove the node first. - * Parameters: 1. node - tree node to be free()'d - * 2. data_free - callback for destroying the data held in node - * Returns: TRUE if the node is destroyed successfully, FALSE if not. + * @brief Free a tree node and it's children. + * @param node: tree node to be free()'d + * @param data_free: callback for destroying the data held in node + * @return Returns TRUE if the node is destroyed successfully, FALSE if not. + * + * If you don't want the children free'd then you need to remove the node first. */ int ecore_tree_node_destroy(Ecore_Tree_Node * node, Ecore_Free_Cb data_free) { @@ -175,11 +146,10 @@ int ecore_tree_node_destroy(Ecore_Tree_Node * node, Ecore_Free_Cb data_free) } /* - * ecore_tree_node_value_set - set the value of the node to value - * @node: the node to be set - * @value: the value to set the node to. - * - * Returns TRUE if the node is set successfully, FALSE if not. + * @brief Set the value of the node to value + * @param node: the node to be set + * @param value: the value to set the node to. + * @return Returns TRUE if the node is set successfully, FALSE if not. */ int ecore_tree_node_value_set(Ecore_Tree_Node * node, void *value) { @@ -194,9 +164,9 @@ int ecore_tree_node_value_set(Ecore_Tree_Node * node, void *value) } /* - * Description: Get the value of the node - * Parameters: 1. node - the node that contains the desired value - * Returns: NULL if an error, otherwise the value associated with node + * @brief Get the value of the node + * @param node: the node that contains the desired value + * @return Returns NULL if an error, otherwise the value associated with node */ void *ecore_tree_node_value_get(Ecore_Tree_Node * node) { @@ -211,11 +181,10 @@ void *ecore_tree_node_value_get(Ecore_Tree_Node * node) } /* - * ecore_tree_node_key_set - set the value of the node's key to key - * @node: the node to be set - * @key: the value to set it's key to. - * - * Returns TRUE if the node is set successfully, FALSE if not. + * @brief Set the value of the node's key to key + * @param node: the node to be set + * @param key: the value to set it's key to. + * @return Returns TRUE if the node is set successfully, FALSE if not. */ int ecore_tree_node_key_set(Ecore_Tree_Node * node, void *key) { @@ -229,10 +198,10 @@ int ecore_tree_node_key_set(Ecore_Tree_Node * node, void *key) } /* - * ecore_tree_node_key_get - get the value of the node's key - * @node: the node that contains the desired key + * @brief Get the value of the node's key + * @param node: the node that contains the desired key * - * Returns NULL if an error occurs, otherwise the key is returned + * @return Returns NULL if an error occurs, otherwise the key is returned */ void *ecore_tree_node_key_get(Ecore_Tree_Node * node) { @@ -247,10 +216,10 @@ void *ecore_tree_node_key_get(Ecore_Tree_Node * node) } /** - * ecore_tree_destroy - free the tree and it's stored data - * @tree: the tree to destroy + * @brief Free the tree and it's stored data + * @param tree: the tree to destroy * - * Returns TRUE if tree destroyed successfully, FALSE if not. + * @return Returns TRUE if tree destroyed successfully, FALSE if not. */ int ecore_tree_destroy(Ecore_Tree * tree) { @@ -272,11 +241,11 @@ int ecore_tree_destroy(Ecore_Tree * tree) } /** - * ecore_tree_get_node - return the node corresponding to key - * @tree: the tree to search - * @key: the key to search for in the tree + * @brief Return the node corresponding to key + * @param tree: the tree to search + * @param key: the key to search for in the tree * - * Returns the node corresponding to the key if found, otherwise NULL. + * @return Returns the node corresponding to the key if found, otherwise NULL. */ Ecore_Tree_Node *ecore_tree_get_node(Ecore_Tree * tree, void *key) { @@ -292,11 +261,10 @@ Ecore_Tree_Node *ecore_tree_get_node(Ecore_Tree * tree, void *key) } /** - * ecore_tree_get - return the value corresponding to key - * @tree: the tree to search - * @key: the key to search for in @tree - * - * Returns the value corresponding to the key if found, otherwise NULL. + * @brief Return the value corresponding to key + * @param tree: the tree to search + * @param key: the key to search for in @a tree + * @return Returns the value corresponding to the key if found, otherwise NULL. */ void *ecore_tree_get(Ecore_Tree * tree, void *key) { @@ -317,11 +285,10 @@ void *ecore_tree_get(Ecore_Tree * tree, void *key) } /** - * ecore_tree_get_closest_larger - find the closest value greater >= key - * @tree: the tree to search - * @key: the key to search for in @tree - * - * Returns NULL if no valid nodes, otherwise the node >= key + * @brief Find the closest value greater >= key + * @param tree: the tree to search + * @param key: the key to search for in @tree + * @return Returns NULL if no valid nodes, otherwise the node >= key */ void *ecore_tree_get_closest_larger(Ecore_Tree * tree, void *key) { @@ -354,11 +321,10 @@ void *ecore_tree_get_closest_larger(Ecore_Tree * tree, void *key) } /** - * ecore_tree_get_closest_smaller - find the closest value <= key - * @tree: the tree to search - * @key: the key to search for in tree - * - * Returns NULL if no valid nodes, otherwise the node <= key + * @brief Find the closest value <= key + * @param tree: the tree to search + * @param key: the key to search for in tree + * @return Returns NULL if no valid nodes, otherwise the node <= key */ void *ecore_tree_get_closest_smaller(Ecore_Tree * tree, void *key) { @@ -384,12 +350,11 @@ void *ecore_tree_get_closest_smaller(Ecore_Tree * tree, void *key) } /** - * ecore_tree_set - set the value associated with key to @value - * @tree: the tree that contains the key/value pair - * @key: the key to identify which node to set a value - * @value: value to set the found node - * - * Returns TRUE if successful, FALSE if not. + * @brief Set the value associated with key to @value + * @param tree: the tree that contains the key/value pair + * @param key: the key to identify which node to set a value + * @param value: value to set the found node + * @return Returns TRUE if successful, FALSE if not. */ int ecore_tree_set(Ecore_Tree * tree, void *key, void *value) { @@ -418,11 +383,10 @@ int ecore_tree_set(Ecore_Tree * tree, void *key, void *value) } /** - * ecore_tree_add_node - place a node in the tree - * @tree: the tree to add @node - * @node: the node to add to @tree - * - * Returns TRUE on a successful add, FALSE otherwise. + * @brief Place a node in the tree + * @param tree: the tree to add @node + * @param node: the node to add to @tree + * @brief Returns TRUE on a successful add, FALSE otherwise. */ int ecore_tree_add_node(Ecore_Tree * tree, Ecore_Tree_Node * node) { @@ -454,11 +418,10 @@ int ecore_tree_add_node(Ecore_Tree * tree, Ecore_Tree_Node * node) /** - * ecore_tree_remove_node - remove the node from the tree - * @tree: the tree to remove @node - * @node: the node to remove from @tree - * - * Returns TRUE on a successful remove, FALSE otherwise. + * @brief Remove the node from the tree + * @param tree: the tree to remove @node + * @param node: the node to remove from @tree + * @return Returns TRUE on a successful remove, FALSE otherwise. */ int ecore_tree_remove_node(Ecore_Tree * tree, Ecore_Tree_Node * node) { @@ -563,11 +526,10 @@ int ecore_tree_remove_node(Ecore_Tree * tree, Ecore_Tree_Node * node) } /** - * ecore_tree_remove - remove the key from the tree - * @tree: the tree to remove @key - * @key: the key to remove from @tree - * - * Returns TRUE on a successful remove, FALSE otherwise. + * @brief Remove the key from the tree + * @param tree: the tree to remove @key + * @param key: the key to remove from @tree + * @return Returns TRUE on a successful remove, FALSE otherwise. */ int ecore_tree_remove(Ecore_Tree * tree, void *key) { @@ -591,10 +553,9 @@ int ecore_tree_remove(Ecore_Tree * tree, void *key) } /** - * ecore_tree_is_empty - test to see if the tree has any nodes - * @tree: the tree to check for nodes - * - * Returns TRUE if no nodes exist, FALSE otherwise + * @brief Test to see if the tree has any nodes + * @param tree: the tree to check for nodes + * @return Returns TRUE if no nodes exist, FALSE otherwise */ int ecore_tree_is_empty(Ecore_Tree * tree) { @@ -607,11 +568,10 @@ int ecore_tree_is_empty(Ecore_Tree * tree) } /** - * ecore_tree_for_each_node_value - execute function for each value in the tree - * @tree: the tree to traverse - * @for_each_func: the function to execute for each value in the tree - * - * Returns TRUE on success, FALSE on failure. + * @brief Execute function for each value in the tree + * @param tree: the tree to traverse + * @param for_each_func: the function to execute for each value in the tree + * @return Returns TRUE on success, FALSE on failure. */ int ecore_tree_for_each_node_value(Ecore_Tree * tree, Ecore_For_Each for_each_func) @@ -626,11 +586,11 @@ int ecore_tree_for_each_node_value(Ecore_Tree * tree, } /** - * ecore_tree_for_each_node - execute the function for each node in the tree - * @tree: the tree to traverse - * @for_each_func: the function to execute for each node + * @brief Execute the function for each node in the tree + * @param tree: the tree to traverse + * @param for_each_func: the function to execute for each node * - * Returns TRUE on success, FALSE on failure. + * @return Returns TRUE on success, FALSE on failure. */ int ecore_tree_for_each_node(Ecore_Tree * tree, Ecore_For_Each for_each_func) { @@ -806,11 +766,10 @@ int tree_node_rotate_left(Ecore_Tree * tree, Ecore_Tree_Node * top_node) } /* - * Description: Execute a function for each node below this point in the tree. - * Parameters: 1. node - the highest node in the tree the function will be - * executed for - * 2. for_each_func - the function to pass the nodes as data into - * Returns: FALSE if an error condition occurs, otherwise TRUE + * @brief Execute a function for each node below this point in the tree. + * @param node: the highest node in the tree the function will be executed for + * @param for_each_func: the function to pass the nodes as data into + * @return Returns FALSE if an error condition occurs, otherwise TRUE */ int tree_for_each_node(Ecore_Tree_Node * node, Ecore_For_Each for_each_func) { @@ -829,11 +788,10 @@ int tree_for_each_node(Ecore_Tree_Node * node, Ecore_For_Each for_each_func) /* - * Description: Execute a function for each node below this point in the tree. - * Parameters: 1. node - the highest node in the tree the function will be - * executed for - * 2. for_each_func - the function to pass the nodes values as data - * Returns: FALSE if an error condition occurs, otherwise TRUE + * @brief Execute a function for each node below this point in the tree. + * @param node: the highest node in the tree the function will be executed for + * @param for_each_func: the function to pass the nodes values as data + * @return Returns FALSE if an error condition occurs, otherwise TRUE */ int tree_for_each_node_value(Ecore_Tree_Node * node, Ecore_For_Each for_each_func)