Add some documentation.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1549984 13f79535-47bb-0310-9956-ffa450edef68

src/userguide/java/org/apache/commons/math3/userguide/genetics/ImageEvolutionExample.java

@@ -52,8 +52,8 @@ import org.apache.commons.math3.userguide.ExampleUtils.ExampleFrame;
 @SuppressWarnings("serial")
 public class ImageEvolutionExample {
 
-    public static final int   POPULATION_SIZE  = 50;
-    public static final int   TOURNAMENT_ARITY = 2;
+    public static final int   POPULATION_SIZE  = 40;
+    public static final int   TOURNAMENT_ARITY = 5;
     public static final float MUTATION_RATE    = 0.02f;
     public static final float MUTATION_CHANGE  = 0.1f;
 

src/userguide/java/org/apache/commons/math3/userguide/genetics/Polygon.java

@@ -8,6 +8,9 @@ import org.apache.commons.math3.genetics.GeneticAlgorithm;
 import org.apache.commons.math3.random.RandomGenerator;
 import org.apache.commons.math3.util.FastMath;
 
+/**
+ * Represents a fixed size polgon with its fill color.
+ */
 public class Polygon {
 
     // the polygon in packed representation:
@@ -16,9 +19,18 @@ public class Polygon {
     //    1  | green component
     //    2  | blue component
     //    3  | alpha channel
-    //   
+    //    4  | first x coordinate
+    //    5  | first y coordinate
+    //    6  | second x coordinate
+    //  ...
+    //    N  | last y coordinate
+    // ---------------------------
+    /// size = 4 + 2*polygonlength
     private float[] data;
 
+    /**
+     * Creates a new random Polygon of the given length.
+     */
     public static Polygon randomPolygon(int length) {
         final int polygonSize = 4 + 2 * length;
 
@@ -42,6 +54,17 @@ public class Polygon {
         return p;
     }
 
+    /**
+     * Return a new Polygon, mutated with the given rate and amount.
+     * <p>
+     * Each component of the Polygon may be mutated according to the specified mutation rate.
+     * In case a component is going to be mutated, its value will be randomly modified in the
+     * uniform range of [-mutationAmount, +mutationAmount].
+     * 
+     * @param mutationRate the mutation rate
+     * @param mutationAmount the mutation amount
+     * @return a new Polygon
+     */
     public Polygon mutate(float mutationRate, float mutationAmount) {
         Polygon mutated = new Polygon();
         int size = data.length;
@@ -62,6 +85,9 @@ public class Polygon {
         return mutated;
     }    
 
+    /**
+     * Draw the Polygon to the buffer of the given size.
+     */
     public void draw(Graphics2D g, int width, int height) {
         g.setColor(new Color(data[0], data[1], data[2], data[3]));
 

src/userguide/java/org/apache/commons/math3/userguide/genetics/PolygonChromosome.java

@@ -12,9 +12,14 @@ import org.apache.commons.math3.genetics.AbstractListChromosome;
 import org.apache.commons.math3.genetics.Chromosome;
 import org.apache.commons.math3.genetics.InvalidRepresentationException;
 
+/**
+ * A simple chromosome representing a list of polygons.
+ */
 public class PolygonChromosome extends AbstractListChromosome<Polygon> {
 
+    /** The reference image for fitness testing. */
     private static BufferedImage refImage;
+    /** The image buffer used to draw the current chromosome during fitness testing. */
     private static BufferedImage testImage;
 
     public static void setRefImage(BufferedImage ref) {
@@ -39,10 +44,21 @@ public class PolygonChromosome extends AbstractListChromosome<Polygon> {
         return new PolygonChromosome(chromosomeRepresentation);
     }
 
+    /**
+     * Return the internal representation, which is needed for our custom mutation policy.
+     *
+     * @return the list of polygons
+     */
     public List<Polygon> getPolygonRepresentation() {
         return getRepresentation();
     }
 
+    /**
+     * Calculate the fitness function for this chromosome.
+     * <p>
+     * For this purpose, we first draw the polygons on the test buffer, and
+     * then compare the resulting image pixel by pixel with the reference image.
+     */
     public double fitness() {
 
         Graphics2D g2 = testImage.createGraphics();
@@ -61,7 +77,7 @@ public class PolygonChromosome extends AbstractListChromosome<Polygon> {
         int idx = 0;
 
         do {
-            if (idx++ % 4 != 0) {
+            if (idx++ % 4 != 0) { // ignore the alpha channel for fitness
                 int dp = testPixels[p] - refPixels[p];
                 if (dp < 0) {
                     diff -= dp;