From 60991013369d976e1084b763fb09b2b6b1290e70 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Wed, 27 May 2026 15:21:46 -0700
Subject: [PATCH] docs: remove stale distanceSQ8 JSDoc left by the SQ8 hook
 refactor

The native SQ8 distance hook renamed the original distanceSQ8 to distanceSQ8Js
and added a dispatcher in its place, but left the old function's doc block
orphaned above distanceSQ8Js (two consecutive comments, the first dangling).
Merge them into one accurate block on distanceSQ8Js with dash-notation params.
---
 src/utils/vectorQuantization.ts | 39 ++++++++++++++-------------------
 1 file changed, 16 insertions(+), 23 deletions(-)

diff --git a/src/utils/vectorQuantization.ts b/src/utils/vectorQuantization.ts
index 36234152..83a16648 100644
--- a/src/utils/vectorQuantization.ts
+++ b/src/utils/vectorQuantization.ts
@@ -96,31 +96,24 @@ export function dequantizeSQ8(quantized: Uint8Array, min: number, max: number):
 }
 
 /**
- * Compute approximate cosine distance between two SQ8-quantized vectors.
+ * Reference JS implementation of {@link distanceSQ8}: approximate cosine distance
+ * between two SQ8-quantized vectors, operating directly on the uint8 arrays without
+ * full dequantization. Cosine distance is `1 - (A·B / (|A| · |B|))`; for quantized
+ * values `q_i` with codebook `(min, max)` the actual value is
+ * `min + q_i * (max - min) / 255`, and the dot product / norms are computed on the
+ * quantized values and rescaled by the codebook parameters.
  *
- * Operates directly on uint8 arrays without full dequantization.
- * Uses integer arithmetic where possible for speed.
+ * Exported so callers can explicitly restore the default after swapping in a native
+ * implementation, and so cross-language parity tests can compare native output
+ * against this baseline.
  *
- * Cosine distance = 1 - (A.B / (|A| * |B|))
- *
- * For quantized values q_i with codebook (min, max):
- *   actual_i = min + q_i * (max - min) / 255
- *
- * The dot product and norms can be computed on quantized values
- * and scaled by the codebook parameters.
- *
- * @param a - First quantized vector
- * @param aMin - First vector codebook minimum
- * @param aMax - First vector codebook maximum
- * @param b - Second quantized vector
- * @param bMin - Second vector codebook minimum
- * @param bMax - Second vector codebook maximum
- * @returns Approximate cosine distance [0, 2]
- */
-/**
- * Reference JS implementation of {@link distanceSQ8}. Exported so callers can
- * explicitly restore the default after swapping in a native implementation, and
- * so cross-language parity tests can compare native output against this baseline.
+ * @param a - First quantized vector.
+ * @param aMin - First vector's codebook minimum.
+ * @param aMax - First vector's codebook maximum.
+ * @param b - Second quantized vector.
+ * @param bMin - Second vector's codebook minimum.
+ * @param bMax - Second vector's codebook maximum.
+ * @returns Approximate cosine distance in [0, 2].
  */
 export function distanceSQ8Js(
   a: Uint8Array,