Opt: Documented opt and its interaction with conf

[libucw.git] / ucw / binheap.h

diff --git a/ucw/binheap.h b/ucw/binheap.h
index bc498e41eaf102a45c3ac96c3d16fe9c731e51f6..89b4a49cf87b51d933bded35de1f345e4c721ad0 100644 (file)
--- a/ucw/binheap.h
+++ b/ucw/binheap.h
@@ -12,49 +12,53 @@
  *  this file with parameters set in the corresponding preprocessor macros
  *  as described below, it generates functions for manipulating the particular
  *  version of the binomial heap.
+ */
+
+/***
+ * [[generator]]
+ * Interface to the generator
+ * --------------------------
  *
- *  You need to specify:
+ * To use the binomial heaps, you need to specify:
  *
- *  BH_PREFIX(x)       macro to add a name prefix (used on all global names
- *                     defined by the hash table generator). All further
- *                     names mentioned here except for macro names will be
- *                     implicitly prefixed.
+ * - `BH_PREFIX(x)`  -- macro to add a name prefix (used on all global names
+ *                     defined by the generator). All further names mentioned
+ *                     here except for macro names will be implicitly prefixed.
  *
- *  Then you continue by including "ucw/binheap-node.h" which defines struct bh_node
- *  and struct bh_root (both without prefix). The heap elements are always allocated by
- *  you and they must include struct bh_node which serves as a handle used for all
- *  the heap functions and it contains all information needed for heap-keeping.
- *  The heap itself is also allocated by you and it's represented by struct bh_heap.
+ * Then you continue by including `ucw/binheap-node.h` which defines <<struct_bh_node,struct bh_node>>
+ * and <<struct_bh_heap,struct bh_heap>> (both without prefix). The heap elements are always allocated by
+ * you and they must include `struct bh_node` which serves as a handle used for all
+ * the heap functions and it contains all information needed for heap-keeping.
+ * The heap itself is also allocated by you and it's represented by `struct bh_heap`.
  *
- *  When you have the declaration of heap nodes, you continue with defining:
+ * When you have the declaration of heap nodes, you continue with defining:
  *
- *  less(p,q)          returns 1 if the key corresponding to bh_node *p
- *                     is less than the one corresponding to *q.
+ * - `less(p,q)`     -- returns `1` if the key corresponding to `bh_node *p`
+ *                     is less than the one corresponding to `*q`.
  *
- *  Then specify what operations you request:
+ * Then specify what operations you request:
  *
- *  <always defined>   init(heap*) -- initialize the heap.
- *  BH_WANT_INSERT     insert(heap*, node*) -- insert the node to the heap.
- *  BH_WANT_FINDMIN    node *findmin(heap*) -- find node with minimum key.
- *  BH_WANT_DELETEMIN  node *deletemin(heap*) -- findmin and delete the node.
+ * - `init(heap\*)` -- initialize the heap (always defined).
+ * - `insert(heap\*, node\*)` -- insert the node to the heap (`BH_WANT_INSERT`).
+ * - `node\* findmin(heap\*)` -- find node with minimum key (`BH_WANT_FINDMIN`).
+ * - `node\* deletemin(heap\*)` -- findmin and delete the node (`BH_WANT_DELETEMIN`).
  *
- *  Then include "ucw/binheap.h" and voila, you have a binomial heap
- *  suiting all your needs (at least those which you've revealed :) ).
+ * Then include `ucw/binheap.h` and voila, you have a binomial heap
+ * suiting all your needs (at least those which you've revealed :) ).
  *
- *  You also get a iterator macro at no extra charge:
+ * You also get a iterator macro at no extra charge:
  *
- *  BH_FOR_ALL(bh_prefix, hash*, variable)
- *    {
- *      // node *variable gets declared automatically
- *      do_something_with_node(variable);
- *      // use BH_BREAK and BH_CONTINUE instead of break and continue
- *     // you must not alter contents of the hash table here
- *    }
- *  BH_END_FOR;
+ *   BH_FOR_ALL(bh_prefix, heap*, variable)
+ *     {
+ *       // node* variable gets declared automatically
+ *       do_something_with_node(variable);
+ *       // use BH_BREAK and BH_CONTINUE instead of break and continue
+ *       // you must not alter contents of the binomial heap here
+ *     }
+ *   BH_END_FOR;
  *
- *  After including this file, all parameter macros are automatically
- *  undef'd.
- */
+ * After including this file, all parameter macros are automatically undef'd.
+ ***/
 
 #define BH_NODE struct bh_node
 #define BH_HEAP struct bh_heap
@@ -107,7 +111,7 @@ BH_PREFIX(merge)(BH_NODE *a, BH_NODE *b)
              s->next_sibling = q;
              q = s;
            }
-         else                          /* otherwise put the result to the a's list */
+         else                          /* otherwise put the result to the a's list */
            {
              p = s->next_sibling = *pp;
              *pp = s;
@@ -128,6 +132,7 @@ BH_PREFIX(insert)(BH_HEAP *heap, BH_NODE *a)
 
   sh.first_son = a;
   a->first_son = a->last_son = a->next_sibling = NULL;
+  a->order = 0;
   BH_PREFIX(merge)(&heap->root, &sh);
 }
 #endif