doc(kpm): rationale comments for kpm/freak too_many_arguments allows (#83)

crates/core/src/kpm/freak/homography.rs

@@ -296,6 +296,9 @@ fn homography_3_points_geometrically_consistent(
 /// `math/geometry.h:71`. Private helper used by RANSAC to filter degenerate
 /// 4-tuples before solving for the homography.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn homography_4_points_geometrically_consistent(
     x1: &[f32; 2],
@@ -964,6 +967,9 @@ pub fn update_projective_motion_post_multiply(hp: &mut [f32; 9], h: &[f32; 9], x
 /// C++ equivalent: `vision::Condition4Points2d<T>` from
 /// `homography_estimation/homography_solver.h:47`.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn condition_4_points_2d(
     xp: &mut [[f32; 2]; 4],
@@ -1022,6 +1028,9 @@ fn condition_4_points_2d(
 /// C++ equivalent: `vision::DenormalizeHomography<T>` from
 /// `homography_estimation/homography_solver.h:104`.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn denormalize_homography(
     hp: &mut [f32; 9],
@@ -1104,6 +1113,9 @@ fn add_homography_point_constraint(dst: &mut [f32; 18], x: &[f32; 2], xp: &[f32;
 /// C++ equivalent: `vision::SolveHomography4PointsInhomogenous<T>` from
 /// `homography_estimation/homography_solver.h:185`.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn solve_homography_4_points_inhomogeneous(
     h: &mut [f32; 9],
@@ -1155,6 +1167,9 @@ fn solve_homography_4_points_inhomogeneous(
 /// `homography_estimation/homography_solver.h:209`. Called from
 /// [`preemptive_robust_homography`] for each RANSAC trial.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn solve_homography_4_points(
     h: &mut [f32; 9],
@@ -1396,6 +1411,9 @@ fn fast_median(a: &mut [(f32, i32)]) {
 /// `vision::PreemptiveRobustHomography<T>` from
 /// `homography_estimation/robust_homography.h:96`.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 pub fn preemptive_robust_homography(
     h: &mut [f32; 9],
@@ -1819,6 +1837,9 @@ fn symmetric_extend_upper_to_lower_8x8(a: &mut [f32; 64]) {
 /// `vision::ComputeHomographyNormalEquationsPostMultiply<T>` from
 /// `homography_estimation/robust_homography.h:397`.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 fn compute_homography_normal_equations_post_multiply(
     jt_j: &mut [f32; 64],
@@ -1983,6 +2004,9 @@ fn solve_positive_definite_system_8x8(x: &mut [f32; 8], a: &[f32; 64], b: &[f32;
 /// `homography_estimation/robust_homography.h:500`. Called by
 /// [`RobustHomography::find`] after the RANSAC step.
 #[inline(always)]
+// rationale: numerical homography routine — the flat point/matrix/scalar
+// signature mirrors the math and the C++ source; a param struct would
+// obscure it. Restructure deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 pub fn polish_homography(
     h: &mut [f32; 9],

crates/core/src/kpm/freak/hough.rs

@@ -104,6 +104,8 @@ impl BinParams {
     /// * `min_y`, `max_y` - Translation y range (min_y < max_y)
     /// * `min_scale`, `max_scale` - Scale range (min_scale < max_scale)
     /// * `scale_k` - Log base for scale (typically 2.0 or e)
+    // rationale: mirrors the C++ HoughSimilarityVoting init parameter list
+    // (bin + scale configuration); struct-grouping deferred to pre-1.0 (#83).
     #[allow(clippy::too_many_arguments)]
     pub fn new(
         num_x_bins: i32,
@@ -213,6 +215,8 @@ impl BinParams {
     /// 0, 0, num_angle_bins, num_scale_bins)` from
     /// `hough_similarity_voting.cpp:95-99`, where `numXBins == 0 &&
     /// numYBins == 0` toggles `mAutoAdjustXYNumBins = true`.
+    // rationale: mirrors the C++ HoughSimilarityVoting init parameter list
+    // (bin + scale configuration); struct-grouping deferred to pre-1.0 (#83).
     #[allow(clippy::too_many_arguments)]
     pub fn new_auto_xy(
         num_angle_bins: i32,
@@ -633,6 +637,8 @@ pub fn find_features(
 /// # Returns
 /// The bin index with the most votes (>= MIN_VOTES_THRESHOLD).
 /// Returns `Err(InvalidInput("insufficient votes for feature matching".into()))` if no bin reaches the threshold.
+// rationale: numerical voting routine — flat signature matches the C++
+// source; struct-grouping deferred to a pre-1.0 pass (#83).
 #[allow(clippy::too_many_arguments)]
 pub fn find_hough_similarity(
     voting: &mut HoughSimilarityVoting,

crates/core/src/kpm/ref_data_set.rs

@@ -244,6 +244,8 @@ impl KpmRefDataSet {
     /// * `page_no`         — page number to assign to all features.
     /// * `image_no`        — image number within the page.
     /// * `matcher`         — backend that will extract FREAK features.
+    // rationale: public generator mirroring the C++ kpmGenRefDataSet parameter
+    // list; struct-grouping deferred to a pre-1.0 pass (#83).
     #[allow(clippy::too_many_arguments)]
     pub fn generate(
         image: &[u8],

docs/design/issue-83-too-many-args-audit.md

@@ -78,9 +78,17 @@ Defer to a deliberate pass rather than obscure the math.
 
 ## Incremental plan
 
-1. **This PR:** refactor `sample_grid`, `make_template`, `select_features`;
-   add rationale comments to the 13 public/SIMD `ar`/`ar2` allows.
-2. **Follow-up:** `kpm/freak` public rationale comments + narrow the
-   `detector.rs` module-level allow.
+1. **Done (PR #228):** refactored `sample_grid`, `make_template`,
+   `select_features`; added rationale comments to the public/SIMD `ar`/`ar2`
+   allows.
+2. **Done:** `kpm/freak` + `ref_data_set` rationale comments — the
+   homography numerical routines, the Hough constructors / voting, and
+   `KpmRefDataSet::generate`. The `webarkit_cpp_*` FFI extern shim and the
+   `detector.rs` module-level allow are left as-is: both already carry an
+   explanatory rationale comment, and narrowing the 34-fn detector module
+   would be churn with no lint benefit.
 3. **Pre-1.0 (maybe):** deliberate public-API restructure of the
-   C-faithful `ar`/`ar2` entry points into param structs (breaking).
+   C-faithful `ar`/`ar2` entry points into param structs (breaking). This is
+   the only remaining item; every current allow is now either removed or
+   carries a `// rationale:` note, so #83 can be closed and this restructure
+   tracked as its own pre-1.0 API task if desired.