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/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,