From 1fa8bb5c2f045a07d6dabe7cd4b054316456c55a Mon Sep 17 00:00:00 2001 From: caro Date: Sat, 6 Nov 2010 12:34:55 +0000 Subject: [PATCH] * improve doc * remove eina_binshare_init() and eina_binshare_shutdown() from eina_binshare.h as they must not be exported git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@54223 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/Doxyfile | 2 +- src/include/eina_accessor.h | 62 ++++++++++++++++++++++++++++++++++++--------- src/include/eina_binshare.h | 2 -- src/include/eina_iterator.h | 62 +++++++++++++++++++++++++++++++++++++-------- src/include/eina_list.h | 15 +++++++++-- src/lib/eina_benchmark.c | 4 ++- src/lib/eina_binshare.c | 20 +++++++++++++-- src/lib/eina_counter.c | 13 +++++----- src/lib/eina_hash.c | 36 +++++++++++++------------- src/lib/eina_str.c | 33 ++++++++++++++++-------- 10 files changed, 184 insertions(+), 65 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index dbc1c8c..42bdc2e 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -1115,7 +1115,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = __UNUSED__= +PREDEFINED = __UNUSED__= EINA_ARG_NONNULL= EINA_MALLOC= EINA_WARN_UNUSED_RESULT= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/src/include/eina_accessor.h b/src/include/eina_accessor.h index 4df6819..1d00d32 100644 --- a/src/include/eina_accessor.h +++ b/src/include/eina_accessor.h @@ -38,36 +38,74 @@ /** * @typedef Eina_Accessor - * Type for accessors. + * Abstract type for accessors. */ typedef struct _Eina_Accessor Eina_Accessor; -typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it, - unsigned int index, - void **data); -typedef void * (*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it); -typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it); +/** + * @typedef Eina_Accessor_Get_At_Callback + * Type for a callback that returns the data of a container as the given index. + */ +typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it, + unsigned int index, + void **data); + +/** + * @typedef Eina_Accessor_Get_Container_Callback + * Type for a callback that returns the container. + */ +typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it); + +/** + * @typedef Eina_Accessor_Free_Callback + * Type for a callback that frees the container. + */ +typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it); + +/** + * @typedef Eina_Accessor_Lock_Callback + * Type for a callback that lock the container. + */ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it); struct _Eina_Accessor { #define EINA_ACCESSOR_VERSION 1 - int version; + int version; /**< Version of the Accessor API. */ - Eina_Accessor_Get_At_Callback get_at EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; - Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; - Eina_Accessor_Free_Callback free EINA_ARG_NONNULL(1); + Eina_Accessor_Get_At_Callback get_at EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; /**< Callback called when a data element is requested. */ + Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */ + Eina_Accessor_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */ - Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; - Eina_Accessor_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; + Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ + Eina_Accessor_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */ #define EINA_MAGIC_ACCESSOR 0x98761232 EINA_MAGIC }; +/** + * @def FUNC_ACCESSOR_GET_AT(Function) + * Helper macro to cast @p Function to a Eina_Accessor_Get_At_Callback. + */ #define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function) + +/** + * @def FUNC_ACCESSOR_GET_CONTAINER(Function) + * Helper macro to cast @p Function to a Eina_Accessor_Get_Container_Callback. + */ #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function) + +/** + * @def FUNC_ACCESSOR_FREE(Function) + * Helper macro to cast @p Function to a Eina_Accessor_Free_Callback. + */ #define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function) + +/** + * @def FUNC_ACCESSOR_LOCK(Function) + * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. + */ #define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function) EAPI void eina_accessor_free(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); diff --git a/src/include/eina_binshare.h b/src/include/eina_binshare.h index 90857d2..6a2f02a 100644 --- a/src/include/eina_binshare.h +++ b/src/include/eina_binshare.h @@ -65,8 +65,6 @@ * @{ */ -EAPI Eina_Bool eina_binshare_init(void); -EAPI Eina_Bool eina_binshare_shutdown(void); EAPI const void *eina_binshare_add_length(const void *obj, unsigned int olen) EINA_PURE EINA_WARN_UNUSED_RESULT; EAPI const void *eina_binshare_ref(const void *obj); diff --git a/src/include/eina_iterator.h b/src/include/eina_iterator.h index 78f44e8..93c0e27 100644 --- a/src/include/eina_iterator.h +++ b/src/include/eina_iterator.h @@ -38,36 +38,76 @@ /** * @typedef Eina_Iterator - * Type for iterators. + * Abstract type for iterators. */ typedef struct _Eina_Iterator Eina_Iterator; +/** + * @typedef Eina_Iterator_Next_Callback + * Type for a callback that returns the next element in a container. + */ typedef Eina_Bool (*Eina_Iterator_Next_Callback)(Eina_Iterator *it, void **data); -typedef void * (*Eina_Iterator_Get_Container_Callback)(Eina_Iterator *it); + +/** + * @typedef Eina_Iterator_Get_Container_Callback + * Type for a callback that returns the container. + */ +typedef void *(*Eina_Iterator_Get_Container_Callback)(Eina_Iterator *it); + +/** + * @typedef Eina_Iterator_Free_Callback + * Type for a callback that frees the container. + */ typedef void (*Eina_Iterator_Free_Callback)(Eina_Iterator *it); + +/** + * @typedef Eina_Iterator_Lock_Callback + * Type for a callback that lock the container. + */ typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it); +/** + * @struct _Eina_Iterator + * structure of an iterator + */ struct _Eina_Iterator { #define EINA_ITERATOR_VERSION 1 - int version; + int version; /**< Version of the Iterator API. */ - Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; - Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; - Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); + Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when a next element is requested. */ + Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */ + Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */ - Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; - Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; + Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ + Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */ #define EINA_MAGIC_ITERATOR 0x98761233 EINA_MAGIC }; +/** + * @def FUNC_ITERATOR_NEXT(Function) + * Helper macro to cast @p Function to a Eina_Iterator_Next_Callback. + */ #define FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function) -#define FUNC_ITERATOR_GET_CONTAINER(Function) (( \ - Eina_Iterator_Get_Container_Callback) \ - Function) + +/** + * @def FUNC_ITERATOR_GET_CONTAINER(Function) + * Helper macro to cast @p Function to a Eina_Iterator_Get_Container_Callback. + */ +#define FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function) + +/** + * @def FUNC_ITERATOR_FREE(Function) + * Helper macro to cast @p Function to a Eina_Iterator_Free_Callback. + */ #define FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function) + +/** + * @def FUNC_ITERATOR_LOCK(Function) + * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. + */ #define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function) EAPI void eina_iterator_free(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); diff --git a/src/include/eina_list.h b/src/include/eina_list.h index e5d915d..e19d67d 100644 --- a/src/include/eina_list.h +++ b/src/include/eina_list.h @@ -52,6 +52,11 @@ */ typedef struct _Eina_List Eina_List; +/** + * @typedef Eina_List_Accounting + * Cache used to store the last element of a list and the number of + * elements, for fast access. + */ typedef struct _Eina_List_Accounting Eina_List_Accounting; /** @@ -68,10 +73,16 @@ struct _Eina_List EINA_MAGIC }; +/** + * @struct _Eina_List_Accounting + * Cache used to store the last element of a list and the number of + * elements, for fast access. It is for private used and must not be + * touched. + */ struct _Eina_List_Accounting { - Eina_List *last; - unsigned int count; + Eina_List *last; /**< Pointer to the last element of the list - don't touch */ + unsigned int count; /**< Number of elements of the list - don't touch */ EINA_MAGIC }; diff --git a/src/lib/eina_benchmark.c b/src/lib/eina_benchmark.c index 5cd3fd3..65d570f 100644 --- a/src/lib/eina_benchmark.c +++ b/src/lib/eina_benchmark.c @@ -536,6 +536,7 @@ eina_benchmark_free(Eina_Benchmark *bench) * @param count_start The start data to be passed to @p bench_cb. * @param count_end The end data to be passed to @p bench_cb. * @param count_step The step data to be passed to @p bench_cb. + * @return #EINA_FALSE on failure, #EINA_TRUE otherwise. * * This function adds the test named @p name to @p benchmark. @p * bench_cb is the function called when the test is executed. That @@ -546,7 +547,8 @@ eina_benchmark_free(Eina_Benchmark *bench) * * If @p bench is @c NULL, this function returns imediatly. If the * allocation of the memory of the test to add fails, the error is set - * to #EINA_ERROR_OUT_OF_MEMORY. + * to #EINA_ERROR_OUT_OF_MEMORY. This function returns #EINA_FALSE + * on failure, #EINA_TRUE otherwise. */ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, diff --git a/src/lib/eina_binshare.c b/src/lib/eina_binshare.c index 3973357..793650f 100644 --- a/src/lib/eina_binshare.c +++ b/src/lib/eina_binshare.c @@ -33,10 +33,23 @@ #include "eina_private.h" #include "eina_binshare.h" +/*============================================================================* + * Local * + *============================================================================*/ + +/** + * @cond LOCAL + */ + /* The actual share */ static Eina_Share *binshare_share; static const char EINA_MAGIC_BINSHARE_NODE_STR[] = "Eina Binshare Node"; +/** + * @endcond + */ + + /*============================================================================* * Global * *============================================================================*/ @@ -79,9 +92,11 @@ eina_binshare_shutdown(void) return ret; } + /*============================================================================* -* API * -*============================================================================*/ + * API * + *============================================================================*/ + /** * @addtogroup Eina_Binshare_Group Binary Share * @@ -172,6 +187,7 @@ eina_binshare_ref(const void *obj) * * @param obj the shared object to know the length. It is safe to * give NULL, in that case -1 is returned. + * @return The length of the shared object. * * This function is a cheap way to known the length of a shared * object. Note that if the given pointer is not shared, bad diff --git a/src/lib/eina_counter.c b/src/lib/eina_counter.c index 8c430dc..daad1f7 100644 --- a/src/lib/eina_counter.c +++ b/src/lib/eina_counter.c @@ -42,8 +42,8 @@ #include "eina_counter.h" /*============================================================================* -* Local * -*============================================================================*/ + * Local * + *============================================================================*/ /** * @cond LOCAL @@ -148,8 +148,8 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...) */ /*============================================================================* -* Global * -*============================================================================*/ + * Global * + *============================================================================*/ /** * @internal @@ -202,8 +202,8 @@ eina_counter_shutdown(void) } /*============================================================================* -* API * -*============================================================================*/ + * API * + *============================================================================*/ /** * @addtogroup Eina_Counter_Group Counter @@ -292,6 +292,7 @@ eina_counter_shutdown(void) * @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 diff --git a/src/lib/eina_hash.c b/src/lib/eina_hash.c index 4c5f533..7f9a044 100644 --- a/src/lib/eina_hash.c +++ b/src/lib/eina_hash.c @@ -40,26 +40,26 @@ #include "eina_hash.h" /*============================================================================* -* Local * -*============================================================================*/ + * Local * + *============================================================================*/ /** * @cond LOCAL */ -#define EINA_MAGIC_CHECK_HASH(d) \ - do { \ - if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_HASH)) { \ - EINA_MAGIC_FAIL(d, EINA_MAGIC_HASH); } \ +#define EINA_MAGIC_CHECK_HASH(d) \ + do { \ + if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_HASH)) { \ + EINA_MAGIC_FAIL(d, EINA_MAGIC_HASH); } \ } while(0) -#define EINA_MAGIC_CHECK_HASH_ITERATOR(d, ...) \ - do { \ - if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_HASH_ITERATOR)) \ - { \ - EINA_MAGIC_FAIL(d, EINA_MAGIC_HASH_ITERATOR); \ - return __VA_ARGS__; \ - } \ +#define EINA_MAGIC_CHECK_HASH_ITERATOR(d, ...) \ + do { \ + if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_HASH_ITERATOR)) \ + { \ + EINA_MAGIC_FAIL(d, EINA_MAGIC_HASH_ITERATOR); \ + return __VA_ARGS__; \ + } \ } while(0) #define EINA_HASH_BUCKET_SIZE 8 @@ -695,12 +695,12 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it) */ /*============================================================================* -* Global * -*============================================================================*/ + * Global * + *============================================================================*/ /*============================================================================* -* API * -*============================================================================*/ + * API * + *============================================================================*/ /** * @addtogroup Eina_Hash_Group Hash Table @@ -739,7 +739,7 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it) * * This function create a new hash table using user-defined callbacks * to manage the hash table. On failure, @c NULL is returned and - * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @pkey_hash_cb + * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb * are @c NULL, @c NULL is returned. If @p buckets_power_size is * smaller or equal than 2, or if it is greater or equal than 17, * @c NULL is returned. diff --git a/src/lib/eina_str.c b/src/lib/eina_str.c index bd9badb..9a62cb3 100644 --- a/src/lib/eina_str.c +++ b/src/lib/eina_str.c @@ -472,12 +472,18 @@ eina_str_join_len(char *dst, } /** - * @brief Use iconv to convert a text string from one encoding to another + * @brief Use Iconv to convert a text string from one encoding to another. * - * @param enc_from encoding to convert from - * @param enc_to encoding to convert to - * @param text text to convert + * @param enc_from Encoding to convert from. + * @param enc_to Encoding to convert to. + * @param text The text to convert. + * @return The converted text. * + * This function converts @p text, encoded in @p enc_from. On success, + * the converted text is returned and is encoded in @p enc_to. On + * failure, @c NULL is returned. Iconv is used to convert @p text. If + * Iconv is not available, @c NULL is returned. When not used anymore, + * the returned value must be freed. */ #ifdef HAVE_ICONV EAPI char * @@ -569,9 +575,12 @@ eina_str_convert(const char *enc_from __UNUSED__, /** * @brief Put a \ before and Space( ), \ or ' in a string. * - * @param str the string to escape + * @param str The string to escape. + * @return The escaped string. * - * A newly allocated string is returned. + * This function returns a newly allocated escaped string on success, + * @c NULL on failure. When not used anymore, the returned value must + * be freed. */ EAPI char * eina_str_escape(const char *str) @@ -600,9 +609,11 @@ eina_str_escape(const char *str) /** * @brief Lowercase all the characters in range [A-Z] in the given string. * - * @param str the string to lowercase + * @param str The string to lowercase. * - * This modifies the original string, changing all characters in [A-Z] to lowercase. + * This function modifies the original string, changing all characters + * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string, + * this function does nothing. */ EAPI void eina_str_tolower(char **str) @@ -618,9 +629,11 @@ eina_str_tolower(char **str) /** * @brief Uppercase all the characters in range [a-z] in the given string. * - * @param str the string to uppercase + * @param str The string to uppercase. * - * This modifies the original string, changing all characters in [a-z] to uppercase. + * This function modifies the original string, changing all characters + * in [a-z] to uppercase. If @p str is @c NULL or is an empty string, + * this function does nothing. */ EAPI void eina_str_toupper(char **str) -- 2.7.4