Modified Doxygen comments on heaps

Author: Nathan Shreve

vpr/src/route/four_ary_heap.h

@@ -4,6 +4,16 @@
 #include "k_ary_heap.h"
 #include <vector>
 
+/**
+ * @brief Minheap with 4 child nodes per parent.
+ *
+ * @note
+ * Currently, KAryHeap's two children are BinaryHeap and FourAryHeap. On small circuits, these
+ * heaps have negligible differences in runtime, but on larger heaps, runtime is lower when
+ * using FourAryHeap. On titan benchmarks, the runtime is ~1.8% better on FourAryHeap compared
+ * to BinaryHeap. This is likely because FourAryHeap is more cache friendly, as we can fit 5
+ * heap_elem on a cache line.
+*/
 class FourAryHeap : public KAryHeap {
   public:
     bool is_valid() const final;

vpr/src/route/heap_type.h

@@ -99,10 +99,12 @@ class HeapStorage {
 /**
  * @brief Interface to heap used for router optimization.
  *
- * @details
- * Note: Objects used in instances of HeapInterface must always be allocated
+ * @note
+ * Objects used in instances of HeapInterface must always be allocated
  * and free'd using the HeapInterface::alloc and HeapInterface::free methods
- * of that instance.  Object pools are likely in use.<BR><BR>
+ * of that instance.  Object pools are likely in use.
+ *
+ * @details
  * As a general rule, any t_heap objects returned from this interface,
  * **must** be HeapInterface::free'd before destroying the HeapInterface
  * instance. This ensure that no leaks are present in the users of the heap.
@@ -135,8 +137,8 @@ class HeapInterface {
     /**
      * @brief Initializes heap storage based on the size of the device.
      *
-     * @details
-     * Note: this method **must** be invoked at least once prior to the
+     * @note
+     * This method **must** be invoked at least once prior to the
      * following methods being called:<BR>
      *  - add_to_heap<BR>
      *  - push_back<BR>
@@ -212,8 +214,10 @@ class HeapInterface {
      *
      * @details
      * This returns all memory allocated by the HeapInterface instance. Only
-     * call this if the heap is no longer being used.<BR><BR>
-     * Note: Only invoke this method if all objects returned from this
+     * call this if the heap is no longer being used.
+     *
+     * @note
+     * Only invoke this method if all objects returned from this
      * HeapInterface instance have been free'd.
      */
     virtual void free_all_memory() = 0;

vpr/src/route/k_ary_heap.h

@@ -6,13 +6,6 @@
 
 /**
  * @brief Abstract class whose children are HeapInterface implementations of a k-ary minheap.
- *
- * @details
- * Currently, KAryHeap's two children are BinaryHeap and FourAryHeap. On small circuits, these
- * heaps have negligible differences in runtime, but on larger heaps, runtime is lower when
- * using FourAryHeap. On titan benchmarks, the runtime is ~1.8% better on FourAryHeap compared
- * to BinaryHeap. This is likely because FourAryHeap is more cache friendly, as we can fit 5
- * heap_elem on a cache line.
  */
 class KAryHeap : public HeapInterface {
   public:
@@ -48,12 +41,14 @@ class KAryHeap : public HeapInterface {
      * @param elem_ptr A pointer to the t_heap struct which contains all
      * the node's information.
      * @param cost The cost of the node.
-     */
-    /* TODO: We are currently storing the node cost in two places (in elem_ptr->cost and cost). This might be fixed in two ways:
-     * 1. Don't store the cost in t_heap.
+     *
+     * @todo
+     * We are currently storing the node cost in two places (in elem_ptr->cost and cost). This might be fixed in two ways:<BR>
+     * 1. Don't store the cost in t_heap.<BR>
      * 2. Instead of using pointers, use a 32-bit ID. If we do this, we can create a new 8-ary heap, which is likely to be even
      * faster as we can fit more heap_elem on one cache line (currently, we can fit 5 as heap_elem is 12 bytes), even with more
-     * comparisons.*/
+     * comparisons.
+     */
     struct heap_elem {
         t_heap* elem_ptr;
         float cost;
@@ -110,11 +105,14 @@ class KAryHeap : public HeapInterface {
     HeapStorage storage_;
 
     /**
+     * @details
      * heap_ is indexed from [1..heap_size]; the 0th element is unused. For BinaryHeap, this simplifies
      * arithmetic in left() and parent() functions. Using a heap beginning at index 0 would simplify
      * first_child() and parent() functions in FourAryHeap, but this does not improve runtime.
+     *
+     * @todo
+     * If an 8-ary heap is implemented, experiment with starting at index 0
      */
-    /* TODO: If an 8-ary heap is implemented, experiment with starting at index 0 */
     std::vector<heap_elem> heap_;
 
     size_t heap_size_; /* Number of slots in the heap array */