1 files changed, 60 insertions, 7 deletions

diff --git a/src/jcgp/backend/population/Population.java b/src/jcgp/backend/population/Population.java
index d99c64e..5d549e9 100644
--- a/src/jcgp/backend/population/Population.java
+++ b/src/jcgp/backend/population/Population.java
@@ -5,6 +5,35 @@ import java.util.Collections;
 
 import jcgp.backend.resources.Resources;
 
+/**
+ * This class primarily holds a collection of chromosomes. In addition, 
+ * it provides a few utility methods for manipulating and copying 
+ * chromosomes, useful for evolutionary strategies.
+ * <br><br>
+ * {@code copyChromosome()} is used to create copies of chromosomes, 
+ * though it is also possible to create a new instance of population
+ * directly from a seed chromosome using the right constructor. 
+ * <br><br>
+ * For convenience, a random chromosome can be retrieved using
+ * {@code getRandomChromosome()}, which is guaranteed to use the
+ * experiment's specified seed. If an entirely random population
+ * is needed, {@code reinitialise()} should be used to randomise
+ * all chromosomes without creating a new instance of {@code Population}.
+ * <br><br>
+ * By convention the population's chromosomes should always be sorted in
+ * order of fitness, from worst to best. This cannot be done automatically
+ * since a higher fitness value does not necessarily mean better fitness;
+ * some problem types might instead interpret fitness 0 as a perfect solution.
+ * Sorting the population is done easily using {@code sortAscending()} and
+ * {@code sortDescending()}, and should be done by the problem type as appropriate.
+ * It is <b>critical</b> to sort the population after it is evaluated as 
+ * evolutionary strategies will obey the convention and assume the population
+ * is sorted in order of fitness.
+ * 
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
 public class Population {
 	
 	private final Chromosome[] chromosomes;
@@ -14,7 +43,7 @@ public class Population {
 	 * Initialise a random population according to the parameters specified
 	 * in the resources.
 	 * 
-	 * @param resources the CGP resources
+	 * @param resources the experiment's resources.
 	 */
 	public Population(Resources resources) {
 		this.resources = resources;
@@ -28,8 +57,8 @@ public class Population {
 	/**
 	 * Initialise a population of copies of the given chromosome.
 	 * 
-	 * @param parent
-	 * @param resources
+	 * @param parent the chromosome to use as a model.
+	 * @param resources a reference to the experiment's resources.
 	 */
 	public Population(Chromosome parent, Resources resources) {
 		this.resources = resources;
@@ -43,8 +72,8 @@ public class Population {
 	/**
 	 * Returns the indexed chromosome.
 	 * 
-	 * @param index
-	 * @return
+	 * @param index the chromosome to return.
+	 * @return the indexed chromosome.
 	 */
 	public Chromosome getChromosome(int index) {
 		return chromosomes[index];
@@ -65,8 +94,8 @@ public class Population {
 	 * 
 	 * This method does nothing if source == target.
 	 * 
-	 * @param source 
-	 * @param target
+	 * @param source the chromosome to copy from.
+	 * @param target the chromosome to copy to.
 	 */
 	public void copyChromosome(int source, int target) {
 		if (source != target) {
@@ -74,16 +103,40 @@ public class Population {
 		}
 	}
 	
+	/**
+	 * Loop through all chromosomes and randomise all connections
+	 * and functions.
+	 */
 	public void reinitialise() {
 		for (int c = 0; c < chromosomes.length; c++) {
 			chromosomes[c].reinitialiseConnections();
 		}
 	}
 	
+	/**
+	 * The fittest chromosome, by convention, is the last one
+	 * in the array. Problem evaluation methods are expected to
+	 * sort the population into ascending order of fitness, such
+	 * that the best chromosome is in the last position (size - 1).
+	 * This method assumes that the population is sorted as such
+	 * and returns the last chromosome in the array.
+	 * 
+	 * @return the fittest chromosome in the population.
+	 */
 	public Chromosome getFittest() {
 		return chromosomes[chromosomes.length - 1];
 	}
 	
+	/**
+	 * The fittest chromosome, by convention, is the last one
+	 * in the array. Problem evaluation methods are expected to
+	 * sort the population into ascending order of fitness, such
+	 * that the best chromosome is in the last position (size - 1).
+	 * This method assumes that the population is sorted as such
+	 * and returns the last index in the array.
+	 * 
+	 * @return the index of the fittest chromosome.
+	 */
 	public int getFittestIndex() {
 		return chromosomes.length - 1;
 	}