Some more review of docs

Author: basvanwesting

AGENTS.md

@@ -108,7 +108,7 @@ for diversity) or `CrossoverRejuvenate` (like Clone but optimized for less memor
 | `MutateMultiGene` | When faster exploration is needed. Multiple genes. |
 | `MutateMultiGeneRange` | When you want random variation in mutation count. |
 | `MutateSingleGeneDynamic` | Auto-adjusts probability based on population cardinality. |
-| `MutateMultiGeneDynamic` | Auto-adjusts count+probability based on cardinality. |
+| `MutateMultiGeneDynamic` | Auto-adjusts probability based on cardinality. Multiple genes. |
 
 ## Constructor Parameter Reference
 

src/mutate/multi_gene_dynamic.rs

@@ -88,8 +88,8 @@ impl<G: EvolveGenotype> Mutate for MultiGeneDynamic<G> {
 }
 
 impl<G: EvolveGenotype> MultiGeneDynamic<G> {
-    /// Create a new MultiGeneDynamic mutation strategy. Auto-adjusts mutation count and
-    /// probability to maintain target population diversity (cardinality).
+    /// Create a new MultiGeneDynamic mutation strategy. Auto-adjusts mutation probability
+    /// to maintain target population diversity (cardinality).
     /// * `number_of_mutations` - max genes mutated per chromosome (sampled uniformly from 1..=n)
     /// * `mutation_probability_step` - step size for probability adjustment each generation
     /// * `target_cardinality` - target number of unique chromosomes in the population

src/select/elite.rs

@@ -10,9 +10,10 @@ use std::cmp::Reverse;
 use std::marker::PhantomData;
 use std::time::Instant;
 
-/// Simply sort the chromosomes with fittest first. Then take the target_population_size (or full
-/// population when in shortage) of the populations best and drop excess chromosomes. This approach
-/// has the risk of locking in to a local optimum.
+/// Sort chromosomes by fitness in a multi-pass process: extract elite, partition into parents and
+/// offspring, select from each group separately based on replacement_rate, then do a final
+/// selection pass on the combined pool to reach target_population_size. Deterministic, but has the
+/// risk of locking in to a local optimum.
 #[derive(Clone, Debug)]
 pub struct Elite<G: EvolveGenotype> {
     _phantom: PhantomData<G>,

src/select/tournament.rs

@@ -9,10 +9,11 @@ use rand::prelude::*;
 use std::marker::PhantomData;
 use std::time::Instant;
 
-/// Run tournaments with randomly chosen chromosomes and pick a single winner. Do this untill the
-/// target_population_size (or full population when in shortage) of the population is reached and
-/// drop excess chromosomes. This approach kind of sorts the fitness first, but not very strictly.
-/// This preserves a level of diversity, which avoids local optimum lock-in.
+/// Run tournaments with randomly chosen chromosomes and pick a single winner. Uses the same
+/// multi-pass process as Elite (extract elite, partition parents/offspring, select separately,
+/// final pass), but uses tournament selection instead of sorting. This approach kind of sorts the
+/// fitness first, but not very strictly. This preserves a level of diversity, which avoids local
+/// optimum lock-in.
 #[derive(Clone, Debug)]
 pub struct Tournament<G: EvolveGenotype> {
     _phantom: PhantomData<G>,

src/strategy/evolve.rs

@@ -52,9 +52,12 @@ pub enum EvolveVariant {
 /// * max_stale_generations: when the ultimate goal in terms of fitness score is unknown and one depends on some convergion
 ///   threshold, or one wants a duration limitation next to the target_fitness_score
 /// * max_generations: when the ultimate goal in terms of fitness score is unknown and there is a effort constraint
-/// * With a scaled [crate::genotype::MutationType]:
-///   * Scale down after max_generations or max_stale_generations is reached and reset scale_generations and stale_generations to zero
-///   * Only trigger max_generations or max_stale_generations ending condition when already reached the smallest scale
+/// * With a scaled [crate::genotype::MutationType] (e.g. RangeScaled, StepScaled):
+///   * When max_generations or max_stale_generations is reached, the current scale ends.
+///     If more scales remain, advance to the next scale and reset scale_generation and
+///     stale_generations to zero, then continue. If already at the smallest scale, the
+///     ending condition terminates the run.
+///   * Without scaled mutation types, ending conditions simply terminate the run.
 ///
 /// General Hyper-parameters:
 /// * `replacement_rate` (selection): the target fraction of the population which exists of