Docs svenstaro#134 - acknowledge best-effort nature of dist traversal

src/bvh/bvh_impl.rs

@@ -133,6 +133,9 @@ impl<T: BHValue, const D: usize> Bvh<T, D> {
     /// Returns a subset of [`shape`], in which the [`Aabb`]s of the elements were hit by [`Ray`].
     /// Return in order from nearest to farthest for ray.
     ///
+    /// This is a best-effort function that orders interior parent nodes before ordering child
+    /// nodes, so the output is not necessarily perfectly sorted.
+    ///
     /// [`Bvh`]: struct.Bvh.html
     /// [`Aabb`]: ../aabb/struct.AABB.html
     ///
@@ -148,6 +151,9 @@ impl<T: BHValue, const D: usize> Bvh<T, D> {
     /// Returns a subset of [`Shape`], in which the [`Aabb`]s of the elements were hit by [`Ray`].
     /// Return in order from farthest to nearest for ray.
     ///
+    /// This is a best-effort function that orders interior parent nodes before ordering child
+    /// nodes, so the output is not necessarily perfectly sorted.
+    ///
     /// [`Bvh`]: struct.Bvh.html
     /// [`Aabb`]: ../aabb/struct.AABB.html
     ///

src/bvh/distance_traverse.rs

@@ -11,7 +11,10 @@ enum RestChild {
 }
 
 /// Iterator to traverse a [`Bvh`] in order from nearest [`Aabb`] to farthest for [`Ray`],
-/// without memory allocations
+/// or vice versa, without memory allocations.
+///
+/// This is a best-effort iterator that orders interior parent nodes before ordering child
+/// nodes, so the output is not necessarily perfectly sorted.
 pub struct DistanceTraverseIterator<
     'bvh,
     'shape,