Document more suitable containers fn

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rectangle-pack"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Chinedu Francis Nwafili <frankie.nwafili@gmail.com>"]
 edition = "2018"
 keywords = ["texture", "atlas", "bin", "box", "packer"]

README.md

@@ -189,11 +189,10 @@ We started with the algorithm described in [rectpack2D] and then made some adjus
 support our goal of flexibly supporting all use cases.
 
 
-- The heuristic is provided by the caller instead of having `rectangle-pack` decide on the heuristic.
+- The heuristic is provided by the caller instead of having `rectangle-pack` decide on a user provided heuristic.
 
 - When splitting an available section of a bin into two new sections of a bin - we do not decide on how the split should occur arbitrarily.
-  Instead, we base it on the heuristic. Whichever split (vertical or horizontal) produces the largest delta between the heuristic scores of the
-  two new bins will be used.
+  Instead, we base it on the user provided `more_suitable_containers` heuristic function.
 
 - There is a third dimension.
 

src/bin_section.rs

@@ -4,6 +4,15 @@ use std::fmt::{Display, Formatter};
 
 /// Given two sets of containers, which of these is the more suitable for our packing.
 ///
+/// Useful when we're determining how to split up the remaining volume/area of a box/rectangle.
+///
+/// For example - we might deem it best to cut the remaining region vertically, or horizontally,
+/// or along the Z-axis.
+///
+/// This decision is based on the more suitable contains heuristic. We determine all 6 possible
+/// ways to divide up remaining space, sort them using the more suitable contains heuristic function
+/// and choose the best one.
+///
 /// Ordering::Greater means the first set of containers is better.
 /// Ordering::Less means the second set of containers is better.
 pub type MoreSuitableContainersFn =

src/lib.rs

@@ -8,7 +8,8 @@ use std::fmt::{Debug, Display, Formatter};
 use std::hash::Hash;
 
 pub use crate::bin_section::contains_smallest_box;
-use crate::bin_section::{BinSection, MoreSuitableContainersFn};
+use crate::bin_section::BinSection;
+pub use crate::bin_section::MoreSuitableContainersFn;
 use crate::grouped_rects_to_place::Group;
 pub use crate::grouped_rects_to_place::GroupedRectsToPlace;
 pub use crate::target_bin::TargetBin;
@@ -369,7 +370,7 @@ mod tests {
         )
     }
 
-    /// If we have two inbound rects the smallest one should be placed first.
+    /// If we have two inbound rects the largest one should be placed first.
     #[test]
     fn places_largest_rectangles_first() {
         let mut groups: GroupedRectsToPlace<_, ()> = GroupedRectsToPlace::new();
@@ -426,7 +427,7 @@ mod tests {
     ///
     /// 1. First place the largest rectangle into the smallest bin.
     ///
-    /// 2. Second place largest rectangle into the next available bin (i.e. the largest one).
+    /// 2. Second place the remaining rectangle into the next available bin (i.e. the largest one).
     #[test]
     fn two_rects_two_bins() {
         let mut groups: GroupedRectsToPlace<_, ()> = GroupedRectsToPlace::new();