* add accessor doc

* fix and add some links


SVN revision: 35865

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
  *

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

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

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,
 /**
  * @}
  */
+
+/**
+ * @}
+ */