Add documentation for Algorithm, Condition and Roulette.

diff --git a/src/algorithm.h b/src/algorithm.h
index f38fff57acb3d11b055e160fc1663feae634a89e..fe79938302c95720cc724de4a8e31d8cef9f1f4a 100644 (file)
--- a/src/algorithm.h
+++ b/src/algorithm.h
@@ -31,6 +31,9 @@ namespace genetic {
 
         /**
          * Fitness function used in selection
+         *
+         * It is a reference, because Fitness is purely virtual class and we
+         * can't have instance of it. It must be one of derived classes.
          */
         Fitness<_Chromosome, FitnessValueType>& fitness;
 
@@ -49,6 +52,12 @@ namespace genetic {
          */
         Generation<_Chromosome> generation;
 
+        /**
+         * Method invoked in each iteration of algorithm.
+         *
+         * Applies selection, crossover and mutation on each of the chromosomes
+         * in generation.
+         */
         void do_search() {
             _Selection selection(this->generation, fitness);
             this->generation = selection.draw();
@@ -56,6 +65,15 @@ namespace genetic {
             this->generation = mutation.mutate(this->generation);
         }
     public:
+        /**
+         * Class constructor. Initializes class with values and breeds initial
+         * population using passed generator::Generation.
+         *
+         * @param _generator Generator used to generate initial population
+         * @param _fitness Fitness class used to check fitness of the chromosome
+         * @param crossoverChance probability of crossover (0 = 0%, 1 = 100%)
+         * @param mutationChance probability of fitness (0 = 0%, 1 = 100%)
+         */
         Algorithm(
             generator::Generation<_Chromosome>& _generator,
             Fitness<_Chromosome, FitnessValueType>& _fitness,
@@ -69,6 +87,16 @@ namespace genetic {
             this->generation = this->generator.breed();
         }
 
+        /**
+         * Starts Algorithm in search for result.
+         * For each generation but initial, condition is checked, if algorithm
+         * should stop.
+         *
+         * Displays separated by space: generation number, generation average
+         * fitness and best chromosome fitness.
+         *
+         * @param condition Condition used to check after breeding new generation
+         */
         void searchForResult(Condition<_Chromosome>& condition) {
             unsigned int i = 0;
             cout << "generation avg best\n";
@@ -83,6 +111,10 @@ namespace genetic {
             } while(condition.check(this->generation) && ++i);
         }
 
+        /**
+         * Displays entire generation.
+         * \attention Method is currently not in use.
+         */
         void showGeneration() {
             for (unsigned int i = 0; i < this->generation.get().size(); i++) {
                 cout << "# " << i << ") ";
@@ -93,6 +125,10 @@ namespace genetic {
             }
         }
 
+        /**
+         * Displays average fitness value of the entire generation.
+         * @todo make it more generic
+         */
         void showAvgFitness() {
             double avg = 0;
             for (unsigned int i = 0; i < this->generation.get().size(); i++) {
@@ -102,6 +138,11 @@ namespace genetic {
             cout << " " << avg / this->generation.get().size();
         }
 
+        /**
+         * Displays best fitness value of the entire generation.
+         * @todo make it more generic, currently has hardcoded WSTI Fitness
+         *      class, due its additional arguments
+         */
         void showBestFitness() {
             double best = -100000;
             for (unsigned int i = 0; i < this->generation.get().size(); i++) {

diff --git a/src/condition/condition.h b/src/condition/condition.h
index 7448052e54f9d67ca2801b43f146a2c34733e81e..be7c798a1a66163501088aa2c819c5baab4819a6 100644 (file)
--- a/src/condition/condition.h
+++ b/src/condition/condition.h
@@ -17,8 +17,15 @@ namespace genetic {
     class Condition {
     public:
     protected:
+        /**
+         * Variable indicating current generation
+         */
         unsigned int currentGeneration = 0;
     private:
+        /**
+         * Variable indicating max number of generations, after which program
+         * will be stopped
+         */
         const unsigned int maxNumberOfGenerations = 1000;
     public:
         Condition() { }

diff --git a/src/selection/roulette.h b/src/selection/roulette.h
index 88141986e214ab7760abcef7bd01895c36f534ff..7f2d2401cd9f58c00e8a2f149099183d429d4e3b 100644 (file)
--- a/src/selection/roulette.h
+++ b/src/selection/roulette.h
@@ -3,7 +3,6 @@
 
 #include <vector>
 #include <utility>      // std::pair
-#include <algorithm>    // std::sort
 #include <map>
 #include <cstdlib>
 #include <iostream>
@@ -15,12 +14,25 @@ using namespace std;
 
 namespace genetic {
 //     namespace selection {
+        /**
+         * Selection class Roulette.
+         * Applies Selection on given Generation using Roulette method.
+         */
         template < typename _Chromosome >
         class Roulette : public Selection<_Chromosome> {
         public:
             typedef Selection<_Chromosome> BaseType;
             typedef typename BaseType::FitnessValueType FitnessValueType;
         protected:
+            /**
+             * Method used for calculating fitness of each Chromosome in
+             * Generation.
+             *
+             * @param generation Generation for which fitness will be calculated
+             * @return vector containing fitness value of each Chromosome in
+             *      Generation. Values are set in the same order as they are in
+             *      the Generation.
+             */
             vector<FitnessValueType> calculateGenerationFitness(
                 Generation<_Chromosome> generation) {
                 vector<FitnessValueType> generationFitness;
@@ -31,12 +43,26 @@ namespace genetic {
 
                 return generationFitness;
             }
+
+            /**
+             * Normalizes calculated fitness values of the generation.
+             *
+             * @param generationFitness fitness values of the generation
+             * @param chromosomeSize number of Gene's in the Chromosome.
+             *
+             * @return multimap containing normalized Fitness as a key and its
+             *      Chromosome as the value
+             */
             multimap<FitnessValueType, _Chromosome> normalizeFitness(
                 vector<FitnessValueType> generationFitness,
                 unsigned int chromosomeSize) {
                 FitnessValueType min;
                 FitnessValueType max;
                 FitnessValueType offset;
+
+                /* we use multimap because it stores multiple values with the
+                 * same key
+                 */
                 multimap<FitnessValueType, _Chromosome> normalizedFitness;
 
                 min = max = generationFitness[0];
@@ -63,6 +89,10 @@ namespace genetic {
 
             /**
              * Spins the Roulette
+             *
+             * @param normalizedFitness multimap containing normalized Fitness
+             *      as a key and its Chromosome as the value
+             * @return new Generation of Chromosome's that passed the selection
              */
             Generation<_Chromosome> spinRoulette(
                 multimap<FitnessValueType, _Chromosome> normalizedFitness) {
@@ -124,7 +154,7 @@ namespace genetic {
             }
 
             /**
-             * Draws random 
+             * Draws new Generation using Roulette method
              */
             Generation<_Chromosome> do_draw() {
                 multimap<FitnessValueType, _Chromosome> normalizedFitness;
@@ -138,6 +168,13 @@ namespace genetic {
             }
 
         public:
+            /**
+             * Class constructor. Initializes class with values.
+             *
+             * @param _generation Generation that will be checked against this
+             *      Selection
+             * @param _fitness Fitness method to calculate fitness of Chromosomes
+             */
             Roulette(Generation<_Chromosome> _generation, genetic::Fitness<_Chromosome>& _fitness) :
                 Selection<_Chromosome>(_generation, _fitness) {
                 this->generation = _generation;