Container page improvements.

SVN revision: 68278

legacy/eina/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
  *