Refine solution commentary for experienced programmers

- Remove redundant or overly simplistic explanations.
- Focus on Rust-specific idioms and design choices.
- Clean up formatting and technical depth.

Author: mgeisler

src/references/solution.md

@@ -4,27 +4,28 @@
 {{#include exercise.rs:solution}}
 ```
 
-This solution highlights the difference between shared and mutable references:
+The solution demonstrates the fundamental distinction between shared and
+exclusive references:
 
-- **Shared References (`&`):** `magnitude` needs to read the vector components
-  but not modify them, so it takes a shared reference (`&[f64; 3]`).
-- **Mutable References (`&mut`):** `normalize` modifies the vector in place, so
-  it requires an exclusive mutable reference (`&mut [f64; 3]`).
-- **Dereferencing:** In the `normalize` loop, `item` is a `&mut f64`. To modify
-  the actual value, we must dereference it using `*item`.
-- **Iteration:** When we iterate over a reference to an array (like `vector`),
-  the iterator yields references to the elements. In `magnitude`, `coord` is
-  `&f64`. In `normalize`, `item` is `&mut f64`.
+- **Shared References (`&`):** Used in `magnitude` because the function only
+  reads the vector components.
+- **Exclusive References (`&mut`):** Required in `normalize` to modify the array
+  elements in place.
+- **Explicit Dereferencing:** Inside `normalize`, `item` is an `&mut f64`. We
+  use `*item` to access and modify the underlying value.
 
 <details>
 
-- Note that in `normalize` we were able to do `*item /= mag` to modify each
-  element. This is because we're iterating using a mutable reference to an
-  array, which causes the `for` loop to give mutable references to each element.
-
-- It is also possible to take slice references here, e.g.,
-  `fn
-  magnitude(vector: &[f64]) -> f64`. This makes the function more general,
-  at the cost of a runtime length check.
+- **Iterating over References:** Iterating over `&vector` or `&mut vector`
+  yields references to the elements. This is why `coord` is `&f64` and `item` is
+  `&mut f64`.
+- **Arrays vs. Slices:** The functions are defined using array references
+  (`&[f64; 3]`), which ensures the length is known at compile time. Using slices
+  (`&[f64]`) would make the functions more flexible but would introduce a
+  runtime length check or potential for panics if the slice has the wrong size.
+- **Method Call Ergonomics:** In `magnitude`, we can call `mag_squared.sqrt()`
+  directly. In `normalize`, we pass `vector` (an `&mut [f64; 3]`) to
+  `magnitude`, and Rust automatically downgrades the exclusive reference to a
+  shared reference to match the signature.
 
 </details>