docs(vm,analyser): drop external repo references and simplify comments 📝

Addresses review feedback on PR #146 from @timfennis:

* scrub all mentions of an external AoC repo (`benches/programs/vec_hot_loop.ndc`,
  three comments in `ndc_vm/src/vm.rs`) — those references don't belong here
* simplify the OpAssignment "both `op=` and `op`" comment in
  `ndc_analyser/src/analyser.rs` — drop the jargon, keep the rationale
* tighten the `analyse_call` doc comment — say what it does, skip the
  side-table mechanics that the caller already documents

No behaviour change.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: timfennis

benches/programs/vec_hot_loop.ndc

@@ -1,7 +1,5 @@
-// Vec dispatch hot loop. Mirrors the per-iteration vec calls that drove
-// the AoC 2025/08 regression in PR #141: a tight loop over millions of
-// `Tuple<Int, Int> + Tuple<Int, Int>` calls. The CallVec fast path
-// should bring this close to the master baseline.
+// Vec dispatch hot loop: a tight loop over many
+// `Tuple<Int, Int> + Tuple<Int, Int>` calls.
 let n = 200_000;
 let acc = (0, 0);
 for i in 0..n {

ndc_analyser/src/analyser.rs

@@ -202,11 +202,8 @@ impl Analyser {
                 let right_type = self.analyse_or_any(r_value);
                 let arg_types = vec![left_type, right_type];
 
-                // Both `op=` and `op` desugar from operator syntax, so vec
-                // dispatch is available for either path. Resolving `op` gives
-                // us the result type to widen the lvalue with — that's how
-                // `a += (3, 4)` on `Tuple<Int, Int>` widens correctly instead
-                // of trying to widen with the scalar `+(Int,Int) -> Int`.
+                // Resolve both `op=` and `op` so we can widen the lvalue
+                // by the result type of whichever one actually fires.
                 let ResolvedCall {
                     binding: assign_binding,
                     ..
@@ -472,11 +469,8 @@ impl Analyser {
         }
     }
 
-    /// Analyse a call expression — either `Call` (regular) or `OperatorCall`.
-    /// Resolves the function binding (with vec dispatch eligible iff
-    /// `kind == Operator`) and returns the inferred result type. The binding
-    /// is written back into the function-identifier node and the return type
-    /// recorded on the call's [`NodeId`] via the surrounding `analyse` wrapper.
+    /// Resolves a call (regular or operator-form) and returns its result type.
+    /// Only operator-form calls are eligible for vec dispatch.
     fn analyse_call(
         &mut self,
         function: &mut ExpressionLocation,

ndc_vm/src/vm.rs

@@ -818,10 +818,9 @@ impl Vm {
     }
 
     /// Probes `OpCode::Call`'s callee for vec dispatch eligibility without
-    /// allocating: returns `(vec_candidates_vars, axis_len)` borrowed off the
-    /// stack when vec applies. `dispatch_vec_call_dynamic` resolves the
-    /// candidates lazily — avoids the `Vec<Function>` allocation per call
-    /// that the eager-resolve version cost on AoC-style hot loops.
+    /// allocating: returns the `OverloadSet` Rc and broadcast axis length
+    /// when vec applies. `dispatch_vec_call_dynamic` resolves the candidates
+    /// lazily from there, avoiding a per-call `Vec<Function>` allocation.
     fn try_vec_dispatch(&self, args: usize) -> Option<(Rc<Object>, usize)> {
         let Value::Object(obj) = &self.stack[self.stack.len() - args - 1] else {
             return None;
@@ -882,11 +881,10 @@ impl Vm {
         })
     }
 
-    /// Vec dispatch when `vec_candidates` lives behind a shared `Object::OverloadSet`
-    /// Rc — the runtime-narrowing path for `Binding::Dynamic` operator calls.
-    /// Resolves the candidate vars to `Function`s lazily inside the broadcast
-    /// loop with a last-match cache, so homogeneous tuples (the common case,
-    /// including the `AoC` 2025/08 hot loop) pay one resolve per outer call
+    /// Vec dispatch for `Binding::Dynamic` operator calls — the runtime
+    /// picks the matching scalar overload per element position. Resolves
+    /// candidates lazily from `vec_candidates` with a last-match cache, so
+    /// homogeneous tuples (the common case) pay one resolve per outer call
     /// instead of N. No upfront `Vec<Function>` allocation.
     fn dispatch_vec_call_dynamic(
         &mut self,
@@ -999,9 +997,8 @@ impl Vm {
         let mut elem_args: Vec<Value> = Vec::with_capacity(args);
         let mut results: Vec<Value> = Vec::with_capacity(axis_len);
         // Cache the last scalar that matched. Homogeneous tuples — the common
-        // case at runtime, including the AoC 2025/08 hot loop — all want the
-        // same scalar at every position, so probing it first short-circuits
-        // the candidate walk for positions 1..N.
+        // case — all want the same scalar at every position, so probing it
+        // first short-circuits the candidate walk for positions 1..N.
         let mut last_match: Option<usize> = None;
 
         for i in 0..axis_len {