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

1 files changed, 42 insertions, 2 deletions

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