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, 23 insertions, 5 deletions

diff --git a/source/blender/blenlib/BLI_buffer.h b/source/blender/blenlib/BLI_buffer.h
index 9d66fe9a14e..7f577443cf7 100644
--- a/source/blender/blenlib/BLI_buffer.h
+++ b/source/blender/blenlib/BLI_buffer.h
@@ -71,13 +71,25 @@ enum {
   } \
   (void)0
 
-/* Never decreases the amount of memory allocated */
+/**
+ * \note Never decreases the amount of memory allocated.
+ */
 void BLI_buffer_resize(BLI_Buffer *buffer, const size_t new_count);
 
-/* Ensure size, throwing away old data, respecting BLI_BUFFER_USE_CALLOC */
+/**
+ * Ensure size, throwing away old data, respecting #BLI_BUFFER_USE_CALLOC.
+ *
+ * Similar to #BLI_buffer_resize, but use when the existing data can be:
+ * - Ignored (malloc'd).
+ * - Cleared (when #BLI_BUFFER_USE_CALLOC is set).
+ */
 void BLI_buffer_reinit(BLI_Buffer *buffer, const size_t new_count);
 
-/* Append an array of elements. */
+/**
+ * Append an array of elements.
+ *
+ * Callers use #BLI_buffer_append_array.
+ */
 void _bli_buffer_append_array(BLI_Buffer *buffer, void *data, size_t count);
 #define BLI_buffer_append_array(buffer_, type_, data_, count_) \
   { \
@@ -87,7 +99,11 @@ void _bli_buffer_append_array(BLI_Buffer *buffer, void *data, size_t count);
   } \
   (void)0
 
-/* Does not free the buffer structure itself */
+/**
+ * Does not free the buffer structure itself.
+ *
+ * Callers use #BLI_buffer_free.
+ */
 void _bli_buffer_free(BLI_Buffer *buffer);
 #define BLI_buffer_free(name_) \
   { \
@@ -96,7 +112,9 @@ void _bli_buffer_free(BLI_Buffer *buffer);
   } \
   (void)0
 
-/* A buffer embedded in a struct. Using memcpy is allowed until first resize. */
+/**
+ * A buffer embedded in a struct. Using #memcpy is allowed until first resize.
+ */
 #define BLI_buffer_field_init(name_, type_) \
   { \
     memset(name_, 0, sizeof(*name_)); \