eina: enhance doxygen in eina_mempool.h

Summary:
Arrange grouping
Add @brief for brief description
Add @details for detailed description
Add @note for noted description
Add [in] & [out] for parameters
Add @see more
Add links for EINA_TRUE, EINA_FALSE, etc.
Fix indentation & Fix typeof
Use @p instead of @a for the consistency

Reviewers: raster, cedric

Subscribers: cedric

Differential Revision: https://phab.enlightenment.org/D1612

Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>

1 files changed, 72 insertions, 87 deletions

diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h
index 7aaffc2652..32774cc0a1 100644
--- a/src/lib/eina/eina_mempool.h
+++ b/src/lib/eina/eina_mempool.h
@@ -25,46 +25,36 @@
 
 
 /**
- * @addtogroup Eina_Memory_Pool_Group Memory Pool
- *
- * @brief These functions provide memory pool management.
+ * @defgroup Eina_Memory_Pool_Group Memory Pool
+ * @ingroup Eina_Tools_Group
+ * @brief This group discusses the functions that provide memory pool management.
  *
- * Several mempool are available:
+ * Several mempools are available:
  *
  * @li @c chained_pool: It is the default one. It allocates a big
- * chunk of memory with malloc() and split the result in chunks of the
+ * chunk of memory with malloc() and splits the result into chunks of the
  * requested size that are pushed inside a stack. When requested, it
  * takes this pointer from the stack to give them to whoever wants
  * them.
  * @li @c pass_through: it just call malloc() and free(). It may be
  * faster on some computers than using our own allocators (like having
  * a huge L2 cache, over 4MB).
- * @li @c one_big: It calls just one time malloc for the requested number
- * of items. Useful when you know in advance how many objects of some
- * type will live during the life of the mempool.
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Memory_Pool_Group Memory Pool
+ * @li @c one_big: It calls malloc() just one time for the requested number
+ * of items. This is useful when you know in advance how many objects of some
+ * type live during the life of the mempool.
  *
  * @{
  */
 
 /**
  * @typedef Eina_Mempool
- * Mempool type.
+ * @brief The opaque type for the mempool structure.
  */
 typedef struct _Eina_Mempool Eina_Mempool;
 
 /**
  * @typedef Eina_Mempool_Backend
- * Mempool backend type.
+ * @brief The opaque type for the mempool backend type.
  */
 typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend;
 
@@ -72,152 +62,151 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend;
 /**
  * @typedef Eina_Mempool_Repack_Cb
  *
- * 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.
+ * @brief The callback type which is called when the mempool "repacks" its data.
+ *
+ * @details 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.
+ * @note 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);
 
 EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE;
 
 /**
+ * @brief Creates a new mempool of the given type
  *
- * @brief Create a new mempool of the given type
- *
- * @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.
+ * @param[in] name Name of the mempool kind to use.
+ * @param[in] context Identifier of the mempool created (for debug purposes).
+ * @param[in] options Unused. Use the variable arguments list instead to pass options to the mempool.
+ * @param[in] ... 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 *name, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 
 /**
+ * @brief Deletes the given mempool.
  *
- * @brief Delete the given mempool.
- *
- * @param mp The mempool to delete
- *
+ * @param[in] mp The mempool to delete
  */
 EAPI void           eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Re-allocate an amount memory by the given mempool.
+ * @brief Re-allocates an amount memory by the given mempool.
  *
- * @param mp The mempool.
- * @param element The element to re-allocate.
- * @param size The size in bytes to re-allocate.
- * @return The newly re-allocated data.
+ * @param[in] mp The mempool
+ * @param[in] element The element to re-allocate
+ * @param[in] size The size in bytes to re-allocate
+ * @return The newly re-allocated data
  *
- * This function re-allocates and returns @p element with @p size bytes using the
- * mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free().
+ * @note This function re-allocates and returns @p element with @p size bytes using the
+ *       mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free().
  * @warning No checks are done for @p mp.
+ *
+ * @see eina_mempool_free()
  */
 static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 
 /**
- * @brief Allocate memory using the given mempool.
+ * @brief Allocates memory using the given mempool.
  *
- * @param mp The mempool.
- * @param size The size in bytes to allocate.
- * @return The newly allocated data.
+ * @param[in] mp The mempool
+ * @param[in] size The size in bytes to allocate
+ * @return The newly allocated data
  *
- * This function allocates and returns @p size bytes using the mempool @p mp.
- * If not used anymore, the data must be freed with eina_mempool_free().
+ * @note This function allocates and returns @p size bytes using the mempool @p mp.
+ *       If not used anymore, the data must be freed with eina_mempool_free().
  * @warning No checks are done for @p mp.
+ *
+ * @see eina_mempool_free()
  */
 static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 
 /**
  * @brief Allocate and zero memory using the given mempool.
  *
- * @param mp The mempool.
- * @param size The size in bytes to allocate.
- * @return The newly allocated data.
+ * @param[in] mp The mempool
+ * @param[in] size The size in bytes to allocate
+ * @return The newly allocated data
  *
- * This function allocates, zeroes, and returns @p size bytes using the mempool @p mp.
- * If not used anymore, the data must be freed with eina_mempool_free().
+ * @details This function allocates, zeroes, and returns @p size bytes using the mempool @p mp.
+ *          If not used anymore, the data must be freed with eina_mempool_free().
  * @warning No checks are done for @p mp.
+ *
  * @since 1.2
+ *
+ * @see eina_mempool_free()
  */
 static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 
 /**
  * @brief Free resources previously allocated by the given mempool.
  *
- * @param mp The mempool.
- * @param element The data to free.
+ * @param[in] mp The mempool
+ * @param[in] element The data to free
+ *
+ * @details This function frees @p element allocated by @p mp. @p element must
+ *          have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or
+ *          eina_mempool_realloc().
  *
- * This function frees @p element allocated by @p mp. @p element must
- * have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or
- * eina_mempool_realloc().
  * @warning No checks are done for @p mp.
+ *
+ * @see eina_mempool_malloc()
+ * @see eina_mempool_calloc()
+ * @see eina_mempool_realloc()
  */
 static inline void  eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Repack the objects in the mempool.
+ * @brief Repacks the objects in the mempool.
  *
- * @param mp The mempool
- * @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.
+ * @param[in] mp The mempool
+ * @param[in] cb A callback to update the pointers the objects with their new location
+ * @param[in] 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 Run a garbage collection cycle.
  *
- * @param mp The mempool
- *
+ * @param[in] mp The mempool
  */
 EAPI void           eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
 
 /**
- *
  * @brief Have the backend update its internal statistics.
  *
- * @param mp The mempool
+ * @param[in] mp The mempool
  *
  */
 EAPI void           eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
 
 /**
+ * @brief Registers the given memory pool backend.
  *
- * @brief Register the given memory pool backend.
- *
- * @param be The backend
+ * @param[in] be The backend
  * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE
- * otherwise.
- *
+ *         otherwise.
  */
 EAPI Eina_Bool      eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
 
 /**
+ * @brief Unregisters the given memory pool backend.
  *
- * @brief Unregister the given memory pool backend.
- *
- * @param be The backend
- *
+ * @param[in] be The backend
  */
 EAPI void           eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
 
 /**
+ * @brief Computers the alignment that would be used when allocating a object of size @p size.
  *
- * @brief Computer the alignment that would be used when allocating a object of size @p size.
- *
- * @param size 
+ * @param[in] size
  * @return The alignment for an allocation of size @p size.
- *
  */
 static inline unsigned int   eina_mempool_alignof(unsigned int size);
 
@@ -227,8 +216,4 @@ static inline unsigned int   eina_mempool_alignof(unsigned int size);
  * @}
  */
 
-/**
- * @}
- */
-
 #endif /* EINA_MEMPOOL_H_ */