More comments

Author: ejmount

src/k_smallest.rs

@@ -49,6 +49,7 @@ where
 
     // Rearrange the into a valid heap by reordering from the second-bottom-most layer up
     // Slightly faster than ordering on each insert, but only by a factor of lg(k)
+    // The resulting heap has the **largest** item on top
     for i in (0..=(storage.len() / 2)).rev() {
         sift_down(&mut storage, &mut is_less_than, i);
     }
@@ -63,18 +64,23 @@ where
                 // Treating this as an push-and-pop saves having to write a sift-up implementation
                 // https://en.wikipedia.org/wiki/Binary_heap#Insert_then_extract
                 storage[0] = val;
+                // We retain the smallest items we've seen so far, but ordered largest first so we can drop the largest efficiently.
                 sift_down(&mut storage, &mut is_less_than, 0);
             }
         });
     }
 
-    let mut heap = &mut storage[..];
+    // Ultimately the items need to be in least-first, strict order, but the heap is currently largest-first.
+    // To achieve this, repeatedly
+    // 1) "pop" the largest item off the heap into the tail slot of the underlying storage
+    // 2) shrink the logical size of the heap by 1
+    // 3) restore the heap property over the remaining items
 
+    let mut heap = &mut storage[..];
     while heap.len() > 1 {
         let last_idx = heap.len() - 1;
         heap.swap(0, last_idx);
-        // Leaves the length shorter than the number of elements
-        // so that sifting does not disturb already popped elements
+        // Sifting over a truncated slice means that the sifting will not disturb already popped elements
         heap = &mut heap[..last_idx];
         sift_down(heap, &mut is_less_than, 0);
     }