borisfaure
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

eina: enhance doxygen in eina_accessor.h 

Summary:
Add @brief for brief description
Add @details for detailed description
Add [in] & [out] for parameters
Fix indentation & Fix typeof

Reviewers: raster, cedric

Reviewed By: cedric

Subscribers: cedric

Differential Revision: https://phab.enlightenment.org/D1580

Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
Tae-Hwan Kim 2014-10-27 09:10:16 +01:00 committed by Cedric BAIL
parent dbe87afd63
commit 72c576ab4e
1 changed files with 98 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
src/lib/eina/eina_accessor.h
View File

@ -28,7 +28,7 @@
* @page eina_accessor_example_01_page Eina_Accessor usage * @page eina_accessor_example_01_page Eina_Accessor usage
* @dontinclude eina_accessor_01.c * @dontinclude eina_accessor_01.c
* *
* We start by including necessary headers, declaring variables and * We start by including necessary headers, declaring variables, and
* initializing eina: * initializing eina:
* @skip #include * @skip #include
* @until eina_init * @until eina_init
@ -40,7 +40,7 @@
* and create an accessor: * and create an accessor:
* @until accessor_new * @until accessor_new
* *
* Once having the accessor we can use it to access certain elements in the * Once we have the accessor we can use it to access certain elements in the
* container: * container:
* @until } * @until }
* @note Unlike iterators accessors allow us non-linear access, which allows us * @note Unlike iterators accessors allow us non-linear access, which allows us
@ -53,19 +53,19 @@
* Now we create another accessor, this time for the list: * Now we create another accessor, this time for the list:
* @until accessor_new * @until accessor_new
* *
* And now the interesting bit, we use the same code we used above to print * And now the interesting part, we use the same code we used above, to print
* parts of the array to print parts of the list: * parts of the array, to print parts of the list:
* @until } * @until }
* *
* And to free the list we use a gimmick, instead of freeing @a list, we ask the * And to free the list we use a gimmick, instead of freeing @a list, we ask the
* accessor for it's container and free that: * accessor for its container and we free that:
* @until list_free * @until list_free
* *
* Finally we shut eina down and leave: * Finally we shut eina down and leave:
* @until } * @until }
* *
* The full source code can be found on the examples folder * The full source code can be found in the examples folder
* on the @ref eina_accessor_01_c "eina_accessor_01.c" file. * in the @ref eina_accessor_01_c "eina_accessor_01.c" file.
*/ */
/** /**
@ -76,9 +76,10 @@
*/ */
/** /**
* @addtogroup Eina_Accessor_Group Accessor Functions * @defgroup Eina_Accessor_Group Accessor Functions
* @ingroup Eina_Content_Access_Group
* *
* @brief These functions manage accessor on containers. * @brief This group discusses the functions to manage an accessor on containers.
* *
* These functions allow to access elements of a container in a * These functions allow to access elements of a container in a
* generic way, without knowing which container is used (a bit like * generic way, without knowing which container is used (a bit like
@ -89,9 +90,9 @@
* Getting an accessor to access elements of a given container is done through * Getting an accessor to access elements of a given container is done through
* the functions of that particular container. There is no function to create * the functions of that particular container. There is no function to create
* a generic accessor as accessors absolutely depend on the container. This * a generic accessor as accessors absolutely depend on the container. This
* means you won't find accessor creation function here, those can be found on * means you won't find an accessor creation function here, those can be found on
* the documentation of the container type you're using. Though created with * the documentation of the container type you're using. Though created with
* container specific functions accessors are always deleted with the same * container specific functions, accessors are always deleted by the same
* function: eina_accessor_free(). * function: eina_accessor_free().
* *
* To get the data of an element at a given * To get the data of an element at a given
@ -99,29 +100,19 @@
* chosen elements of a container, use eina_accessor_over(). * chosen elements of a container, use eina_accessor_over().
* *
* See an example @ref eina_accessor_example_01_page "here". * See an example @ref eina_accessor_example_01_page "here".
*/
/**
* @addtogroup Eina_Content_Access_Group Content Access
*
* @{
*/
/**
* @defgroup Eina_Accessor_Group Accessor Functions
* *
* @{ * @{
*/ */
/** /**
* @typedef Eina_Accessor * @typedef Eina_Accessor
* Abstract type for accessors. * @brief Type for a accessor structure.
*/ */
typedef struct _Eina_Accessor Eina_Accessor; typedef struct _Eina_Accessor Eina_Accessor;
/** /**
* @typedef Eina_Accessor_Get_At_Callback * @typedef Eina_Accessor_Get_At_Callback
* Type for a callback that returns the data of a container as the given index. * @brief 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, typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it,
unsigned int idx, unsigned int idx,
@ -129,47 +120,46 @@ typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it,
/** /**
* @typedef Eina_Accessor_Get_Container_Callback * @typedef Eina_Accessor_Get_Container_Callback
* Type for a callback that returns the container. * @brief Type for a callback to return the container of the accessor.
*/ */
typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it); typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it);
/** /**
* @typedef Eina_Accessor_Free_Callback * @typedef Eina_Accessor_Free_Callback
* Type for a callback that frees the container. * @brief Type for a callback to free the accessor.
*/ */
typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it); typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it);
/** /**
* @typedef Eina_Accessor_Lock_Callback * @typedef Eina_Accessor_Lock_Callback
* Type for a callback that lock the container. * @brief Type for a callback to lock the accessor.
*/ */
typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it); typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
/** /**
* @typedef Eina_Accessor_Clone_Callback * @typedef Eina_Accessor_Clone_Callback
* Type for a callback that returns a clone for the accessor * @brief Type for a callback to return a clone for the accessor
* @since 1.10 * @since 1.10
*/ */
typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it); typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it);
/** /**
* @struct _Eina_Accessor * @struct _Eina_Accessor
* Type to provide random access to data structures. * @brief Structure to provide random access to data structures.
* *
* If creating an accessor remember to set the type using @ref EINA_MAGIC_SET. * @note When creating an accessor remember to set the type using #EINA_MAGIC_SET
*
*/ */
struct _Eina_Accessor struct _Eina_Accessor
{ {
#define EINA_ACCESSOR_VERSION 2 #define EINA_ACCESSOR_VERSION 2
int version; /**< Version of the Accessor API. */ int version; /**< Version of the Accessor API */
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_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_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_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed */
Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ 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. */ Eina_Accessor_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked */
#define EINA_MAGIC_ACCESSOR 0x98761232 #define EINA_MAGIC_ACCESSOR 0x98761232
EINA_MAGIC EINA_MAGIC
@ -179,88 +169,89 @@ struct _Eina_Accessor
/** /**
* @def FUNC_ACCESSOR_GET_AT(Function) * @def FUNC_ACCESSOR_GET_AT(Function)
* Helper macro to cast @p Function to a Eina_Accessor_Get_At_Callback. * @brief Helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback.
*/ */
#define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function) #define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_GET_CONTAINER(Function) * @def FUNC_ACCESSOR_GET_CONTAINER(Function)
* Helper macro to cast @p Function to a Eina_Accessor_Get_Container_Callback. * @brief Helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback.
*/ */
#define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function) #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_FREE(Function) * @def FUNC_ACCESSOR_FREE(Function)
* Helper macro to cast @p Function to a Eina_Accessor_Free_Callback. * @brief Helper macro to cast @a Function to a Eina_Accessor_Free_Callback.
*/ */
#define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function) #define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_LOCK(Function) * @def FUNC_ACCESSOR_LOCK(Function)
* Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. * @brief Helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
*/ */
#define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function) #define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_CLONE(Function) * @def FUNC_ACCESSOR_CLONE(Function)
* Helper macro to cast @p Function to a Eina_Iterator_Clone_Callback. * @brief Helper macro to cast @p Function to a Eina_Iterator_Clone_Callback.
* @since 1.10 * @since 1.10
*/ */
#define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function) #define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function)
/** /**
* @brief Free an accessor. * @brief Frees an accessor.
* *
* @param accessor The accessor to free. * @param[in] accessor The accessor to free
* *
* This function frees @p accessor if it is not @c NULL; * @details This function frees @a accessor if it is not @c NULL.
*/ */
EAPI void eina_accessor_free(Eina_Accessor *accessor); EAPI void eina_accessor_free(Eina_Accessor *accessor);
/** /**
* @brief Retrieve the data of an accessor at a given position. * @brief Gets the data of an accessor at the given position.
* *
* @param accessor The accessor. * @param[in] accessor The accessor
* @param position The position of the element. * @param[in] position The position of the element
* @param data The pointer that stores the data to retrieve. * @param[in] data The pointer that stores the data to retrieve
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, otherwise #EINA_FALSE
*
* @details This function retrieves the data of the element pointed by
* @p accessor at the position @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurs, #EINA_FALSE
* is returned, otherwise #EINA_TRUE is returned.
* *
* This function retrieves the data of the element pointed by
* @p accessor at the porition @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurred, #EINA_FALSE
* is returned, otherwise #EINA_TRUE is returned.
*/ */
EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor, EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
unsigned int position, unsigned int position,
void **data) EINA_ARG_NONNULL(1); void **data) EINA_ARG_NONNULL(1);
/** /**
* @brief Return the container of an accessor. * @brief Gets the container of an accessor.
* *
* @param accessor The accessor. * @param[in] accessor The accessor
* @return The container which created the accessor. * @return The container that created the accessor
* *
* This function returns the container which created @p accessor. If * @details This function returns the container that created @p accessor. If
* @p accessor is @c NULL, this function returns @c NULL. * @p accessor is @c NULL, this function returns @c NULL.
*/ */
EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE; EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE;
/** /**
* @brief Iterate over the container and execute a callback on chosen elements. * @brief Iterates over the container and executes a callback on the chosen elements.
* *
* @param accessor The accessor. * @param[in] accessor The accessor
* @param cb The callback called on the chosen elements. * @param[in] cb The callback called on the chosen elements
* @param start The position of the first element. * @param[in] start The position of the first element
* @param end The position of the last element. * @param[in] end The position of the last element
* @param fdata The data passed to the callback. * @param[in] fdata The data passed to the callback
* *
* This function iterates over the elements pointed by @p accessor, * @details This function iterates over the elements pointed by @p accessor,
* starting from the element at position @p start and ending to the * starting from the element at position @p start and ending at the
* element at position @p end. For Each element, the callback * element at position @p end. For each element, the callback
* @p cb is called with the data @p fdata. If @p accessor is @c NULL * @p cb is called with the data @p fdata. If @p accessor is @c NULL
* or if @p start is greter or equal than @p end, the function returns * or if @p start is greater than or equal to @p end, the function returns
* immediately. * immediately.
*/ */
EAPI void eina_accessor_over(Eina_Accessor *accessor, EAPI void eina_accessor_over(Eina_Accessor *accessor,
Eina_Each_Cb cb, Eina_Each_Cb cb,
@ -269,25 +260,25 @@ EAPI void eina_accessor_over(Eina_Accessor *accessor,
const void *fdata) EINA_ARG_NONNULL(2); const void *fdata) EINA_ARG_NONNULL(2);
/** /**
* @brief Lock the container of the accessor. * @brief Locks the container of the accessor.
* *
* @param accessor The accessor. * @param[in] accessor The accessor
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, otherwise #EINA_FALSE
* *
* If the container of the @p accessor permits it, it will be locked. When a * @note If the container of the @p accessor permits it, it is locked. When a
* container is locked calling eina_accessor_over() on it will return * container is locked by calling eina_accessor_over() on it, it returns
* immediately. If @p accessor is @c NULL or if a problem occurred, #EINA_FALSE * immediately. If @p accessor is @c NULL or if a problem occurs, #EINA_FALSE
* is returned, otherwise #EINA_TRUE is returned. If the container isn't * is returned, otherwise #EINA_TRUE is returned. If the container is not
* lockable, it will return #EINA_TRUE. * lockable, it returns #EINA_TRUE.
* *
* @warning None of the existing eina data structures are lockable. * @warnning None of the existing eina data structures are lockable.
*/ */
EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
/** /**
* @brief Clone the accessor. * @brief Clones the container of the accessor.
* *
* @param accessor The accessor. * @param[in] accessor The accessor.
* @return Another accessor * @return Another accessor
* @since 1.10 * @since 1.10
*/ */
@ -296,14 +287,13 @@ EAPI Eina_Accessor* eina_accessor_clone(Eina_Accessor *accessor) EINA_ARG_NONNUL
/** /**
* @brief Unlock the container of the accessor. * @brief Unlock the container of the accessor.
* *
* @param accessor The accessor. * @param[in] accessor The accessor
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, otherwise #EINA_FALSE
* *
* If the container of the @p accessor permits it and was previously * @note If the container of the @p accessor permits it and is previously
* locked, it will be unlocked. If @p accessor is @c NULL or if a * locked, it is unlocked. If @p accessor is @c NULL or if a
* problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE * problem occurs, #EINA_FALSE is returned, otherwise #EINA_TRUE
* is returned. If the container is not lockable, it will * is returned. If the container is not lockable, it returns #EINA_TRUE.
* return #EINA_TRUE.
* *
* @warning None of the existing eina data structures are lockable. * @warning None of the existing eina data structures are lockable.
*/ */
@ -311,17 +301,17 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
/** /**
* @def EINA_ACCESSOR_FOREACH * @def EINA_ACCESSOR_FOREACH
* @brief Macro to iterate over all elements easily. * @brief Helper macro to iterate over all the elements easily.
* *
* @param accessor The accessor to use. * @param accessor The accessor to use
* @param counter A counter used by eina_accessor_data_get() when * @param counter A counter used by eina_accessor_data_get() when
* iterating over the container. * iterating over the container.
* @param data Where to store * data, must be a pointer support getting * @param data A pointer to store the data \n
* its address since * eina_accessor_data_get() requires a pointer to * It must be a pointer to support getting
* pointer! * its address since eina_accessor_data_get() requires a pointer.
* *
* This macro allows a convenient way to loop over all elements in an * @details This macro allows a convenient way to loop over all elements in an
* accessor, very similar to EINA_LIST_FOREACH(). * accessor, very similar to EINA_LIST_FOREACH().
* *
* This macro can be used for freeing the data of a list, like in the * This macro can be used for freeing the data of a list, like in the
* following example. It has the same goal as the one documented in * following example. It has the same goal as the one documented in
@ -343,20 +333,20 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
* eina_list_free(list); * eina_list_free(list);
* @endcode * @endcode
* *
* @note if the datatype provides both iterators and accessors prefer * @note If the data type provides both iterators and accessors, prefer
* to use iterators to iterate over, as they're likely to be more * to use iterators to iterate over, as they're likely to be more
* optimized for such task. * optimized for such a task.
* *
* @note this example is not optimal algorithm to release a list since * @note This example is not an optimal algorithm to release a list as
* it will walk the list twice, but it serves as an example. For * it walks through the list twice, but it serves as an example. For an
* optimized version use EINA_LIST_FREE() * optimized version use EINA_LIST_FREE().
* *
* @warning unless explicitly stated in functions returning accessors, * @warning Unless explicitly stated in the function's returning accessors,
* do not modify the accessed object while you walk it, in this * do not modify the accessed object while you walk through it. In this
* example using lists, do not remove list nodes or you might * example using lists, do not remove list nodes or the program might
* crash! This is not a limitation of accessors themselves, * crash. This is not a limitation of the accessors themselves,
* rather in the accessors implementations to keep them as simple * but a limitation in the accessors implementations to keep them as simple
* and fast as possible. * and fast as possible.
*/ */
#define EINA_ACCESSOR_FOREACH(accessor, counter, data) \ #define EINA_ACCESSOR_FOREACH(accessor, counter, data) \
for ((counter) = 0; \ for ((counter) = 0; \
@ -367,8 +357,4 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
* @} * @}
*/ */
/**
* @}
*/
#endif #endif