online.py: Add more comments

cinematinator/__init__.py

+"""
+Empty file required for Python's package structure.
+"""

cinematinator/online.py

@@ -23,6 +23,13 @@ class OnlineFirstFitSolver:
         self.cinema = cinema
 
     def try_seat_group(self, group_size: GroupSize) -> Optional[Coordinates]:
+        """
+        Try to seat a group using the "first-fit" strategy.
+
+        Iterate over each row from left to right, top to bottom, and seat a group in the
+        first found position that will fit.
+        """
+
         for y in range(self.cinema.height):
             for x in range(self.cinema.width):
                 if self.cinema.can_seat_group(x, y, group_size):
@@ -37,6 +44,14 @@ class OnlineLastFitSolver:
         self.cinema = cinema
 
     def try_seat_group(self, group_size: GroupSize) -> Optional[Coordinates]:
+        """
+        Try to seat a group using the "last-fit" strategy.
+
+        Iterate over each row from right to left, bottom to top, and seat a group in the
+        first found position that will fit.
+
+        Identical to first-fit except for `reversed` usages.
+        """
         for y in reversed(range(self.cinema.height)):
             for x in reversed(range(self.cinema.width)):
                 if self.cinema.can_seat_group(x, y, group_size):
@@ -47,11 +62,25 @@ class OnlineLastFitSolver:
 
 
 class OnlineHeuristicSolver:
+    """
+    Allows choosing positions based on a heuristic function, which is calculated for
+    each spot that could fit a group of the given size.
+
+    If two locations return the same minimum value for a group size the top-leftmost
+    position is chosen.
+    """
+
     def __init__(self, cinema: Cinema, heuristic: Heuristic) -> None:
         self.cinema = cinema
         self.heuristic = heuristic
 
     def try_seat_group(self, group_size: GroupSize) -> Optional[Coordinates]:
+        """
+        Calculate the penalty value for each of the positions that will fit a group of
+        the given size, then choose the "best" location (with minimum penalty).
+
+        If no such position exists None is returned.
+        """
         potential_locations: List[Tuple[int, Coordinates]] = []
 
         for y in range(self.cinema.height):
@@ -93,11 +122,20 @@ class OnlineHeuristicSolver:
 
 
 def greedy_heuristic(cinema: Cinema, spot: Coordinates, group_size: GroupSize) -> int:
+    """
+    "Greedy" heuristic: returns the amount of seats that would be newly blocked by
+    placing a group of this size at this spot in this cinema.
+    """
     x, y = spot
     return cinema.newly_blocked_seats(x, y, group_size)
 
 
 def center_heuristic(cinema: Cinema, spot: Coordinates, group_size: GroupSize) -> int:
+    """
+    "Center" heuristic: prefers seating groups near to the center of the cinema (as
+    "these seats have a better view").
+    Not intended to be competitive or described in the paper.
+    """
     x, y = spot
     left_edge = x
     right_edge = x + group_size