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/pareto/archive.rs

@@ -9,6 +9,23 @@ use crate::core::objective::ObjectiveSpace;
 /// archive insert/extend operations maintain the non-domination property among
 /// members; `truncate` enforces a maximum size by simple tail-truncation in
 /// v1.
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![
+///     Objective::minimize("f1"),
+///     Objective::minimize("f2"),
+/// ]);
+/// let mut a: ParetoArchive<u32> = ParetoArchive::new(s);
+/// a.insert(Candidate::new(1, Evaluation::new(vec![1.0, 4.0])));
+/// a.insert(Candidate::new(2, Evaluation::new(vec![3.0, 2.0])));
+/// // Dominated by both — should be discarded:
+/// a.insert(Candidate::new(3, Evaluation::new(vec![5.0, 5.0])));
+/// assert_eq!(a.members().len(), 2);
+/// ```
 #[derive(Debug, Clone)]
 pub struct ParetoArchive<D> {
     /// The current approximate non-dominated set.