eina document eina mempools' API.

Except for the weird _Eina_Mempool_Backend_ABI1/ABI2 work-around which is
completely internal and probably is of interest to noone (the only person
on Earth who will be interested in it in a decade will hate me for skipping
it).

2 files changed, 44 insertions, 20 deletions

diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x
index c33af06971..59bf523e1e 100644
--- a/src/lib/eina/eina_inline_mempool.x
+++ b/src/lib/eina/eina_inline_mempool.x
@@ -27,14 +27,30 @@ typedef struct _Eina_Mempool_Backend_ABI2 Eina_Mempool_Backend_ABI2;
 
 struct _Eina_Mempool_Backend
 {
+   /** Name of the mempool backend */
    const char *name;
+   /** Function to initialize the backend. */
    void *(*init)(const char *context, const char *options, va_list args);
+   /** Function to free memory back to the mempool. */
    void (*free)(void *data, void *element);
+   /** Function to allocate memory from the mempool. */
    void *(*alloc)(void *data, unsigned int size);
+   /** Function to change the size of a block of memory that is currently
+    * allocated. */
    void *(*realloc)(void *data, void *element, unsigned int size);
+   /** Function to trigger a garbage collection; can be NULL if the feature
+    * isn't available in the backend. */
    void (*garbage_collect)(void *data);
+   /** Report statistics on the content of the mempool; can be NULL if the
+    * feature isn't available in the backend. */
    void (*statistics)(void *data);
+   /** Function to destroy the backend, freeing memory back to the operating
+    * system. */
    void (*shutdown)(void *data);
+   /** Function to optimize the placement of objects in the mempool (it's
+    * different from garbage_collect); can be NULL if the feature isn't
+    * available in the backend.
+    * @see Eina_Mempool_Repack_Cb */
    void (*repack)(void *data, Eina_Mempool_Repack_Cb cb, void *cb_data);
 };
 
diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h
index 9e1d97fcc1..7aaffc2652 100644
--- a/src/lib/eina/eina_mempool.h
+++ b/src/lib/eina/eina_mempool.h
@@ -71,8 +71,14 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend;
 
 /**
  * @typedef Eina_Mempool_Repack_Cb
- * Type for a callback who need to unreference an old object from a mempool
- * and reference the new one instead. Memcpy is taken care by the mempool.
+ *
+ * Type for a callback which is called when the mempool "repacks" its data,
+ * i.e. moves it around to optimize the way it is stored in memory. This is
+ * useful to improve data locality and to free internal pools back to the OS.
+ *
+ * The callback needs to update users of the data to stop accessing the object
+ * from the old location and access it using the new location instead. The copy
+ * of memory is taken care of by the mempool.
  */
 typedef void (*Eina_Mempool_Repack_Cb)(void *dst, void *src, void *data);
 
@@ -80,21 +86,22 @@ EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE;
 
 /**
  *
- * @brief TODO
+ * @brief Create a new mempool of the given type
  *
- * @param module
- * @param context
- * @param options
+ * @param name Name of the mempool kind to use.
+ * @param context Identifier of the mempool created (for debug purposes).
+ * @param options Unused. Use the variable arguments list instead to pass options to the mempool.
+ * @param ... Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big.
  * @return Newly allocated mempool instance, NULL otherwise.
  *
  */
-EAPI Eina_Mempool  *eina_mempool_add(const char *module, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+EAPI Eina_Mempool  *eina_mempool_add(const char *name, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 
 /**
  *
- * @brief TODO
+ * @brief Delete the given mempool.
  *
- * @param mp The mempools
+ * @param mp The mempool to delete
  *
  */
 EAPI void           eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
@@ -154,19 +161,21 @@ static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EIN
 static inline void  eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1);
 
 /**
- *
- * @brief TODO
+ * @brief Repack the objects in the mempool.
  *
  * @param mp The mempool
- * @param cb The after repack callback
- * @param data The data
+ * @param cb A callback to update the pointers the objects with their new location.
+ * @param data Data to pass as third argument to @p cb.
+ *
+ * @see Eina_Mempool_Repack_Cb
+ * @see _Eina_Mempool_Backend
  *
  */
 EAPI void	        eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2);
 
 /**
  *
- * @brief TODO (garbage collect)
+ * @brief Run a garbage collection cycle.
  *
  * @param mp The mempool
  *
@@ -175,7 +184,7 @@ EAPI void           eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
 
 /**
  *
- * @brief TODO
+ * @brief Have the backend update its internal statistics.
  *
  * @param mp The mempool
  *
@@ -184,7 +193,7 @@ EAPI void           eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1
 
 /**
  *
- * @brief TODO
+ * @brief Register the given memory pool backend.
  *
  * @param be The backend
  * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE
@@ -195,7 +204,7 @@ EAPI Eina_Bool      eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NON
 
 /**
  *
- * @brief TODO
+ * @brief Unregister the given memory pool backend.
  *
  * @param be The backend
  *
@@ -204,11 +213,10 @@ EAPI void           eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_N
 
 /**
  *
- * @brief TODO
+ * @brief Computer the alignment that would be used when allocating a object of size @p size.
  *
  * @param size 
- * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE
- * otherwise.
+ * @return The alignment for an allocation of size @p size.
  *
  */
 static inline unsigned int   eina_mempool_alignof(unsigned int size);