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/autoslicer_feedback.py

@@ -7,7 +7,6 @@ import cv2
 import numpy as np
 
 
-# AutoslicerFeedbackMixin: class definition for ScanSlicer behavior.
 class AutoslicerFeedbackMixin:
     AUTOTUNE_PROFILE_ORDER = ("Fast", "Balanced", "Thorough", "Exhaustive")
     DEFAULT_AUTOTUNE_PROFILE = "Balanced"
@@ -86,15 +85,12 @@ class AutoslicerFeedbackMixin:
         },
     }
 
-    # autotune_profile_names: function definition for ScanSlicer behavior.
     def autotune_profile_names(self):
         return list(self.AUTOTUNE_PROFILE_ORDER)
 
-    # default_autotune_profile_name: function definition for ScanSlicer behavior.
     def default_autotune_profile_name(self):
         return self.DEFAULT_AUTOTUNE_PROFILE
 
-    # normalize_autotune_profile: function definition for ScanSlicer behavior.
     def normalize_autotune_profile(self, profile_name):
         text = str(profile_name).strip().lower() if profile_name is not None else ""
         for name in self.AUTOTUNE_PROFILE_ORDER:
@@ -102,12 +98,10 @@ class AutoslicerFeedbackMixin:
                 return name
         return self.DEFAULT_AUTOTUNE_PROFILE
 
-    # get_autotune_profile_config: function definition for ScanSlicer behavior.
     def get_autotune_profile_config(self, profile_name):
         normalized = self.normalize_autotune_profile(profile_name)
         return normalized, dict(self.AUTOTUNE_PROFILES[normalized])
 
-    # sample_candidates_evenly: function definition for ScanSlicer behavior.
     def sample_candidates_evenly(self, candidates, max_candidates):
         if max_candidates <= 0 or len(candidates) <= max_candidates:
             return list(candidates)
@@ -136,7 +130,6 @@ class AutoslicerFeedbackMixin:
 
         return selected
 
-    # feedback_path: function definition for ScanSlicer behavior.
     def feedback_path(self):
         override = os.environ.get("SCANSLICER_FEEDBACK_PATH")
         if override:
@@ -150,7 +143,6 @@ class AutoslicerFeedbackMixin:
             config_home = os.path.join(os.path.expanduser("~"), ".config")
         return os.path.join(config_home, "scanslicer", "autotune-feedback.json")
 
-    # load_feedback_entries: function definition for ScanSlicer behavior.
     def load_feedback_entries(self):
         path = self.feedback_path()
         if not os.path.isfile(path):
@@ -184,7 +176,6 @@ class AutoslicerFeedbackMixin:
             cleaned.append(entry)
         return cleaned[-self.MAX_FEEDBACK_ENTRIES:]
 
-    # save_feedback_entries: function definition for ScanSlicer behavior.
     def save_feedback_entries(self):
         path = self.feedback_path()
         directory = os.path.dirname(path)
@@ -194,7 +185,6 @@ class AutoslicerFeedbackMixin:
             json.dump(self.feedback_entries[-self.MAX_FEEDBACK_ENTRIES:], fh, indent=2, sort_keys=True)
         return path
 
-    # clear_feedback_entries: function definition for ScanSlicer behavior.
     def clear_feedback_entries(self):
         cleared_count = len(self.feedback_entries)
         self.feedback_entries = []
@@ -209,7 +199,6 @@ class AutoslicerFeedbackMixin:
             "removed_file": removed_file,
         }
 
-    # get_param_range_map: function definition for ScanSlicer behavior.
     def get_param_range_map(self):
         range_map = {}
         for spec in self.params.SPECS:
@@ -221,7 +210,6 @@ class AutoslicerFeedbackMixin:
             range_map[name] = max(1.0, float(max_value - min_value))
         return range_map
 
-    # compute_image_features: function definition for ScanSlicer behavior.
     def compute_image_features(self, image_gray=None):
         gray = image_gray if image_gray is not None else self.image_gray
         if gray is None:
@@ -239,7 +227,6 @@ class AutoslicerFeedbackMixin:
             "edge_density": float(edge_density),
         }
 
-    # normalize_boxes_for_storage: function definition for ScanSlicer behavior.
     def normalize_boxes_for_storage(self, boxes):
         normalized = []
         for box in boxes:
@@ -247,7 +234,6 @@ class AutoslicerFeedbackMixin:
             normalized.append([[float(arr[i, 0]), float(arr[i, 1])] for i in range(4)])
         return normalized
 
-    # boxes_signature: function definition for ScanSlicer behavior.
     def boxes_signature(self, boxes):
         if not boxes:
             return ""
@@ -264,7 +250,6 @@ class AutoslicerFeedbackMixin:
         ]
         return json.dumps(rounded, sort_keys=True)
 
-    # record_feedback: function definition for ScanSlicer behavior.
     def record_feedback(self, image_path, final_boxes, detected_boxes=None):
         if not image_path or not final_boxes:
             return False
@@ -303,7 +288,6 @@ class AutoslicerFeedbackMixin:
         self.save_feedback_entries()
         return True
 
-    # image_similarity: function definition for ScanSlicer behavior.
     def image_similarity(self, a, b):
         if not a or not b:
             return 0.0
@@ -314,7 +298,6 @@ class AutoslicerFeedbackMixin:
         dist += abs(float(a.get("edge_density", 0.0)) - float(b.get("edge_density", 0.0))) / 0.2
         return float(math.exp(-dist))
 
-    # param_similarity: function definition for ScanSlicer behavior.
     def param_similarity(self, candidate_values, reference_values, range_map):
         distances = []
         for key in self.AUTOTUNE_PARAM_KEYS:
@@ -333,7 +316,6 @@ class AutoslicerFeedbackMixin:
         mean_dist = float(np.mean(distances))
         return max(0.0, 1.0 - min(1.0, mean_dist))
 
-    # feedback_score_bonus: function definition for ScanSlicer behavior.
     def feedback_score_bonus(self, candidate_values, box_count, image_features):
         if not self.feedback_entries or not image_features:
             return 0.0
@@ -368,7 +350,6 @@ class AutoslicerFeedbackMixin:
         # Keep this as a moderate bias, not an override.
         return bonus * 280.0
 
-    # score_detected_boxes: function definition for ScanSlicer behavior.
     def score_detected_boxes(self, boxes, candidate_values=None, image_features=None, box_area_props=None):
         if not boxes:
             return -1e9
@@ -418,13 +399,11 @@ class AutoslicerFeedbackMixin:
         score += self.feedback_score_bonus(candidate, count, image_features)
         return score
 
-    # build_autotune_candidates: function definition for ScanSlicer behavior.
     def build_autotune_candidates(self, base_values, profile_name=None):
         _, profile = self.get_autotune_profile_config(profile_name)
         base = dict(base_values)
         candidates = []
 
-        # add: function definition for ScanSlicer behavior.
         def add(overrides):
             c = dict(base)
             c.update(overrides)
@@ -521,7 +500,6 @@ class AutoslicerFeedbackMixin:
         )
         return self.sample_candidates_evenly(deduped_candidates, max_candidates)
 
-    # rank_autotune_candidates: function definition for ScanSlicer behavior.
     def rank_autotune_candidates(self, candidates, base_values, image_features):
         if not candidates:
             return []
@@ -569,7 +547,6 @@ class AutoslicerFeedbackMixin:
         ranked.sort(key=lambda item: item[0], reverse=True)
         return [candidate for _, candidate in ranked]
 
-    # autodetect_candidate_boxes: function definition for ScanSlicer behavior.
     def autodetect_candidate_boxes(self, candidate_values, fast_mode=False, downscale_max_dim=None):
         original_image = self.image
         original_gray = self.image_gray
@@ -611,7 +588,6 @@ class AutoslicerFeedbackMixin:
                 self.image = original_image
                 self.image_gray = original_gray
 
-    # autotune_for_current_image: function definition for ScanSlicer behavior.
     def autotune_for_current_image(self, update_status_callback=None, profile_name=None):
         if not self.image_loaded():
             raise RuntimeError("No image loaded for auto-tune.")