Cleanup: move docs out of header

2 files changed, 18 insertions, 22 deletions

diff --git a/source/blender/blenlib/BLI_heap.h b/source/blender/blenlib/BLI_heap.h
index 3d7e526ebe4..dcdbf53c0bb 100644
--- a/source/blender/blenlib/BLI_heap.h
+++ b/source/blender/blenlib/BLI_heap.h
@@ -23,7 +23,7 @@
 
 /** \file BLI_heap.h
  *  \ingroup bli
- *  \brief A heap / priority queue ADT
+ *  \brief A min-heap / priority queue ADT
  */
 
 struct Heap;
@@ -33,36 +33,17 @@ typedef struct HeapNode HeapNode;
 
 typedef void (*HeapFreeFP)(void *ptr);
 
-/* Creates a new heap. BLI_memarena is used for allocating nodes. Removed nodes
- * are recycled, so memory usage will not shrink. */
 Heap           *BLI_heap_new_ex(unsigned int tot_reserve) ATTR_WARN_UNUSED_RESULT;
 Heap           *BLI_heap_new(void) ATTR_WARN_UNUSED_RESULT;
 void            BLI_heap_clear(Heap *heap, HeapFreeFP ptrfreefp) ATTR_NONNULL(1);
 void            BLI_heap_free(Heap *heap, HeapFreeFP ptrfreefp) ATTR_NONNULL(1);
-
-/* Insert heap node with a value (often a 'cost') and pointer into the heap,
- * duplicate values are allowed. */
 HeapNode       *BLI_heap_insert(Heap *heap, float value, void *ptr) ATTR_NONNULL(1);
-
-/* Insert or update */
 void            BLI_heap_insert_or_update(Heap *heap, HeapNode **node_p, float value, void *ptr) ATTR_NONNULL(1, 2);
-
-/* Remove a heap node. */
 void            BLI_heap_remove(Heap *heap, HeapNode *node) ATTR_NONNULL(1, 2);
-
-/* Return 0 if the heap is empty, 1 otherwise. */
 bool            BLI_heap_is_empty(const Heap *heap) ATTR_NONNULL(1);
-
-/* Return the size of the heap. */
 unsigned int    BLI_heap_size(const Heap *heap) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
-
-/* Return the top node of the heap. This is the node with the lowest value. */
 HeapNode       *BLI_heap_top(const Heap *heap) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
-
-/* Pop the top node off the heap and return it's pointer. */
 void           *BLI_heap_popmin(Heap *heap) ATTR_NONNULL(1);
-
-/* Update the priority in the heap (may be slow but generally faster than remove/insert). */
 void            BLI_heap_node_value_update(Heap *heap, HeapNode *node, float value) ATTR_NONNULL(1, 2);
 void            BLI_heap_node_value_update_ptr(Heap *heap, HeapNode *node, float value, void *ptr) ATTR_NONNULL(1, 2);
 
diff --git a/source/blender/blenlib/intern/BLI_heap.c b/source/blender/blenlib/intern/BLI_heap.c
index 84b15ca1cf9..4643b98f520 100644
--- a/source/blender/blenlib/intern/BLI_heap.c
+++ b/source/blender/blenlib/intern/BLI_heap.c
@@ -23,7 +23,7 @@
 /** \file blender/blenlib/intern/BLI_heap.c
  *  \ingroup bli
  *
- * A heap / priority queue ADT.
+ * A min-heap / priority queue ADT.
  */
 
 #include <stdlib.h>
@@ -188,7 +188,11 @@ static void heap_node_free(Heap *heap, HeapNode *node)
 /** \name Public Heap API
  * \{ */
 
-/* use when the size of the heap is known in advance */
+/**
+ * Creates a new heap. Removed nodes are recycled, so memory usage will not shrink.
+ *
+ * \note Use when the size of the heap is known in advance.
+ */
 Heap *BLI_heap_new_ex(uint tot_reserve)
 {
 	Heap *heap = MEM_mallocN(sizeof(Heap), __func__);
@@ -251,6 +255,10 @@ void BLI_heap_clear(Heap *heap, HeapFreeFP ptrfreefp)
 	heap->nodes.free = NULL;
 }
 
+/**
+ * Insert heap node with a value (often a 'cost') and pointer into the heap,
+ * duplicate values are allowed.
+ */
 HeapNode *BLI_heap_insert(Heap *heap, float value, void *ptr)
 {
 	HeapNode *node;
@@ -299,11 +307,18 @@ uint BLI_heap_size(const Heap *heap)
 	return heap->size;
 }
 
+/**
+ * Return the top node of the heap.
+ * This is the node with the lowest value.
+ */
 HeapNode *BLI_heap_top(const Heap *heap)
 {
 	return heap->tree[0];
 }
 
+/**
+ * Pop the top node off the heap and return it's pointer.
+ */
 void *BLI_heap_popmin(Heap *heap)
 {
 	void *ptr = heap->tree[0]->ptr;