* add doc for iterators

* add table of content on the main page


SVN revision: 35864

legacy/eina/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
+ *
+ * <ul>
+ *   <li> @ref eina_intro_sec
+ *   <li> @ref eina_data_types_sec
+ *   <ul>
+ *     <li> @ref eina_container_subsec
+ *     <ul>
+ *       <li> @ref eina_array_subsubsec
+ *       <li> @ref eina_hash_subsubsec
+ *       <li> @ref eina_inlist_subsubsec
+ *       <li> @ref eina_rbtree_subsubsec
+ *       <li> @ref eina_list_subsubsec
+ *     </ul>
+ *     <li> @ref eina_stringshare_subsec
+ *   </ul>
+ *   <li> @ref eina_access_contents_sec
+ *   <ul>
+ *     <li> @ref eina_iterators_subsec
+ *     <li> @ref eina_accessors_subsec
+ *   </ul>
+ *   <li> @ref eina_tools_sec
+ *   <ul>
+ *     <li> @ref eina_convert_subsec
+ *     <li> @ref eina_counter_subsec
+ *     <li> @ref eina_error_subsec
+ *   </ul>
+ * </ul>
+ *
+ * @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.
  *

legacy/eina/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

legacy/eina/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 ;
    }
 }
+
+/**
+ * @}
+ */