Did more commenting, implemented reflection and statistics

1 files changed, 129 insertions, 32 deletions

diff --git a/src/jcgp/backend/resources/Resources.java b/src/jcgp/backend/resources/Resources.java
index e1438f1..1f79627 100644
--- a/src/jcgp/backend/resources/Resources.java
+++ b/src/jcgp/backend/resources/Resources.java
@@ -4,13 +4,24 @@ import java.util.Random;
 
 import jcgp.backend.function.Function;
 import jcgp.backend.function.FunctionSet;
-import jcgp.backend.resources.parameters.IntegerParameter;
+import jcgp.backend.parameters.IntegerParameter;
 
 /**
  * 
  * The resources class encapsulates all of the resources based on which the program operates.
  * Each instance of JCGP contains a single instance of Resources, which gets passed to the selected
  * modules as the program executes.
+ * <br><br>
+ * The experiment's {@code Resources} object is passed to modules as the program operates, and
+ * the actual parameter values can be obtained using getter methods. Note that, for code brevity,
+ * this class's getters do not start with the word "get". For instance, to get the number of rows, 
+ * one would use {@code rows()} instead of {@code getRows()}.
+ * <br><br>
+ * In addition to parameters, this class also offers utility methods. Any necessary random numbers
+ * should be obtained using {@code getRandomInt()} and {@code getRandomDouble()}. Functions from the
+ * selected function set can be obtained through this class as well. Finally, printing to the console
+ * should be done via the resources using the report and print methods, so that these prints also
+ * get sent to the GUI console (if one is present).
  * 
  * @author Eduardo Pedroni
  *
@@ -22,102 +33,102 @@ public class Resources {
 
 	protected Random numberGenerator = new Random();
 	protected FunctionSet functionSet;
-	// GUI console
+	
 	protected Console console;
 	
 	/**
-	 * @return the rows
+	 * @return the number of rows.
 	 */
 	public int rows() {
 		return rows.get();
 	}
 
 	/**
-	 * @return the columns
+	 * @return the number of columns.
 	 */
 	public int columns() {
 		return columns.get();
 	}
 
 	/**
-	 * @return the inputs
+	 * @return the number of inputs.
 	 */
 	public int inputs() {
 		return inputs.get();
 	}
 
 	/**
-	 * @return the outputs
+	 * @return the number of outputs.
 	 */
 	public int outputs() {
 		return outputs.get();
 	}
 
 	/**
-	 * @return the populationSize
+	 * @return the population size.
 	 */
 	public int populationSize() {
 		return populationSize.get();
 	}
 
 	/**
-	 * @return the levelsBack
+	 * @return the levels back value.
 	 */
 	public int levelsBack() {
 		return levelsBack.get();
 	}
 
 	/**
-	 * @return the nodes
+	 * @return the total number of nodes.
 	 */
 	public int nodes() {
 		return columns.get() * rows.get();
 	}
 
 	/**
-	 * @return the currentGeneration
+	 * @return the current generation.
 	 */
 	public int currentGeneration() {
 		return currentGeneration.get();
 	}
 
 	/**
-	 * @return the generations
+	 * @return the total number of generations.
 	 */
 	public int generations() {
 		return generations.get();
 	}
 
 	/**
-	 * @return the currentRun
+	 * @return the current run.
 	 */
 	public int currentRun() {
 		return currentRun.get();
 	}
 
 	/**
-	 * @return the runs
+	 * @return the total number of runs.
 	 */
 	public int runs() {
 		return runs.get();
 	}
 
 	/**
-	 * @return the arity
+	 * @return the maximum arity out of the function set.
 	 */
 	public int arity() {
 		return arity.get();
 	}
 
 	/**
-	 * @return the seed
+	 * @return the random seed being used.
 	 */
 	public int seed() {
 		return seed.get();
 	}
 
 	/**
-	 * @return the report interval
+	 * @return the report interval.
 	 */
 	public int reportInterval() {
 		return reportInterval.get();
@@ -126,14 +137,37 @@ public class Resources {
 	/*
 	 * Utility functions
 	 */
+	/**
+	 * Gets the next random integer using the experiment's random
+	 * number generator. The integer returned will be between 0 (inclusive)
+	 * and limit (exclusive).
+	 * 
+	 * @param limit the limit value.
+	 * @return a random integer between 0 and limit.
+	 */
 	public int getRandomInt(int limit) {
 		return numberGenerator.nextInt(limit);
 	}
 	
+	/**
+	 * Gets the next random double using the experiment's random
+	 * number generator. The double returned will be between 0 (inclusive)
+	 * and limit (exclusive).
+	 * 
+	 * @param limit the limit value.
+	 * @return a random double between 0 and limit.
+	 */
 	public double getRandomDouble(int limit) {
 		return numberGenerator.nextDouble() * limit;
 	}
 	
+	/**
+	 * Gets the next random integer using the experiment's random
+	 * number generator. The integer returned will be between 0 (inclusive)
+	 * and 1 (exclusive).
+	 * 
+	 * @return a random integer between 0 and 1.
+	 */
 	public double getRandomDouble() {
 		return numberGenerator.nextDouble();
 	}
@@ -141,53 +175,94 @@ public class Resources {
 	/*
 	 * FunctionSet functions
 	 */
+	/**
+	 * Gets a random allowed function from the problem function set.
+	 * This function uses {@code getRandomInt()} to choose the random
+	 * function.
+	 * 
+	 * @return a random allowed function.
+	 */
 	public Function getRandomFunction() {
 		Function f = functionSet.getAllowedFunction(numberGenerator.nextInt(functionSet.getAllowedFunctionCount()));
 		return f;
 	}
 
+	/**
+	 * Gets the indexed function out of the
+	 * complete set of functions.
+	 * 
+	 * @param index the function to return.
+	 * @return the indexed function.
+	 */
 	public Function getFunction(int index) {
-		return functionSet.getAllowedFunction(index);
+		return functionSet.getFunction(index);
 	}
 	
 	/**
-	 * @return the functionSet
+	 * @return the problem's function set.
 	 */
 	public FunctionSet getFunctionSet() {
 		return functionSet;
 	}
 	
+	/**
+	 * Returns the index of a specified function. If the function is not found,
+	 * -1 is returned.
+	 * 
+	 * @param function the function with unknown index.
+	 * @return the index of the function, or -1 if it was not found.
+	 */
 	public int getFunctionIndex(Function function) {
 		for (int i = 0; i < functionSet.getTotalFunctionCount(); i++) {
 			if (function == functionSet.getFunction(i)) {
 				return i;
 			}
 		}
-		// not found, default to 0
-		return 0;
+		// not found, default to -1
+		return -1;
 	}
 	
 	/*
 	 * Console functionality
 	 * These are affected by parameter report interval
 	 */
-	public void reportln(String s) {
+	/**
+	 * Prints a message to the consoles taking into account the
+	 * report interval parameter. If no reports are allowed in
+	 * the current generation, this does nothing.
+	 * <br>
+	 * This method automatically appends a line break to the message
+	 * being printed.
+	 * 
+	 * @param message the message to print.
+	 */
+	public void reportln(String message) {
 		if (reportInterval.get() > 0) {
 			if (currentGeneration.get() % reportInterval.get() == 0) {
-				System.out.println(s);
+				System.out.println(message);
 				if (console != null) {
-					console.println(s);
+					console.println(message);
 				}
 			}
 		}
 	}
 	
-	public void report(String s) {
+	/**
+	 * Prints a message to the consoles taking into account the
+	 * report interval parameter. If no reports are allowed in
+	 * the current generation, this does nothing.
+	 * <br>
+	 * This method does not append a line break to the message
+	 * being printed.
+	 * 
+	 * @param message the message to print.
+	 */
+	public void report(String message) {
 		if (reportInterval.get() > 0) {
 			if (currentGeneration.get() % reportInterval.get() == 0) {
-				System.out.print(s);
+				System.out.print(message);
 				if (console != null) {
-					console.print(s);
+					console.print(message);
 				}
 			}
 		}
@@ -197,17 +272,39 @@ public class Resources {
 	 * Console functionality
 	 * These are not affected by parameter report interval
 	 */
-	public void println(String s) {
-		System.out.println(s);
+	/**
+	 * Prints a message to the consoles ignoring
+	 * report interval. In other words, messages printed 
+	 * using this method will always appear (though the
+	 * GUI console will still need to be flushed).
+	 * <br>
+	 * This method automatically appends a line break to the message
+	 * being printed.
+	 * 
+	 * @param message the message to print.
+	 */
+	public void println(String message) {
+		System.out.println(message);
 		if (console != null) {
-			console.println(s);
+			console.println(message);
 		}
 	}
 	
-	public void print(String s) {
-		System.out.print(s);
+	/**
+	 * Prints a message to the consoles ignoring
+	 * report interval. In other words, messages printed 
+	 * using this method will always appear (though the
+	 * GUI console will still need to be flushed).
+	 * <br>
+	 * This method does not append a line break to the message
+	 * being printed.
+	 * 
+	 * @param message the message to print.
+	 */
+	public void print(String message) {
+		System.out.print(message);
 		if (console != null) {
-			console.print(s);
+			console.print(message);
 		}
 	}
 }
\ No newline at end of file