docs: ga module

src/ga.rs

@@ -19,26 +19,40 @@ use self::{
 
 type FitnessFn<S> = fn(&S) -> f64;
 
+/// Parameters for the genetic algorithm
 pub struct GAParams {
+  /// **Unused for now**
   pub selection_rate: f64,
+
+  /// Describes chance of a individual gene to be mutated
+  ///
+  /// This parameter is passed down to a mutation operator
+  ///
+  /// Must be in range [0, 1]
   pub mutation_rate: f64,
+
+  /// Number of individuals in population
+  ///
+  /// In current implementation of the algorithm the size of population
+  /// is constant throughout generations
   pub population_size: usize,
+
+  /// Maximum number of generations (search termination)
+  ///
+  /// This works interchangeably with `max_duration` - first limit hit terminates the algorithm
   pub generation_limit: usize,
+
+  /// Maximum duration of computations (search termination)
+  ///
+  /// This works interchangeably with `generation_limit` - first limit hit terminates the algorithm
   pub max_duration: std::time::Duration,
 }
 
-// impl Default for GAParams {
-//   fn default() -> Self {
-//     Self {
-//       selection_rate: 0.5f64,
-//       mutation_rate: 0.05,
-//       population_size: 100,
-//       generation_limit: 200,
-//       max_duration: None,
-//     }
-//   }
-// }
-
+/// Configuration for the genetic algorithm
+///
+/// It describes initial parameters & operators for the algorithm
+///
+/// Configuration of genetic algorithm is done via builder interface though
 pub struct GAConfig<T, M, C, S, P, Pr>
 where
   T: Chromosome,
@@ -48,20 +62,42 @@ where
   P: PopulationGenerator<T>,
   Pr: Probe<T>,
 {
+  /// Set of parameters for the genetic algorithm. See [GAParams] for details.
   pub params: GAParams,
-  // pub ops: GAOps<S>,
+
+  /// Fitness function. It must operate on a solution representation - chromosome. Should return `f64`.
+  /// Please note that some of the genetic operators require fitness function to be positive.
   pub fitness_fn: FitnessFn<T>,
+
+  /// Mutation operator. See [MutationOperator](crate::ga::operators::mutation::MutationOperator) for details.
   pub mutation_operator: M,
+
+  /// Crossover operator. See [CrossoverOperator](create::ga::operators::crossover::CrossoverOperator) for details.
   pub crossover_operator: C,
+
+  /// Selection operator. See [SelectionOperator](crate::ga::operators::selection::SelectionOperator) for details.
   pub selection_operator: S,
+
+  /// Population generator. See [PopulationGenerator](crate::ga::population::PopulationGenerator) for details.
   pub population_factory: P,
+
+  /// Probe. See [Probe](crate::ga::probe::Probe) for details.
   pub probe: Pr,
 }
 
+/// Structure representing advancement of the computations
+///
+/// This struct is passed to probes, so they can make better decisions whether to log or not.
 #[derive(Default)]
 pub struct GAMetadata {
+  /// Computations start time. This field is filled just after GA's `run` method starts executing.
+  /// You can expect it to be always defined (the value is `Some`).
   pub start_time: Option<std::time::Instant>,
+
+  /// Duration of the computations. Measured in the very beginning of main loop (each iteration).
   pub duration: Option<std::time::Duration>,
+
+  /// Current generation number. Before entering the main loop it is equal to `0`.
   pub generation: usize,
 }
 
@@ -79,6 +115,9 @@ impl GAMetadata {
   }
 }
 
+/// Custom implementation of genetic algorithm.
+///
+/// TODO: Extensive description
 pub struct GeneticAlgorithm<T, M, C, S, P, Pr>
 where
   T: Chromosome,