From: caro Date: Sun, 27 Dec 2009 08:45:30 +0000 (+0000) Subject: * finish benchmark tutorial X-Git-Tag: 2.0_alpha~70^2~718 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=676e2793222350142d1001440c0a65ae5cc1a44a;p=framework%2Fuifw%2Feina.git * finish benchmark tutorial * move internal _init and _shutdown functions in the Global part of the code, as it is where they belong * fix minor documentation stuff git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@44730 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- diff --git a/src/include/eina_inlist.h b/src/include/eina_inlist.h index 833d539..635cae1 100644 --- a/src/include/eina_inlist.h +++ b/src/include/eina_inlist.h @@ -42,12 +42,21 @@ * @{ */ +/** + * @typedef Eina_Inlist + * Inlined list type. + */ typedef struct _Eina_Inlist Eina_Inlist; + +/** + * @struct _Eina_Inlist + * Inlined list type. + */ struct _Eina_Inlist { - Eina_Inlist *next; - Eina_Inlist *prev; - Eina_Inlist *last; + Eina_Inlist *next; /**< next node */ + Eina_Inlist *prev; /**< previous node */ + Eina_Inlist *last; /**< last node */ }; #define EINA_INLIST Eina_Inlist __in_list diff --git a/src/include/eina_iterator.h b/src/include/eina_iterator.h index 71605ec..68c5faf 100644 --- a/src/include/eina_iterator.h +++ b/src/include/eina_iterator.h @@ -74,7 +74,7 @@ EAPI void eina_iterator_foreach (Eina_Iterator *iterator, * @def EINA_ITERATOR_FOREACH * @brief Macro to iterate over all elements easily. * - * @param iterator The iterator to use. + * @param itr The iterator to use. * @param data Where to store * data, must be a pointer support getting * its address since * eina_iterator_next() requires a pointer * to pointer! diff --git a/src/include/eina_list.h b/src/include/eina_list.h index d99fa18..5088c44 100644 --- a/src/include/eina_list.h +++ b/src/include/eina_list.h @@ -63,7 +63,7 @@ struct _Eina_List /** A linked list node */ void *data; /**< Pointer to list element payload */ Eina_List *next; /**< Next member in the list */ Eina_List *prev; /**< Previous member in the list */ - struct _Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */ + Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */ EINA_MAGIC }; diff --git a/src/include/eina_log.h b/src/include/eina_log.h index 0b481ee..1cd4b2a 100644 --- a/src/include/eina_log.h +++ b/src/include/eina_log.h @@ -152,16 +152,24 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; #define EINA_LOG_DBG(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_DBG, fmt, ##__VA_ARGS__) +/** + * @typedef Eina_Log_Domain + * The domain used for logging. + */ typedef struct _Eina_Log_Domain Eina_Log_Domain; +/** + * @struct _Eina_Log_Domain + * The domain used for logging. + */ struct _Eina_Log_Domain { - int level; /**< Max level to log */ + int level; /**< Max level to log */ const char *domain_str; /**< Formatted string with color to print */ const char *name; /**< Domain name */ /* Private */ - Eina_Bool deleted:1; /**< Flags deletion of domain, a free slot */ + Eina_Bool deleted:1; /**< Flags deletion of domain, a free slot */ }; EAPI void eina_log_threads_enable(void); diff --git a/src/include/eina_tiler.h b/src/include/eina_tiler.h index 1a04a9c..f94c559 100644 --- a/src/include/eina_tiler.h +++ b/src/include/eina_tiler.h @@ -23,16 +23,42 @@ #include "eina_iterator.h" #include "eina_rectangle.h" +/** + * @addtogroup Eina_Data_Types_Group Data Types + * + * @{ + */ + +/** + * @defgroup Eina_Tiler_Group Tiler + * + * @{ + */ + +/** + * @typedef Eina_Tiler + * Tiler type. + */ typedef struct _Eina_Tiler Eina_Tiler; +/** + * @typedef Eina_Tile_Grid_Info + * Grid type of a tiler. + */ +typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info; + +/** + * @struct Eina_Tile_Grid_Info + * Grid type of a tiler. + */ struct Eina_Tile_Grid_Info { - unsigned long col, row; - Eina_Rectangle rect; - Eina_Bool full; + unsigned long col; /**< column of the tiler grid */ + unsigned long row; /**< row of the tiler grid*/ + Eina_Rectangle rect; /**< rectangle of the tiler grid*/ + Eina_Bool full; /**< whether the grid is full or not */ }; -typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info; typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer; EAPI Eina_Tiler *eina_tiler_new(int w, int h); @@ -48,4 +74,13 @@ static inline Eina_Bool eina_tile_grid_slicer_setup(Eina_Tile_Grid_Slicer *slc, #include "eina_inline_tiler.x" + +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_TILER_H_ */ diff --git a/src/include/eina_types.h b/src/include/eina_types.h index 9a2b2ab..60f0751 100644 --- a/src/include/eina_types.h +++ b/src/include/eina_types.h @@ -184,8 +184,23 @@ # define EINA_LIKELY(exp) exp #else /* ! __GNUC__ && ! _WIN32 && ! __SUNPRO_C */ + +/** + * @def EINA_WARN_UNUSED_RESULT + * Used to warn when the returned value of the function is not used. + */ # define EINA_WARN_UNUSED_RESULT + +/** + * @def EINA_ARG_NONNULL + * Used to warn when the specified arguments of the function are @c NULL. + */ # define EINA_ARG_NONNULL(idx, ...) + +/** + * @def EINA_DEPRECATED + * Used to warn when the function is considered as deprecated. + */ # define EINA_DEPRECATED # define EINA_MALLOC # define EINA_PURE @@ -201,14 +216,24 @@ /* remove this TRUE/FALSE redifinitions */ +/** + * @deprecated Use #EINA_TRUE instead. + */ #ifndef TRUE # define TRUE 1 #endif +/** + * @deprecated Use #EINA_FALSE instead. + */ #ifndef FALSE # define FALSE 0 #endif +/** + * @typedef Eina_Bool + * Type to mimic a boolean. + */ typedef unsigned char Eina_Bool; /** @@ -228,15 +253,41 @@ EAPI extern const unsigned int eina_prime_table[]; #define EINA_SORT_MIN 0 #define EINA_SORT_MAX 1 +/** + * @typedef Eina_Compare_Cb + * Function used in functions using sorting. It compares @p data1 and + * @p data2. If @p data1 is 'less' than @p data2, -1 must be returned, + * if it is 'greater', 1 must be returned, and if they are equal, 0 + * must be returned. + */ typedef int (*Eina_Compare_Cb) (const void *data1, const void *data2); + +/** + * @def EINA_COMPARE_CB + * Macro to cast to Eina_Compare_Cb. + */ #define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function) typedef Eina_Bool (*Eina_Each)(const void *container, void *data, void *fdata); + +/** + * @def EINA_EACH + * Macro to cast to Eina_Each. + */ #define EINA_EACH(Function) ((Eina_Each)Function) +/** + * @typedef Eina_Free_Cb + * A callback type used to free data when iterating over a container. + */ typedef void (*Eina_Free_Cb)(void *data); + +/** + * @def EINA_FREE_CB + * Macro to cast to Eina_Free_Cb. + */ #define EINA_FREE_CB(Function) ((Eina_Free_Cb)Function) /** diff --git a/src/lib/eina_accessor.c b/src/lib/eina_accessor.c index 0e1b71e..9eaea04 100644 --- a/src/lib/eina_accessor.c +++ b/src/lib/eina_accessor.c @@ -56,30 +56,6 @@ static const char EINA_MAGIC_ACCESSOR_STR[] = "Eina Accessor"; * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Accessor_Group Accessor Functions - * - * @brief These functions manage accessor on containers. - * - * These functions allow to access elements of a container in a - * generic way, without knowing which container is used (a bit like - * iterators in the C++ STL). Accessors allows random access (that is, any - * element in the container). For sequential access, see - * @ref Eina_Iterator_Group. - * - * An accessor is created from container data types, so no creation - * function is available here. An accessor is deleted with - * eina_accessor_free(). To get the data of an element at a given - * position, use eina_accessor_data_get(). To call a function on - * chosen elements of a container, use eina_accessor_over(). - * - * @{ - */ - /** * @internal * @brief Initialize the accessor module. @@ -114,6 +90,30 @@ eina_accessor_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Accessor_Group Accessor Functions + * + * @brief These functions manage accessor on containers. + * + * These functions allow to access elements of a container in a + * generic way, without knowing which container is used (a bit like + * iterators in the C++ STL). Accessors allows random access (that is, any + * element in the container). For sequential access, see + * @ref Eina_Iterator_Group. + * + * An accessor is created from container data types, so no creation + * function is available here. An accessor is deleted with + * eina_accessor_free(). To get the data of an element at a given + * position, use eina_accessor_data_get(). To call a function on + * chosen elements of a container, use eina_accessor_over(). + * + * @{ + */ + /** * @brief Free an accessor. * diff --git a/src/lib/eina_array.c b/src/lib/eina_array.c index 040ffbd..f03e29d 100644 --- a/src/lib/eina_array.c +++ b/src/lib/eina_array.c @@ -287,48 +287,6 @@ eina_array_grow(Eina_Array *array) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Array_Group Array - * - * @brief These functions provide array management. - * - * The Array data type in Eina is designed to have a very fast access to - * its data (compared to the Eina @ref Eina_List_Group). On the other hand, - * data can be added or removed only at the end of the array. To insert - * data at any place, the Eina @ref Eina_List_Group is the correct container - * to use. - * - * To use the array data type, eina_init() must be called before any - * other array functions. When eina is no more array function is used, - * eina_shutdown() must be called to free all the resources. - * - * An array must be created with eina_array_new(). It allocated all - * the necessary data for an array. When not needed anymore, an array - * is freed with eina_array_free(). This function does not free any - * allocated memory used to store the data of each element. For that, - * just iterate over the array to free them. A convenient way to do - * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given - * in the description of this macro. - * - * @warning All the other functions do not check if the used array is - * valid or not. It's up to the user to be sure of that. It is - * designed like that for performance reasons. - * - * The usual features of an array are classic ones: to append an - * element, use eina_array_push() and to remove the last element, use - * eina_array_pop(). To retrieve the element at a given positin, use - * eina_array_data_get(). The number of elements can be retrieved with - * eina_array_count_get(). - * - * For more information, you can look at the @ref tutorial_array_page. - * - * @{ - */ - /** * @internal * @brief Initialize the array module. @@ -377,6 +335,48 @@ eina_array_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Array_Group Array + * + * @brief These functions provide array management. + * + * The Array data type in Eina is designed to have a very fast access to + * its data (compared to the Eina @ref Eina_List_Group). On the other hand, + * data can be added or removed only at the end of the array. To insert + * data at any place, the Eina @ref Eina_List_Group is the correct container + * to use. + * + * To use the array data type, eina_init() must be called before any + * other array functions. When eina is no more array function is used, + * eina_shutdown() must be called to free all the resources. + * + * An array must be created with eina_array_new(). It allocated all + * the necessary data for an array. When not needed anymore, an array + * is freed with eina_array_free(). This function does not free any + * allocated memory used to store the data of each element. For that, + * just iterate over the array to free them. A convenient way to do + * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given + * in the description of this macro. + * + * @warning All the other functions do not check if the used array is + * valid or not. It's up to the user to be sure of that. It is + * designed like that for performance reasons. + * + * The usual features of an array are classic ones: to append an + * element, use eina_array_push() and to remove the last element, use + * eina_array_pop(). To retrieve the element at a given positin, use + * eina_array_data_get(). The number of elements can be retrieved with + * eina_array_count_get(). + * + * For more information, you can look at the @ref tutorial_array_page. + * + * @{ + */ + /** * @brief Create a new array. * diff --git a/src/lib/eina_benchmark.c b/src/lib/eina_benchmark.c index 6dda351..482346a 100644 --- a/src/lib/eina_benchmark.c +++ b/src/lib/eina_benchmark.c @@ -37,7 +37,7 @@ * @li Run the benchmark. * @li Free the memory. * - * Here is a basic example which bechmark which creates two functions + * Here is a basic example of bechmark which creates two functions * that will be run. These functions just print a message. * * @code @@ -129,7 +129,7 @@ * last 3 values passed to eina_benchmark_register(). See the document * of that function for the detailed behavior. * - * The Gnuplot file will be named bench_test_run.gnuplot. Just run: + * The gnuplot file will be named bench_test_run.gnuplot. Just run: * * @code * gnuplot bench_test_run.gnuplot @@ -141,9 +141,173 @@ * @section tutorial_benchmark_advanced_usage More Advanced Usage * * In this section, several test will be created and run. The idea is - * exactly the same than in the previous section. + * exactly the same than in the previous section, but with some basic + * automatic way to run all the benchmarks. The following code + * benchmarks some Eina converts functions, and some Eina containers + * types: * - * to be done. + * @code + * #include + * #include + * #include + * + * #include + * + * static void bench_convert(Eina_Benchmark *bench); + * static void bench_container(Eina_Benchmark *bench); + * + * typedef struct _Benchmark_Case Benchmark_Case; + * + * struct _Benchmark_Case + * { + * const char *bench_case; + * void (*build)(Eina_Benchmark *bench); + * }; + * + * static const Benchmark_Case benchmarks[] = { + * { "Bench 1", bench_convert }, + * { "Bench 2", bench_container }, + * { NULL, NULL } + * }; + * + * static + * void convert1(int request) + * { + * char tmp[128]; + * int i; + * + * srand(time(NULL)); + * + * for (i = 0; i < request; ++i) + * eina_convert_itoa(rand(), tmp); + * } + * + * static + * void convert2(int request) + * { + * char tmp[128]; + * int i; + * + * srand(time(NULL)); + * + * for (i = 0; i < request; ++i) + * eina_convert_xtoa(rand(), tmp); + * } + * + * static void + * bench_convert(Eina_Benchmark *bench) + * { + * eina_benchmark_register(bench, "convert-1", EINA_BENCHMARK(convert1), 200, 400, 10); + * eina_benchmark_register(bench, "convert-2", EINA_BENCHMARK(convert2), 200, 400, 10); + * } + * + * static + * void array(int request) + * { + * Eina_Array *array; + * Eina_Array_Iterator it; + * int *data; + * int i; + * + * srand(time(NULL)); + * + * array = eina_array_new(64); + * + * for (i = 0; i < request; ++i) + * { + * data = (int *)malloc(sizeof(int)); + * if (!data) continue; + * *data = rand(); + * eina_array_push(array, data); + * } + * + * EINA_ARRAY_ITER_NEXT(array, i, data, it) + * free(data); + * + * eina_array_free(array); + * } + * + * static + * void list(int request) + * { + * Eina_List *l = NULL; + * int *data; + * int i; + * + * srand(time(NULL)); + * + * for (i = 0; i < request; ++i) + * { + * data = (int *)malloc(sizeof(int)); + * if (!data) continue; + * *data = rand(); + * l = eina_list_prepend(l, data); + * } + * + * while (l) + * { + * free(eina_list_data_get(l)); + * l = eina_list_remove_list(l, l); + * } + * } + * + * static void + * bench_container(Eina_Benchmark *bench) + * { + * eina_benchmark_register(bench, "array", EINA_BENCHMARK(array), 200, 300, 10); + * eina_benchmark_register(bench, "list", EINA_BENCHMARK(list), 200, 300, 10); + * } + * + * int main() + * { + * Eina_Benchmark *test; + * Eina_Array *ea; + * unsigned int i; + * + * if (!eina_init()) + * return EXIT_FAILURE; + * + * for (i = 0; benchmarks[i].bench_case != NULL; ++i) + * { + * test = eina_benchmark_new(benchmarks[i].bench_case, "Benchmark example"); + * if (!test) + * continue; + * + * benchmarks[i].build(test); + * + * ea = eina_benchmark_run(test); + * if(ea) + * { + * Eina_Array_Iterator it; + * char *tmp; + * unsigned int i; + * + * EINA_ARRAY_ITER_NEXT(ea, i, tmp, it) + * free(tmp); + * + * eina_array_free(ea); + * } + * + * if (test) + * eina_benchmark_free(test); + * } + * + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * gnuplot can be used to see how are performed the convert functions + * together, as well as how are performed the containers. So it is now + * easy to see that the hexadecimal convert function is faster than + * the decimal one, and that arrays are faster than lists. + * + * You can improve all that by executing automatically gnuplot in your + * program, or integrate the Eina benchmark framework in an autotooled + * project. See that + * page + * for more informations. * */ @@ -234,37 +398,6 @@ static int _eina_benchmark_log_dom = -1; * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Benchmark_Group Benchmark - * - * These functions allow you to add benchmark framework in a project - * for timing critical part and detect slow parts of code. It is used - * in Eina to compare the time used by eina, glib, evas and ecore data - * types. - * - * To use the benchmark module, Eina must be initialized with - * eina_init() and later shut down with eina_shutdown(). A benchmark - * is created with eina_benchmark_new() and freed with - * eina_benchmark_free(). - * - * eina_benchmark_register() adds a test to a benchmark. That test can - * be run a certain amount of times. Adding more than one test to be - * executed allows the comparison between several parts of a program, - * or different implementations. - * - * eina_benchmark_run() runs all the tests registered with - * eina_benchmark_register(). The amount of time of each test is - * written in a gnuplot file. - * - * For more information, you can look at the @ref tutorial_benchmark_page. - * - * @{ - */ - /** * @internal * @brief Initialize the benchmark module. @@ -308,6 +441,37 @@ eina_benchmark_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Benchmark_Group Benchmark + * + * These functions allow you to add benchmark framework in a project + * for timing critical part and detect slow parts of code. It is used + * in Eina to compare the time used by eina, glib, evas and ecore data + * types. + * + * To use the benchmark module, Eina must be initialized with + * eina_init() and later shut down with eina_shutdown(). A benchmark + * is created with eina_benchmark_new() and freed with + * eina_benchmark_free(). + * + * eina_benchmark_register() adds a test to a benchmark. That test can + * be run a certain amount of times. Adding more than one test to be + * executed allows the comparison between several parts of a program, + * or different implementations. + * + * eina_benchmark_run() runs all the tests registered with + * eina_benchmark_register(). The amount of time of each test is + * written in a gnuplot file. + * + * For more information, you can look at the @ref tutorial_benchmark_page. + * + * @{ + */ + /** * @brief Create a new array. * diff --git a/src/lib/eina_convert.c b/src/lib/eina_convert.c index a608051..581bb0f 100644 --- a/src/lib/eina_convert.c +++ b/src/lib/eina_convert.c @@ -84,10 +84,6 @@ static inline void reverse(char s[], int length) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - /** * @cond LOCAL */ @@ -105,6 +101,64 @@ static const char EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH_STR[] = "Error outrun */ /** + * @internal + * @brief Initialize the convert module. + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function sets up the convert module of Eina. It is called by + * eina_init(). + * + * This function sets up the error module of Eina and registers the + * errors #EINA_ERROR_CONVERT_0X_NOT_FOUND, + * #EINA_ERROR_CONVERT_P_NOT_FOUND and + * #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH. + * + * @see eina_init() + */ +Eina_Bool +eina_convert_init(void) +{ + _eina_convert_log_dom = eina_log_domain_register("eina_convert", EINA_LOG_COLOR_DEFAULT); + if (_eina_convert_log_dom < 0) + { + EINA_LOG_ERR("Could not register log domain: eina_convert"); + return EINA_FALSE; + } + +#define EEMR(n) n = eina_error_msg_static_register(n##_STR) + EEMR(EINA_ERROR_CONVERT_0X_NOT_FOUND); + EEMR(EINA_ERROR_CONVERT_P_NOT_FOUND); + EEMR(EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH); +#undef EEMR + + return EINA_TRUE; +} + +/** + * @internal + * @brief Shut down the convert module. + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function shuts down the convert module set up by + * eina_convert_init(). It is called by eina_shutdown(). + * + * @see eina_shutdown() + */ +Eina_Bool +eina_convert_shutdown(void) +{ + eina_log_domain_unregister(_eina_convert_log_dom); + _eina_convert_log_dom = -1; + return EINA_TRUE; +} + +/*============================================================================* + * API * + *============================================================================*/ + +/** * @addtogroup Eina_Convert_Group Convert * * These functions allow you to convert integer or real numbers to @@ -222,60 +276,6 @@ static const char EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH_STR[] = "Error outrun * @{ */ -/** - * @internal - * @brief Initialize the convert module. - * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function sets up the convert module of Eina. It is called by - * eina_init(). - * - * This function sets up the error module of Eina and registers the - * errors #EINA_ERROR_CONVERT_0X_NOT_FOUND, - * #EINA_ERROR_CONVERT_P_NOT_FOUND and - * #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH. - * - * @see eina_init() - */ -Eina_Bool -eina_convert_init(void) -{ - _eina_convert_log_dom = eina_log_domain_register("eina_convert", EINA_LOG_COLOR_DEFAULT); - if (_eina_convert_log_dom < 0) - { - EINA_LOG_ERR("Could not register log domain: eina_convert"); - return EINA_FALSE; - } - -#define EEMR(n) n = eina_error_msg_static_register(n##_STR) - EEMR(EINA_ERROR_CONVERT_0X_NOT_FOUND); - EEMR(EINA_ERROR_CONVERT_P_NOT_FOUND); - EEMR(EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH); -#undef EEMR - - return EINA_TRUE; -} - -/** - * @internal - * @brief Shut down the convert module. - * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function shuts down the convert module set up by - * eina_convert_init(). It is called by eina_shutdown(). - * - * @see eina_shutdown() - */ -Eina_Bool -eina_convert_shutdown(void) -{ - eina_log_domain_unregister(_eina_convert_log_dom); - _eina_convert_log_dom = -1; - return EINA_TRUE; -} - /* * Come from the second edition of The C Programming Language ("K&R2") on page 64 */ @@ -581,7 +581,7 @@ eina_convert_dtoa(double d, char *des) * @param des The destination buffer to store the converted fixed point number. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * - * This function converts the 32.32 fixed point number @fp to a + * This function converts the 32.32 fixed point number @p fp to a * string. The string is stored in the buffer pointed by @p des and * must be sufficiently large to contain the converted fixed point * number. The returned string is terminated and has the following diff --git a/src/lib/eina_counter.c b/src/lib/eina_counter.c index a6bbaf6..9dabf90 100644 --- a/src/lib/eina_counter.c +++ b/src/lib/eina_counter.c @@ -144,6 +144,54 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...) * Global * *============================================================================*/ +/** + * @internal + * @brief Initialize the eina counter internal structure. + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function shuts down the counter module set up by + * eina_counter_init(). It is called by eina_init(). + * + * 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_ERROR_COUNTER_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. + * + * @see eina_init() + */ +Eina_Bool +eina_counter_init(void) +{ +#ifdef _WIN32 + EINA_ERROR_COUNTER_WINDOWS = eina_error_msg_static_register(EINA_ERROR_COUNTER_WINDOWS_STR); + if (!QueryPerformanceFrequency(&_eina_counter_frequency)) + { + eina_error_set(EINA_ERROR_COUNTER_WINDOWS); + return EINA_FALSE; + } +#endif /* _WIN2 */ + return EINA_TRUE; +} + +/** + * @internal + * @brief Shut down the counter module. + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function shuts down the counter module set up by + * eina_counter_init(). It is called by eina_shutdown(). + * + * @see eina_shutdown() + */ +Eina_Bool +eina_counter_shutdown(void) +{ + return EINA_TRUE; +} + /*============================================================================* * API * *============================================================================*/ @@ -230,54 +278,6 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...) */ /** - * @internal - * @brief Initialize the eina counter internal structure. - * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function shuts down the counter module set up by - * eina_counter_init(). It is called by eina_init(). - * - * 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_ERROR_COUNTER_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. - * - * @see eina_init() - */ -Eina_Bool -eina_counter_init(void) -{ -#ifdef _WIN32 - EINA_ERROR_COUNTER_WINDOWS = eina_error_msg_static_register(EINA_ERROR_COUNTER_WINDOWS_STR); - if (!QueryPerformanceFrequency(&_eina_counter_frequency)) - { - eina_error_set(EINA_ERROR_COUNTER_WINDOWS); - return EINA_FALSE; - } -#endif /* _WIN2 */ - return EINA_TRUE; -} - -/** - * @internal - * @brief Shut down the counter module. - * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function shuts down the counter module set up by - * eina_counter_init(). It is called by eina_shutdown(). - * - * @see eina_shutdown() - */ -Eina_Bool -eina_counter_shutdown(void) -{ - return EINA_TRUE; -} - -/** * @brief Return a counter. * * @param name The name of the counter. diff --git a/src/lib/eina_error.c b/src/lib/eina_error.c index d2af26b..408a556 100644 --- a/src/lib/eina_error.c +++ b/src/lib/eina_error.c @@ -216,27 +216,6 @@ _eina_error_msg_alloc(void) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Error_Group Error - * - * @brief These functions provide error management for projects. - * - * To use the error system Eina must be initialized with eina_init() - * and later shut down with eina_shutdown(). Error codes are - * registered with eina_error_msg_register() and converted from - * identifier to original message string with eina_error_msg_get(). - * - * Logging functions are not in eina_error anymore, see - * eina_log_print() instead. - * - * @{ - */ - - /** * @cond LOCAL */ @@ -301,6 +280,26 @@ eina_error_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Error_Group Error + * + * @brief These functions provide error management for projects. + * + * To use the error system Eina must be initialized with eina_init() + * and later shut down with eina_shutdown(). Error codes are + * registered with eina_error_msg_register() and converted from + * identifier to original message string with eina_error_msg_get(). + * + * Logging functions are not in eina_error anymore, see + * eina_log_print() instead. + * + * @{ + */ + /** * @brief Register a new error type. * diff --git a/src/lib/eina_iterator.c b/src/lib/eina_iterator.c index 7bec398..6e42720 100644 --- a/src/lib/eina_iterator.c +++ b/src/lib/eina_iterator.c @@ -57,30 +57,6 @@ static const char EINA_MAGIC_ITERATOR_STR[] = "Eina Iterator"; * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Iterator_Group Iterator Functions - * - * @brief These functions manage iterators on containers. - * - * These functions allow to access elements of a container in a - * generic way, without knowing which container is used (a bit like - * iterators in the C++ STL). Iterators only allows sequential access - * (that is, from an element to the next one). For random access, see - * @ref Eina_Accessor_Group. - * - * An iterator is created from container data types, so no creation - * function is available here. An iterator is deleted with - * eina_iterator_free(). To get the data and iterate, use - * eina_iterator_next(). To call a function on all the elements of a - * container, use eina_iterator_foreach(). - * - * @{ - */ - /** * @internal * @brief Initialize the iterator module. @@ -115,6 +91,30 @@ eina_iterator_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Iterator_Group Iterator Functions + * + * @brief These functions manage iterators on containers. + * + * These functions allow to access elements of a container in a + * generic way, without knowing which container is used (a bit like + * iterators in the C++ STL). Iterators only allows sequential access + * (that is, from an element to the next one). For random access, see + * @ref Eina_Accessor_Group. + * + * An iterator is created from container data types, so no creation + * function is available here. An iterator is deleted with + * eina_iterator_free(). To get the data and iterate, use + * eina_iterator_next(). To call a function on all the elements of a + * container, use eina_iterator_foreach(). + * + * @{ + */ + /** * @brief Free an iterator. * diff --git a/src/lib/eina_list.c b/src/lib/eina_list.c index 12aa0b6..b6651c6 100644 --- a/src/lib/eina_list.c +++ b/src/lib/eina_list.c @@ -436,20 +436,6 @@ eina_list_sort_merge(Eina_List *a, Eina_List *b, Eina_Compare_Cb func) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_List_Group List - * - * @brief These functions provide double linked list management. - * - * For more information, you can look at the @ref tutorial_list_page. - * - * @{ - */ - /** * @internal * @brief Initialize the list module. @@ -539,6 +525,20 @@ eina_list_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_List_Group List + * + * @brief These functions provide double linked list management. + * + * For more information, you can look at the @ref tutorial_list_page. + * + * @{ + */ + /** * @brief Append the given data to the given linked list. * @@ -848,6 +848,7 @@ eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *re * @brief Insert a new node into a sorted list. * * @param list The given linked list, @b must be sorted. + * @param func The function called for the sort. * @param data The data to insert sorted. * @return A list pointer. * @@ -857,7 +858,7 @@ eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *re * used in place of the one given to this function is * returned. Otherwise, the old pointer is returned. See eina_error_get(). * - * @note O(log2(n)) comparisons (calls to func) average/worst case + * @note O(log2(n)) comparisons (calls to @p func) average/worst case * performance as it uses eina_list_search_sorted_near_list() and thus * is bounded to that. As said in eina_list_search_sorted_near_list(), * lists do not have O(1) access time, so walking to the correct node diff --git a/src/lib/eina_log.c b/src/lib/eina_log.c index f620338..1f91ba1 100644 --- a/src/lib/eina_log.c +++ b/src/lib/eina_log.c @@ -857,94 +857,87 @@ eina_log_domain_parse_pending_globs(void) } } -/** - * @endcond - */ +static inline int +eina_log_domain_register_unlocked(const char *name, const char *color) +{ + Eina_Log_Domain_Level_Pending *pending = NULL; + int i; + for (i = 0; i < _log_domains_count; i++) + { + if (_log_domains[i].deleted) + { + // Found a flagged slot, free domain_str and replace slot + eina_log_domain_new(&_log_domains[i], name, color); + goto finish_register; + } + } -/*============================================================================* - * Global * - *============================================================================*/ + if (_log_domains_count >= _log_domains_allocated) + { + Eina_Log_Domain *tmp; + size_t size; -/*============================================================================* - * API * - *============================================================================*/ + if (!_log_domains) + // special case for init, eina itself will allocate a dozen of domains + size = 24; + else + // grow 8 buckets to minimize reallocs + size = _log_domains_allocated + 8; -/** - * @addtogroup Eina_Log_Group Log - * - * @brief These functions provide log management for projects. - * - * To use the log system Eina must be initialized with eina_init() and - * later shut down with eina_shutdown(). The most generic way to print - * logs is to use eina_log_print() but the helper macros - * EINA_LOG_ERR(), EINA_LOG_INFO(), EINA_LOG_WARN() and EINA_LOG_DBG() - * should be used instead. - * - * Here is a straightforward example: - * - * @code - * #include - * #include - * - * #include - * - * void test_warn(void) - * { - * EINA_LOG_WARN("Here is a warning message"); - * } - * - * int main(void) - * { - * if (!eina_init()) - * { - * printf("log during the initialization of Eina_Log module\n"); - * return EXIT_FAILURE; - * } - * - * test_warn(); - * - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * Compile this code with the following command: - * - * @code - * gcc -Wall -o test_Eina_Log test_eina.c `pkg-config --cflags --libs eina` - * @endcode - * - * If Eina is compiled without debug mode, then executing the - * resulting program displays nothing because the default log level - * is #EINA_LOG_LEVEL_ERR and we want to display a warning - * message, which level is strictly greater than the log level (see - * eina_log_print() for more informations). Now execute the program - * with: - * - * @code - * EINA_LOG_LEVEL=2 ./test_eina_log - * @endcode - * - * You should see a message displayed in the terminal. - * - * For more information, you can look at the @ref tutorial_log_page. - * - * @{ - */ + tmp = realloc(_log_domains, sizeof(Eina_Log_Domain) * size); + if (tmp) + { + // Success! + _log_domains = tmp; + _log_domains_allocated = size; + } + else + return -1; + } -/** - * @cond LOCAL - */ + // Use an allocated slot + eina_log_domain_new(&_log_domains[i], name, color); + _log_domains_count++; -EAPI int EINA_LOG_DOMAIN_GLOBAL = 0; +finish_register: + EINA_INLIST_FOREACH(_glob_list, pending) + { + if (!fnmatch(pending->name, name, 0)) + { + _log_domains[i].level = pending->level; + break; + } + } + + EINA_INLIST_FOREACH(_pending_list, pending) + { + if (!strcmp(pending->name, name)) + { + _log_domains[i].level = pending->level; + _pending_list = eina_inlist_remove(_pending_list, EINA_INLIST_GET(pending)); + free(pending); + break; + } + } + + // Check if level is still UNKNOWN, set it to global + if (_log_domains[i].level == EINA_LOG_LEVEL_UNKNOWN) + _log_domains[i].level = _log_level; + + return i; +} /** * @endcond */ + +/*============================================================================* + * Global * + *============================================================================*/ + /** * @internal * @brief Initialize the log module. @@ -1058,7 +1051,6 @@ eina_log_shutdown(void) return EINA_TRUE; } - #ifdef EFL_HAVE_PTHREAD /** @@ -1097,6 +1089,85 @@ eina_log_threads_shutdown(void) #endif +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Log_Group Log + * + * @brief These functions provide log management for projects. + * + * To use the log system Eina must be initialized with eina_init() and + * later shut down with eina_shutdown(). The most generic way to print + * logs is to use eina_log_print() but the helper macros + * EINA_LOG_ERR(), EINA_LOG_INFO(), EINA_LOG_WARN() and EINA_LOG_DBG() + * should be used instead. + * + * Here is a straightforward example: + * + * @code + * #include + * #include + * + * #include + * + * void test_warn(void) + * { + * EINA_LOG_WARN("Here is a warning message"); + * } + * + * int main(void) + * { + * if (!eina_init()) + * { + * printf("log during the initialization of Eina_Log module\n"); + * return EXIT_FAILURE; + * } + * + * test_warn(); + * + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the following command: + * + * @code + * gcc -Wall -o test_Eina_Log test_eina.c `pkg-config --cflags --libs eina` + * @endcode + * + * If Eina is compiled without debug mode, then executing the + * resulting program displays nothing because the default log level + * is #EINA_LOG_LEVEL_ERR and we want to display a warning + * message, which level is strictly greater than the log level (see + * eina_log_print() for more informations). Now execute the program + * with: + * + * @code + * EINA_LOG_LEVEL=2 ./test_eina_log + * @endcode + * + * You should see a message displayed in the terminal. + * + * For more information, you can look at the @ref tutorial_log_page. + * + * @{ + */ + + +/** + * @cond LOCAL + */ + +EAPI int EINA_LOG_DOMAIN_GLOBAL = 0; + +/** + * @endcond + */ + /** * Enable logging module to handle threads. @@ -1159,78 +1230,6 @@ eina_log_level_set(Eina_Log_Level level) _log_level = level; } -static inline int -eina_log_domain_register_unlocked(const char *name, const char *color) -{ - Eina_Log_Domain_Level_Pending *pending = NULL; - int i; - - for (i = 0; i < _log_domains_count; i++) - { - if (_log_domains[i].deleted) - { - // Found a flagged slot, free domain_str and replace slot - eina_log_domain_new(&_log_domains[i], name, color); - goto finish_register; - } - } - - if (_log_domains_count >= _log_domains_allocated) - { - Eina_Log_Domain *tmp; - size_t size; - - if (!_log_domains) - // special case for init, eina itself will allocate a dozen of domains - size = 24; - else - // grow 8 buckets to minimize reallocs - size = _log_domains_allocated + 8; - - tmp = realloc(_log_domains, sizeof(Eina_Log_Domain) * size); - - if (tmp) - { - // Success! - _log_domains = tmp; - _log_domains_allocated = size; - } - else - return -1; - } - - // Use an allocated slot - eina_log_domain_new(&_log_domains[i], name, color); - _log_domains_count++; - -finish_register: - EINA_INLIST_FOREACH(_glob_list, pending) - { - if (!fnmatch(pending->name, name, 0)) - { - _log_domains[i].level = pending->level; - break; - } - } - - EINA_INLIST_FOREACH(_pending_list, pending) - { - if (!strcmp(pending->name, name)) - { - _log_domains[i].level = pending->level; - _pending_list = eina_inlist_remove(_pending_list, EINA_INLIST_GET(pending)); - free(pending); - break; - } - } - - // Check if level is still UNKNOWN, set it to global - if (_log_domains[i].level == EINA_LOG_LEVEL_UNKNOWN) - _log_domains[i].level = _log_level; - - return i; -} - /** * @param name Domain name * @param color Color of the domain name diff --git a/src/lib/eina_magic.c b/src/lib/eina_magic.c index ea291bc..ff697e1 100644 --- a/src/lib/eina_magic.c +++ b/src/lib/eina_magic.c @@ -123,18 +123,6 @@ _eina_magic_strings_alloc(void) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Magic_Group Magic - * - * @brief These functions provide magic checks management for projects. - * - * @{ - */ - /** * @internal * @brief Initialize the magic string module. @@ -194,6 +182,18 @@ eina_magic_string_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Magic_Group Magic + * + * @brief These functions provide magic checks management for projects. + * + * @{ + */ + /** * @brief Return the string associated to the given magic identifier. * @@ -231,7 +231,8 @@ eina_magic_string_get(Eina_Magic magic) * @brief Set the string associated to the given magic identifier. * * @param magic The magic identifier. - * @param The string associated to the identifier, must not be @c NULL. + * @param magic_name The string associated to the identifier, must not + * be @c NULL. * * @return #EINA_TRUE on success, #EINA_FALSE on failure. * @@ -270,9 +271,9 @@ eina_magic_string_set(Eina_Magic magic, const char *magic_name) * @brief Set the string associated to the given magic identifier. * * @param magic The magic identifier. - * @param The string associated to the identifier, must not be @c NULL, - * it will not be duplcated, just referenced thus it must be live - * during magic number usage. + * @param magic_name The string associated to the identifier, must not be + * @c NULL, it will not be duplcated, just referenced thus it must + * be live during magic number usage. * * @return #EINA_TRUE on success, #EINA_FALSE on failure. * @@ -312,7 +313,7 @@ eina_magic_string_static_set(Eina_Magic magic, const char *magic_name) * @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 fnc 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 diff --git a/src/lib/eina_matrixsparse.c b/src/lib/eina_matrixsparse.c index 07c0a45..53467e1 100644 --- a/src/lib/eina_matrixsparse.c +++ b/src/lib/eina_matrixsparse.c @@ -766,20 +766,6 @@ _eina_matrixsparse_iterator_complete_free(Eina_Matrixsparse_Iterator_Complete *i * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Matrixsparse_Group Sparse Matrix - * - * @brief These functions provide matrix sparse management. - * - * For more information, you can look at the @ref tutorial_matrixsparse_page. - * - * @{ - */ - /** * @internal * @brief Initialize the matrixsparse module. @@ -873,6 +859,20 @@ eina_matrixsparse_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Matrixsparse_Group Sparse Matrix + * + * @brief These functions provide matrix sparse management. + * + * For more information, you can look at the @ref tutorial_matrixsparse_page. + * + * @{ + */ + /** * @brief Create a new Sparse Matrix. * @@ -1228,7 +1228,7 @@ eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data) * Change cell value without freeing the possibly existing old value, using * indexes. * - * @param cell the cell reference, must @b not be @c NULL. + * @param m the sparse matrix, must @b not be @c NULL. * @param row the row number to set the value. * @param col the column number to set the value. * @param data new data to set. @@ -1267,7 +1267,7 @@ eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsi * In contrast to eina_matrixsparse_data_idx_replace(), this function will * call @c free_func() on existing value. * - * @param cell the cell reference, must @b not be @c NULL. + * @param m the sparse matrix, must @b not be @c NULL. * @param row the row number to set the value. * @param col the column number to set the value. * @param data new data to set. diff --git a/src/lib/eina_mempool.c b/src/lib/eina_mempool.c index 310af05..002a513 100644 --- a/src/lib/eina_mempool.c +++ b/src/lib/eina_mempool.c @@ -121,6 +121,18 @@ void fixed_bitmap_shutdown(void); * Global * *============================================================================*/ +/** + * @cond LOCAL + */ + +EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0; + +static const char EINA_ERROR_NOT_MEMPOOL_MODULE_STR[] = "Not a memory pool module."; + +/** + * @endcond + */ + EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) { @@ -137,22 +149,6 @@ eina_mempool_unregister(Eina_Mempool_Backend *be) eina_hash_del(_backends, be->name, 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; - -static const char EINA_ERROR_NOT_MEMPOOL_MODULE_STR[] = "Not a memory pool module."; - Eina_Bool eina_mempool_init(void) { @@ -249,6 +245,18 @@ eina_mempool_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Memory_Pool_Group Memory Pool + * + * @brief These functions provide memory pool management. + * + * @{ + */ + EAPI Eina_Mempool * eina_mempool_add(const char *name, const char *context, const char *options, ...) { diff --git a/src/lib/eina_module.c b/src/lib/eina_module.c index dce5f1d..03bbb86 100644 --- a/src/lib/eina_module.c +++ b/src/lib/eina_module.c @@ -170,18 +170,6 @@ static void _dir_list_cb(const char *name, const char *path, void *data) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Module_Group Module - * - * @brief These functions provide module management. - * - * @{ - */ - /** * @cond LOCAL */ @@ -253,6 +241,18 @@ eina_module_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Module_Group Module + * + * @brief These functions provide module management. + * + * @{ + */ + /** * @brief Return a new module. * diff --git a/src/lib/eina_rectangle.c b/src/lib/eina_rectangle.c index e6bc564..5748ce9 100644 --- a/src/lib/eina_rectangle.c +++ b/src/lib/eina_rectangle.c @@ -243,10 +243,6 @@ _eina_rectangle_empty_space_find(Eina_List *empty, int w, int h, int *x, int *y) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - Eina_Bool eina_rectangle_init(void) { @@ -312,6 +308,24 @@ eina_rectangle_shutdown(void) return EINA_TRUE; } +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @brief Create a new rectangle. + * + * @param x The X coordinate of the top left corner of the rectangle. + * @param y The Y coordinate of the top left corner of the rectangle. + * @param w The width of the rectangle. + * @param h The height of the rectangle. + * @return The new rectangle on success, @ NULL otherwise. + * + * This function creates a rectangle which top left corner has the + * coordinates (@p x, @p y), with height @p w and height @p h and adds + * it to the rectangles pool. No check is done on @p w and @p h. This + * function returns a new rectangle on success, @c NULL otherwhise. + */ EAPI Eina_Rectangle * eina_rectangle_new(int x, int y, int w, int h) { @@ -333,6 +347,13 @@ eina_rectangle_new(int x, int y, int w, int h) return rect; } +/** + * @brief Free the given rectangle. + * + * @param rect The rectangle to free. + * + * This function removes @p rect from the rectangles pool. + */ EAPI void eina_rectangle_free(Eina_Rectangle *rect) { @@ -399,6 +420,14 @@ eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) MAGIC_FREE(pool); } +/** + * @brief Return the number of rectangles in the given pool. + * + * @param pool The pool. + * @return The number of rectangles in the pool. + * + * This function returns the number of rectangles in @p pool. + */ EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) { @@ -500,6 +529,15 @@ eina_rectangle_pool_release(Eina_Rectangle *rect) } } +/** + * @brief Return the pool of the given rectangle. + * + * @param rect The rectangle. + * @return The pool of the given rectangle. + * + * This function returns the pool in which @p rect is. If @p rect is + * @c NULL, @c NULL is returned. + */ EAPI Eina_Rectangle_Pool * eina_rectangle_pool_get(Eina_Rectangle *rect) { @@ -513,6 +551,15 @@ eina_rectangle_pool_get(Eina_Rectangle *rect) return era->pool; } +/** + * @brief Set the data to the given pool. + * + * @param pool The pool. + * @param data The data to set. + * + * This function sets @p data to @p pool. If @p pool is @c NULL, this + * function does nothing. + */ EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) { @@ -525,6 +572,16 @@ eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) pool->data = (void*) data; } +/** + * @brief Get the data from the given pool. + * + * @param pool The pool. + * @return The returned data. + * + * This function gets the data from @p pool set by + * eina_rectangle_pool_data_set(). If @p pool is @c NULL, this + * function returns @c NULL. + */ EAPI void * eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) { @@ -534,6 +591,19 @@ eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) return pool->data; } +/** + * @brief Return the width and height of the given pool. + * + * @param pool The pool. + * @param w The returned width. + * @param h The returned height. + * @return #EINA_TRUE on sucess, #EINA_FALSE otherwise. + * + * This function returns the width and height of @p pool and store + * them in respectively @p w and @p h if they are not @c NULL. If + * @p pool is @c NULL, #EINA_FALSE is returned. Otherwise #EINA_TRUE is + * returned. + */ EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) { diff --git a/src/lib/eina_safety_checks.c b/src/lib/eina_safety_checks.c index 8e15b52..7c8a7bc 100644 --- a/src/lib/eina_safety_checks.c +++ b/src/lib/eina_safety_checks.c @@ -16,6 +16,43 @@ * if not, see . */ +#ifdef HAVE_CONFIG_H +# include "config.h" +#endif + +#include "eina_error.h" +#include "eina_private.h" +#include "eina_safety_checks.h" + +/*============================================================================* + * Local * + *============================================================================*/ + +/*============================================================================* + * Global * + *============================================================================*/ + +/** + * @internal + * @brief Shut down the safety checks module. + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function shuts down the error module set up by + * eina_safety_checks_init(). It is called by eina_shutdown(). + * + * @see eina_shutdown() + */ +Eina_Bool +eina_safety_checks_shutdown(void) +{ + return EINA_TRUE; +} + +/*============================================================================* + * API * + *============================================================================*/ + /** * @addtogroup Eina_Safety_Checks_Group Safety Checks * @@ -40,14 +77,6 @@ * @{ */ -#ifdef HAVE_CONFIG_H -# include "config.h" -#endif - -#include "eina_error.h" -#include "eina_private.h" -#include "eina_safety_checks.h" - /** * @cond LOCAL */ @@ -79,22 +108,5 @@ eina_safety_checks_init(void) } /** - * @internal - * @brief Shut down the safety checks module. - * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function shuts down the error module set up by - * eina_safety_checks_init(). It is called by eina_shutdown(). - * - * @see eina_shutdown() - */ -Eina_Bool -eina_safety_checks_shutdown(void) -{ - return EINA_TRUE; -} - -/** * @} */ diff --git a/src/lib/eina_stringshare.c b/src/lib/eina_stringshare.c index a40dbba..59ce9f1 100644 --- a/src/lib/eina_stringshare.c +++ b/src/lib/eina_stringshare.c @@ -839,34 +839,6 @@ _eina_stringshare_node_alloc(int slen) * Global * *============================================================================*/ -/*============================================================================* - * API * - *============================================================================*/ - -/** - * @addtogroup Eina_Stringshare_Group Stringshare - * - * These functions allow you to store one copy of a string, and use it - * throughout your program. - * - * This is a method to reduce the number of duplicated strings kept in - * memory. It's pretty common for the same strings to be dynamically - * allocated repeatedly between applications and libraries, especially in - * circumstances where you could have multiple copies of a structure that - * allocates the string. So rather than duplicating and freeing these - * strings, you request a read-only pointer to an existing string and - * only incur the overhead of a hash lookup. - * - * It sounds like micro-optimizing, but profiling has shown this can have - * a significant impact as you scale the number of copies up. It improves - * string creation/destruction speed, reduces memory use and decreases - * memory fragmentation, so a win all-around. - * - * For more information, you can look at the @ref tutorial_stringshare_page. - * - * @{ - */ - /** * @internal * @brief Initialize the stringshare module. @@ -983,6 +955,34 @@ eina_stringshare_threads_shutdown(void) #endif +/*============================================================================* + * API * + *============================================================================*/ + +/** + * @addtogroup Eina_Stringshare_Group Stringshare + * + * These functions allow you to store one copy of a string, and use it + * throughout your program. + * + * This is a method to reduce the number of duplicated strings kept in + * memory. It's pretty common for the same strings to be dynamically + * allocated repeatedly between applications and libraries, especially in + * circumstances where you could have multiple copies of a structure that + * allocates the string. So rather than duplicating and freeing these + * strings, you request a read-only pointer to an existing string and + * only incur the overhead of a hash lookup. + * + * It sounds like micro-optimizing, but profiling has shown this can have + * a significant impact as you scale the number of copies up. It improves + * string creation/destruction speed, reduces memory use and decreases + * memory fragmentation, so a win all-around. + * + * For more information, you can look at the @ref tutorial_stringshare_page. + * + * @{ + */ + /** * @brief Retrieve an instance of a string for use in a program. * @@ -1088,7 +1088,7 @@ eina_stringshare_add_length(const char *str, unsigned int slen) * it is added to the strings to be searched and a duplicated string * of @p str is returned. * - * The string @a str must be NULL terminated ('\0') and its full + * The string @p str must be NULL terminated ('@\0') and its full * length will be used. To use part of the string or non-null * terminated, use eina_stringshare_add_length() instead. * @@ -1127,6 +1127,10 @@ _eina_stringshare_node_from_str(const char *str) /** * Increment references of the given shared string. * + * @param str The shared string. + * @return A pointer to an instance of the string on success. + * @c NULL on failure. + * * This is similar to eina_stringshare_add(), but it's faster since it will * avoid lookups if possible, but on the down side it requires the parameter * to be shared before, in other words, it must be the return of a previous diff --git a/src/lib/eina_tiler.c b/src/lib/eina_tiler.c index 9ceb489..0a4189e 100644 --- a/src/lib/eina_tiler.c +++ b/src/lib/eina_tiler.c @@ -1094,13 +1094,11 @@ static void _iterator_free(Eina_Iterator_Tiler *it) /*============================================================================* * Global * *============================================================================*/ + /*============================================================================* * API * *============================================================================*/ -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Tiler *eina_tiler_new(int w, int h) { Eina_Tiler *t; @@ -1114,20 +1112,14 @@ EAPI Eina_Tiler *eina_tiler_new(int w, int h) _splitter_new(t); return t; } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void eina_tiler_free(Eina_Tiler *t) { EINA_MAGIC_CHECK_TILER(t); _splitter_del(t); free(t); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h) { EINA_MAGIC_CHECK_TILER(t); @@ -1137,10 +1129,7 @@ EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h) t->tile.h = h; _splitter_tile_size_set(t, w, h); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle *r) { Eina_Rectangle tmp; @@ -1155,10 +1144,7 @@ EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle *r) return EINA_FALSE; return _splitter_rect_add(t, &tmp); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r) { Eina_Rectangle tmp; @@ -1173,10 +1159,7 @@ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r) return; _splitter_rect_del(t, &tmp); } -/** - * To be documented - * FIXME: To be fixed - */ + EAPI void eina_tiler_clear(Eina_Tiler *t) { EINA_MAGIC_CHECK_TILER(t);