improved docs

jagua-rs/src/collision_detection/mod.rs

@@ -1,5 +1,8 @@
+/// Collision detection engine itself
 pub mod cd_engine;
 pub mod hazard;
 pub mod hazard_filter;
+
+/// Everything related to the Hazard Proximity Grid
 pub mod hpg;
 pub mod quadtree;

jagua-rs/src/entities/bin.rs

@@ -14,15 +14,20 @@ use crate::geometry::transformation::Transformation;
 use crate::util::config::CDEConfig;
 
 /// A `Bin` is a container in which items can be placed.
-/// Its interior is defined by an outer polygon and zero or more holes.
 #[derive(Clone, Debug)]
 pub struct Bin {
     pub id: usize,
+    /// The contour of the bin
     pub outer: Arc<SimplePolygon>,
+    /// The cost of using the bin
     pub value: u64,
+    /// Every bin is centered around its centroid (using this transformation)
     pub centering_transform: Transformation,
+    /// Shapes of holes/defects in the bins, if any
     pub holes: Vec<Arc<SimplePolygon>>,
+    /// Zones of different qualities in the bin, stored per quality.
     pub quality_zones: [Option<QualityZone>; N_QUALITIES],
+    /// The starting state of the `CDEngine` for this bin.
     pub base_cde: Arc<CDEngine>,
     pub area: f64,
 }
@@ -62,7 +67,7 @@ impl Bin {
 
         let base_cde = CDEngine::new(
             outer.bbox().inflate_to_square(),
-            Self::generate_hazards(&outer, &holes, &quality_zones),
+            Bin::generate_hazards(&outer, &holes, &quality_zones),
             cde_config,
         );
         let base_cde = Arc::new(base_cde);
@@ -80,6 +85,7 @@ impl Bin {
         }
     }
 
+    /// Create a new `Bin` for a strip-packing problem. Instead of a shape, the bin is always rectangular.
     pub fn from_strip(id: usize, width: f64, height: f64, cde_config: CDEConfig) -> Self {
         let poly = SimplePolygon::from(AARectangle::new(0.0, 0.0, width, height));
         let value = poly.area() as u64;
@@ -99,27 +105,25 @@ impl Bin {
         holes: &[Arc<SimplePolygon>],
         quality_zones: &[Option<QualityZone>],
     ) -> Vec<Hazard> {
+        //Hazard induced by the outside of the bin
         let mut hazards = vec![Hazard::new(HazardEntity::BinExterior, outer.clone())];
+
+        //Hazard induced by any holes in the bin
         hazards.extend(holes.iter().enumerate().map(|(i, shape)| {
             let haz_entity = HazardEntity::BinHole { id: i };
             Hazard::new(haz_entity, shape.clone())
         }));
 
-        hazards.extend(
-            quality_zones
-                .iter()
-                .flatten()
-                .map(|q_zone| {
-                    q_zone.zones.iter().enumerate().map(|(id, shape)| {
-                        let haz_entity = HazardEntity::QualityZoneInferior {
-                            quality: q_zone.quality,
-                            id,
-                        };
-                        Hazard::new(haz_entity, shape.clone())
-                    })
-                })
-                .flatten(),
-        );
+        //Hazards induced by quality zones
+        for q_zone in quality_zones.iter().flatten() {
+            for (id, shape) in q_zone.zones.iter().enumerate() {
+                let haz_entity = HazardEntity::QualityZoneInferior {
+                    quality: q_zone.quality,
+                    id,
+                };
+                hazards.push(Hazard::new(haz_entity, shape.clone()));
+            }
+        }
 
         hazards
     }

jagua-rs/src/entities/instances/bin_packing.rs

@@ -12,7 +12,7 @@ pub struct BPInstance {
     pub items: Vec<(Item, usize)>,
     /// Total area of all items in the instance
     pub item_area: f64,
-
+    /// Set of bins available to pack the items, along with their quantities
     pub bins: Vec<(Bin, usize)>,
 }
 

jagua-rs/src/entities/instances/strip_packing.rs

@@ -6,8 +6,11 @@ use crate::geometry::geo_traits::Shape;
 /// The items are to be packed in such a way that the total width of the strip used is minimized.
 #[derive(Debug, Clone)]
 pub struct SPInstance {
+    /// The items to be packed and their quantities
     pub items: Vec<(Item, usize)>,
+    /// The total area of the items
     pub item_area: f64,
+    /// The (fixed) height of the strip
     pub strip_height: f64,
 }
 

jagua-rs/src/entities/item.rs

@@ -6,7 +6,7 @@ use crate::geometry::primitives::simple_polygon::SimplePolygon;
 use crate::geometry::transformation::Transformation;
 use crate::util::config::SPSurrogateConfig;
 
-/// An `Item` can be placed in a `Bin`.
+/// An `Item` to be placed in a `Bin`.
 #[derive(Clone, Debug)]
 pub struct Item {
     pub id: usize,

jagua-rs/src/entities/placing_option.rs

@@ -5,9 +5,13 @@ use crate::geometry::transformation::Transformation;
 #[derive(Clone, Debug)]
 /// Encapsulates all required information to place an `Item` in a `Problem`
 pub struct PlacingOption {
+    /// Which layout to place the item in
     pub layout_index: LayoutIndex,
+    /// The id of the item to be placed
     pub item_id: usize,
+    /// The transformation to be applied to the item
     pub transform: Transformation,
+    /// The decomposition of the transformation
     pub d_transform: DTransformation,
 }
 

jagua-rs/src/geometry/geo_enums.rs

@@ -23,7 +23,10 @@ pub enum GeoRelation {
 
 #[derive(Clone, Debug, PartialEq)]
 pub enum AllowedRotation {
+    /// No rotation is allowed
     None,
+    /// Any rotation is allowed
     Continuous,
+    /// Only a limited set of rotations is allowed
     Discrete(Vec<f64>),
 }

jagua-rs/src/io/json_instance.rs

@@ -25,8 +25,8 @@ pub struct JsonInstance {
 pub struct JsonBin {
     /// The cost of using this bin
     pub cost: u64,
-    /// Number of this bin available
-    pub stock: u64,
+    /// Number of this bin available, if not present, it is assumed to be unlimited
+    pub stock: Option<u64>,
     /// Polygon shape of the bin
     pub shape: JsonPoly,
     /// A list of zones with different quality levels
@@ -47,8 +47,7 @@ pub struct JsonStrip {
 pub struct JsonItem {
     /// Number of times this item should be produced
     pub demand: u64,
-    /// List of allowed orientations angles (in degrees).
-    /// Some(_) if only the specified angles are allowed; None if continuous rotation is allowed
+    /// List of allowed orientations angles (in degrees), if not present, any orientation is allowed
     #[serde(skip_serializing_if = "Option::is_none")]
     pub allowed_orientations: Option<Vec<f64>>,
     /// Polygon shape of the item

jagua-rs/src/io/parser.rs

@@ -32,6 +32,7 @@ use crate::util::config::CDEConfig;
 use crate::util::polygon_simplification;
 use crate::util::polygon_simplification::{PolySimplConfig, PolySimplMode};
 
+/// Parses a `JsonInstance` into an `Instance`.
 pub struct Parser {
     poly_simpl_config: PolySimplConfig,
     cde_config: CDEConfig,
@@ -51,6 +52,7 @@ impl Parser {
         }
     }
 
+    /// Parses a `JsonInstance` into an `Instance`.
     pub fn parse(&self, json_instance: &JsonInstance) -> Instance {
         let mut items: Vec<(Item, usize)> = vec![];
         let mut instance = None;
@@ -171,8 +173,9 @@ impl Parser {
                                 quality_zones,
                                 self.cde_config,
                             );
+                            let stock = json_bin.stock.unwrap_or(u64::MAX) as usize;
 
-                            (bin, json_bin.stock as usize)
+                            (bin, stock)
                         });
                         bin_join_handles.push(handle);
                     }
@@ -219,6 +222,7 @@ impl Parser {
         instance
     }
 
+    /// Parses a `JsonInstance` and accompanying `JsonLayout`s into an `Instance` and `Solution`.
     pub fn parse_and_build_solution(
         &self,
         json_instance: &JsonInstance,
@@ -232,6 +236,7 @@ impl Parser {
     }
 }
 
+/// Builds a `Solution` from a set of `JsonLayout`s and an `Instance`.
 fn build_solution_from_json(
     json_layouts: &[JsonLayout],
     instance: Arc<Instance>,
@@ -335,6 +340,7 @@ fn build_solution_from_json(
     problem.create_solution(&None)
 }
 
+/// Composes a `JsonSolution` from a `Solution` and an `Instance`.
 pub fn compose_json_solution(
     solution: &Solution,
     instance: &Instance,
@@ -442,7 +448,7 @@ fn json_shape_to_simple_polygon(
     (shape, centering_transform)
 }
 
-pub fn simple_json_shape_to_simple_polygon(
+fn simple_json_shape_to_simple_polygon(
     s_json_shape: &JsonSimplePoly,
     center_polygon: bool,
     simpl_config: PolySimplConfig,

jagua-rs/src/lib.rs

@@ -1,5 +1,14 @@
+/// Everything collision detection engine related
 pub mod collision_detection;
+
+/// Entities to model 2D irregular cutting and packing problems
 pub mod entities;
+
+/// Geometric primitives and base algorithms
 pub mod geometry;
+
+/// Parser and JSON (de)serialization
 pub mod io;
+
+/// Helper functions
 pub mod util;

jagua-rs/src/util/mod.rs

@@ -1,11 +1,17 @@
 use crate::entities::layout::Layout;
 
+/// Set of functions used throughout assure the correctness of the library.
 pub mod assertions;
+
+/// Configuration options for the library
 pub mod config;
+
 pub mod f64a;
+
+/// Functions to simplify polygons in preprocessing
 pub mod polygon_simplification;
 
-///Intended for debugging purposes
+///Prints code to recreate a layout. Intended for debugging purposes.
 pub fn print_layout(layout: &Layout) {
     println!(
         "let mut layout = Layout::new(0, instance.bin({}).clone());",