chore: prune boilerplate and refresh stale docs

- Remove 257 redundant per-definition comment stubs across the package
- Drop dead nonlocal declarations in autoslicer_detection.py
- Document the swapped flag and swap_left_right in architecture docs
- Remove unsupported 'legacy override' claims from autotune/runtime docs

scanslicer/canvas_state.py

@@ -4,9 +4,7 @@ from PySide6.QtCore import QPointF, QRectF
 from .slices import PhotoSlice, polys_iou
 
 
-# CanvasStateMixin: class definition for ScanSlicer behavior.
 class CanvasStateMixin:
-    # fit_image_to_view: function definition for ScanSlicer behavior.
     def fit_image_to_view(self):
         if self.image is None:
             return
@@ -22,7 +20,6 @@ class CanvasStateMixin:
         shown_h = image_h * self.zoom
         self.pan_offset = QPointF((view_w - shown_w) / 2.0, (view_h - shown_h) / 2.0)
 
-    # reset_view: function definition for ScanSlicer behavior.
     def reset_view(self):
         if self.image is None:
             return False
@@ -32,7 +29,6 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # set_image: function definition for ScanSlicer behavior.
     def set_image(self, image, new_image=False):
         if self.image is None or new_image:
             self.user_transformed_view = False
@@ -44,27 +40,23 @@ class CanvasStateMixin:
             self.fit_image_to_view()
         self.update()
 
-    # _clamp_slice_to_image: function definition for ScanSlicer behavior.
     def _clamp_slice_to_image(self, slice_obj):
         if slice_obj is None:
             return None
         slice_obj.bbox = self._clamp_bbox_to_image(slice_obj.bbox)
         return slice_obj
 
-    # _coerce_slice_in_bounds: function definition for ScanSlicer behavior.
     def _coerce_slice_in_bounds(self, bbx):
         if isinstance(bbx, PhotoSlice):
             return self._clamp_slice_to_image(bbx)
         return PhotoSlice(self._clamp_bbox_to_image(bbx))
 
-    # add_bbox: function definition for ScanSlicer behavior.
     def add_bbox(self, bbx):
         self.slices.append(self._coerce_slice_in_bounds(bbx))
         self.set_active_slice(len(self.slices) - 1)
         self.update()
 
     @staticmethod
-    # _aabb_overlaps: function definition for ScanSlicer behavior.
     def _aabb_overlaps(poly_a, poly_b):
         a = np.array(poly_a, dtype=np.float32).reshape(-1, 2)
         b = np.array(poly_b, dtype=np.float32).reshape(-1, 2)
@@ -83,7 +75,6 @@ class CanvasStateMixin:
             or b_max_y < a_min_y
         )
 
-    # update_bboxes: function definition for ScanSlicer behavior.
     def update_bboxes(self, bbxs=None):
         if bbxs is not None:
             active_slice = None
@@ -114,7 +105,6 @@ class CanvasStateMixin:
 
         self.update()
 
-    # set_active_slice: function definition for ScanSlicer behavior.
     def set_active_slice(self, index):
         if index is None:
             normalized = None
@@ -130,7 +120,6 @@ class CanvasStateMixin:
         self.active_slice_changed.emit(-1 if normalized is None else normalized)
         self.update()
 
-    # get_active_slice: function definition for ScanSlicer behavior.
     def get_active_slice(self):
         if self.active_slice_index is None:
             return None
@@ -139,7 +128,6 @@ class CanvasStateMixin:
             return None
         return self.slices[self.active_slice_index]
 
-    # set_active_slice_locked: function definition for ScanSlicer behavior.
     def set_active_slice_locked(self, locked):
         active_slice = self.get_active_slice()
         if active_slice is None:
@@ -148,20 +136,17 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # set_all_slices_locked: function definition for ScanSlicer behavior.
     def set_all_slices_locked(self, locked):
         for s in self.slices:
             s.toggle_locked(bool(locked))
         self.update()
         return len(self.slices)
 
-    # are_all_slices_locked: function definition for ScanSlicer behavior.
     def are_all_slices_locked(self):
         if len(self.slices) == 0:
             return False
         return all(s.locked for s in self.slices)
 
-    # remove_active_slice: function definition for ScanSlicer behavior.
     def remove_active_slice(self):
         if self.active_slice_index is None:
             return False
@@ -183,7 +168,6 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # squarize_active_slice: function definition for ScanSlicer behavior.
     def squarize_active_slice(self):
         active_slice = self.get_active_slice()
         if active_slice is None:
@@ -192,7 +176,6 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # swap_active_slice_left_right: function definition for ScanSlicer behavior.
     def swap_active_slice_left_right(self):
         active_slice = self.get_active_slice()
         if active_slice is None:
@@ -201,7 +184,6 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # reset_active_slice_rotation: function definition for ScanSlicer behavior.
     def reset_active_slice_rotation(self):
         active_slice = self.get_active_slice()
         if active_slice is None:
@@ -211,11 +193,9 @@ class CanvasStateMixin:
         self.update()
         return True
 
-    # set_rotate_handles_mode: function definition for ScanSlicer behavior.
     def set_rotate_handles_mode(self, enabled):
         self.rotate_handles_mode = bool(enabled)
 
-    # _image_rect_view: function definition for ScanSlicer behavior.
     def _image_rect_view(self):
         if self.image is None:
             return QRectF()
@@ -226,7 +206,6 @@ class CanvasStateMixin:
             self.image.height() * self.zoom,
         )
 
-    # _view_to_image: function definition for ScanSlicer behavior.
     def _view_to_image(self, p):
         return np.array(
             [
@@ -236,7 +215,6 @@ class CanvasStateMixin:
             dtype=np.float64,
         )
 
-    # _clamp_view_pos_to_canvas: function definition for ScanSlicer behavior.
     def _clamp_view_pos_to_canvas(self, p):
         max_x = max(0.0, float(self.width() - 1))
         max_y = max(0.0, float(self.height() - 1))
@@ -245,7 +223,6 @@ class CanvasStateMixin:
             min(max(p.y(), 0.0), max_y),
         )
 
-    # _clamp_image_point: function definition for ScanSlicer behavior.
     def _clamp_image_point(self, point):
         if self.image is None:
             return np.array(point, dtype=np.float64)
@@ -257,7 +234,6 @@ class CanvasStateMixin:
         p[1] = min(max(p[1], 0.0), max_y)
         return p
 
-    # _clamp_bbox_to_image: function definition for ScanSlicer behavior.
     def _clamp_bbox_to_image(self, bbox):
         if self.image is None:
             return np.array(bbox, dtype=np.float64)
@@ -269,7 +245,6 @@ class CanvasStateMixin:
         pts[:, 1] = np.clip(pts[:, 1], 0.0, max_y)
         return pts
 
-    # _image_to_view: function definition for ScanSlicer behavior.
     def _image_to_view(self, p):
         return QPointF(
             p[0] * self.zoom + self.pan_offset.x(),