From 9110d8d574327f24fe262856f26154d991afe1fa Mon Sep 17 00:00:00 2001 From: Vincent Torri Date: Mon, 22 Jun 2009 20:03:58 +0000 Subject: [PATCH] fix a bit the documentation, but there are still a lot of doc to write... SVN revision: 41164 --- legacy/eina/src/include/eina_accessor.h | 18 +++- legacy/eina/src/include/eina_file.h | 2 +- legacy/eina/src/include/eina_inline_array.x | 6 +- legacy/eina/src/include/eina_inlist.h | 27 +++++- legacy/eina/src/include/eina_iterator.h | 10 +++ legacy/eina/src/include/eina_list.h | 6 +- legacy/eina/src/include/eina_magic.h | 20 +++++ legacy/eina/src/include/eina_main.h | 20 +++++ legacy/eina/src/include/eina_mempool.h | 19 ++++- legacy/eina/src/include/eina_module.h | 9 +- legacy/eina/src/include/eina_types.h | 10 +++ legacy/eina/src/lib/eina_accessor.c | 10 --- legacy/eina/src/lib/eina_array.c | 33 ++++--- legacy/eina/src/lib/eina_benchmark.c | 36 ++++---- legacy/eina/src/lib/eina_convert.c | 10 --- legacy/eina/src/lib/eina_counter.c | 34 ++++---- legacy/eina/src/lib/eina_error.c | 44 +++++----- legacy/eina/src/lib/eina_file.c | 12 +-- legacy/eina/src/lib/eina_hash.c | 34 +++----- legacy/eina/src/lib/eina_inlist.c | 56 ++++++------ legacy/eina/src/lib/eina_iterator.c | 10 --- legacy/eina/src/lib/eina_list.c | 35 +++++--- legacy/eina/src/lib/eina_magic.c | 95 +++++++++++++++++++++ legacy/eina/src/lib/eina_main.c | 53 +++++++++++- legacy/eina/src/lib/eina_mempool.c | 32 ++++--- legacy/eina/src/lib/eina_module.c | 54 +++++------- legacy/eina/src/lib/eina_stringshare.c | 10 --- 27 files changed, 463 insertions(+), 242 deletions(-) diff --git a/legacy/eina/src/include/eina_accessor.h b/legacy/eina/src/include/eina_accessor.h index 6539bbe240..55952d4b18 100644 --- a/legacy/eina/src/include/eina_accessor.h +++ b/legacy/eina/src/include/eina_accessor.h @@ -24,6 +24,12 @@ #include "eina_types.h" #include "eina_magic.h" +/** + * @addtogroup Eina_Content_Access_Group Content Access + * + * @{ + */ + /** * @defgroup Eina_Accessor_Group Accessor Functions * @@ -71,11 +77,13 @@ EAPI void eina_accessor_over (Eina_Accessor *accessor, * @brief Macro to iterate over all elements easily. * * @param accessor The accessor to use. + * @param counter A counter used by eina_accessor_data_get() when + * iterating over the container. * @param data Where to store * data, must be a pointer support getting - * its address since * eina_accessor_data_get() requires a pointer - * to pointer! + * its address since * eina_accessor_data_get() requires a pointer to + * pointer! * - * This macro is a convenient way to loop over all elements in an + * This macro allows a convenient way to loop over all elements in an * accessor, very similar to EINA_LIST_FOREACH(). * * This macro can be used for freeing the data of a list, like in the @@ -115,6 +123,10 @@ EAPI void eina_accessor_over (Eina_Accessor *accessor, */ #define EINA_ACCESSOR_FOREACH(accessor, counter, data) for ((counter) = 0; eina_accessor_data_get((accessor), (counter), (void **)&(data)); (counter)++) +/** + * @} + */ + /** * @} */ diff --git a/legacy/eina/src/include/eina_file.h b/legacy/eina/src/include/eina_file.h index 7210904d8a..7011781178 100644 --- a/legacy/eina/src/include/eina_file.h +++ b/legacy/eina/src/include/eina_file.h @@ -29,7 +29,7 @@ */ /** - * @defgroup Eina_File_Group Memory File + * @defgroup Eina_File_Group File * * @{ */ diff --git a/legacy/eina/src/include/eina_inline_array.x b/legacy/eina/src/include/eina_inline_array.x index f13b9f1e9d..a9a2ba3ec3 100644 --- a/legacy/eina/src/include/eina_inline_array.x +++ b/legacy/eina/src/include/eina_inline_array.x @@ -109,8 +109,8 @@ eina_array_data_get(const Eina_Array *array, unsigned int index) * @brief Return the data at a given position in an array. * * @param array The array. - * @param index The potition of the data to retrieve. - * @return The retrieved data. + * @param index The potition of the data to set. + * @param data The data to set. * * This function returns the data at the position @p index in @p * array. For performance reasons, there is no check of @p array or @p @@ -123,7 +123,7 @@ eina_array_data_set(const Eina_Array *array, unsigned int index, const void *dat } /** - * @brief Return the number of elements in the array. + * @brief Return the number of elements in an array. * * @param array The array. * @return The number of elements. diff --git a/legacy/eina/src/include/eina_inlist.h b/legacy/eina/src/include/eina_inlist.h index 7a010be67c..bedcc5f98b 100644 --- a/legacy/eina/src/include/eina_inlist.h +++ b/legacy/eina/src/include/eina_inlist.h @@ -24,7 +24,20 @@ #include "eina_accessor.h" /** - * @defgroup Inline_List_Group Inline List + * @addtogroup Eina_Data_Types_Group Data Types + * + * @{ + */ + +/** + * @addtogroup Eina_Containers_Group Containers + * + * @{ + */ + +/** + * @defgroup Eina_Inline_List_Group Inline List + * * @{ */ @@ -56,6 +69,16 @@ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MA #define EINA_INLIST_FOREACH(list, l) for (l = (void*)list; l; l = (void*)(l->__in_list.next)) #define EINA_INLIST_REVERSE_FOREACH(list, l) for (l = (list ? (void*)(list->last) : NULL); l; l = (void*)(l->__in_list.prev)) -/** @} */ +/** + * @} + */ + +/** + * @} + */ + +/** + * @} + */ #endif /*EINA_INLIST_H_*/ diff --git a/legacy/eina/src/include/eina_iterator.h b/legacy/eina/src/include/eina_iterator.h index 7309b2bbff..71605ec07c 100644 --- a/legacy/eina/src/include/eina_iterator.h +++ b/legacy/eina/src/include/eina_iterator.h @@ -24,6 +24,12 @@ #include "eina_types.h" #include "eina_magic.h" +/** + * @addtogroup Eina_Content_Access_Group Content Access + * + * @{ + */ + /** * @defgroup Eina_Iterator_Group Iterator Functions * @@ -108,6 +114,10 @@ EAPI void eina_iterator_foreach (Eina_Iterator *iterator, */ #define EINA_ITERATOR_FOREACH(itr, data) while (eina_iterator_next((itr), (void **)&(data))) +/** + * @} + */ + /** * @} */ diff --git a/legacy/eina/src/include/eina_list.h b/legacy/eina/src/include/eina_list.h index fc52fdd159..5b23b0b4a2 100644 --- a/legacy/eina/src/include/eina_list.h +++ b/legacy/eina/src/include/eina_list.h @@ -129,7 +129,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EI * data of each element of the list. @p l is an #Eina_List that is * used as counter. * - * This macro can be used for freeing the data of alist, like in + * This macro can be used for freeing the data of a list, like in * the following example: * * @code @@ -148,7 +148,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EI * * @note this example is not optimal algorithm to release a list since * it will walk the list twice, but it serves as an example. For - * optimized version use EINA_LIST_FREE() + * optimized version use EINA_LIST_FREE(). * * @warning do not delete list nodes, specially the current node, * while iterating. If you wish to do so, use @@ -169,7 +169,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EI * the data of each element of the list. @p l is an #Eina_List that is * used as counter. * - * This macro can be used for freeing the data of alist, like in + * This macro can be used for freeing the data of a list, like in * the following example: * * @code diff --git a/legacy/eina/src/include/eina_magic.h b/legacy/eina/src/include/eina_magic.h index 4dd34cea35..e9370a586d 100644 --- a/legacy/eina/src/include/eina_magic.h +++ b/legacy/eina/src/include/eina_magic.h @@ -23,6 +23,18 @@ #include "eina_config.h" #include "eina_types.h" +/** + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ + +/** + * @defgroup Eina_Magic_Group Magic + * + * @{ + */ + EAPI int eina_magic_string_init(void); EAPI int eina_magic_string_shutdown(void); @@ -59,4 +71,12 @@ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, #endif +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_MAGIC_H_ */ diff --git a/legacy/eina/src/include/eina_main.h b/legacy/eina/src/include/eina_main.h index d33071f2c6..c504bbb9d6 100644 --- a/legacy/eina/src/include/eina_main.h +++ b/legacy/eina/src/include/eina_main.h @@ -19,8 +19,28 @@ #ifndef EINA_MAIN_H_ #define EINA_MAIN_H_ +/** + * @addtogroup Eina_Core_Group Core + * + * @{ + */ + +/** + * @defgroup Eina_Main_Group Main + * + * @{ + */ + EAPI int eina_init(void); EAPI int eina_shutdown(void); +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_MAIN_H_ */ diff --git a/legacy/eina/src/include/eina_mempool.h b/legacy/eina/src/include/eina_mempool.h index 86b7b70787..d5e0f74d45 100644 --- a/legacy/eina/src/include/eina_mempool.h +++ b/legacy/eina/src/include/eina_mempool.h @@ -24,9 +24,17 @@ #include "eina_module.h" /** - * @defgroup Memory_Pool_Group Memory Pool + * @addtogroup Eina_Tools_Group Tools + * * @{ */ + +/** + * @defgroup Eina_Memory_Pool_Group Memory Pool + * + * @{ + */ + typedef struct _Eina_Mempool Eina_Mempool; typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend; @@ -49,6 +57,13 @@ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NONNULL( EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); #include "eina_inline_mempool.x" -/** @} */ + +/** + * @} + */ + +/** + * @} + */ #endif /* EINA_MEMPOOL_H_ */ diff --git a/legacy/eina/src/include/eina_module.h b/legacy/eina/src/include/eina_module.h index 41f5c18d8b..9789f0af28 100644 --- a/legacy/eina/src/include/eina_module.h +++ b/legacy/eina/src/include/eina_module.h @@ -24,7 +24,14 @@ #include "eina_error.h" /** - * @defgroup Module_Group Module + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ + +/** + * @defgroup Eina_Module_Group Module + * * @{ */ diff --git a/legacy/eina/src/include/eina_types.h b/legacy/eina/src/include/eina_types.h index e86bd28ba4..d34fe47500 100644 --- a/legacy/eina/src/include/eina_types.h +++ b/legacy/eina/src/include/eina_types.h @@ -19,6 +19,12 @@ #ifndef EINA_TYPES_H_ #define EINA_TYPES_H_ +/** + * @addtogroup Eina_Core_Group Core + * + * @{ + */ + /** * @defgroup Eina_Types_Group Types * @@ -210,6 +216,10 @@ typedef Eina_Bool (*Eina_Each)(const void *container, typedef void (*Eina_Free_Cb)(void *data); #define EINA_FREE_CB(Function) ((Eina_Free_Cb)Function) +/** + * @} + */ + /** * @} */ diff --git a/legacy/eina/src/lib/eina_accessor.c b/legacy/eina/src/lib/eina_accessor.c index 520ec092bd..f89768a096 100644 --- a/legacy/eina/src/lib/eina_accessor.c +++ b/legacy/eina/src/lib/eina_accessor.c @@ -56,12 +56,6 @@ * API * *============================================================================*/ -/** - * @addtogroup Eina_Content_Access_Group Content Access - * - * @{ - */ - /** * @addtogroup Eina_Accessor_Group Accessor Functions * @@ -181,7 +175,3 @@ eina_accessor_over(Eina_Accessor *accessor, /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_array.c b/legacy/eina/src/lib/eina_array.c index 688fa4b546..c44bdd4e9b 100644 --- a/legacy/eina/src/lib/eina_array.c +++ b/legacy/eina/src/lib/eina_array.c @@ -351,10 +351,18 @@ eina_array_grow(Eina_Array *array) * * @return 1 or greater on success, 0 on error. * - * This function just sets up the error module or Eina. It is also - * called by eina_init(). It returns 0 on failure, otherwise it - * returns the number of times eina_error_init() has already been - * called. + * This function sets up the error and magic modules or Eina. It is + * also called by eina_init(). It returns 0 on failure, otherwise it + * returns the number of times it has already been called. See + * eina_error_init() and eina_magic_string_init() for the + * documentation of the initialisation of the dependency modules. + * + * When no more Eina arrays are used, call eina_array_shutdown() to shut + * down the array module. + * + * @see eina_error_init() + * @see eina_magic_string_init() + * @see eina_init() */ EAPI int eina_array_init(void) @@ -392,13 +400,19 @@ eina_array_init(void) /** * @brief Shut down the array module. * - * @return 0 when the error module is completely shut down, 1 or + * @return 0 when the list module is completely shut down, 1 or * greater otherwise. * - * This function just shut down the error module set up by - * eina_array_init(). It is also called by eina_shutdown(). It returns - * 0 when it is called the same number of times than - * eina_error_init(). + * This function shuts down the array module. It returns 0 when it has + * been called the same number of times than eina_array_init(). In + * that case it shut down the magic and error modules. This function + * is also called by eina_shutdown(). See eina_error_shutdown() and + * eina_magic_string_shutdown() for the documentation of the + * shutting down of the dependency modules. + * + * @see eina_error_shutdown() + * @see eina_magic_string_shutdown() + * @see eina_shutdown() */ EAPI int eina_array_shutdown(void) @@ -714,4 +728,3 @@ eina_array_accessor_new(const Eina_Array *array) /** * @} */ - diff --git a/legacy/eina/src/lib/eina_benchmark.c b/legacy/eina/src/lib/eina_benchmark.c index c63776a4ba..1cdf43b393 100644 --- a/legacy/eina/src/lib/eina_benchmark.c +++ b/legacy/eina/src/lib/eina_benchmark.c @@ -61,6 +61,9 @@ void *alloca (size_t); * @cond LOCAL */ +#define EINA_BENCHMARK_FILENAME_MASK "bench_%s_%s.gnuplot" +#define EINA_BENCHMARK_DATA_MASK "bench_%s_%s.%s.data" + typedef struct _Eina_Run Eina_Run; struct _Eina_Run { @@ -95,12 +98,6 @@ static int _eina_benchmark_count = 0; * API * *============================================================================*/ -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - /** * @addtogroup Eina_Benchmark_Group Benchmark * @@ -135,8 +132,18 @@ static int _eina_benchmark_count = 0; * * This function sets up the error, array and counter modules or * Eina. It is also called by eina_init(). It returns 0 on failure, - * otherwise it returns the number of times eina_error_init() has - * already been called. + * otherwise it returns the number of times it has already been + * called. See eina_error_init(), eina_array_init() and + * eina_counter_init() for the documentation of the initialisation of + * the dependency modules. + * + * When no more Eina benchmarks are used, call + * eina_benchmark_shutdown() to shut down the benchmark module. + * + * @see eina_error_init() + * @see eina_array_init() + * @see eina_counter_init() + * @see eina_init() */ EAPI int eina_benchmark_init(void) @@ -178,7 +185,12 @@ eina_benchmark_init(void) * * This function shut down the error, array and counter modules set up * by eina_array_init(). It is also called by eina_shutdown(). It returns - * 0 when it is called the same number of times than eina_error_init(). + * 0 when it is called the same number of times than eina_benchmark_init(). + * + * @see eina_error_shutdown() + * @see eina_array_shutdown() + * @see eina_counter_shutdown() + * @see eina_shutdown() */ EAPI int eina_benchmark_shutdown(void) @@ -326,8 +338,6 @@ eina_benchmark_register(Eina_Benchmark *bench, const char *name, Eina_Benchmark_ * immediatly. Otherwise, it returns the list of the names of each * test. */ -#define EINA_BENCHMARK_FILENAME_MASK "bench_%s_%s.gnuplot" -#define EINA_BENCHMARK_DATA_MASK "bench_%s_%s.%s.data" EAPI Eina_Array * eina_benchmark_run(Eina_Benchmark *bench) { @@ -436,7 +446,3 @@ eina_benchmark_run(Eina_Benchmark *bench) /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_convert.c b/legacy/eina/src/lib/eina_convert.c index 75cf81056c..27fac408c6 100644 --- a/legacy/eina/src/lib/eina_convert.c +++ b/legacy/eina/src/lib/eina_convert.c @@ -79,12 +79,6 @@ EAPI Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH = 0; * @endcond */ -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - /** * @addtogroup Eina_Convert_Group Convert * @@ -555,7 +549,3 @@ eina_convert_dtoa(double d, char *des) /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_counter.c b/legacy/eina/src/lib/eina_counter.c index 1c61dc7b65..a4d23bf04b 100644 --- a/legacy/eina/src/lib/eina_counter.c +++ b/legacy/eina/src/lib/eina_counter.c @@ -146,12 +146,6 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...) * API * *============================================================================*/ -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - /** * @addtogroup Eina_Counter_Group Counter * @@ -237,12 +231,20 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...) * * @return 1 or greater on success, 0 on error. * - * This function allocates the memory needed by the counter, which - * means that it sets up the error module of Eina, and only on Windows + * This function sets up the error module of Eina and only on Windows, * it initializes the high precision timer. It also registers, only on * Windows, the error #EINA_COUNTER_ERROR_WINDOWS. It is also called * by eina_init(). It returns 0 on failure, otherwise it returns the - * number of times it has already been called. + * number of times it has already been called. See eina_error_init() + * for the documentation of the initialisation of the dependency + * modules. + * + * Once the counter module is not used anymore, then + * eina_counter_shutdown() must be called to shut down the counter + * module. + * + * @see eina_error_init() + * @see eina_init() */ EAPI int eina_counter_init(void) @@ -275,9 +277,13 @@ eina_counter_init(void) * @return 0 when the counter module is completely shut down, 1 or * greater otherwise. * - * This function just shuts down the error module. It is also called by - * eina_shutdown(). It returns 0 when it is called the same number of - * times than eina_counter_init(). + * This function shuts down the counter module set up by + * eina_counter_init(). It is called by eina_shutdown(). It + * returns 0 when it is called the same number of times than + * eina_counter_init(). + * + * @see eina_error_shutdown() + * @see eina_shutdown() */ EAPI int eina_counter_shutdown(void) @@ -479,7 +485,3 @@ eina_counter_dump(Eina_Counter *counter) /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_error.c b/legacy/eina/src/lib/eina_error.c index a3f0a22e97..0cd8f45442 100644 --- a/legacy/eina/src/lib/eina_error.c +++ b/legacy/eina/src/lib/eina_error.c @@ -419,12 +419,6 @@ static const char *_colors[EINA_ERROR_LEVELS] = { * API * *============================================================================*/ -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - /** * @addtogroup Eina_Error_Group Error * @@ -501,14 +495,14 @@ EAPI Eina_Error EINA_ERROR_OUT_OF_MEMORY = 0; */ /** - * @brief Initialize the error system. + * @brief Initialize the error module. * * @return 1 or greater on success, 0 on error. * - * This function sets up the error system or Eina. It is called by - * eina_init() and by all subsystems initialization functions. It - * returns 0 on failure, otherwise it returns the number of times it - * is called. + * This function sets up the error module of Eina. It is called by + * eina_init() and by all modules initialization functions. It returns + * @c 0 on failure, otherwise it returns the number of times it is + * called. * * The default error level value is set by default to * #EINA_ERROR_LEVEL_DBG if Eina is compiled with debug mode, or to @@ -520,9 +514,13 @@ EAPI Eina_Error EINA_ERROR_OUT_OF_MEMORY = 0; * #EINA_ERROR_LEVEL_INFO and #EINA_ERROR_LEVEL_DBG. That value can * also be set later with eina_error_log_level_set(). * - * If you call explicitly this function and once the error subsystem - * is not used anymore, then eina_error_shutdown() must be called to - * shut down the error system. + * This function registers the error #EINA_ERROR_OUT_OF_MEMORY. + * + * Once the error module is not used anymore, then + * eina_error_shutdown() must be called to shut down the error + * module. + * + * @see eina_init() */ EAPI int eina_error_init(void) { @@ -541,16 +539,18 @@ EAPI int eina_error_init(void) } /** - * @brief Shut down the error system. + * @brief Shut down the error module. * - * @return 0 when the error system is completely shut down, 1 or + * @return 0 when the error module is completely shut down, 1 or * greater otherwise. * - * This function shut down the error system set up by + * This function shuts down the error module set up by * eina_error_init(). It is called by eina_shutdown() and by all - * subsystems shutdown functions. It returns 0 when it is called the - * same number of times than eina_error_init() and it clears the error - * list. + * modules shutdown functions. It returns 0 when it is called the + * same number of times than eina_error_init(). In that case it clears + * the error list. + * + * @see eina_shutdown() */ EAPI int eina_error_shutdown(void) { @@ -798,7 +798,3 @@ EAPI void eina_error_log_level_set(Eina_Error_Level level) /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_file.c b/legacy/eina/src/lib/eina_file.c index a2a681e33e..c958f9eb45 100644 --- a/legacy/eina/src/lib/eina_file.c +++ b/legacy/eina/src/lib/eina_file.c @@ -71,13 +71,7 @@ void *alloca (size_t); *============================================================================*/ /** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** - * @addtogroup Eina_File_Group Memory File + * @addtogroup Eina_File_Group File * * @brief Functions to traverse directories and split paths. * @@ -279,7 +273,3 @@ eina_file_split(char *path) /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_hash.c b/legacy/eina/src/lib/eina_hash.c index 538daf1194..ac32b6cbbd 100644 --- a/legacy/eina/src/lib/eina_hash.c +++ b/legacy/eina/src/lib/eina_hash.c @@ -612,18 +612,6 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it) * API * *============================================================================*/ -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - /** * @addtogroup Eina_Hash_Group Hash Table * @@ -654,10 +642,16 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it) * * @return 1 or greater on success, 0 on error. * - * This function just sets up the error module or Eina. It is also - * called by eina_init(). It returns 0 on failure, otherwise it - * returns the number of times eina_error_init() has already been - * called. + * This function sets up the error module of Eina. It is also called + * by eina_init(). It returns 0 on failure, otherwise it returns the + * number of times it has already been called. See eina_error_init() + * for the documentation of the initialisation of the dependency + * module. + * + * When no more Eina hash tables are used, call eina_hash_shutdown() + * to shut down the array module. + * + * @see eina_error_init() */ EAPI int eina_hash_init(void) @@ -1505,11 +1499,3 @@ eina_hash_superfast(const char *key, int len) /** * @} */ - -/** - * @} - */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_inlist.c b/legacy/eina/src/lib/eina_inlist.c index 29d5900002..c9fd58f6ef 100644 --- a/legacy/eina/src/lib/eina_inlist.c +++ b/legacy/eina/src/lib/eina_inlist.c @@ -34,6 +34,10 @@ * Local * *============================================================================*/ +/** + * @cond LOCAL + */ + typedef struct _Eina_Iterator_Inlist Eina_Iterator_Inlist; typedef struct _Eina_Accessor_Inlist Eina_Accessor_Inlist; @@ -126,6 +130,11 @@ eina_inlist_accessor_free(Eina_Accessor_Inlist *it) { free(it); } +/** + * @endcond + */ + + /*============================================================================* * Global * *============================================================================*/ @@ -135,9 +144,13 @@ eina_inlist_accessor_free(Eina_Accessor_Inlist *it) { *============================================================================*/ /** - * To be documented - * FIXME: To be fixed + * @addtogroup Eina_Inline_List_Group Inline List + * + * @brief These functions provide inline list management. + * + * @{ */ + EAPI Eina_Inlist * eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l) { @@ -161,10 +174,7 @@ eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l) list->last = new_l; return list; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l) { @@ -182,10 +192,7 @@ eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l) list->last = NULL; return new_l; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_append_relative(Eina_Inlist *list, Eina_Inlist *new_l, @@ -207,10 +214,7 @@ eina_inlist_append_relative(Eina_Inlist *list, } return eina_inlist_append(list, new_l); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_prepend_relative(Eina_Inlist *list, Eina_Inlist *new_l, @@ -238,10 +242,7 @@ eina_inlist_prepend_relative(Eina_Inlist *list, } return eina_inlist_prepend(list, new_l); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item) { @@ -268,10 +269,7 @@ eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item) item->prev = NULL; return return_l; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item) { @@ -296,10 +294,7 @@ eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item) return item; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item) { @@ -331,10 +326,7 @@ eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item) l->last = item; return l; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Inlist * eina_inlist_find(Eina_Inlist *list, Eina_Inlist *item) { @@ -420,3 +412,7 @@ eina_inlist_accessor_new(const Eina_Inlist *list) return &it->accessor; } + +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_iterator.c b/legacy/eina/src/lib/eina_iterator.c index b2f7383a66..24644d0baa 100644 --- a/legacy/eina/src/lib/eina_iterator.c +++ b/legacy/eina/src/lib/eina_iterator.c @@ -57,12 +57,6 @@ * API * *============================================================================*/ -/** - * @addtogroup Eina_Content_Access_Group Content Access - * - * @{ - */ - /** * @addtogroup Eina_Iterator_Group Iterator Functions * @@ -175,7 +169,3 @@ eina_iterator_foreach(Eina_Iterator *iterator, /** * @} */ - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_list.c b/legacy/eina/src/lib/eina_list.c index 352b042baa..395bffce1e 100644 --- a/legacy/eina/src/lib/eina_list.c +++ b/legacy/eina/src/lib/eina_list.c @@ -423,7 +423,7 @@ eina_list_sort_merge(Eina_List *a, Eina_List *b, Eina_Compare_Cb func) /** * @addtogroup Eina_List_Group List * - * @brief These functions provide single linked list management. + * @brief These functions provide double linked list management. * * For more information, you can look at the @ref tutorial_list_page. * @@ -435,10 +435,25 @@ eina_list_sort_merge(Eina_List *a, Eina_List *b, Eina_Compare_Cb func) * * @return 1 or greater on success, 0 on error. * - * This function just sets up the error module or Eina. It is also - * called by eina_init(). It returns 0 on failure, otherwise it - * returns the number of times eina_error_init() has already been - * called. + * This function sets up the error, magic and mempool modules of + * Eina. It is also called by eina_init(). It returns 0 on failure, + * otherwise it returns the number of times it has already been + * called. If Eina has been configured with the default memory pool, + * then the memory pool used in an Eina list will be + * "pass_through". Otherwise, the environment variable EINA_MEMPOOL is + * read and its value is chosen as memory pool ; if EINA_MEMPOOL is + * not defined, then the "chained_mempool" memory pool is chosen. If + * the memory pool is not found, then eina_list_init() return @c 0. + * See eina_error_init(), eina_magic_string_init() and + * eina_mempool_init() for the documentation of the initialisation of + * the dependency modules. + * + * When no more Eina lists are used, call eina_list_shutdown() to shut + * down the list module. + * + * @see eina_error_init() + * @see eina_magic_string_init() + * @see eina_mempool_init() */ EAPI int eina_list_init(void) @@ -516,13 +531,13 @@ eina_list_init(void) /** * @brief Shut down the list module. * - * @return 0 when the error module is completely shut down, 1 or + * @return 0 when the list module is completely shut down, 1 or * greater otherwise. * - * This function just shut down the error module set up by - * eina_list_init(). It is also called by eina_shutdown(). It returns - * 0 when it is called the same number of times than - * eina_error_init(). + * This function shuts down the mempool, magic and error modules set + * up by eina_list_init(). It is also called by eina_shutdown(). It + * returns 0 when it is called the same number of times than + * eina_list_init(). */ EAPI int eina_list_shutdown(void) diff --git a/legacy/eina/src/lib/eina_magic.c b/legacy/eina/src/lib/eina_magic.c index bf7187b5f6..9ca2a52421 100644 --- a/legacy/eina/src/lib/eina_magic.c +++ b/legacy/eina/src/lib/eina_magic.c @@ -37,6 +37,10 @@ * Local * *============================================================================*/ +/** + * @cond LOCAL + */ + #ifdef EINA_MAGIC_DEBUG typedef struct _Eina_Magic_String Eina_Magic_String; @@ -53,6 +57,10 @@ static Eina_Inlist *strings = NULL; #endif +/** + * @endcond + */ + /*============================================================================* * Global * *============================================================================*/ @@ -61,6 +69,28 @@ static Eina_Inlist *strings = NULL; * API * *============================================================================*/ +/** + * @addtogroup Eina_Magic_Group Magic + * + * @brief These functions provide magic checks management for projects. + * + * @{ + */ + +/** + * @brief Initialize the magic module. + * + * @return 1 or greater. + * + * This function just increases a reference counter. If the magic + * module is disabled at configure time, then it always returns @c 1. + * + * Once the magic module is not used anymore, then + * eina_magic_shutdown() must be called to shut down the magic + * module. + * + * @see eina_init() + */ EAPI int eina_magic_string_init(void) { @@ -73,6 +103,21 @@ eina_magic_string_init(void) #endif } +/** + * @brief Shut down the magic module. + * + * @return 0 when the magic module is completely shut down, 1 or + * greater otherwise. + * + * This function shuts down the magic module set up by + * eina_magic_string_init(). It is called by eina_shutdown() and by + * all modules shutdown functions. It returns 0 when it is called the + * same number of times than eina_magic_string_init(). In that case it + * clears the magic list and return @c 0. If the magic module is + * disabled at configure time, then it always returns @c 0. + * + * @see eina_shutdown() + */ EAPI int eina_magic_string_shutdown(void) { @@ -102,6 +147,16 @@ eina_magic_string_shutdown(void) #ifdef EINA_MAGIC_DEBUG +/** + * @brief Return the string associated to the given magic identifier. + * + * @param magic The magic identifier. + * @return The string associated to the identifier. + * + * This function returns the string associated to @p magic. If none + * are found, the this function returns @c NULL. The returned value + * must not be freed. + */ EAPI const char* eina_magic_string_get(Eina_Magic magic) { @@ -114,6 +169,17 @@ eina_magic_string_get(Eina_Magic magic) return NULL; } +/** + * @brief Set the string associated to the given magic identifier. + * + * @param magic The magic identifier. + * @param The string associated to the identifier. + * + * This function sets the string @p magic_name to @p magic. If a + * string is already associated to @p magic, then it is freed and @p + * magic_name is duplicated. Otherwise, it is added to the list of + * magic strings. + */ EAPI void eina_magic_string_set(Eina_Magic magic, const char *magic_name) { @@ -131,6 +197,8 @@ eina_magic_string_set(Eina_Magic magic, const char *magic_name) } ems = malloc(sizeof (Eina_Magic_String)); + if (!ems) + return; ems->magic = magic; if (magic_name) ems->string = strdup(magic_name); @@ -140,6 +208,29 @@ eina_magic_string_set(Eina_Magic magic, const char *magic_name) strings = eina_inlist_prepend(strings, EINA_INLIST_GET(ems)); } +/** + * @brief Display a message or abort is a magic check failed. + * + * @param d The checked data pointer. + * @param m The magic identifer to check. + * @param req_m The requested magic identifier to check. + * @param file The file in which the magic check failed. + * @param fcn The function in which the magic check failed. + * @param line The line at which the magic check failed. + * + * This function displays an error message if a magic check has + * failed, using the following logic in the following order: + * @li If @p d is @c NULL, a message warns about a @c NULL pointer. + * @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message + * warns about a handle that was already freed. + * @li Otherwise, if @p m is equal to @p req_m, a message warns about + * a handle that is of wrong type. + * @li Otherwise, a message warns you about ab-using that function... + * + * If the environment variable EINA_ERROR_ABORT is set, abort() is + * called and the program stops. It is useful for debugging programs + * with gdb. + */ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line) { @@ -185,3 +276,7 @@ eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const } #endif + +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_main.c b/legacy/eina/src/lib/eina_main.c index cec96bc50d..756f43977a 100644 --- a/legacy/eina/src/lib/eina_main.c +++ b/legacy/eina/src/lib/eina_main.c @@ -34,6 +34,20 @@ #include "eina_magic.h" #include "eina_rectangle.h" +/*============================================================================* + * Local * + *============================================================================*/ + +/** + * @cond LOCAL + */ + +static int _eina_main_count = 0; + +/** + * @endcond + */ + /*============================================================================* * Global * *============================================================================*/ @@ -42,8 +56,28 @@ * API * *============================================================================*/ -static int _eina_main_count = 0; +/** + * @addtogroup Eina_Main_Group Main + * + * @brief These functions provide general initialisation and shut down + * functions. + * + * @{ + */ +/** + * @brief Initialize the Eina library. + * + * @return 1 or greater on success, 0 on error. + * + * This function sets up all the eina modules. It returns 0 on + * failure (that is, when one of the module fails to initialize), + * otherwise it returns the number of times it has already been + * called. + * + * When Eina is not used anymore, call eina_shutdown() to shut down + * the Eina library. + */ EAPI int eina_init(void) { @@ -117,6 +151,20 @@ eina_init(void) return 0; } +/** + * @brief Shut down the Eina library. + * + * @return 0 when all the modules is completely shut down, 1 or + * greater otherwise. + * + * This function shuts down the Eina library. It returns 0 when it has + * been called the same number of times than eina_init(). In that case + * it shut down all the Eina modules. + * + * Once this function succeeds (that is, @c 0 is returned), you must + * not call any of the Eina function anymore. You must call + * eina_init() again to use the Eina functions again. + */ EAPI int eina_shutdown(void) { @@ -136,3 +184,6 @@ eina_shutdown(void) return --_eina_main_count; } +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_mempool.c b/legacy/eina/src/lib/eina_mempool.c index c28ec25b06..c495e1329a 100644 --- a/legacy/eina/src/lib/eina_mempool.c +++ b/legacy/eina/src/lib/eina_mempool.c @@ -35,6 +35,10 @@ * Local * *============================================================================*/ +/** + * @cond LOCAL + */ + static Eina_Hash *_backends; static Eina_Array *_modules; static int _init_count = 0; @@ -93,6 +97,10 @@ Eina_Bool fixed_bitmap_init(void); void fixed_bitmap_shutdown(void); #endif +/** + * @endcond + */ + /*============================================================================* * Global * *============================================================================*/ @@ -111,11 +119,16 @@ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) * API * *============================================================================*/ +/** + * @addtogroup Eina_Memory_Pool_Group Memory Pool + * + * @brief These functions provide memory pool management. + * + * @{ + */ + EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0; -/** - * - */ EAPI int eina_mempool_init(void) { @@ -184,9 +197,6 @@ eina_mempool_init(void) } -/** - * - */ EAPI int eina_mempool_shutdown(void) { @@ -220,9 +230,6 @@ eina_mempool_shutdown(void) return 0; } -/** - * - */ EAPI Eina_Mempool * eina_mempool_new(const char *name, const char *context, const char *options, ...) { @@ -238,9 +245,6 @@ eina_mempool_new(const char *name, const char *context, const char *options, ... return mp; } -/** - * - */ EAPI void eina_mempool_delete(Eina_Mempool *mp) { EINA_SAFETY_ON_NULL_RETURN(mp); @@ -262,3 +266,7 @@ EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_SAFETY_ON_NULL_RETURN(mp->backend.statistics); mp->backend.statistics(mp->backend_data); } + +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_module.c b/legacy/eina/src/lib/eina_module.c index 9398ebe2b6..2ae4902bc4 100644 --- a/legacy/eina/src/lib/eina_module.c +++ b/legacy/eina/src/lib/eina_module.c @@ -158,9 +158,13 @@ static int _eina_module_count = 0; *============================================================================*/ /** - * To be documented - * FIXME: To be fixed + * @addtogroup Eina_Module_Group Module + * + * @brief These functions provide module management. + * + * @{ */ + EAPI int eina_module_init(void) { @@ -177,10 +181,7 @@ eina_module_init(void) end_init: return _eina_module_count; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI int eina_module_shutdown(void) { @@ -197,10 +198,7 @@ eina_module_shutdown(void) end_shutdown: return _eina_module_count; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Bool eina_module_load(Eina_Module *m) { void *dl_handle; @@ -236,10 +234,7 @@ loaded: eina_error_set(0); return EINA_TRUE; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Bool eina_module_unload(Eina_Module *m) { Eina_Module_Shutdown *shut; @@ -257,10 +252,7 @@ EAPI Eina_Bool eina_module_unload(Eina_Module *m) } return EINA_FALSE; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Module * eina_module_new(const char *file) { Eina_Module *m; @@ -276,10 +268,7 @@ EAPI Eina_Module * eina_module_new(const char *file) return m; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Bool eina_module_delete(Eina_Module *m) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE); @@ -293,20 +282,14 @@ EAPI Eina_Bool eina_module_delete(Eina_Module *m) free(m); return EINA_TRUE; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void * eina_module_symbol_get(Eina_Module *m, const char *symbol) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); EINA_SAFETY_ON_NULL_RETURN_VAL(m->handle, NULL); return dlsym(m->handle, symbol); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI const char * eina_module_file_get(Eina_Module *m) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); @@ -408,6 +391,7 @@ EAPI Eina_Array * eina_module_list_get(Eina_Array *array, const char *path, unsi return list_get_cb_data.array; } + /** * Load every module on the list of modules * @param list The list of modules @@ -423,10 +407,7 @@ EAPI void eina_module_list_load(Eina_Array *array) EINA_ARRAY_ITER_NEXT(array, i, m, iterator) eina_module_load(m); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void eina_module_list_unload(Eina_Array *array) { Eina_Array_Iterator iterator; @@ -438,6 +419,7 @@ EAPI void eina_module_list_unload(Eina_Array *array) EINA_ARRAY_ITER_NEXT(array, i, m, iterator) eina_module_unload(m); } + /** * Helper function that iterates over the list of modules and calls * eina_module_delete on each @@ -455,3 +437,7 @@ EAPI void eina_module_list_delete(Eina_Array *array) eina_array_flush(array); } + +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_stringshare.c b/legacy/eina/src/lib/eina_stringshare.c index a165768bcb..5e3c62af13 100644 --- a/legacy/eina/src/lib/eina_stringshare.c +++ b/legacy/eina/src/lib/eina_stringshare.c @@ -776,12 +776,6 @@ _eina_stringshare_node_alloc(int slen) * API * *============================================================================*/ -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - /** * @addtogroup Eina_Stringshare_Group Stringshare * @@ -1293,7 +1287,3 @@ eina_stringshare_dump(void) /** * @} */ - -/** - * @} - */