From 1469a0f261dced6cda2212e9d8462eefb20b40c1 Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Tue, 17 Jul 2012 17:51:10 +0000 Subject: Iterator and Accessor doc improvements. SVN revision: 74004 --- src/include/Eina.h | 16 ++++++++++++++++ src/include/eina_accessor.h | 14 +++++++++++--- src/include/eina_iterator.h | 17 ++++++++++++----- 3 files changed, 39 insertions(+), 8 deletions(-) diff --git a/src/include/Eina.h b/src/include/Eina.h index df4908b..a2aa580 100644 --- a/src/include/Eina.h +++ b/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 diff --git a/src/include/eina_accessor.h b/src/include/eina_accessor.h index 7d52d19..c51c86d 100644 --- a/src/include/eina_accessor.h +++ b/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 - * function is available here. An accessor is deleted with - * eina_accessor_free(). To get the data of an element at a given + * Getting an accessor to access elements of a given container is done through + * the functions of that particular container. There is no function to create + * 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 { diff --git a/src/include/eina_iterator.h b/src/include/eina_iterator.h index 1f47b6e..291b98d 100644 --- a/src/include/eina_iterator.h +++ b/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 - * 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(). + * Getting an iterator to access elements of a given container is done through + * the functions of that particular container. There is no function to create + * a generic iterator as iterators absolutely depend on the container. This + * means you won't find iterator creation function here, those can be found on + * 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 { -- cgit v1.2.1