Container page improvements.

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@68278 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/src/include/Eina.h b/src/include/Eina.h
index 2134e90..d99b129 100644 (file)
--- a/src/include/Eina.h
+++ b/src/include/Eina.h
@@ -104,6 +104,31 @@
  * their elements with an @ref Eina_Iterator_Group, or eventually an
  * @ref Eina_Accessor_Group.
  *
+ * The containers in eina are designed with performance in mind, one consequence
+ * of this is that they @b don't check the validity of data structures given to
+ * them(@ref Eina_Magic_Group).
+ *
+ * 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:
+ * @li List
+ * @li Inline list
+ * @li Array
+ * @li Inline array
+ * @li Hash
+ *
+ * All types have virtues and vices. The following considerations are good
+ * starting point in deciding which container to use:
+ * @li Hashes are appropriate for datasets which will be searched often;
+ * @li arrays are good when accessing members by position;
+ * @li lists provide good versatility for adding elements in any position with
+ * minimal overhead;
+ * @li inline arrays use very little memory and don't cause fragmentation and
+ * therefore are a good option in memory constrained systems;
+ * @li inline lists are the appropriate type to use when the flexibility of a
+ * list is required but the overhead of pointer indirection is not acceptable.
+ * @warning These are general considerations, every situation is different,
+ * don't follow these recommendations blindly.
  *
  * @defgroup Eina_Tools_Group Tools
  *