From a300d23379c7569f0e736f6f4e629431b6fbe1d3 Mon Sep 17 00:00:00 2001 From: raster Date: Thu, 7 Apr 2011 11:40:55 +0000 Subject: [PATCH] more doxy -> .h git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@58421 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/include/eina_counter.h | 162 +++++++++++++++++++++++++++++++++++++++++++++ src/lib/eina_counter.c | 157 ------------------------------------------- 2 files changed, 162 insertions(+), 157 deletions(-) diff --git a/src/include/eina_counter.h b/src/include/eina_counter.h index 9a0430a..c07f5fd 100644 --- a/src/include/eina_counter.h +++ b/src/include/eina_counter.h @@ -22,6 +22,89 @@ #include "eina_types.h" /** + * @addtogroup Eina_Counter_Group Counter + * + * @brief These functions allow you to get the time spent in a part of a code. + * + * Before using the counter system, Eina must be initialized with + * eina_init() and later shut down with eina_shutdown(). The create a + * counter, use eina_counter_new(). To free it, use + * eina_counter_free(). + * + * To time a part of a code, call eina_counter_start() just before it, + * and eina_counter_stop() just after it. Each time you start to time + * a code, a clock is added to a list. You can give a number of that + * clock with the second argument of eina_counter_stop(). To send all + * the registered clocks to a stream (like stdout, ofr a file), use + * eina_counter_dump(). + * + * Here is a straightforward example: + * + * @code + * #include + * #include + * + * #include + * + * void test_malloc(void) + * { + * int i; + * + * for (i = 0; i < 100000; ++i) + * { + * void *buf; + * + * buf = malloc(100); + * free(buf); + * } + * } + * + * int main(void) + * { + * Eina_Counter *counter; + * + * if (!eina_init()) + * { + * printf("Error during the initialization of eina\n"); + * return EXIT_FAILURE; + * } + * + * counter = eina_counter_new("malloc"); + * + * eina_counter_start(counter); + * test_malloc(); + * eina_counter_stop(counter, 1); + * + * char* result = eina_counter_dump(counter); + * printf("%s", result); + * free(result); + * + * eina_counter_free(counter); + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the following commant: + * + * @verbatim + * gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina` + * @endverbatim + * + * The result should be something like that: + * + * @verbatim + * \# specimen experiment time starting time ending time + * 1 9794125 783816 10577941 + * @endverbatim + * + * Note that the displayed time is in nanosecond. + * + * @{ + */ + +/** * @addtogroup Eina_Tools_Group Tools * * @{ @@ -39,11 +122,86 @@ */ typedef struct _Eina_Counter Eina_Counter; + +/** + * @brief Return a counter. + * + * @param name The name of the counter. + * @return A newly allocated counter. + * + * This function returns a new counter. It is characterized by @p + * name. If @p name is @c NULL, the function returns @c NULL + * immediately. If memory allocation fails, @c NULL is returned and the + * error is set to #EINA_ERROR_OUT_OF_MEMORY. + * + * Whe the new counter is not needed anymore, use eina_counter_free() to + * free the allocated memory. + */ EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Delete a counter. + * + * @param counter The counter to delete. + * + * This function remove the clock of @p counter from the used clocks + * (see eina_counter_start()) and frees the memory allocated for + * @p counter. If @p counter is @c NULL, the function returns + * immediately. + */ EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1); + +/** + * @brief Start the time count. + * + * @param counter The counter. + * + * This function specifies that the part of the code beginning just + * after its call is being to be timed, using @p counter. If + * @p counter is @c NULL, this function returns immediately. + * + * This function adds the clock associated to @p counter in a list. If + * the memory needed by that clock can not be allocated, the function + * returns and the error is set to #EINA_ERROR_OUT_OF_MEMORY. + * + * To stop the timing, eina_counter_stop() must be called with the + * same counter. + */ EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1); + +/** + * @brief Stop the time count. + * + * @param counter The counter. + * @param specimen The number of the test. + * + * This function stop the timing that has been started with + * eina_counter_start(). @p counter must be the same than the one used + * with eina_counter_start(). @p specimen is the number of the + * test. If @p counter or its associated clock are @c NULL, or if the + * time can't be retrieved the function exits. + */ EAPI void eina_counter_stop(Eina_Counter *counter, int specimen) EINA_ARG_NONNULL(1); + +/** + * @brief Dump the result of all clocks of a counter to a stream. + * + * @return A string with a summary of the test. + * @param counter The counter. + * + * This function returns an malloc'd string containing the dump of + * all the valid clocks of @p counter. + * If @p counter @c NULL, the functions exits + * immediately. Otherwise, the output is formattted like that: + * + * @verbatim + * \# specimen experiment time starting time ending time + * 1 208 120000 120208 + * @endverbatim + * + * The unit of time is the nanosecond. + */ EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1); /** @@ -54,4 +212,8 @@ EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1); * @} */ +/** + * @} + */ + #endif /* EINA_COUNTER_H_ */ diff --git a/src/lib/eina_counter.c b/src/lib/eina_counter.c index e0c2f4c..116246b 100644 --- a/src/lib/eina_counter.c +++ b/src/lib/eina_counter.c @@ -214,103 +214,6 @@ eina_counter_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Counter_Group Counter - * - * @brief These functions allow you to get the time spent in a part of a code. - * - * Before using the counter system, Eina must be initialized with - * eina_init() and later shut down with eina_shutdown(). The create a - * counter, use eina_counter_new(). To free it, use - * eina_counter_free(). - * - * To time a part of a code, call eina_counter_start() just before it, - * and eina_counter_stop() just after it. Each time you start to time - * a code, a clock is added to a list. You can give a number of that - * clock with the second argument of eina_counter_stop(). To send all - * the registered clocks to a stream (like stdout, ofr a file), use - * eina_counter_dump(). - * - * Here is a straightforward example: - * - * @code - * #include - * #include - * - * #include - * - * void test_malloc(void) - * { - * int i; - * - * for (i = 0; i < 100000; ++i) - * { - * void *buf; - * - * buf = malloc(100); - * free(buf); - * } - * } - * - * int main(void) - * { - * Eina_Counter *counter; - * - * if (!eina_init()) - * { - * printf("Error during the initialization of eina\n"); - * return EXIT_FAILURE; - * } - * - * counter = eina_counter_new("malloc"); - * - * eina_counter_start(counter); - * test_malloc(); - * eina_counter_stop(counter, 1); - * - * char* result = eina_counter_dump(counter); - * printf("%s", result); - * free(result); - * - * eina_counter_free(counter); - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * Compile this code with the following commant: - * - * @verbatim - * gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina` - * @endverbatim - * - * The result should be something like that: - * - * @verbatim - * \# specimen experiment time starting time ending time - * 1 9794125 783816 10577941 - * @endverbatim - * - * Note that the displayed time is in nanosecond. - * - * @{ - */ - -/** - * @brief Return a counter. - * - * @param name The name of the counter. - * @return A newly allocated counter. - * - * This function returns a new counter. It is characterized by @p - * name. If @p name is @c NULL, the function returns @c NULL - * immediately. If memory allocation fails, @c NULL is returned and the - * error is set to #EINA_ERROR_OUT_OF_MEMORY. - * - * Whe the new counter is not needed anymore, use eina_counter_free() to - * free the allocated memory. - */ EAPI Eina_Counter * eina_counter_new(const char *name) { @@ -335,16 +238,6 @@ eina_counter_new(const char *name) return counter; } -/** - * @brief Delete a counter. - * - * @param counter The counter to delete. - * - * This function remove the clock of @p counter from the used clocks - * (see eina_counter_start()) and frees the memory allocated for - * @p counter. If @p counter is @c NULL, the function returns - * immediately. - */ EAPI void eina_counter_free(Eina_Counter *counter) { @@ -361,22 +254,6 @@ eina_counter_free(Eina_Counter *counter) free(counter); } -/** - * @brief Start the time count. - * - * @param counter The counter. - * - * This function specifies that the part of the code beginning just - * after its call is being to be timed, using @p counter. If - * @p counter is @c NULL, this function returns immediately. - * - * This function adds the clock associated to @p counter in a list. If - * the memory needed by that clock can not be allocated, the function - * returns and the error is set to #EINA_ERROR_OUT_OF_MEMORY. - * - * To stop the timing, eina_counter_stop() must be called with the - * same counter. - */ EAPI void eina_counter_start(Eina_Counter *counter) { @@ -401,18 +278,6 @@ eina_counter_start(Eina_Counter *counter) clk->start = tp; } -/** - * @brief Stop the time count. - * - * @param counter The counter. - * @param specimen The number of the test. - * - * This function stop the timing that has been started with - * eina_counter_start(). @p counter must be the same than the one used - * with eina_counter_start(). @p specimen is the number of the - * test. If @p counter or its associated clock are @c NULL, or if the - * time can't be retrieved the function exits. - */ EAPI void eina_counter_stop(Eina_Counter *counter, int specimen) { @@ -433,24 +298,6 @@ eina_counter_stop(Eina_Counter *counter, int specimen) clk->valid = EINA_TRUE; } -/** - * @brief Dump the result of all clocks of a counter to a stream. - * - * @return A string with a summary of the test. - * @param counter The counter. - * - * This function returns an malloc'd string containing the dump of - * all the valid clocks of @p counter. - * If @p counter @c NULL, the functions exits - * immediately. Otherwise, the output is formattted like that: - * - * @verbatim - * \# specimen experiment time starting time ending time - * 1 208 120000 120208 - * @endverbatim - * - * The unit of time is the nanosecond. - */ EAPI char * eina_counter_dump(Eina_Counter *counter) { @@ -509,7 +356,3 @@ eina_counter_dump(Eina_Counter *counter) return result; } - -/** - * @} - */ -- 2.7.4