diff --git a/legacy/eina/src/include/Eina.h b/legacy/eina/src/include/Eina.h index db87fbae5f..55926d523a 100644 --- a/legacy/eina/src/include/Eina.h +++ b/legacy/eina/src/include/Eina.h @@ -80,9 +80,9 @@ * @subsection eina_container_subsec Containers * * Containers are data types that hold data and allow iteration over - * their elements with an @ref eina_iterators, or eventually an - * @ref eina_accessors. The only data type that is not a container (in - * that sense) is the @ref eina_stringshare. + * their elements with an @ref eina_iterators_subsec, or eventually an + * @ref eina_accessors_subsec. The only data type that is not a container (in + * that sense) is the @ref eina_stringshare_subsec. * * @subsubsection eina_array_subsubsec Array * @@ -98,20 +98,22 @@ * * @section eina_access_contents_sec Accessing Data Struct Contents * - * For the above data types, you can access to the elements + * For the container data types, you can access to the elements * sequentially with iterators, or randomly with accessors. They are - * created from the data types (named 'containers') themselves and - * allow a genenric way to traverse these data types. + * created from the data types themselves and allow a generic way to + * traverse these data types. * * @subsection eina_iterators_subsec Iterator * - * Iterators allow to access the data of a container in a sequential - * way. They can only access the next element. To look at the API, go - * to @ref Eina_Iterator_Group. + * Iterators allow a sequential access of the data of a + * container. They can only access the next element. To look at the + * API, go to @ref Eina_Iterator_Group. * * @subsection eina_accessors_subsec Accessor * - * Accessors can access randomly the elements of a container. + * Accessors allow a random access of the data of a container. They + * can access an element at any position. To look at the API, go to + * @ref Eina_Accessor_Group. * * @section eina_tools_sec Eina Tools * diff --git a/legacy/eina/src/include/eina_accessor.h b/legacy/eina/src/include/eina_accessor.h index 21d514b978..5b55e302f1 100644 --- a/legacy/eina/src/include/eina_accessor.h +++ b/legacy/eina/src/include/eina_accessor.h @@ -20,8 +20,17 @@ #define EINA_ACCESSOR_H__ #include "eina_types.h" -#include "eina_error.h" +/** + * @defgroup Eina_Accessor_Group Accessor Functions + * + * @{ + */ + +/** + * @typedef Eina_Accessor + * Type for accessors. + */ typedef struct _Eina_Accessor Eina_Accessor; EAPI void eina_accessor_free (Eina_Accessor *accessor); @@ -35,4 +44,8 @@ EAPI void eina_accessor_over (Eina_Accessor *accessor, unsigned int end, const void *fdata); +/** + * @} + */ + #endif diff --git a/legacy/eina/src/lib/eina_accessor.c b/legacy/eina/src/lib/eina_accessor.c index cac87ea1f4..760938151c 100644 --- a/legacy/eina/src/lib/eina_accessor.c +++ b/legacy/eina/src/lib/eina_accessor.c @@ -36,19 +36,54 @@ * API * *============================================================================*/ +/** + * @addtogroup Eina_Content_Access_Group Content Access + * + * @{ + */ + +/** + * @addtogroup Eina_Accessor_Group Accessors 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. + * + * @param accessor The accessor to free. + * + * This function frees @p accessor if it is not @c NULL; + */ EAPI void eina_accessor_free(Eina_Accessor *accessor) { if (accessor) accessor->free(accessor); } -EAPI Eina_Bool -eina_accessor_data_get(Eina_Accessor *accessor, unsigned int position, void **data) -{ - if (!accessor) return EINA_FALSE; - return accessor->get_at(accessor, position, data); -} - +/** + * @brief Return the container of an accessor. + * + * @param accessor The accessor. + * @return The container which created the accessor. + * + * This function returns the container which created @p accessor. If + * @p accessor is @c NULL, this function returns @c NULL. + */ EAPI void * eina_accessor_container_get(Eina_Accessor *accessor) { @@ -56,6 +91,42 @@ eina_accessor_container_get(Eina_Accessor *accessor) return accessor->get_container(accessor); } +/** + * @brief Retrieve the data of an accessor at a given position. + * + * @param accessor The accessor. + * @param position The position of the element. + * @param data The pointer that stores the data to retrieve. + * @return #EINA_TRUE on success, #EIA_FALSE otherwise. + * + * 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, unsigned int position, void **data) +{ + if (!accessor) return EINA_FALSE; + return accessor->get_at(accessor, position, data); +} + +/** + * @brief Iterate over the container and execute a callback on chosen elements. + * + * @param accessor The accessor. + * @param cb The callback called on the chosen elements. + * @param start The position of the first element. + * @param end The position of the last element. + * @param fdata The data passed to the callback. + * + * This function iterates over the elements pointed by @p accessor, + * starting from the element at position @p start and ending to the + * 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 + * or if @p start is greter or equal than @p end, the function returns + * immediatly. + */ EAPI void eina_accessor_over(Eina_Accessor *accessor, Eina_Each cb, @@ -75,4 +146,10 @@ eina_accessor_over(Eina_Accessor *accessor, if (cb(container, data, (void*) fdata) != EINA_TRUE) return ; } +/** + * @} + */ +/** + * @} + */ diff --git a/legacy/eina/src/lib/eina_iterator.c b/legacy/eina/src/lib/eina_iterator.c index 2d8909d0b0..b2ca00851b 100644 --- a/legacy/eina/src/lib/eina_iterator.c +++ b/legacy/eina/src/lib/eina_iterator.c @@ -37,15 +37,21 @@ *============================================================================*/ /** - * @addtogroup Eina_Iterators_Group Iterators Functions + * @addtogroup Eina_Content_Access_Group Content Access + * + * @{ + */ + +/** + * @addtogroup Eina_Iterator_Group Iterators Functions * * @brief These functions manage iterators on containers. * - * These functions allow to iterate over a container in a generic way, - * without knowing which container is used (a bit like iterators in - * the C++ STL). Iterators only allows sequential iteration (that is, - * from an element to the next one). For random iteration, see - * @ref Eina_Accessors. + * 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 @@ -57,7 +63,7 @@ */ /** - * @brief Free an iterator + * @brief Free an iterator. * * @param iterator The iterator to free. * @@ -135,3 +141,7 @@ eina_iterator_foreach(Eina_Iterator *iterator, /** * @} */ + +/** + * @} + */