summaryrefslogtreecommitdiff
path: root/legacy/eina
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2012-07-17 17:51:10 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2012-07-17 17:51:10 +0000
commitb03e262ed8c76ddfd4fc9add7db46035fde0c1a5 (patch)
treeb705d9d0e738dcd7ab99e517d3d5c7a27b271d55 /legacy/eina
parent30cff2b5fb94cd58d175a61f3961bc3bccbb96c8 (diff)
Iterator and Accessor doc improvements.
SVN revision: 74004
Diffstat (limited to 'legacy/eina')
-rw-r--r--legacy/eina/src/include/Eina.h16
-rw-r--r--legacy/eina/src/include/eina_accessor.h14
-rw-r--r--legacy/eina/src/include/eina_iterator.h17
3 files changed, 39 insertions, 8 deletions
diff --git a/legacy/eina/src/include/Eina.h b/legacy/eina/src/include/Eina.h
index df4908b89f..a2aa580275 100644
--- a/legacy/eina/src/include/Eina.h
+++ b/legacy/eina/src/include/Eina.h
@@ -100,6 +100,7 @@
100 * 100 *
101 * @defgroup Eina_Containers_Group Containers 101 * @defgroup Eina_Containers_Group Containers
102 * 102 *
103 * @section Intro Introduction
103 * Containers are data types that hold data and allow iteration over 104 * Containers are data types that hold data and allow iteration over
104 * their elements with an @ref Eina_Iterator_Group, or eventually an 105 * their elements with an @ref Eina_Iterator_Group, or eventually an
105 * @ref Eina_Accessor_Group. 106 * @ref Eina_Accessor_Group.
@@ -108,6 +109,8 @@
108 * of this is that they @b don't check the validity of data structures given to 109 * of this is that they @b don't check the validity of data structures given to
109 * them(@ref Eina_Magic_Group). 110 * them(@ref Eina_Magic_Group).
110 * 111 *
112 * @section Choice Choosing container type
113 *
111 * The choice of which container to use in each situation is very important in 114 * The choice of which container to use in each situation is very important in
112 * achieving good performance and readable code. The most common container types 115 * achieving good performance and readable code. The most common container types
113 * to be used are: 116 * to be used are:
@@ -130,6 +133,19 @@
130 * @warning These are general considerations, every situation is different, 133 * @warning These are general considerations, every situation is different,
131 * don't follow these recommendations blindly. 134 * don't follow these recommendations blindly.
132 * 135 *
136 * @section Creation Creating custom container types
137 *
138 * @note Before creating a custom container check if one of the existing ones
139 * doesn't suit your needs. For example, while there is no stack type @ref
140 * Eina_Array_Group is a very good substitute, similarly there is no queue type
141 * however an @ref Eina_List_Group works very well as a queue.
142 *
143 * If creating a custom container type consider allowing access to the data in
144 * your container through @ref Eina_Iterator_Group "Iterators" and @ref
145 * Eina_Accessor_Group "Accessors". To do so your container should have an
146 * iterator creation function and an accessor creation function, these functions
147 * should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor.
148 *
133 * @defgroup Eina_Tools_Group Tools 149 * @defgroup Eina_Tools_Group Tools
134 * 150 *
135 * Eina tools aims to help application development, providing ways to 151 * Eina tools aims to help application development, providing ways to
diff --git a/legacy/eina/src/include/eina_accessor.h b/legacy/eina/src/include/eina_accessor.h
index 7d52d19123..c51c86da6e 100644
--- a/legacy/eina/src/include/eina_accessor.h
+++ b/legacy/eina/src/include/eina_accessor.h
@@ -86,9 +86,15 @@
86 * element in the container). For sequential access, see 86 * element in the container). For sequential access, see
87 * @ref Eina_Iterator_Group. 87 * @ref Eina_Iterator_Group.
88 * 88 *
89 * An accessor is created from container data types, so no creation 89 * Getting an accessor to access elements of a given container is done through
90 * function is available here. An accessor is deleted with 90 * the functions of that particular container. There is no function to create
91 * eina_accessor_free(). To get the data of an element at a given 91 * a generic accessor as accessors absolutely depend on the container. This
92 * means you won't find accessor creation function here, those can be found on
93 * the documentation of the container type you're using. Though created with
94 * container specific functions accessors are always deleted with the same
95 * function: eina_accessor_free().
96 *
97 * To get the data of an element at a given
92 * position, use eina_accessor_data_get(). To call a function on 98 * position, use eina_accessor_data_get(). To call a function on
93 * chosen elements of a container, use eina_accessor_over(). 99 * chosen elements of a container, use eina_accessor_over().
94 * 100 *
@@ -142,6 +148,8 @@ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
142/** 148/**
143 * @struct _Eina_Accessor 149 * @struct _Eina_Accessor
144 * Type to provide random access to data structures. 150 * Type to provide random access to data structures.
151 *
152 * If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
145 */ 153 */
146struct _Eina_Accessor 154struct _Eina_Accessor
147{ 155{
diff --git a/legacy/eina/src/include/eina_iterator.h b/legacy/eina/src/include/eina_iterator.h
index 1f47b6e3e6..291b98d66f 100644
--- a/legacy/eina/src/include/eina_iterator.h
+++ b/legacy/eina/src/include/eina_iterator.h
@@ -93,11 +93,16 @@
93 * (that is, from an element to the next one). For random access, see 93 * (that is, from an element to the next one). For random access, see
94 * @ref Eina_Accessor_Group. 94 * @ref Eina_Accessor_Group.
95 * 95 *
96 * An iterator is created from container data types, so no creation 96 * Getting an iterator to access elements of a given container is done through
97 * function is available here. An iterator is deleted with 97 * the functions of that particular container. There is no function to create
98 * eina_iterator_free(). To get the data and iterate, use 98 * a generic iterator as iterators absolutely depend on the container. This
99 * eina_iterator_next(). To call a function on all the elements of a 99 * means you won't find iterator creation function here, those can be found on
100 * container, use eina_iterator_foreach(). 100 * the documentation of the container type you're using. Though created with
101 * container specific functions iterators are always deleted with the same
102 * function: eina_iterator_free().
103 *
104 * To get the data and iterate, use eina_iterator_next(). To call a function on
105 * all the elements of a container, use eina_iterator_foreach().
101 * 106 *
102 * Here an @ref eina_iterator_example_page "example" 107 * Here an @ref eina_iterator_example_page "example"
103 */ 108 */
@@ -147,6 +152,8 @@ typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it);
147/** 152/**
148 * @struct _Eina_Iterator 153 * @struct _Eina_Iterator
149 * structure of an iterator 154 * structure of an iterator
155 *
156 * If creating an iterator remember to set the type using @ref EINA_MAGIC_SET.
150 */ 157 */
151struct _Eina_Iterator 158struct _Eina_Iterator
152{ 159{