From 2c85cff20b328933b32dbe69866c120fd3dbae21 Mon Sep 17 00:00:00 2001 From: Vincent Torri Date: Wed, 7 Dec 2011 12:07:18 +0000 Subject: [PATCH] Eina: improve a bit the doc SVN revision: 65987 --- legacy/eina/src/include/Eina.h | 6 +- legacy/eina/src/include/eina_array.h | 2 +- legacy/eina/src/include/eina_benchmark.h | 8 +- legacy/eina/src/include/eina_clist.h | 50 +++++------ legacy/eina/src/include/eina_hash.h | 2 +- legacy/eina/src/include/eina_inlist.h | 84 +++++++++---------- legacy/eina/src/include/eina_list.h | 2 +- legacy/eina/src/include/eina_log.h | 15 +++- legacy/eina/src/include/eina_main.h | 3 + legacy/eina/src/include/eina_module.h | 47 ++++++----- .../eina/src/include/eina_simple_xml_parser.h | 42 +++++----- legacy/eina/src/include/eina_str.h | 16 ++-- legacy/eina/src/include/eina_stringshare.h | 1 + legacy/eina/src/include/eina_types.h | 4 + legacy/eina/src/include/eina_unicode.h | 23 +++-- legacy/eina/src/include/eina_xattr.h | 6 +- 16 files changed, 172 insertions(+), 139 deletions(-) diff --git a/legacy/eina/src/include/Eina.h b/legacy/eina/src/include/Eina.h index 68c41f5638..b320041a9c 100644 --- a/legacy/eina/src/include/Eina.h +++ b/legacy/eina/src/include/Eina.h @@ -47,7 +47,7 @@ * * @version 1.1 * @date 2008-2011 - * + * * @section eina_intro_sec Introduction * * The Eina library is a library that implements an API for data types @@ -62,7 +62,7 @@ * @li @ref Eina_Array_Group standard array of @c void* data. * @li @ref Eina_Hash_Group standard hash of @c void* data. * @li @ref Eina_Inline_List_Group list with nodes inlined into user type. - * @li @ref Eina_CList_Group compact inlined list. + * @li @ref Eina_CList_Group Compact List. * @li @ref Eina_List_Group standard list of @c void* data. * @li @ref Eina_Iterator_Group Iterator functions. * @li @ref Eina_Matrixsparse_Group sparse matrix of @c void* data. @@ -89,7 +89,7 @@ * * Please see the @ref authors page for contact details. * - * @defgroup Eina_Data_Types_Group Data types + * @defgroup Eina_Data_Types_Group Data Types * * Eina provide easy to use and optimized data types and structures. * diff --git a/legacy/eina/src/include/eina_array.h b/legacy/eina/src/include/eina_array.h index d33f5e976c..57ec04d206 100644 --- a/legacy/eina/src/include/eina_array.h +++ b/legacy/eina/src/include/eina_array.h @@ -394,7 +394,7 @@ EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA */ static inline Eina_Bool eina_array_foreach(Eina_Array *array, Eina_Each_Cb cb, - void *data); + void *fdata); /** * @def EINA_ARRAY_ITER_NEXT * @brief Macro to iterate over an array easily. diff --git a/legacy/eina/src/include/eina_benchmark.h b/legacy/eina/src/include/eina_benchmark.h index 721e1c01e2..9e96d64f31 100644 --- a/legacy/eina/src/include/eina_benchmark.h +++ b/legacy/eina/src/include/eina_benchmark.h @@ -398,9 +398,9 @@ EAPI void eina_benchmark_free(Eina_Benchmark *bench); * * This function adds the test named @p name to @p benchmark. @p * bench_cb is the function called when the test is executed. That - * test can be executed a certain amount of time. @p start, @p end and - * @p step define a loop with a step increment. The integer that is - * increasing by @p step from @p start to @p end is passed to @p + * test can be executed a certain amount of time. @p count_start, @p count_end and + * @p count_step define a loop with a step increment. The integer that is + * increasing by @p count_step from @p count_start to @p count_end is passed to @p * bench_cb when eina_benchmark_run() is called. * * If @p bench is @c NULL, this function returns imediatly. If the @@ -413,7 +413,7 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, Eina_Benchmark_Specimens bench_cb, int count_start, int count_end, - int count_set); + int count_step); /** * @brief Run the benchmark tests that have been registered. diff --git a/legacy/eina/src/include/eina_clist.h b/legacy/eina/src/include/eina_clist.h index 29fa801a94..096a4b7b75 100644 --- a/legacy/eina/src/include/eina_clist.h +++ b/legacy/eina/src/include/eina_clist.h @@ -23,7 +23,22 @@ #define __EINA_CLIST_H__ /** - * @addtogroup Eina_CList_Group Compact inline list + * @addtogroup Eina_Data_Types_Group Data Types + * + * @{ + */ + +/** + * @addtogroup Eina_Containers_Group Containers + * + * @{ + */ + +/** + * @defgroup Eina_CList_Group Compact List + * + * @{ + * * @brief Eina_Clist is a compact (inline) list implementation * * Elements of this list are members of the structs stored in the list @@ -42,9 +57,8 @@ * @note There's no NULL at the end of the list, the last item points to the head. * * @note List heads must be initialized with EINA_CLIST_INIT or by calling eina_clist_element_init - */ - -/* Define a list like so: + * + * Define a list like so: * * @code * struct gadget @@ -87,24 +101,6 @@ * */ -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** - * @defgroup Eina_CList_Group Compact list - * - * @{ - */ - /** * @typedef Eina_Clist * This is the list head and the list entry. @@ -218,7 +214,7 @@ static inline void eina_clist_remove(Eina_Clist *elem); * @param list The list * @param elem An element * @pre @a elem is in @a list - * @return The element after @elem in @list or NULL if @a elem is last in @a list + * @return The element after @a elem in @a list or @c NULL if @a elem is last in @a list * @since 1.1.0 */ static inline Eina_Clist *eina_clist_next(const Eina_Clist *list, const Eina_Clist *elem); @@ -247,7 +243,7 @@ static inline Eina_Clist *eina_clist_head(const Eina_Clist *list); * Get the last element. * * @param list The list - * @returns The last element in @a list or NULL if @list is empty + * @returns The last element in @a list or NULL if @a list is empty * @since 1.1.0 */ static inline Eina_Clist *eina_clist_tail(const Eina_Clist *list); @@ -367,15 +363,15 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src); #include "eina_inline_clist.x" -/* +/** * @} */ -/* +/** * @} */ -/* +/** * @} */ diff --git a/legacy/eina/src/include/eina_hash.h b/legacy/eina/src/include/eina_hash.h index c8eb04861b..467eb7a5d2 100644 --- a/legacy/eina/src/include/eina_hash.h +++ b/legacy/eina/src/include/eina_hash.h @@ -1005,7 +1005,7 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL * @endcode */ EAPI void eina_hash_foreach(const Eina_Hash *hash, - Eina_Hash_Foreach cb, + Eina_Hash_Foreach func, const void *fdata) EINA_ARG_NONNULL(1, 2); /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */ EAPI int eina_hash_superfast(const char *key, diff --git a/legacy/eina/src/include/eina_inlist.h b/legacy/eina/src/include/eina_inlist.h index 1b3ab274f9..f57fcab26b 100644 --- a/legacy/eina/src/include/eina_inlist.h +++ b/legacy/eina/src/include/eina_inlist.h @@ -428,17 +428,17 @@ struct _Eina_Inlist * Add a new node to end of a list. * * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * walk @a in_list. * - * @note @a new_l is considered to be in no list. If it was in another + * @note @a in_item is considered to be in no list. If it was in another * list before, eina_inlist_remove() it before adding. No * check of @a new_l prev and next pointers is done, so it's safe * to have them uninitialized. * - * @param list existing list head or NULL to create a new list. - * @param new_l new list node, must not be NULL. + * @param in_list existing list head or NULL to create a new list. + * @param in_item new list node, must not be NULL. * - * @return the new list head. Use it and not @a list anymore. + * @return the new list head. Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -447,17 +447,17 @@ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, * Add a new node to beginning of list. * * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * walk @a in_list. * * @note @a new_l is considered to be in no list. If it was in another * list before, eina_inlist_remove() it before adding. No * check of @a new_l prev and next pointers is done, so it's safe * to have them uninitialized. * - * @param list existing list head or NULL to create a new list. - * @param new_l new list node, must not be NULL. + * @param in_list existing list head or NULL to create a new list. + * @param in_item new list node, must not be NULL. * - * @return the new list head. Use it and not @a list anymore. + * @return the new list head. Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -466,21 +466,21 @@ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, * Add a new node after the given relative item in list. * * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * walk @a in_list. * - * @note @a new_l is considered to be in no list. If it was in another + * @note @a in_item_l is considered to be in no list. If it was in another * list before, eina_inlist_remove() it before adding. No - * check of @a new_l prev and next pointers is done, so it's safe + * check of @a in_item prev and next pointers is done, so it's safe * to have them uninitialized. * - * @note @a relative is considered to be inside @a list, no checks are + * @note @a in_relative is considered to be inside @a in_list, no checks are * done to confirm that and giving nodes from different lists - * will lead to problems. Giving NULL @a relative is the same as + * will lead to problems. Giving NULL @a in_relative is the same as * eina_list_append(). * - * @param list existing list head or NULL to create a new list. - * @param new_l new list node, must not be NULL. - * @param relative reference node, @a new_l will be added after it. + * @param in_list existing list head or NULL to create a new list. + * @param in_item new list node, must not be NULL. + * @param in_relative reference node, @a in_item will be added after it. * * @return the new list head. Use it and not @a list anymore. */ @@ -492,23 +492,23 @@ EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, * Add a new node before the given relative item in list. * * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * walk @a in_list. * - * @note @a new_l is considered to be in no list. If it was in another + * @note @a in_item is considered to be in no list. If it was in another * list before, eina_inlist_remove() it before adding. No - * check of @a new_l prev and next pointers is done, so it's safe + * check of @a in_item prev and next pointers is done, so it's safe * to have them uninitialized. * - * @note @a relative is considered to be inside @a list, no checks are + * @note @a in_relative is considered to be inside @a in_list, no checks are * done to confirm that and giving nodes from different lists - * will lead to problems. Giving NULL @a relative is the same as + * will lead to problems. Giving NULL @a in_relative is the same as * eina_list_prepend(). * - * @param list existing list head or NULL to create a new list. - * @param new_l new list node, must not be NULL. - * @param relative reference node, @a new_l will be added before it. + * @param in_list existing list head or NULL to create a new list. + * @param in_item new list node, must not be NULL. + * @param in_relative reference node, @a in_item will be added before it. * - * @return the new list head. Use it and not @a list anymore. + * @return the new list head. Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, Eina_Inlist *in_item, @@ -520,14 +520,14 @@ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, * @note this code is meant to be fast: appends are O(1) and do not * walk @a list. * - * @note @a item is considered to be inside @a list, no checks are + * @note @a in_item is considered to be inside @a in_list, no checks are * done to confirm that and giving nodes from different lists - * will lead to problems, especially if @a item is the head since + * will lead to problems, especially if @a in_item is the head since * it will be different from @a list and the wrong new head will * be returned. * - * @param list existing list head, must not be NULL. - * @param item existing list node, must not be NULL. + * @param in_list existing list head, must not be NULL. + * @param in_item existing list node, must not be NULL. * * @return the new list head. Use it and not @a list anymore. */ @@ -540,10 +540,10 @@ EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, * @warning this is an expensive call and has O(n) cost, possibly * walking the whole list. * - * @param list existing list to search @a item in, must not be NULL. - * @param item what to search for, must not be NULL. + * @param in_list existing list to search @a in_item in, must not be NULL. + * @param in_item what to search for, must not be NULL. * - * @return @a item if found, NULL if not. + * @return @a in_item if found, NULL if not. */ EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -603,11 +603,11 @@ EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_ /** * @brief Returns a new iterator associated to @a list. * - * @param list The list. + * @param in_list The list. * @return A new iterator. * * This function returns a newly allocated iterator associated to @p - * list. If @p list is @c NULL or the count member of @p list is less + * in_list. If @p in_list is @c NULL or the count member of @p in_list is less * or equal than 0, this function still returns a valid iterator that * will always return false on eina_iterator_next(), thus keeping API * sane. @@ -625,13 +625,13 @@ EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MA /** * @brief Returns a new accessor associated to a list. * - * @param list The list. + * @param in_list The list. * @return A new accessor. * * This function returns a newly allocated accessor associated to - * @p list. If @p list is @c NULL or the count member of @p list is - * less or equal than 0, this function returns NULL. If the memory can - * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * @p in_list. If @p in_list is @c NULL or the count member of @p in_list is + * less or equal than 0, this function returns @c NULL. If the memory can + * not be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is * set. Otherwise, a valid accessor is returned. */ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; @@ -728,13 +728,13 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list, /** * @brief Sort a list according to the ordering func will return. * - * @param list The list handle to sort. + * @param head The list handle to sort. * @param func A function pointer that can handle comparing the list data * nodes. * @return the new head of list. * - * This function sorts all the elements of @p list. @p func is used to - * compare two elements of @p list. If @p list or @p func are @c NULL, + * This function sorts all the elements of @p head. @p func is used to + * compare two elements of @p head. If @p head or @p func are @c NULL, * this function returns @c NULL. * * @note @b in-place: this will change the given list, so you should diff --git a/legacy/eina/src/include/eina_list.h b/legacy/eina/src/include/eina_list.h index 8a8f25ea7f..06a3eae60b 100644 --- a/legacy/eina/src/include/eina_list.h +++ b/legacy/eina/src/include/eina_list.h @@ -202,7 +202,7 @@ * * If you don't know how to create lists see * @ref list_01_example_page. In this example we also use - * @ref eina_stringshare, however it should be possible to understand the code + * @ref Eina_Stringshare_Group, however it should be possible to understand the code * regardless of previous knowledge about it. * * Here we have the usual list creation code with a twist, now we are using as diff --git a/legacy/eina/src/include/eina_log.h b/legacy/eina/src/include/eina_log.h index 8b001485ea..186397d7a8 100644 --- a/legacy/eina/src/include/eina_log.h +++ b/legacy/eina/src/include/eina_log.h @@ -732,7 +732,7 @@ EAPI void eina_log_domain_unregister(int domain); * specified value (eina_log_level_set() or environment * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. * @param file filename that originated the call, must @b not be @c NULL. - * @param fnc function that originated the call, must @b not be @c NULL. + * @param function function that originated the call, must @b not be @c NULL. * @param line originating line in @a file. * @param fmt printf-like format to use. Should not provide trailing * '\n' as it is automatically included. @@ -786,7 +786,7 @@ EAPI void eina_log_vprint(int domain, */ /** - * Alternative logging method, this will output to standard output stream. + * @brief Alternative logging method, this will output to standard output stream. * * @param d The domain. * @param level The level. @@ -821,7 +821,16 @@ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d, va_list args); /** - * Default logging method, this will output to standard error stream. + * @brief Default logging method, this will output to standard error stream. + * + * @param d The domain. + * @param level The level. + * @param file The file which is logged. + * @param fnc The function which is logged. + * @param line The line which is logged. + * @param fmt The ouptut format to use. + * @param data Not used. + * @param args The arguments needed by the format. * * This method will colorize output based on domain provided color and * message logging level. diff --git a/legacy/eina/src/include/eina_main.h b/legacy/eina/src/include/eina_main.h index fa34d593ba..6d88a45252 100644 --- a/legacy/eina/src/include/eina_main.h +++ b/legacy/eina/src/include/eina_main.h @@ -134,6 +134,9 @@ EAPI int eina_threads_shutdown(void); /** * @brief Check if you are calling this function from the same thread Eina was initialized or not + * + * @return #EINA_TRUE is the calling function is the same thread, #EINA_FALSE otherwise. + * * @since 1.1.0 * * Most EFL function are not thread safe and all the call need to happen in diff --git a/legacy/eina/src/include/eina_module.h b/legacy/eina/src/include/eina_module.h index 58e38f9352..178fa9ab31 100644 --- a/legacy/eina/src/include/eina_module.h +++ b/legacy/eina/src/include/eina_module.h @@ -67,6 +67,10 @@ */ typedef struct _Eina_Module Eina_Module; +/** + * @typedef Eina_Module_Cb + * Dynamic module loader callback. + */ typedef Eina_Bool (*Eina_Module_Cb)(Eina_Module *m, void *data); /** @@ -135,21 +139,21 @@ EAPI Eina_Module * /** * @brief Delete a module. * - * @param m The module to delete. + * @param module The module to delete. * @return EINA_TRUE on success, EINA_FALSE otherwise. * - * This function calls eina_module_unload() if @p m has been previously + * This function calls eina_module_unload() if @p module has been previously * loaded and frees the allocated memory. On success this function - * returns EINA_TRUE and EINA_FALSE otherwise. If @p m is @c NULL, the + * returns EINA_TRUE and EINA_FALSE otherwise. If @p module is @c NULL, the * function returns immediately. */ EAPI Eina_Bool - eina_module_free(Eina_Module *m) EINA_ARG_NONNULL(1); + eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1); /** * @brief Load a module. * - * @param m The module to load. + * @param module The module to load. * @return EINA_TRUE on success, EINA_FALSE otherwise. * * This function load the shared file object passed in @@ -160,7 +164,7 @@ EAPI Eina_Bool * module can not be initialized, the error * #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is * returned. If the module has already been loaded, it's refeence - * counter is increased by one and #EINA_TRUE is returned. If @p m is + * counter is increased by one and #EINA_TRUE is returned. If @p module is * @c NULL, the function returns immediately #EINA_FALSE. * * When the symbols of the shared file objetcts are not needed @@ -172,29 +176,29 @@ EAPI Eina_Bool /** * @brief Unload a module. * - * @param m The module to load. + * @param module The module to load. * @return EINA_TRUE on success, EINA_FALSE otherwise. * - * This function unload the module @p m that has been previously - * loaded by eina_module_load(). If the reference counter of @p m is + * This function unload the module @p module that has been previously + * loaded by eina_module_load(). If the reference counter of @p module is * strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the * shared object file is closed and if it is a internal Eina module, it * is shutted down just before. In that case, #EINA_TRUE is - * returned. In all case, the reference counter is decreased. If @p m + * returned. In all case, the reference counter is decreased. If @p module * is @c NULL, the function returns immediately #EINA_FALSE. */ EAPI Eina_Bool - eina_module_unload(Eina_Module *m) EINA_ARG_NONNULL(1); + eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1); /** * @brief Retrive the data associated to a symbol. * - * @param m The module. + * @param module The module. * @param symbol The symbol. * @return The data associated to the symbol, or @c NULL on failure. * - * This function returns the data associated to @p symbol of @p m. @p - * m must have been loaded before with eina_module_load(). If @p m + * This function returns the data associated to @p symbol of @p module. @p + * module must have been loaded before with eina_module_load(). If @p module * is @c NULL, or if it has not been correctly loaded before, the * function returns immediately @c NULL. */ @@ -204,15 +208,15 @@ EAPI void * /** * @brief Return the file name associated to the module. * - * @param m The module. + * @param module The module. * @return The file name. * * This function returns the file name passed in eina_module_new(). If - * @p m is @c NULL, the function returns immediately @c NULL. The + * @p module is @c NULL, the function returns immediately @c NULL. The * returned value must no be freed. */ EAPI const char * - eina_module_file_get(const Eina_Module *m) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** @@ -256,6 +260,7 @@ EAPI char * * @param array The array that stores the list of the modules. * @param path The directory's path to search for modules. * @param arch The architecture string. + * @return The array of modules found in @p path matching @p arch. * * This function adds to @p array the module names found in @p path * which match the cpu architecture @p arch. If @p path or @p arch is @@ -273,6 +278,7 @@ EAPI Eina_Array * * @param recursive Iterate recursively on the path. * @param cb Callback function to call on each module. * @param data Data passed to the callback function. + * @return The array of modules found in @p path. * * This function adds to @p array the list of modules found in * @p path. If @p recursive is #EINA_TRUE, then recursive search is @@ -295,7 +301,7 @@ EAPI Eina_Array * * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void - eina_module_list_load(Eina_Array *list) EINA_ARG_NONNULL(1); + eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1); /** * @brief Unload every module on the list of modules. @@ -306,7 +312,7 @@ EAPI void * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void - eina_module_list_unload(Eina_Array *list) EINA_ARG_NONNULL(1); + eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1); /** * @p Free every module on the list of modules. @@ -317,13 +323,14 @@ EAPI void * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void - eina_module_list_free(Eina_Array *list) EINA_ARG_NONNULL(1); + eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1); /** * @brief Find an module in array. * * @param array The array to find the module. * @param module The name of module to be searched. + * @return The module to find on success, @c NULL otherwise. * * This function finds an @p module in @p array. * If the element is found the function returns the module, else diff --git a/legacy/eina/src/include/eina_simple_xml_parser.h b/legacy/eina/src/include/eina_simple_xml_parser.h index db9a4e1744..8dbb6171d2 100644 --- a/legacy/eina/src/include/eina_simple_xml_parser.h +++ b/legacy/eina/src/include/eina_simple_xml_parser.h @@ -137,7 +137,7 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c /** * Parse a section of XML string text - * + * * @param buf the input string. May not contain \0 terminator. * @param buflen the input string size. * @param strip whenever this parser should strip leading and trailing @@ -164,12 +164,15 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, /** * Given the contents of a tag, find where the attributes start. * - * The tag contents is returned by eina_simple_xml_parse() when - * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY. - * + * @param buf the input string. May not contain \0 terminator. + * @param buflen the input string size. * @return pointer to the start of attributes, it can be used * to feed eina_simple_xml_attributes_parse(). NULL is returned * if no attributes were found. + * + * The tag contents is returned by eina_simple_xml_parse() when + * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY. + * */ EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned buflen); @@ -183,6 +186,7 @@ EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned * key (null-terminated) and the last is the value (null * terminated). These strings should not be modified and * reference is just valid until the function return. + * @param data data to pass to the callback function. * * @return EINA_TRUE on success or EINA_FALSE if it was aborted by user or * parsing error. @@ -238,8 +242,8 @@ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag); * * @param parent if provided, will be set in the resulting structure * as well as the data will be appended to children list. - * @param content string to be used. Must not be NULL. - * @param length size in bytes of @a content. + * @param contents string to be used. Must not be NULL. + * @param length size in bytes of @a contents. * * @return newly allocated memory or NULL on error. This memory should be * released with eina_simple_xml_node_data_free() or indirectly @@ -250,7 +254,7 @@ EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_N /** * Remove data from parent and delete it. * - * @param data to release memory. + * @param node to release memory. */ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node); @@ -260,7 +264,7 @@ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node); * * @param parent if provided, will be set in the resulting structure * as well as the cdata will be appended to children list. - * @param content string to be used. Must not be NULL. + * @param contents string to be used. Must not be NULL. * @param length size in bytes of @a content. * * @return newly allocated memory or NULL on error. This memory should be @@ -272,7 +276,7 @@ EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML /** * Remove cdata from parent and delete it. * - * @param cdata to release memory. + * @param node to release memory. */ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node); @@ -282,8 +286,8 @@ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node); * * @param parent if provided, will be set in the resulting structure * as well as the processing will be appended to children list. - * @param content string to be used. Must not be NULL. - * @param length size in bytes of @a content. + * @param contents string to be used. Must not be NULL. + * @param length size in bytes of @a contents. * * @return newly allocated memory or NULL on error. This memory should be * released with eina_simple_xml_node_processing_free() or indirectly @@ -294,7 +298,7 @@ EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_ /** * Remove processing from parent and delete it. * - * @param processing to release memory. + * @param node processing to release memory. */ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node); @@ -304,8 +308,8 @@ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node); * * @param parent if provided, will be set in the resulting structure * as well as the doctype will be appended to children list. - * @param content string to be used. Must not be NULL. - * @param length size in bytes of @a content. + * @param contents string to be used. Must not be NULL. + * @param length size in bytes of @a contents. * * @return newly allocated memory or NULL on error. This memory should be * released with eina_simple_xml_node_doctype_free() or indirectly @@ -316,7 +320,7 @@ EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple /** * Remove doctype from parent and delete it. * - * @param doctype to release memory. + * @param node doctype to release memory. */ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node); @@ -326,8 +330,8 @@ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node); * * @param parent if provided, will be set in the resulting structure * as well as the comment will be appended to children list. - * @param content string to be used. Must not be NULL. - * @param length size in bytes of @a content. + * @param contents string to be used. Must not be NULL. + * @param length size in bytes of @a contents. * * @return newly allocated memory or NULL on error. This memory should be * released with eina_simple_xml_node_comment_free() or indirectly @@ -338,7 +342,7 @@ EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple /** * Remove comment from parent and delete it. * - * @param comment to release memory. + * @param node comment to release memory. */ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node); @@ -370,7 +374,7 @@ EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root); * @param node the base node to convert. * @param indent indentation string, or NULL to disable it. * - * @param NULL on errors or a newly allocated string on success. + * @return NULL on errors or a newly allocated string on success. */ EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent); diff --git a/legacy/eina/src/include/eina_str.h b/legacy/eina/src/include/eina_str.h index 32c1cc66ab..2913fbfbfb 100644 --- a/legacy/eina/src/include/eina_str.h +++ b/legacy/eina/src/include/eina_str.h @@ -161,14 +161,14 @@ EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EI /** * @brief Split a string using a delimiter. * - * @param str The string to split. - * @param delim The string which specifies the places at which to split the string. + * @param string The string to split. + * @param delimiter The string which specifies the places at which to split the string. * @param max_tokens The maximum number of strings to split string into. * @return A newly-allocated NULL-terminated array of strings or NULL if it * fails to allocate the array. * - * This functin splits @p str into a maximum of @p max_tokens pieces, - * using the given delimiter @p delim. @p delim is not included in any + * This functin splits @p string into a maximum of @p max_tokens pieces, + * using the given delimiter @p delimiter. @p delimiter is not included in any * of the resulting strings, unless @p max_tokens is reached. If * @p max_tokens is less than @c 1, the string is splitted completely. If * @p max_tokens is reached, the last string in the returned string @@ -185,16 +185,16 @@ EAPI char **eina_str_split(const char *string, const char *delimiter, i /** * @brief Split a string using a delimiter and returns number of elements. * - * @param str The string to split. - * @param delim The string which specifies the places at which to split the string. + * @param string The string to split. + * @param delimiter The string which specifies the places at which to split the string. * @param max_tokens The maximum number of strings to split string into. * @param elements Where to return the number of elements in returned * array (not counting the terminating @c NULL). May be @c NULL. * @return A newly-allocated NULL-terminated array of strings or NULL if it * fails to allocate the array. * - * This function splits @p str into a maximum of @p max_tokens pieces, - * using the given delimiter @p delim. @p delim is not included in any + * This function splits @p string into a maximum of @p max_tokens pieces, + * using the given delimiter @p delimiter. @p delimiter is not included in any * of the resulting strings, unless @p max_tokens is reached. If * @p max_tokens is less than @c 1, the string is splitted completely. If * @p max_tokens is reached, the last string in the returned string diff --git a/legacy/eina/src/include/eina_stringshare.h b/legacy/eina/src/include/eina_stringshare.h index af58add1af..862b2b2c57 100644 --- a/legacy/eina/src/include/eina_stringshare.h +++ b/legacy/eina/src/include/eina_stringshare.h @@ -289,6 +289,7 @@ EAPI void eina_stringshare_del(const char *str); * * @param str the shared string to know the length. It is safe to * give NULL, in that case -1 is returned. + * @return The length of a shared string. * * This function is a cheap way to known the length of a shared * string. Note that if the given pointer is not shared, bad diff --git a/legacy/eina/src/include/eina_types.h b/legacy/eina/src/include/eina_types.h index 8c77cdface..16539495e7 100644 --- a/legacy/eina/src/include/eina_types.h +++ b/legacy/eina/src/include/eina_types.h @@ -251,6 +251,10 @@ typedef int (*Eina_Compare_Cb)(const void *data1, const void *data2); */ #define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function) +/** + * @typedef Eina_Each_Cb + * A callback type used when iterating over a container. + */ typedef Eina_Bool (*Eina_Each_Cb)(const void *container, void *data, void *fdata); /** diff --git a/legacy/eina/src/include/eina_unicode.h b/legacy/eina/src/include/eina_unicode.h index aed59af9cf..ed7ecce016 100644 --- a/legacy/eina/src/include/eina_unicode.h +++ b/legacy/eina/src/include/eina_unicode.h @@ -68,7 +68,16 @@ EAPI Eina_Unicode *eina_unicode_strdup(const Eina_Unicode *text) EINA_WARN_UNUSE /** - * @brief Same as strdup but cuts on n. Assumes n < len + * @brief Same as strdup but cuts on the given size. Assumes n < len + * + * @param text The text to duplicate. + * @param n The maximum size of the text to duplicate. + * @return The duplicated string. + * + * This function duplicates @p text. The resuting string is cut on @p + * n. @p n is assumed to be lesser (<) than the length of @t + * text. When not needed anymore, the returned string must be freed. + * * @since 1.1.0 */ EAPI Eina_Unicode *eina_unicode_strndup(const Eina_Unicode *text, size_t n) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; @@ -107,9 +116,9 @@ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL /** - * Reads UTF8 bytes from @buf, starting at *@index and returns - * the decoded code point at iindex offset, and advances iindex - * to the next code point after this. iindex is always advanced, + * Reads UTF8 bytes from @p buf, starting at @p iindex and returns + * the decoded code point at @p iindex offset, and advances @p iindex + * to the next code point after this. @p iindex is always advanced, * unless if the advancement is after the NULL. * On error: return a codepoint between DC80 to DCFF where the low 8 bits * are the byte's value. @@ -122,9 +131,9 @@ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2); /** - * Reads UTF8 bytes from @buf, starting at *@iindex and returns - * the decoded code point at iindex offset, and moves iindex - * to the previous code point. iindex is always moved, as long + * Reads UTF8 bytes from @p buf, starting at @p iindex and returns + * the decoded code point at @p iindex offset, and moves àp iindex + * to the previous code point. @p iindex is always moved, as long * as it's not past the start of the string. * On error: return a codepoint between DC80 to DCFF where the low 8 bits * are the byte's value. diff --git a/legacy/eina/src/include/eina_xattr.h b/legacy/eina/src/include/eina_xattr.h index 8ddb30a4e1..5ab294d04d 100644 --- a/legacy/eina/src/include/eina_xattr.h +++ b/legacy/eina/src/include/eina_xattr.h @@ -57,7 +57,7 @@ EAPI Eina_Iterator *eina_xattr_ls(const char *file); * @brief Retrieve an extended attribute from a file. * * @param file The file to retrieve the extended attribute from. - * @param atttribute The extended attribute name to retrieve. + * @param attribute The extended attribute name to retrieve. * @param size The size of the retrieved extended attribute. * @return the allocated data that hold the extended attribute value. * @@ -112,7 +112,7 @@ EAPI char *eina_xattr_string_get(const char *file, const char *attribute); * * @param file The file to set the double to. * @param attribute The attribute to set. - * @param data The NULL terminated double to set. + * @param value The NULL terminated double to set. * @param flags Define the set policy. * @return EINA_TRUE on success, EINA_FALSE otherwise. * @@ -139,7 +139,7 @@ EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, do * * @param file The file to set the int to. * @param attribute The attribute to set. - * @param data The NULL terminated int to set. + * @param value The NULL terminated int to set. * @param flags Define the set policy. * @return EINA_TRUE on success, EINA_FALSE otherwise. *