Iterator and Accessor doc improvements.

SVN revision: 74004

legacy/eina/src/include/Eina.h

@@ -100,6 +100,7 @@
  *
  * @defgroup Eina_Containers_Group Containers
  *
+ * @section Intro Introduction
  * Containers are data types that hold data and allow iteration over
  * their elements with an @ref Eina_Iterator_Group, or eventually an
  * @ref Eina_Accessor_Group.
@@ -108,6 +109,8 @@
  * of this is that they @b don't check the validity of data structures given to
  * them(@ref Eina_Magic_Group).
  *
+ * @section Choice Choosing container type
+ *
  * The choice of which container to use in each situation is very important in
  * achieving good performance and readable code. The most common container types
  * to be used are:
@@ -130,6 +133,19 @@
  * @warning These are general considerations, every situation is different,
  * don't follow these recommendations blindly.
  *
+ * @section Creation Creating custom container types
+ *
+ * @note Before creating a custom container check if one of the existing ones
+ * doesn't suit your needs. For example, while there is no stack type @ref
+ * Eina_Array_Group is a very good substitute, similarly there is no queue type
+ * however an @ref Eina_List_Group works very well as a queue.
+ *
+ * If creating a custom container type consider allowing access to the data in
+ * your container through @ref Eina_Iterator_Group "Iterators" and @ref
+ * Eina_Accessor_Group "Accessors". To do so your container should have an
+ * iterator creation function and an accessor creation function, these functions
+ * should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor.
+ *
  * @defgroup Eina_Tools_Group Tools
  *
  * Eina tools aims to help application development, providing ways to

legacy/eina/src/include/eina_accessor.h

@@ -86,9 +86,15 @@
  * element in the container). For sequential access, see
  * @ref Eina_Iterator_Group.
  *
- * An accessor is created from container data types, so no creation
+ * Getting an accessor to access elements of a given container is done through
- * function is available here. An accessor is deleted with
+ * the functions of that particular container. There is no function to create
- * eina_accessor_free(). To get the data of an element at a given
+ * a generic accessor as accessors absolutely depend on the container. This
+ * means you won't find accessor creation function here, those can be found on
+ * the documentation of the container type you're using. Though created with
+ * container specific functions accessors are always deleted with the same
+ * function: 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().
  *
@@ -142,6 +148,8 @@ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
 /**
  * @struct _Eina_Accessor
  * Type to provide random access to data structures.
+ *
+ * If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
  */
 struct _Eina_Accessor
 {

legacy/eina/src/include/eina_iterator.h

@@ -93,11 +93,16 @@
  * (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
+ * Getting an iterator to access elements of a given container is done through
- * function is available here. An iterator is deleted with
+ * the functions of that particular container. There is no function to create
- * eina_iterator_free(). To get the data and iterate, use
+ * a generic iterator as iterators absolutely depend on the container. This
- * eina_iterator_next(). To call a function on all the elements of a
+ * means you won't find iterator creation function here, those can be found on
- * container, use eina_iterator_foreach().
+ * the documentation of the container type you're using. Though created with
+ * container specific functions iterators are always deleted with the same
+ * function: 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().
  * 
  * Here an @ref eina_iterator_example_page "example"
  */
@@ -147,6 +152,8 @@ typedef Eina_Bool           (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it);
 /**
  * @struct _Eina_Iterator
  * structure of an iterator
+ *
+ * If creating an iterator remember to set the type using @ref EINA_MAGIC_SET.
  */
 struct _Eina_Iterator
 {