From 9e365069afe156f33fadfad9705e1325f894cd54 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 20:01:44 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenlib' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenlib/BLI_mempool.h | 44 ++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) (limited to 'source/blender/blenlib/BLI_mempool.h') diff --git a/source/blender/blenlib/BLI_mempool.h b/source/blender/blenlib/BLI_mempool.h index 61b572a4943..d6abae36e00 100644 --- a/source/blender/blenlib/BLI_mempool.h +++ b/source/blender/blenlib/BLI_mempool.h @@ -44,19 +44,52 @@ void *BLI_mempool_alloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT A ATTR_NONNULL(1); void *BLI_mempool_calloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL ATTR_NONNULL(1); +/** + * Free an element from the mempool. + * + * \note doesn't protect against double frees, take care! + */ void BLI_mempool_free(BLI_mempool *pool, void *addr) ATTR_NONNULL(1, 2); +/** + * Empty the pool, as if it were just created. + * + * \param pool: The pool to clear. + * \param totelem_reserve: Optionally reserve how many items should be kept from clearing. + */ void BLI_mempool_clear_ex(BLI_mempool *pool, const int totelem_reserve) ATTR_NONNULL(1); +/** + * Wrap #BLI_mempool_clear_ex with no reserve set. + */ void BLI_mempool_clear(BLI_mempool *pool) ATTR_NONNULL(1); +/** + * Free the mempool its self (and all elements). + */ void BLI_mempool_destroy(BLI_mempool *pool) ATTR_NONNULL(1); int BLI_mempool_len(const BLI_mempool *pool) ATTR_NONNULL(1); void *BLI_mempool_findelem(BLI_mempool *pool, unsigned int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Fill in \a data with pointers to each element of the mempool, + * to create lookup table. + * + * \param pool: Pool to create a table from. + * \param data: array of pointers at least the size of 'pool->totused' + */ void BLI_mempool_as_table(BLI_mempool *pool, void **data) ATTR_NONNULL(1, 2); +/** + * A version of #BLI_mempool_as_table that allocates and returns the data. + */ void **BLI_mempool_as_tableN(BLI_mempool *pool, const char *allocstr) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * Fill in \a data with the contents of the mempool. + */ void BLI_mempool_as_array(BLI_mempool *pool, void *data) ATTR_NONNULL(1, 2); +/** + * A version of #BLI_mempool_as_array that allocates and returns the data. + */ void *BLI_mempool_as_arrayN(BLI_mempool *pool, const char *allocstr) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); @@ -67,9 +100,10 @@ void BLI_mempool_set_memory_debug(void); /** * Iteration stuff. - * NOTE: this may easy to produce bugs with. + * \note this may easy to produce bugs with. */ -/* private structure */ + +/* Private structure. */ typedef struct BLI_mempool_iter { BLI_mempool *pool; struct BLI_mempool_chunk *curchunk; @@ -89,7 +123,13 @@ enum { BLI_MEMPOOL_ALLOW_ITER = (1 << 0), }; +/** + * Initialize a new mempool iterator, #BLI_MEMPOOL_ALLOW_ITER flag must be set. + */ void BLI_mempool_iternew(BLI_mempool *pool, BLI_mempool_iter *iter) ATTR_NONNULL(); +/** + * Step over the iterator, returning the mempool item or NULL. + */ void *BLI_mempool_iterstep(BLI_mempool_iter *iter) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); #ifdef __cplusplus -- cgit v1.2.3