fix a bit the documentation, but there are still

a lot of doc to write...


SVN revision: 41164

16 files changed, 330 insertions, 226 deletions

diff --git a/src/lib/eina_accessor.c b/src/lib/eina_accessor.c
index 520ec09..f89768a 100644
--- a/src/lib/eina_accessor.c
+++ b/src/lib/eina_accessor.c
@@ -57,12 +57,6 @@
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Content_Access_Group Content Access
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Accessor_Group Accessor Functions
  *
  * @brief These functions manage accessor on containers.
@@ -181,7 +175,3 @@ eina_accessor_over(Eina_Accessor *accessor,
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_array.c b/src/lib/eina_array.c
index 688fa4b..c44bdd4 100644
--- a/src/lib/eina_array.c
+++ b/src/lib/eina_array.c
@@ -351,10 +351,18 @@ eina_array_grow(Eina_Array *array)
  *
  * @return 1 or greater on success, 0 on error.
  *
- * This function just sets up the error module or Eina. It is also
- * called by eina_init(). It returns 0 on failure, otherwise it
- * returns the number of times eina_error_init() has already been
- * called.
+ * This function sets up the error and magic modules or Eina. It is
+ * also called by eina_init(). It returns 0 on failure, otherwise it
+ * returns the number of times it has already been called. See
+ * eina_error_init() and eina_magic_string_init() for the
+ * documentation of the initialisation of the dependency modules.
+ *
+ * When no more Eina arrays are used, call eina_array_shutdown() to shut
+ * down the array module.
+ *
+ * @see eina_error_init()
+ * @see eina_magic_string_init()
+ * @see eina_init()
  */
 EAPI int
 eina_array_init(void)
@@ -392,13 +400,19 @@ eina_array_init(void)
 /**
  * @brief Shut down the array module.
  *
- * @return 0 when the error module is completely shut down, 1 or
+ * @return 0 when the list module is completely shut down, 1 or
  * greater otherwise.
  *
- * This function just shut down the error module set up by
- * eina_array_init(). It is also called by eina_shutdown(). It returns
- * 0 when it is called the same number of times than
- * eina_error_init().
+ * This function shuts down the array module. It returns 0 when it has
+ * been called the same number of times than eina_array_init(). In
+ * that case it shut down the magic and error modules. This function
+ * is also called by eina_shutdown(). See eina_error_shutdown() and
+ * eina_magic_string_shutdown() for the documentation of the
+ * shutting down of the dependency modules.
+ *
+ * @see eina_error_shutdown()
+ * @see eina_magic_string_shutdown()
+ * @see eina_shutdown()
  */
 EAPI int
 eina_array_shutdown(void)
@@ -714,4 +728,3 @@ eina_array_accessor_new(const Eina_Array *array)
 /**
  * @}
  */
-
diff --git a/src/lib/eina_benchmark.c b/src/lib/eina_benchmark.c
index c63776a..1cdf43b 100644
--- a/src/lib/eina_benchmark.c
+++ b/src/lib/eina_benchmark.c
@@ -61,6 +61,9 @@ void *alloca (size_t);
  * @cond LOCAL
  */
 
+#define EINA_BENCHMARK_FILENAME_MASK "bench_%s_%s.gnuplot"
+#define EINA_BENCHMARK_DATA_MASK "bench_%s_%s.%s.data"
+
 typedef struct _Eina_Run Eina_Run;
 struct _Eina_Run
 {
@@ -96,12 +99,6 @@ static int _eina_benchmark_count = 0;
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Benchmark_Group Benchmark
  *
  * These functions allow you to add benchmark framework in a project
@@ -135,8 +132,18 @@ static int _eina_benchmark_count = 0;
  *
  * This function sets up the error, array and counter modules or
  * Eina. It is also called by eina_init(). It returns 0 on failure,
- * otherwise it returns the number of times eina_error_init() has
- * already been called.
+ * otherwise it returns the number of times it has already been
+ * called. See eina_error_init(), eina_array_init() and
+ * eina_counter_init() for the documentation of the initialisation of
+ * the dependency modules.
+ *
+ * When no more Eina benchmarks are used, call
+ * eina_benchmark_shutdown() to shut down the benchmark module.
+ *
+ * @see eina_error_init()
+ * @see eina_array_init()
+ * @see eina_counter_init()
+ * @see eina_init()
  */
 EAPI int
 eina_benchmark_init(void)
@@ -178,7 +185,12 @@ eina_benchmark_init(void)
  *
  * This function shut down the error, array and counter modules set up
  * by eina_array_init(). It is also called by eina_shutdown(). It returns
- * 0 when it is called the same number of times than eina_error_init().
+ * 0 when it is called the same number of times than eina_benchmark_init().
+ *
+ * @see eina_error_shutdown()
+ * @see eina_array_shutdown()
+ * @see eina_counter_shutdown()
+ * @see eina_shutdown()
  */
 EAPI int
 eina_benchmark_shutdown(void)
@@ -326,8 +338,6 @@ eina_benchmark_register(Eina_Benchmark *bench, const char *name, Eina_Benchmark_
  * immediatly. Otherwise, it returns the list of the names of each
  * test.
  */
-#define EINA_BENCHMARK_FILENAME_MASK "bench_%s_%s.gnuplot"
-#define EINA_BENCHMARK_DATA_MASK "bench_%s_%s.%s.data"
 EAPI Eina_Array *
 eina_benchmark_run(Eina_Benchmark *bench)
 {
@@ -436,7 +446,3 @@ eina_benchmark_run(Eina_Benchmark *bench)
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_convert.c b/src/lib/eina_convert.c
index 75cf810..27fac40 100644
--- a/src/lib/eina_convert.c
+++ b/src/lib/eina_convert.c
@@ -80,12 +80,6 @@ EAPI Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH = 0;
  */
 
 /**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Convert_Group Convert
  *
  * These functions allow you to convert integer or real numbers to
@@ -555,7 +549,3 @@ eina_convert_dtoa(double d, char *des)
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_counter.c b/src/lib/eina_counter.c
index 1c61dc7..a4d23bf 100644
--- a/src/lib/eina_counter.c
+++ b/src/lib/eina_counter.c
@@ -147,12 +147,6 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...)
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Counter_Group Counter
  *
  * @brief These functions allow you to get the time spent in a part of a code.
@@ -237,12 +231,20 @@ _eina_counter_asiprintf(char *base, int *position, const char *format, ...)
  *
  * @return 1 or greater on success, 0 on error.
  *
- * This function allocates the memory needed by the counter, which
- * means that it sets up the error module of Eina, and only on Windows
+ * This function sets up the error module of Eina and only on Windows,
  * it initializes the high precision timer. It also registers, only on
  * Windows, the error #EINA_COUNTER_ERROR_WINDOWS. It is also called
  * by eina_init(). It returns 0 on failure, otherwise it returns the
- * number of times it has already been called.
+ * number of times it has already been called. See eina_error_init()
+ * for the documentation of the initialisation of the dependency
+ * modules.
+ *
+ * Once the counter module is not used anymore, then
+ * eina_counter_shutdown() must be called to shut down the counter
+ * module.
+ *
+ * @see eina_error_init()
+ * @see eina_init()
  */
 EAPI int
 eina_counter_init(void)
@@ -275,9 +277,13 @@ eina_counter_init(void)
  * @return 0 when the counter module is completely shut down, 1 or
  * greater otherwise.
  *
- * This function just shuts down the error module. It is also called by
- * eina_shutdown(). It returns 0 when it is called the same number of
- * times than eina_counter_init().
+ * This function shuts down the counter module set up by
+ * eina_counter_init(). It is called by eina_shutdown(). It
+ * returns 0 when it is called the same number of times than
+ * eina_counter_init().
+ *
+ * @see eina_error_shutdown()
+ * @see eina_shutdown()
  */
 EAPI int
 eina_counter_shutdown(void)
@@ -479,7 +485,3 @@ eina_counter_dump(Eina_Counter *counter)
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_error.c b/src/lib/eina_error.c
index a3f0a22..0cd8f45 100644
--- a/src/lib/eina_error.c
+++ b/src/lib/eina_error.c
@@ -420,12 +420,6 @@ static const char *_colors[EINA_ERROR_LEVELS] = {
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Error_Group Error
  *
  * @brief These functions provide error management for projects.
@@ -501,14 +495,14 @@ EAPI Eina_Error EINA_ERROR_OUT_OF_MEMORY = 0;
  */
 
 /**
- * @brief Initialize the error system.
+ * @brief Initialize the error module.
  *
  * @return 1 or greater on success, 0 on error.
  *
- * This function sets up the error system or Eina. It is called by
- * eina_init() and by all subsystems initialization functions. It
- * returns 0 on failure, otherwise it returns the number of times it
- * is called.
+ * This function sets up the error module of Eina. It is called by
+ * eina_init() and by all modules initialization functions. It returns
+ * @c 0 on failure, otherwise it returns the number of times it is
+ * called.
  *
  * The default error level value is set by default to
  * #EINA_ERROR_LEVEL_DBG if Eina is compiled with debug mode, or to
@@ -520,9 +514,13 @@ EAPI Eina_Error EINA_ERROR_OUT_OF_MEMORY = 0;
  * #EINA_ERROR_LEVEL_INFO and #EINA_ERROR_LEVEL_DBG. That value can
  * also be set later with eina_error_log_level_set().
  *
- * If you call explicitly this function and once the error subsystem
- * is not used anymore, then eina_error_shutdown() must be called to
- * shut down the error system.
+ * This function registers the error #EINA_ERROR_OUT_OF_MEMORY.
+ *
+ * Once the error module is not used anymore, then
+ * eina_error_shutdown() must be called to shut down the error
+ * module.
+ *
+ * @see eina_init()
  */
 EAPI int eina_error_init(void)
 {
@@ -541,16 +539,18 @@ EAPI int eina_error_init(void)
 }
 
 /**
- * @brief Shut down the error system.
+ * @brief Shut down the error module.
  *
- * @return 0 when the error system is completely shut down, 1 or
+ * @return 0 when the error module is completely shut down, 1 or
  * greater otherwise.
  *
- * This function shut down the error system set up by
+ * This function shuts down the error module set up by
  * eina_error_init(). It is called by eina_shutdown() and by all
- * subsystems shutdown functions. It returns 0 when it is called the
- * same number of times than eina_error_init() and it clears the error
- * list.
+ * modules shutdown functions. It returns 0 when it is called the
+ * same number of times than eina_error_init(). In that case it clears
+ * the error list.
+ *
+ * @see eina_shutdown()
  */
 EAPI int eina_error_shutdown(void)
 {
@@ -798,7 +798,3 @@ EAPI void eina_error_log_level_set(Eina_Error_Level level)
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_file.c b/src/lib/eina_file.c
index a2a681e..c958f9e 100644
--- a/src/lib/eina_file.c
+++ b/src/lib/eina_file.c
@@ -71,13 +71,7 @@ void *alloca (size_t);
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_File_Group Memory File
+ * @addtogroup Eina_File_Group File
  *
  * @brief Functions to traverse directories and split paths.
  *
@@ -279,7 +273,3 @@ eina_file_split(char *path)
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_hash.c b/src/lib/eina_hash.c
index 538daf1..ac32b6c 100644
--- a/src/lib/eina_hash.c
+++ b/src/lib/eina_hash.c
@@ -613,18 +613,6 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it)
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Hash_Group Hash Table
  *
  * @brief give a small description here : what it is for, what it does
@@ -654,10 +642,16 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it)
  *
  * @return 1 or greater on success, 0 on error.
  *
- * This function just sets up the error module or Eina. It is also
- * called by eina_init(). It returns 0 on failure, otherwise it
- * returns the number of times eina_error_init() has already been
- * called.
+ * This function sets up the error module of Eina. It is also called
+ * by eina_init(). It returns 0 on failure, otherwise it returns the
+ * number of times it has already been called. See eina_error_init()
+ * for the documentation of the initialisation of the dependency
+ * module.
+ *
+ * When no more Eina hash tables are used, call eina_hash_shutdown()
+ * to shut down the array module.
+ *
+ * @see eina_error_init()
  */
 EAPI int
 eina_hash_init(void)
@@ -1505,11 +1499,3 @@ eina_hash_superfast(const char *key, int len)
 /**
  * @}
  */
-
-/**
- * @}
- */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_inlist.c b/src/lib/eina_inlist.c
index 29d5900..c9fd58f 100644
--- a/src/lib/eina_inlist.c
+++ b/src/lib/eina_inlist.c
@@ -34,6 +34,10 @@
  *                                  Local                                     *
  *============================================================================*/
 
+/**
+ * @cond LOCAL
+ */
+
 typedef struct _Eina_Iterator_Inlist Eina_Iterator_Inlist;
 typedef struct _Eina_Accessor_Inlist Eina_Accessor_Inlist;
 
@@ -126,6 +130,11 @@ eina_inlist_accessor_free(Eina_Accessor_Inlist *it) {
 	free(it);
 }
 
+/**
+ * @endcond
+ */
+
+
 /*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
@@ -135,9 +144,13 @@ eina_inlist_accessor_free(Eina_Accessor_Inlist *it) {
  *============================================================================*/
 
 /**
- * To be documented
- * FIXME: To be fixed
+ * @addtogroup Eina_Inline_List_Group Inline List
+ *
+ * @brief These functions provide inline list management.
+ *
+ * @{
  */
+
 EAPI Eina_Inlist *
 eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l)
 {
@@ -161,10 +174,7 @@ eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l)
    list->last = new_l;
    return list;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l)
 {
@@ -182,10 +192,7 @@ eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l)
    list->last = NULL;
    return new_l;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_append_relative(Eina_Inlist *list,
 			    Eina_Inlist *new_l,
@@ -207,10 +214,7 @@ eina_inlist_append_relative(Eina_Inlist *list,
    }
    return eina_inlist_append(list, new_l);
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_prepend_relative(Eina_Inlist *list,
 			     Eina_Inlist *new_l,
@@ -238,10 +242,7 @@ eina_inlist_prepend_relative(Eina_Inlist *list,
    }
    return eina_inlist_prepend(list, new_l);
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item)
 {
@@ -268,10 +269,7 @@ eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item)
    item->prev = NULL;
    return return_l;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item)
 {
@@ -296,10 +294,7 @@ eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item)
 
    return item;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item)
 {
@@ -331,10 +326,7 @@ eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item)
    l->last = item;
    return l;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Inlist *
 eina_inlist_find(Eina_Inlist *list, Eina_Inlist *item)
 {
@@ -420,3 +412,7 @@ eina_inlist_accessor_new(const Eina_Inlist *list)
 
    return &it->accessor;
 }
+
+/**
+ * @}
+ */
diff --git a/src/lib/eina_iterator.c b/src/lib/eina_iterator.c
index b2f7383..24644d0 100644
--- a/src/lib/eina_iterator.c
+++ b/src/lib/eina_iterator.c
@@ -58,12 +58,6 @@
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Content_Access_Group Content Access
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Iterator_Group Iterator Functions
  *
  * @brief These functions manage iterators on containers.
@@ -175,7 +169,3 @@ eina_iterator_foreach(Eina_Iterator *iterator,
 /**
  * @}
  */
-
-/**
- * @}
- */
diff --git a/src/lib/eina_list.c b/src/lib/eina_list.c
index 352b042..395bffc 100644
--- a/src/lib/eina_list.c
+++ b/src/lib/eina_list.c
@@ -423,7 +423,7 @@ eina_list_sort_merge(Eina_List *a, Eina_List *b, Eina_Compare_Cb func)
 /**
  * @addtogroup Eina_List_Group List
  *
- * @brief These functions provide single linked list management.
+ * @brief These functions provide double linked list management.
  *
  * For more information, you can look at the @ref tutorial_list_page.
  *
@@ -435,10 +435,25 @@ eina_list_sort_merge(Eina_List *a, Eina_List *b, Eina_Compare_Cb func)
  *
  * @return 1 or greater on success, 0 on error.
  *
- * This function just sets up the error module or Eina. It is also
- * called by eina_init(). It returns 0 on failure, otherwise it
- * returns the number of times eina_error_init() has already been
- * called.
+ * This function sets up the error, magic and mempool modules of
+ * Eina. It is also called by eina_init(). It returns 0 on failure,
+ * otherwise it returns the number of times it has already been
+ * called. If Eina has been configured with the default memory pool,
+ * then the memory pool used in an Eina list will be
+ * "pass_through". Otherwise, the environment variable EINA_MEMPOOL is
+ * read and its value is chosen as memory pool ; if EINA_MEMPOOL is
+ * not defined, then the "chained_mempool" memory pool is chosen. If
+ * the memory pool is not found, then eina_list_init() return @c 0.
+ * See eina_error_init(), eina_magic_string_init() and
+ * eina_mempool_init() for the documentation of the initialisation of
+ * the dependency modules.
+ *
+ * When no more Eina lists are used, call eina_list_shutdown() to shut
+ * down the list module.
+ *
+ * @see eina_error_init()
+ * @see eina_magic_string_init()
+ * @see eina_mempool_init()
  */
 EAPI int
 eina_list_init(void)
@@ -516,13 +531,13 @@ eina_list_init(void)
 /**
  * @brief Shut down the list module.
  *
- * @return 0 when the error module is completely shut down, 1 or
+ * @return 0 when the list module is completely shut down, 1 or
  * greater otherwise.
  *
- * This function just shut down the error module set up by
- * eina_list_init(). It is also called by eina_shutdown(). It returns
- * 0 when it is called the same number of times than
- * eina_error_init().
+ * This function shuts down the mempool, magic and error modules set
+ * up by eina_list_init(). It is also called by eina_shutdown(). It
+ * returns 0 when it is called the same number of times than
+ * eina_list_init().
  */
 EAPI int
 eina_list_shutdown(void)
diff --git a/src/lib/eina_magic.c b/src/lib/eina_magic.c
index bf7187b..9ca2a52 100644
--- a/src/lib/eina_magic.c
+++ b/src/lib/eina_magic.c
@@ -37,6 +37,10 @@
  *                                  Local                                     *
  *============================================================================*/
 
+/**
+ * @cond LOCAL
+ */
+
 #ifdef EINA_MAGIC_DEBUG
 
 typedef struct _Eina_Magic_String Eina_Magic_String;
@@ -53,6 +57,10 @@ static Eina_Inlist *strings = NULL;
 
 #endif
 
+/**
+ * @endcond
+ */
+
 /*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
@@ -61,6 +69,28 @@ static Eina_Inlist *strings = NULL;
  *                                   API                                      *
  *============================================================================*/
 
+/**
+ * @addtogroup Eina_Magic_Group Magic
+ *
+ * @brief These functions provide magic checks management for projects.
+ *
+ * @{
+ */
+
+/**
+ * @brief Initialize the magic module.
+ *
+ * @return 1 or greater.
+ *
+ * This function just increases a reference counter. If the magic
+ * module is disabled at configure time, then it always returns @c 1.
+ *
+ * Once the magic module is not used anymore, then
+ * eina_magic_shutdown() must be called to shut down the magic
+ * module.
+ *
+ * @see eina_init()
+ */
 EAPI int
 eina_magic_string_init(void)
 {
@@ -73,6 +103,21 @@ eina_magic_string_init(void)
 #endif
 }
 
+/**
+ * @brief Shut down the magic module.
+ *
+ * @return 0 when the magic module is completely shut down, 1 or
+ * greater otherwise.
+ *
+ * This function shuts down the magic module set up by
+ * eina_magic_string_init(). It is called by eina_shutdown() and by
+ * all modules shutdown functions. It returns 0 when it is called the
+ * same number of times than eina_magic_string_init(). In that case it
+ * clears the magic list and return @c 0. If the magic module is
+ * disabled at configure time, then it always returns @c 0.
+ *
+ * @see eina_shutdown()
+ */
 EAPI int
 eina_magic_string_shutdown(void)
 {
@@ -102,6 +147,16 @@ eina_magic_string_shutdown(void)
 
 #ifdef EINA_MAGIC_DEBUG
 
+/**
+ * @brief Return the string associated to the given magic identifier.
+ *
+ * @param magic The magic identifier.
+ * @return The string associated to the identifier.
+ *
+ * This function returns the string associated to @p magic. If none
+ * are found, the this function returns @c NULL. The returned value
+ * must not be freed.
+ */
 EAPI const char*
 eina_magic_string_get(Eina_Magic magic)
 {
@@ -114,6 +169,17 @@ eina_magic_string_get(Eina_Magic magic)
    return NULL;
 }
 
+/**
+ * @brief Set the string associated to the given magic identifier.
+ *
+ * @param magic The magic identifier.
+ * @param The string associated to the identifier.
+ *
+ * This function sets the string @p magic_name to @p magic. If a
+ * string is already associated to @p magic, then it is freed and @p
+ * magic_name is duplicated. Otherwise, it is added to the list of
+ * magic strings.
+ */
 EAPI void
 eina_magic_string_set(Eina_Magic magic, const char *magic_name)
 {
@@ -131,6 +197,8 @@ eina_magic_string_set(Eina_Magic magic, const char *magic_name)
        }
 
    ems = malloc(sizeof (Eina_Magic_String));
+   if (!ems)
+     return;
    ems->magic = magic;
    if (magic_name)
      ems->string = strdup(magic_name);
@@ -140,6 +208,29 @@ eina_magic_string_set(Eina_Magic magic, const char *magic_name)
    strings = eina_inlist_prepend(strings, EINA_INLIST_GET(ems));
 }
 
+/**
+ * @brief Display a message or abort is a magic check failed.
+ *
+ * @param d The checked data pointer.
+ * @param m The magic identifer to check.
+ * @param req_m The requested magic identifier to check.
+ * @param file The file in which the magic check failed.
+ * @param fcn The function in which the magic check failed.
+ * @param line The line at which the magic check failed.
+ *
+ * This function displays an error message if a magic check has
+ * failed, using the following logic in the following order:
+ * @li If @p d is @c NULL, a message warns about a @c NULL pointer.
+ * @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
+ * warns about a handle that was already freed.
+ * @li Otherwise, if @p m is equal to @p req_m, a message warns about
+ * a handle that is of wrong type.
+ * @li Otherwise, a message warns you about ab-using that function...
+ *
+ * If the environment variable EINA_ERROR_ABORT is set, abort() is
+ * called and the program stops. It is useful for debugging programs
+ * with gdb.
+ */
 EAPI void
 eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line)
 {
@@ -185,3 +276,7 @@ eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const
 }
 
 #endif
+
+/**
+ * @}
+ */
diff --git a/src/lib/eina_main.c b/src/lib/eina_main.c
index cec96bc..756f439 100644
--- a/src/lib/eina_main.c
+++ b/src/lib/eina_main.c
@@ -35,6 +35,20 @@
 #include "eina_rectangle.h"
 
 /*============================================================================*
+ *                                  Local                                     *
+ *============================================================================*/
+
+/**
+ * @cond LOCAL
+ */
+
+static int _eina_main_count = 0;
+
+/**
+ * @endcond
+ */
+
+/*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
 
@@ -42,8 +56,28 @@
  *                                   API                                      *
  *============================================================================*/
 
-static int _eina_main_count = 0;
+/**
+ * @addtogroup Eina_Main_Group Main
+ *
+ * @brief These functions provide general initialisation and shut down
+ * functions.
+ *
+ * @{
+ */
 
+/**
+ * @brief Initialize the Eina library.
+ *
+ * @return 1 or greater on success, 0 on error.
+ *
+ * This function sets up all the eina modules. It returns 0 on
+ * failure (that is, when one of the module fails to initialize),
+ * otherwise it returns the number of times it has already been
+ * called.
+ *
+ * When Eina is not used anymore, call eina_shutdown() to shut down
+ * the Eina library.
+ */
 EAPI int
 eina_init(void)
 {
@@ -117,6 +151,20 @@ eina_init(void)
    return 0;
 }
 
+/**
+ * @brief Shut down the Eina library.
+ *
+ * @return 0 when all the modules is completely shut down, 1 or
+ * greater otherwise.
+ *
+ * This function shuts down the Eina library. It returns 0 when it has
+ * been called the same number of times than eina_init(). In that case
+ * it shut down all the Eina modules.
+ *
+ * Once this function succeeds (that is, @c 0 is returned), you must
+ * not call any of the Eina function anymore. You must call
+ * eina_init() again to use the Eina functions again.
+ */
 EAPI int
 eina_shutdown(void)
 {
@@ -136,3 +184,6 @@ eina_shutdown(void)
    return --_eina_main_count;
 }
 
+/**
+ * @}
+ */
diff --git a/src/lib/eina_mempool.c b/src/lib/eina_mempool.c
index c28ec25..c495e13 100644
--- a/src/lib/eina_mempool.c
+++ b/src/lib/eina_mempool.c
@@ -35,6 +35,10 @@
  *                                  Local                                     *
  *============================================================================*/
 
+/**
+ * @cond LOCAL
+ */
+
 static Eina_Hash *_backends;
 static Eina_Array *_modules;
 static int _init_count = 0;
@@ -93,6 +97,10 @@ Eina_Bool fixed_bitmap_init(void);
 void fixed_bitmap_shutdown(void);
 #endif
 
+/**
+ * @endcond
+ */
+
 /*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
@@ -111,11 +119,16 @@ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be)
  *                                   API                                      *
  *============================================================================*/
 
-EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0;
-
 /**
+ * @addtogroup Eina_Memory_Pool_Group Memory Pool
+ *
+ * @brief These functions provide memory pool management.
  *
+ * @{
  */
+
+EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0;
+
 EAPI int
 eina_mempool_init(void)
 {
@@ -184,9 +197,6 @@ eina_mempool_init(void)
 
 }
 
-/**
- *
- */
 EAPI int
 eina_mempool_shutdown(void)
 {
@@ -220,9 +230,6 @@ eina_mempool_shutdown(void)
 	return 0;
 }
 
-/**
- *
- */
 EAPI Eina_Mempool *
 eina_mempool_new(const char *name, const char *context, const char *options, ...)
 {
@@ -238,9 +245,6 @@ eina_mempool_new(const char *name, const char *context, const char *options, ...
 	return mp;
 }
 
-/**
- *
- */
 EAPI void eina_mempool_delete(Eina_Mempool *mp)
 {
         EINA_SAFETY_ON_NULL_RETURN(mp);
@@ -262,3 +266,7 @@ EAPI void eina_mempool_statistics(Eina_Mempool *mp)
         EINA_SAFETY_ON_NULL_RETURN(mp->backend.statistics);
 	mp->backend.statistics(mp->backend_data);
 }
+
+/**
+ * @}
+ */
diff --git a/src/lib/eina_module.c b/src/lib/eina_module.c
index 9398ebe..2ae4902 100644
--- a/src/lib/eina_module.c
+++ b/src/lib/eina_module.c
@@ -158,9 +158,13 @@ static int _eina_module_count = 0;
  *============================================================================*/
 
 /**
- * To be documented
- * FIXME: To be fixed
+ * @addtogroup Eina_Module_Group Module
+ *
+ * @brief These functions provide module management.
+ *
+ * @{
  */
+
 EAPI int
 eina_module_init(void)
 {
@@ -177,10 +181,7 @@ eina_module_init(void)
 end_init:
 	return _eina_module_count;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI int
 eina_module_shutdown(void)
 {
@@ -197,10 +198,7 @@ eina_module_shutdown(void)
 end_shutdown:
 	return _eina_module_count;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Bool eina_module_load(Eina_Module *m)
 {
 	void *dl_handle;
@@ -236,10 +234,7 @@ loaded:
 	eina_error_set(0);
 	return EINA_TRUE;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Bool eina_module_unload(Eina_Module *m)
 {
 	Eina_Module_Shutdown *shut;
@@ -257,10 +252,7 @@ EAPI Eina_Bool eina_module_unload(Eina_Module *m)
 	}
 	return EINA_FALSE;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Module * eina_module_new(const char *file)
 {
 	Eina_Module *m;
@@ -276,10 +268,7 @@ EAPI Eina_Module * eina_module_new(const char *file)
 
 	return m;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI Eina_Bool eina_module_delete(Eina_Module *m)
 {
 	EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE);
@@ -293,20 +282,14 @@ EAPI Eina_Bool eina_module_delete(Eina_Module *m)
 	free(m);
 	return EINA_TRUE;
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI void * eina_module_symbol_get(Eina_Module *m, const char *symbol)
 {
 	EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL);
 	EINA_SAFETY_ON_NULL_RETURN_VAL(m->handle, NULL);
 	return dlsym(m->handle, symbol);
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI const char * eina_module_file_get(Eina_Module *m)
 {
 	EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL);
@@ -408,6 +391,7 @@ EAPI Eina_Array * eina_module_list_get(Eina_Array *array, const char *path, unsi
 
 	return list_get_cb_data.array;
 }
+
 /**
  * Load every module on the list of modules
  * @param list The list of modules
@@ -423,10 +407,7 @@ EAPI void eina_module_list_load(Eina_Array *array)
 	EINA_ARRAY_ITER_NEXT(array, i, m, iterator)
 		eina_module_load(m);
 }
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
 EAPI void eina_module_list_unload(Eina_Array *array)
 {
 	Eina_Array_Iterator iterator;
@@ -438,6 +419,7 @@ EAPI void eina_module_list_unload(Eina_Array *array)
 	EINA_ARRAY_ITER_NEXT(array, i, m, iterator)
 		eina_module_unload(m);
 }
+
 /**
  * Helper function that iterates over the list of modules and calls
  * eina_module_delete on each
@@ -455,3 +437,7 @@ EAPI void eina_module_list_delete(Eina_Array *array)
 
 	eina_array_flush(array);
 }
+
+/**
+ * @}
+ */
diff --git a/src/lib/eina_stringshare.c b/src/lib/eina_stringshare.c
index a165768..5e3c62a 100644
--- a/src/lib/eina_stringshare.c
+++ b/src/lib/eina_stringshare.c
@@ -777,12 +777,6 @@ _eina_stringshare_node_alloc(int slen)
  *============================================================================*/
 
 /**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
  * @addtogroup Eina_Stringshare_Group Stringshare
  *
  * These functions allow you to store one copy of a string, and use it
@@ -1293,7 +1287,3 @@ eina_stringshare_dump(void)
 /**
  * @}
  */
-
-/**
- * @}
- */