More comments

Author: ejmount

src/k_smallest.rs

@@ -7,7 +7,9 @@ where
     I: Iterator,
     F: FnMut(&I::Item, &I::Item) -> Ordering,
 {
-    /// Sift the element currently at `origin` **away** from the root until it is properly ordered
+    /// Sift the element currently at `origin` away from the root until it is properly ordered
+    ///
+    /// This will leave **larger** elements closer to the root of the heap
     fn sift_down<T, F>(heap: &mut [T], is_less_than: &mut F, mut origin: usize)
     where
         F: FnMut(&T, &T) -> bool,
@@ -56,6 +58,7 @@ where
         // So feed them into the heap
         // Also avoids unexpected behaviour with restartable iterators
         iter.for_each(|val| {
+            // `for_each` is potentially more performant for deeply nested iterators, see its docs.
             if is_less_than(&val, &mut storage[0]) {
                 // 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