docs(rustdoc): add runnable examples across operators, metrics, and Pareto utilities

Completes the rustdoc audit — every public item now has at least one
```rust example block in its docstring, exercised by
`cargo test --doc` (55 doctests, all passing).

- Operators: BitFlipMutation, SwapMutation, RealBounds,
  GaussianMutation, BoundedGaussianMutation,
  SimulatedBinaryCrossover, PolynomialMutation, LevyMutation,
  ClampToBounds, ProjectToSimplex.
- Metrics: hypervolume_2d, hypervolume_nd, spacing.
- Pareto utilities: pareto_compare, pareto_front, best_candidate,
  non_dominated_sort, crowding_distance, das_dennis,
  ParetoArchive.

Each example is short (5-15 lines) and self-contained — copy-paste
into a fresh project and it runs.

src/operators/binary.rs

@@ -9,6 +9,19 @@ use crate::traits::Variation;
 ///
 /// Always returns exactly one child (spec §11.3). Panics if `probability` is
 /// outside `[0.0, 1.0]` or if no parents are provided.
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let mut rng = rng_from_seed(42);
+/// let mut m = BitFlipMutation { probability: 0.5 };
+/// let parent = vec![true, false, true, false];
+/// let children = m.vary(std::slice::from_ref(&parent), &mut rng);
+/// assert_eq!(children.len(), 1);
+/// assert_eq!(children[0].len(), parent.len());
+/// ```
 #[derive(Debug, Clone)]
 pub struct BitFlipMutation {
     /// Per-bit flip probability. Must lie in `[0.0, 1.0]`.