# 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.
/**
* @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);
* @{
*/
-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);
/**
* @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);
*/
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;
/**
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
};
* @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
*
* 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,
#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 *
*============================================================================*/
return ret;
}
+
/*============================================================================*
-* API *
-*============================================================================*/
+ * API *
+ *============================================================================*/
+
/**
* @addtogroup Eina_Binshare_Group Binary Share
*
*
* @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
#include "eina_counter.h"
/*============================================================================*
-* Local *
-*============================================================================*/
+ * Local *
+ *============================================================================*/
/**
* @cond LOCAL
*/
/*============================================================================*
-* Global *
-*============================================================================*/
+ * Global *
+ *============================================================================*/
/**
* @internal
}
/*============================================================================*
-* API *
-*============================================================================*/
+ * API *
+ *============================================================================*/
/**
* @addtogroup Eina_Counter_Group 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
#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
*/
/*============================================================================*
-* Global *
-*============================================================================*/
+ * Global *
+ *============================================================================*/
/*============================================================================*
-* API *
-*============================================================================*/
+ * API *
+ *============================================================================*/
/**
* @addtogroup Eina_Hash_Group Hash Table
*
* 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.
}
/**
- * @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 *
/**
* @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)
/**
* @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)
/**
* @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)
projects / framework / uifw / eina.git / commitdiff