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.

src/pareto/crowding.rs

@@ -11,6 +11,28 @@ use crate::core::objective::ObjectiveSpace;
 /// `f64::INFINITY`. If the front has 0 entries an empty vector is returned;
 /// 1 or 2 entries return all `f64::INFINITY`. All comparisons happen on
 /// minimization-oriented objective values (spec §9.6).
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![
+///     Objective::minimize("f1"),
+///     Objective::minimize("f2"),
+/// ]);
+/// // Three points along a Pareto-like trade-off; the interior point gets
+/// // a finite crowding distance, the boundaries get +∞.
+/// let pop = [
+///     Candidate::new((), Evaluation::new(vec![0.0, 4.0])),
+///     Candidate::new((), Evaluation::new(vec![2.0, 2.0])),
+///     Candidate::new((), Evaluation::new(vec![4.0, 0.0])),
+/// ];
+/// let d = crowding_distance(&pop, &[0, 1, 2], &s);
+/// assert!(d[0].is_infinite());
+/// assert!(d[1].is_finite() && d[1] > 0.0);
+/// assert!(d[2].is_infinite());
+/// ```
 pub fn crowding_distance<D>(
     population: &[Candidate<D>],
     front: &[usize],

src/pareto/dominance.rs

@@ -29,6 +29,21 @@ pub enum Dominance {
 ///    `constraint_violation` dominates.
 /// 3. Otherwise compare objective values after converting both to
 ///    minimization orientation via [`ObjectiveSpace::as_minimization`].
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![
+///     Objective::minimize("f1"),
+///     Objective::minimize("f2"),
+/// ]);
+/// let a = Evaluation::new(vec![1.0, 1.0]);
+/// let b = Evaluation::new(vec![2.0, 2.0]);
+/// assert_eq!(pareto_compare(&a, &b, &s), Dominance::Dominates);
+/// assert_eq!(pareto_compare(&b, &a, &s), Dominance::DominatedBy);
+/// ```
 pub fn pareto_compare(a: &Evaluation, b: &Evaluation, objectives: &ObjectiveSpace) -> Dominance {
     let a_feasible = a.is_feasible();
     let b_feasible = b.is_feasible();

src/pareto/front.rs

@@ -8,6 +8,25 @@ use crate::pareto::dominance::{Dominance, pareto_compare};
 ///
 /// O(N²·M) in v1 (spec §9.3). Input order is preserved among returned
 /// candidates.
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![
+///     Objective::minimize("f1"),
+///     Objective::minimize("f2"),
+/// ]);
+/// let pop = [
+///     Candidate::new(1u32, Evaluation::new(vec![1.0, 4.0])), // non-dominated
+///     Candidate::new(2u32, Evaluation::new(vec![3.0, 2.0])), // non-dominated
+///     Candidate::new(3u32, Evaluation::new(vec![5.0, 5.0])), // dominated
+/// ];
+/// let front = pareto_front(&pop, &s);
+/// let kept: Vec<u32> = front.iter().map(|c| c.decision).collect();
+/// assert_eq!(kept, vec![1, 2]);
+/// ```
 pub fn pareto_front<D: Clone>(
     population: &[Candidate<D>],
     objectives: &ObjectiveSpace,
@@ -34,6 +53,21 @@ pub fn pareto_front<D: Clone>(
 ///
 /// Returns `None` if there is not exactly one objective, if the population is
 /// empty, or if every candidate is infeasible (spec §9.4).
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![Objective::minimize("f")]);
+/// let pop = [
+///     Candidate::new(1u32, Evaluation::new(vec![3.0])),
+///     Candidate::new(2u32, Evaluation::new(vec![1.0])),
+///     Candidate::new(3u32, Evaluation::new(vec![2.0])),
+/// ];
+/// let best = best_candidate(&pop, &s).unwrap();
+/// assert_eq!(best.decision, 2);
+/// ```
 pub fn best_candidate<D: Clone>(
     population: &[Candidate<D>],
     objectives: &ObjectiveSpace,

src/pareto/reference_points.rs

@@ -10,6 +10,21 @@
 ///
 /// # Panics
 /// If `num_objectives == 0`.
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// // 3 objectives, 4 divisions → binomial(6, 2) = 15 points.
+/// let pts = das_dennis(3, 4);
+/// assert_eq!(pts.len(), 15);
+/// for w in &pts {
+///     assert_eq!(w.len(), 3);
+///     let sum: f64 = w.iter().sum();
+///     assert!((sum - 1.0).abs() < 1e-12);
+/// }
+/// ```
 pub fn das_dennis(num_objectives: usize, divisions: usize) -> Vec<Vec<f64>> {
     assert!(
         num_objectives > 0,

src/pareto/sort.rs

@@ -9,6 +9,26 @@ use crate::core::objective::ObjectiveSpace;
 /// non-dominated after removing `fronts[0]`, and so on. Each entry is an index
 /// into the input population. Equal-objective candidates land on the same
 /// front. O(N²·M) is acceptable for v1 (spec §9.5).
+///
+/// # Example
+///
+/// ```
+/// use heuropt::prelude::*;
+///
+/// let s = ObjectiveSpace::new(vec![
+///     Objective::minimize("f1"),
+///     Objective::minimize("f2"),
+/// ]);
+/// let pop = [
+///     Candidate::new((), Evaluation::new(vec![1.0, 5.0])), // front 0
+///     Candidate::new((), Evaluation::new(vec![2.0, 3.0])), // front 0
+///     Candidate::new((), Evaluation::new(vec![4.0, 1.0])), // front 0
+///     Candidate::new((), Evaluation::new(vec![3.0, 4.0])), // front 1
+///     Candidate::new((), Evaluation::new(vec![5.0, 6.0])), // front 2
+/// ];
+/// let fronts = non_dominated_sort(&pop, &s);
+/// assert_eq!(fronts.len(), 3);
+/// ```
 pub fn non_dominated_sort<D>(
     population: &[Candidate<D>],
     objectives: &ObjectiveSpace,