Cleanup: move docs out of header
authorCampbell Barton <ideasman42@gmail.com>
Sun, 29 Oct 2017 05:07:07 +0000 (16:07 +1100)
committerCampbell Barton <ideasman42@gmail.com>
Sun, 29 Oct 2017 05:08:10 +0000 (16:08 +1100)
source/blender/blenlib/BLI_heap.h
source/blender/blenlib/intern/BLI_heap.c

index 3d7e526ebe4a0536c4181b567d1ac9d48f894793..dcdbf53c0bbb16f93fed8196512602aa73029096 100644 (file)
@@ -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);
 
index 84b15ca1cf980704a87ff948d621c48de0f2fa99..4643b98f520a63f6be3340d97a81a71b9d9518ed 100644 (file)
@@ -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;