From fd0d681bce11a5f0f3b15ca27625dcc2c45e8aa8 Mon Sep 17 00:00:00 2001 From: caro Date: Sun, 7 Sep 2008 05:44:00 +0000 Subject: [PATCH] * add doc for iterators * add table of content on the main page git-svn-id: http://svn.enlightenment.org/svn/e/trunk/PROTO/eina@35864 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/include/Eina.h | 73 ++++++++++++++++++++++++++++++++++++++------- src/include/eina_iterator.h | 15 +++++++++- src/lib/eina_iterator.c | 64 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 11 deletions(-) diff --git a/src/include/Eina.h b/src/include/Eina.h index ca13692..db87fba 100644 --- a/src/include/Eina.h +++ b/src/include/Eina.h @@ -24,7 +24,36 @@ * @author Jorge Luis Zapata Muga * @date 2008 * - * @section intro_sec Introduction + * @section eina_toc_sec Table of contents + * + * + * + * @section eina_intro_sec Introduction * * The Eina library is a library that implemente an API for data types * in an efficient way. It also provides some useful tools like @@ -48,25 +77,49 @@ * * @section eina_data_types_sec Eina Data Types * - * @subsection eina_array Array + * @subsection eina_container_subsec Containers * - * @subsection eina_hash Hash Table + * 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. * - * @subsection eina_inlist Inlined List + * @subsubsection eina_array_subsubsec Array * - * @subsection eina_rbtree Inlined Red Black Tree + * @subsubsection eina_hash_subsubsec Hash Table * - * @subsection eina_list List + * @subsubsection eina_inlist_subsubsec Inlined List * - * @subsection eina_stringshare Shared String + * @subsubsection eina_rbtree_subsubsec Inlined Red Black Tree + * + * @subsubsection eina_list_subsubsec List + * + * @subsection eina_stringshare_subsec Shared String + * + * @section eina_access_contents_sec Accessing Data Struct Contents + * + * For the above 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. + * + * @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. + * + * @subsection eina_accessors_subsec Accessor + * + * Accessors can access randomly the elements of a container. * * @section eina_tools_sec Eina Tools * - * @subsection eina_convert Convert Functions + * @subsection eina_convert_subsec Convert Functions * - * @subsection eina_counter Timing Functions + * @subsection eina_counter_subsec Timing Functions * - * @subsection eina_error Error Functions + * @subsection eina_error_subsec Error Functions * * Take a look at the API of @ref Eina_Error_Group. * diff --git a/src/include/eina_iterator.h b/src/include/eina_iterator.h index adcc679..0512971 100644 --- a/src/include/eina_iterator.h +++ b/src/include/eina_iterator.h @@ -20,8 +20,17 @@ #define EINA_ITERATOR_H__ #include "eina_types.h" -#include "eina_error.h" +/** + * @defgroup Eina_Iterator_Group Iterator Functions + * + * @{ + */ + +/** + * @typedef Eina_Iterator + * Type for iterators. + */ typedef struct _Eina_Iterator Eina_Iterator; EAPI void eina_iterator_free (Eina_Iterator *iterator); @@ -33,4 +42,8 @@ EAPI void eina_iterator_foreach (Eina_Iterator *iterator, Eina_Each callback, const void *fdata); +/** + * @} + */ + #endif diff --git a/src/lib/eina_iterator.c b/src/lib/eina_iterator.c index 2f97024..2d8909d 100644 --- a/src/lib/eina_iterator.c +++ b/src/lib/eina_iterator.c @@ -36,12 +36,48 @@ * API * *============================================================================*/ +/** + * @addtogroup Eina_Iterators_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. + * + * 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) { if (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) { @@ -49,6 +85,18 @@ 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 occured, #EINA_FALSE is + * returned, otherwise #EINA_TRUE is returned. + */ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator, void **data) { @@ -56,6 +104,18 @@ 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 immediatly. + */ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, Eina_Each cb, @@ -71,3 +131,7 @@ eina_iterator_foreach(Eina_Iterator *iterator, if (cb(container, data, (void*) fdata) != EINA_TRUE) return ; } } + +/** + * @} + */ -- 2.7.4