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, 20 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_gsqueue.h b/source/blender/blenlib/BLI_gsqueue.h
index 9cc61bc8059..8b32c09b56b 100644
--- a/source/blender/blenlib/BLI_gsqueue.h
+++ b/source/blender/blenlib/BLI_gsqueue.h
@@ -32,10 +32,30 @@ extern "C" {
 typedef struct _GSQueue GSQueue;
 
 GSQueue *BLI_gsqueue_new(const size_t elem_size);
+/**
+ * Returns true if the queue is empty, false otherwise.
+ */
 bool BLI_gsqueue_is_empty(const GSQueue *queue);
 size_t BLI_gsqueue_len(const GSQueue *queue);
+/**
+ * Retrieves and removes the first element from the queue.
+ * The value is copies to \a r_item, which must be at least \a elem_size bytes.
+ *
+ * Does not reduce amount of allocated memory.
+ */
 void BLI_gsqueue_pop(GSQueue *queue, void *r_item);
+/**
+ * Copies the source value onto the end of the queue
+ *
+ * \note This copies #GSQueue.elem_size bytes from \a item,
+ * (the pointer itself is not stored).
+ *
+ * \param item: source data to be copied to the queue.
+ */
 void BLI_gsqueue_push(GSQueue *queue, const void *item);
+/**
+ * Free the queue's data and the queue itself.
+ */
 void BLI_gsqueue_free(GSQueue *queue);
 
 #ifdef __cplusplus