Add better docs to some convex hull util functions

geo/src/algorithm/convex_hull/graham.rs

@@ -1,4 +1,4 @@
-use super::{swap_remove_to_first, trivial_hull};
+use super::{swap_with_first_and_remove, trivial_hull};
 use crate::kernels::*;
 use crate::{Coord, GeoNum, LineString};
 
@@ -34,7 +34,7 @@ where
     use crate::utils::least_index;
     use std::cmp::Ordering;
     let min_idx = least_index(points);
-    let head = swap_remove_to_first(&mut points, min_idx);
+    let head = swap_with_first_and_remove(&mut points, min_idx);
     output.push(*head);
 
     // Sort rest of the points by angle it makes with head

geo/src/algorithm/convex_hull/mod.rs

@@ -99,9 +99,12 @@ where
     ls
 }
 
-// Utility function: swap idx to head(0th position), remove
-// head (modifies the slice), and return head as a reference
-fn swap_remove_to_first<'a, T>(slice: &mut &'a mut [T], idx: usize) -> &'a mut T {
+/// Utility function for convex hull ops
+///
+/// 1. _swap_ the element at `idx` with the element at `head` (0th position)
+/// 2. remove the _new_ `head` element (modifying the slice)
+/// 3. return a _mutable ref_ to the removed head element
+fn swap_with_first_and_remove<'a, T>(slice: &mut &'a mut [T], idx: usize) -> &'a mut T {
     // temporarily replace `slice` with an empty value
     let tmp = std::mem::take(slice);
     tmp.swap(0, idx);

geo/src/algorithm/convex_hull/qhull.rs

@@ -1,4 +1,4 @@
-use super::{swap_remove_to_first, trivial_hull};
+use super::{swap_with_first_and_remove, trivial_hull};
 use crate::kernels::{Kernel, Orientation};
 use crate::utils::partition_slice;
 use crate::{coord, Coord, GeoNum, LineString};
@@ -31,7 +31,7 @@ where
     use crate::utils::least_and_greatest_index;
     let (min, max) = {
         let (min_idx, mut max_idx) = least_and_greatest_index(points);
-        let min = swap_remove_to_first(&mut points, min_idx);
+        let min = swap_with_first_and_remove(&mut points, min_idx);
 
         // Two special cases to consider:
         // (1) max_idx = 0, and got swapped
@@ -44,7 +44,7 @@ where
         // 0, and we should not decrement it.
         max_idx = max_idx.saturating_sub(1);
 
-        let max = swap_remove_to_first(&mut points, max_idx);
+        let max = swap_with_first_and_remove(&mut points, max_idx);
         (min, max)
     };
 
@@ -62,7 +62,7 @@ where
     hull
 }
 
-// recursively calculate the convex hull of a subset of points
+/// Recursively calculate the convex hull of a subset of points
 fn hull_set<T>(p_a: Coord<T>, p_b: Coord<T>, mut set: &mut [Coord<T>], hull: &mut Vec<Coord<T>>)
 where
     T: GeoNum,
@@ -98,7 +98,7 @@ where
         .0;
 
     // move Coord at furthest_point from set into hull
-    let furthest_point = swap_remove_to_first(&mut set, furthest_idx);
+    let furthest_point = swap_with_first_and_remove(&mut set, furthest_idx);
     // points over PB
     {
         let (points, _) = partition_slice(set, |p| is_ccw(*furthest_point, p_b, *p));