Merge pull request svenstaro#135 from finnbear/docs_134

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

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Fix some assertions [#129](https://github.com/svenstaro/bvh/pull/129) (thanks @finnbear)
 - Fix traversal in case of single-node BVH [#130](https://github.com/svenstaro/bvh/pull/130) (thanks @finnbear)
 - Fix intersection between rays and AABBs that lack depth. [#131](https://github.com/svenstaro/bvh/pull/131) (thanks @finnbear)
+- Document the limitations of distance traversal best-effort ordering. [#135](https://github.com/svenstaro/bvh/pull/135) (thanks @finnbear)
 
 ## 0.10.0 - 2024-07-06
 - Don't panic when traversing empty BVH [#106](https://github.com/svenstaro/bvh/pull/106) (thanks @finnbear)

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,