diff --git a/legacy/eina/src/include/eina_iterator.h b/legacy/eina/src/include/eina_iterator.h index 56b1718047..6358d5b1e4 100644 --- a/legacy/eina/src/include/eina_iterator.h +++ b/legacy/eina/src/include/eina_iterator.h @@ -24,6 +24,27 @@ #include "eina_types.h" #include "eina_magic.h" + +/** + * @addtogroup Eina_Iterator_Group Iterator Functions + * + * @brief These functions manage iterators 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). 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 + * eina_iterator_free(). To get the data and iterate, use + * eina_iterator_next(). To call a function on all the elements of a + * container, use eina_iterator_foreach(). + * + * @{ + */ + /** * @addtogroup Eina_Content_Access_Group Content Access * @@ -110,17 +131,87 @@ struct _Eina_Iterator */ #define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function) + +/** + * @brief Free an iterator. + * + * @param iterator The iterator to free. + * + * This function frees @p iterator if it is not @c NULL; + */ EAPI void eina_iterator_free(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); + +/** + * @brief Return the container of an iterator. + * + * @param iterator The iterator. + * @return The container which created the iterator. + * + * This function returns the container which created @p iterator. If + * @p iterator is @c NULL, this function returns @c NULL. + */ EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Return the value of the current element and go to the next one. + * + * @param iterator The iterator. + * @param data The data of the element. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns the value of the current element pointed by + * @p iterator in @p data, then goes to the next element. If @p + * iterator is @c NULL or if a problem occurred, #EINA_FALSE is + * returned, otherwise #EINA_TRUE is returned. + */ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator, void **data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Iterate over the container and execute a callback on each element. + * + * @param iterator The iterator. + * @param cb The callback called on each iteration. + * @param fdata The data passed to the callback. + * + * This function iterates over the elements pointed by @p iterator, + * beginning from the current element. For Each element, the callback + * @p cb is called with the data @p fdata. If @p iterator is @c NULL, + * the function returns immediately. Also, if @p cb returns @c + * EINA_FALSE, the iteration stops at that point. + */ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, Eina_Each_Cb callback, const void *fdata) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Lock the container of the iterator. + * + * @param iterator The iterator. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * If the container of the @p iterator permit it, it will be locked. + * If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE is + * returned, otherwise #EINA_TRUE is returned. If the container + * is not lockable, it will return EINA_TRUE. + */ EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); + +/** + * @brief Unlock the container of the iterator. + * + * @param iterator The iterator. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * If the container of the @p iterator permit it and was previously + * locked, it will be unlocked. If @p iterator is @c NULL or if a + * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE + * is returned. If the container is not lockable, it will return + * EINA_TRUE. + */ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); /** @@ -177,4 +268,8 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) * @} */ +/** + * @} + */ + #endif diff --git a/legacy/eina/src/lib/eina_iterator.c b/legacy/eina/src/lib/eina_iterator.c index 66dbbf4ee7..0721066e54 100644 --- a/legacy/eina/src/lib/eina_iterator.c +++ b/legacy/eina/src/lib/eina_iterator.c @@ -92,33 +92,6 @@ eina_iterator_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Iterator_Group Iterator Functions - * - * @brief These functions manage iterators 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). 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 - * eina_iterator_free(). To get the data and iterate, use - * eina_iterator_next(). To call a function on all the elements of a - * container, use eina_iterator_foreach(). - * - * @{ - */ - -/** - * @brief Free an iterator. - * - * @param iterator The iterator to free. - * - * This function frees @p iterator if it is not @c NULL; - */ EAPI void eina_iterator_free(Eina_Iterator *iterator) { @@ -128,15 +101,6 @@ eina_iterator_free(Eina_Iterator *iterator) iterator->free(iterator); } -/** - * @brief Return the container of an iterator. - * - * @param iterator The iterator. - * @return The container which created the iterator. - * - * This function returns the container which created @p iterator. If - * @p iterator is @c NULL, this function returns @c NULL. - */ EAPI void * eina_iterator_container_get(Eina_Iterator *iterator) { @@ -146,18 +110,6 @@ eina_iterator_container_get(Eina_Iterator *iterator) return iterator->get_container(iterator); } -/** - * @brief Return the value of the current element and go to the next one. - * - * @param iterator The iterator. - * @param data The data of the element. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns the value of the current element pointed by - * @p iterator in @p data, then goes to the next element. If @p - * iterator is @c NULL or if a problem occurred, #EINA_FALSE is - * returned, otherwise #EINA_TRUE is returned. - */ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator, void **data) { @@ -171,19 +123,6 @@ eina_iterator_next(Eina_Iterator *iterator, void **data) return iterator->next(iterator, data); } -/** - * @brief Iterate over the container and execute a callback on each element. - * - * @param iterator The iterator. - * @param cb The callback called on each iteration. - * @param fdata The data passed to the callback. - * - * This function iterates over the elements pointed by @p iterator, - * beginning from the current element. For Each element, the callback - * @p cb is called with the data @p fdata. If @p iterator is @c NULL, - * the function returns immediately. Also, if @p cb returns @c - * EINA_FALSE, the iteration stops at that point. - */ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, Eina_Each_Cb cb, @@ -210,17 +149,6 @@ eina_iterator_foreach(Eina_Iterator *iterator, (void) eina_iterator_unlock(iterator); } -/** - * @brief Lock the container of the iterator. - * - * @param iterator The iterator. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * If the container of the @p iterator permit it, it will be locked. - * If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE is - * returned, otherwise #EINA_TRUE is returned. If the container - * is not lockable, it will return EINA_TRUE. - */ EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) { @@ -232,18 +160,6 @@ eina_iterator_lock(Eina_Iterator *iterator) return EINA_TRUE; } -/** - * @brief Unlock the container of the iterator. - * - * @param iterator The iterator. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * If the container of the @p iterator permit it and was previously - * locked, it will be unlocked. If @p iterator is @c NULL or if a - * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE - * is returned. If the container is not lockable, it will return - * EINA_TRUE. - */ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) { @@ -254,7 +170,3 @@ eina_iterator_unlock(Eina_Iterator *iterator) return iterator->unlock(iterator); return EINA_TRUE; } - -/** - * @} - */