From 5371cc697b50a2af9345783d3e8a651b6055a98d Mon Sep 17 00:00:00 2001
From: obucklin <obucklin@gmail.com>
Date: Wed, 24 Apr 2024 17:19:04 +0200
Subject: [PATCH] added docstrings

---
 src/compas_timber/planning/beam_nesting.py | 35 ++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/compas_timber/planning/beam_nesting.py b/src/compas_timber/planning/beam_nesting.py
index ba881af47..08b5fdecd 100644
--- a/src/compas_timber/planning/beam_nesting.py
+++ b/src/compas_timber/planning/beam_nesting.py
@@ -3,6 +3,20 @@
 
 
 class Nester(object):
+    """Class for nesting beams into a stock beam
+
+
+    Attributes
+    ----------
+    stock_length : float
+        length of the stock beam in which to be nested
+    tolerance : float
+        tolerance for the nesting algorithm, if the remaining space in a bin is less than the tolerance, the bin is considered full
+    total_length : float
+        total length of all beams to be nested
+
+    """
+
     def __init__(self):
         pass
 
@@ -10,11 +24,13 @@ def shuffle(self, lst):
         random.shuffle(lst)
 
     def space_remaining(self, bin):
+        """returns the space remaining in a bin"""
         if len(bin) == 0:
             return self.stock_length
         return self.stock_length - (sum([beam.blank_length for beam in bin]))
 
     def sorted_dict(self, bin_dict):
+        """sorts a dictionary of bins by space remaining in each bin"""
         if len(bin_dict.items()) < 2:
             return bin_dict
         bin_list = sorted(bin_dict.values(), key=lambda x: self.space_remaining(x))
@@ -24,9 +40,11 @@ def sorted_dict(self, bin_dict):
         return dict
 
     def total_space(self, bin_dict):
+        """returns the total space remaining in all bins, AKA total waste"""
         return sum([self.space_remaining(bin) for bin in bin_dict.values()])
 
     def get_initial_bins(self, beams):
+        """returns a dictionary of bins with beams nested in them"""
         bins = OrderedDict([(0, [])])
         for beam in beams:
             fits = False
@@ -41,6 +59,7 @@ def get_initial_bins(self, beams):
         return bins
 
     def fill_bins(self, bins, beams):
+        """fills a partial bins dictionary with beams, returns a dictionary of bins with beams nested in them"""
         for beam in beams:
             fits = False
             bins = self.sorted_dict(bins)
@@ -54,6 +73,7 @@ def fill_bins(self, bins, beams):
         return bins
 
     def parse_bins(self, bin_dict):
+        """evaluates the success of the nesting, returns a dictionary with the results of the nesting process"""
         dict_out = {"done": False}
         dict_out["finished_bins"] = bin_dict
         if self.total_space(bin_dict) < self.stock_length:
@@ -73,6 +93,21 @@ def parse_bins(self, bin_dict):
             return dict_out
 
     def get_bins(self, beams, stock_length, tolerance=1, iterations=10):
+        """returns a dictionary of bins with beams nested in them
+
+        Parameters
+        ----------
+        beams : list(:class:`compas_timber.parts.Beam`)
+            list of beams to be nested
+        stock_length : float
+            length of the stock beam in which to be nested
+        tolerance : float
+            tolerance for the nesting algorithm, if the remaining space in a bin is less than the tolerance, the bin is considered full
+        iterations : int
+            number of iterations to run the nesting algorithm, the algorithm will stop when the total waste is less than the stock length
+
+        """
+
         self.stock_length = stock_length
         self.tolerance = tolerance
         if tolerance is None: