Did some more comments, almost there...

2 files changed, 161 insertions, 23 deletions

diff --git a/src/jcgp/gui/GUI.java b/src/jcgp/gui/GUI.java
index 2f09dea..8735ccd 100644
--- a/src/jcgp/gui/GUI.java
+++ b/src/jcgp/gui/GUI.java
@@ -352,9 +352,14 @@ public class GUI extends Application {
 	}
 
 	/**
-	 * 
+	 * Run/pause method.
+	 * Run the experiment if it is paused, or pause it if it is running.
+	 * <br>
+	 * This method is the callback used by the run/pause button. It
+	 * controls the jcgp service.
 	 */
 	public void runPause() {
+		// do nothing if experiment is finished or parameters aren't valid
 		if (!jcgp.isFinished() && settingsPane.areParametersValid()) {
 			if (!running) {
 				runningMode(true);
@@ -366,7 +371,15 @@ public class GUI extends Application {
 		}
 	}
 	
+	/**
+	 * Perform a single generation using {@code nextGeneration()}. 
+	 * <br>
+	 * On top of that, this method performs all of the housekeeping 
+	 * that is normally done before and after running, such as 
+	 * refreshing the chromosome panes.
+	 */
 	public void step() {
+		// do nothing if experiment is finished, running or parameters aren't valid
 		if (!running && !jcgp.isFinished() && settingsPane.areParametersValid()) {
 			if (settingsPane.isResetRequired()) {
 				reset();
@@ -382,6 +395,11 @@ public class GUI extends Application {
 		}
 	}
 	
+	/**
+	 * Reset button callback. If the parameters are valid, 
+	 * this resets the entire experiment by calling {@code reset()}
+	 * on jcgp.
+	 */
 	public void reset() {
 		if (!running && settingsPane.areParametersValid()) {
 			setEvaluating(false);
@@ -391,6 +409,10 @@ public class GUI extends Application {
 		}
 	}
 	
+	/**
+	 * Does a complete GUI refresh. 
+	 * This is potentially lengthy, so use with care.
+	 */
 	public void reDraw() {
 		populationPane.remakeTabs();
 		settingsPane.revalidateParameters();
@@ -398,6 +420,17 @@ public class GUI extends Application {
 		console.flush();
 	}
 	
+	/**
+	 * Toggles the entire GUI between run and pause
+	 * mode. 
+	 * <br><br>
+	 * A lot of the GUI must be enabled or disabled
+	 * depending on what the experiment is doing. This
+	 * method provides a one-line way to make
+	 * all required adjustments.
+	 * 
+	 * @param value true if experiment is running, false otherwise.
+	 */
 	private void runningMode(boolean value) {		
 		if (value) {
 			populationPane.unlockOutputs();
@@ -415,42 +448,86 @@ public class GUI extends Application {
 		running = value;
 	}
 	
+	/**
+	 * Refresh the function selector, used when functions are enabled or disabled.
+	 */
 	public void updateFunctionSelector() {
 		functionSelector.remakeFunctions(jcgp.getResources().getFunctionSet());
 	}
 	
+	/**
+	 * @return true if jcgp is evolving.
+	 */
 	public boolean isWorking() {
 		return running;
 	}
 
+	/**
+	 * Relocate the function selector to the right position
+	 * relative to the specified node and set it visible.
+	 * 
+	 * @param event the mouse event containing cursor coordinates.
+	 * @param node the node whose function should be changed.
+	 */
 	public void bringFunctionSelector(MouseEvent event, GUINode node) {
 		functionSelector.relocateAndShow(event, node);
 	}
 
+	/**
+	 * @return a reference to the {@code JCGP} experiment.
+	 */
 	public JCGP getExperiment() {
 		return jcgp;
 	}
 	
+	/**
+	 * Starts the evaluation process with the given test case.
+	 * It does so by calling {@code evaluateTestCase()} on
+	 * the population pane.
+	 * 
+	 * @param testCase the test case to evaluate.
+	 */
 	public void evaluateTestCase(TestCase<Object> testCase) {
 		populationPane.evaluateTestCase(testCase);
 	}
 
+	/**
+	 * Hide all evaluated values. This should be called when
+	 * evaluations are no longer being performed.
+	 */
 	public void hideGeneValues() {
 		populationPane.hideValues();
 	}
 
+	/**
+	 * Set the system into evaluation mode. 
+	 * When in evaluation mode, the population pane
+	 * refreshes the node values whenever connection
+	 * changes happen.
+	 * 
+	 * @param value true if evaluations are happening, false otherwise.
+	 */
 	public void setEvaluating(boolean value) {
 		populationPane.setEvaluating(value);
 	}
 
+	/**
+	 * @return a reference to the GUI stage.
+	 */
 	public Stage getStage() {
 		return stage;
 	}
 	
+	/**
+	 * Writes all buffered content out to the GUI console.
+	 */
 	public void flushConsole() {
 		console.flush();
 	}
 
+	/**
+	 * @return the index of the chromosome currently being looked at.
+	 */
 	public int getChromosomeIndex() {
 		return populationPane.getSelectionModel().getSelectedIndex();
 	}
diff --git a/src/jcgp/gui/settings/SettingsPane.java b/src/jcgp/gui/settings/SettingsPane.java
index d9d8825..c0939e9 100644
--- a/src/jcgp/gui/settings/SettingsPane.java
+++ b/src/jcgp/gui/settings/SettingsPane.java
@@ -29,34 +29,62 @@ import jcgp.gui.GUI;
 import jcgp.gui.settings.parameters.GUIParameter;
 import jcgp.gui.settings.testcase.TestCaseTable;
 
+/**
+ * This is a fairly hefty class which encapsulates the entire right-hand
+ * control pane. It contains base parameters, module selectors and their
+ * associated parameters, flow controls and file loading/saving buttons.
+ * <br><br>
+ * A single instance of this class is used in {@code GUI}.
+ * 
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
 public class SettingsPane extends AnchorPane {
 	
+	/*
+	 * The primary containers, these make up each section of the settings pane.
+	 */
 	private VBox mainContainer;
 	private VBox baseParameterPane, eaPane, mutatorPane, problemPane;
 	private VBox nodeFunctions;
 	
+	// all buttons
 	private Button runPause = new Button("Run"), step = new Button("Step"), reset = new Button("Reset");
 	private Button loadParameters = new Button("Load parameters"), loadChromosome = new Button("Load chromosome"), saveChromosome = new Button("Save chromosome");
 	
+	// this is a list of parameters used for parameter validity checks
 	private ArrayList<GUIParameter<?>> parameters = new ArrayList<GUIParameter<?>>();
 	
+	// the test case table stage
 	private TestCaseTable testCaseTable;
 	
+	// a reference to the parent GUI
 	private GUI gui;
 	
 	private int currentArity;
 		
+	/**
+	 * Create a new instance of {@code SettingsPane} associated
+	 * with the specified {@code GUI} object.
+	 * 
+	 * @param gui a reference to this object's parent.
+	 */
 	public SettingsPane(GUI gui) {
 		super();
 		this.gui = gui;
+		
+		// acquire a reference to jcgp, for convenience
 		final JCGP jcgp = gui.getExperiment();
 		
+		// make the overarching container
 		mainContainer = new VBox(8);
 		mainContainer.setPadding(new Insets(5, GUI.RESIZE_MARGIN, 0, 2));
 		
 		setMinWidth(GUI.SETTINGS_MIN_WIDTH);
 		setPrefWidth(GUI.SETTINGS_MIN_WIDTH);
 		
+		// initialise all sub-divisions
 		initialiseBaseParameters(jcgp);
 		
 		initialiseEAParameters(jcgp);
@@ -67,19 +95,27 @@ public class SettingsPane extends AnchorPane {
 		
 		createControls(gui);
 		
+		// prepare the scroll pane
 		ScrollPane scroll = new ScrollPane();
 		scroll.setFitToWidth(true);
 		scroll.setContent(mainContainer);
 		scroll.setStyle("-fx-background-color: #FFFFFF");
 		
+		// anchor the scroll pane to itself, bearing in mind the resize margin
 		AnchorPane.setTopAnchor(scroll, 0.0);
 		AnchorPane.setBottomAnchor(scroll, 0.0);
 		AnchorPane.setRightAnchor(scroll, 0.0);
 		AnchorPane.setLeftAnchor(scroll, GUI.RESIZE_MARGIN);
 		
+		// add the scroll pane, all done!
 		getChildren().add(scroll);
 	}
 
+	/**
+	 * Creates the base parameters pane
+	 * 
+	 * @param jcgp
+	 */
 	private void initialiseBaseParameters(JCGP jcgp) {
 		baseParameterPane = new VBox(2);
 		
@@ -367,53 +403,73 @@ public class SettingsPane extends AnchorPane {
 	}
 	
 	/**
-	 * @param cgp
-	 * @param vb
+	 * Builds {@code GUIParameter}s and adds them to the provided {@code VBox}. 
+	 * The parameters built are taken from the specified list.
+	 *
+	 * @param newParameters the list of parameters to add.
+	 * @param container the container to add the parameters to.
 	 */
-	private void refreshParameters(ArrayList<Parameter<?>> newParameters, VBox vb) {
-		parameters.removeAll(vb.getChildren());
-		vb.getChildren().clear();
+	private void refreshParameters(ArrayList<Parameter<?>> newParameters, VBox container) {
+		// remove what is currently in the container from the parameter list
+		parameters.removeAll(container.getChildren());
+		// remove everything in the container
+		container.getChildren().clear();
+		// if there are parameters to add, add them all
 		if (newParameters != null) {
 			for (int i = 0; i < newParameters.size(); i++) {
-				GUIParameter<?> gp = GUIParameter.create(newParameters.get(i), this);
-				parameters.add(gp);
-				vb.getChildren().add(gp);
+				// factory method returns the right subtype of GUIParameter
+				GUIParameter<?> guiParameter = GUIParameter.create(newParameters.get(i), this);
+				// make sure to add it to the parameter list as well
+				parameters.add(guiParameter);
+				container.getChildren().add(guiParameter);
 			}
 		}
+		// do a quick refresh just in case something is invalid
 		revalidateParameters();
 	}
 	
 	/**
 	 * This method handles a problem type change by updating the list of allowed
 	 * node functions.
+	 * <br><br>
+	 * It does so by creating new checkboxes for each function in the function set.
 	 */
 	private void refreshFunctions() {
+		// remove all current functions
 		nodeFunctions.getChildren().clear();
-		CheckBox cb;
-		final FunctionSet fs = gui.getExperiment().getResources().getFunctionSet();
-		for (int i = 0; i < fs.getTotalFunctionCount(); i++) {
-			cb = new CheckBox(fs.getFunction(i).toString());
-			cb.setId(String.valueOf(i));
-			cb.setSelected(fs.isEnabled(fs.getFunction(i)));
+		CheckBox checkBox;
+		// get a reference to the function set
+		final FunctionSet functionSet = gui.getExperiment().getResources().getFunctionSet();
+		for (int i = 0; i < functionSet.getTotalFunctionCount(); i++) {
+			// add a checkbox for each function
+			checkBox = new CheckBox(functionSet.getFunction(i).toString());
+			checkBox.setId(String.valueOf(i));
+			// make sure the selection matches the function set
+			checkBox.setSelected(functionSet.isEnabled(functionSet.getFunction(i)));
 			final int index = i;
-			cb.setOnAction(new EventHandler<ActionEvent>() {
+			// set listener so function set gets updated if the checkboxes change
+			checkBox.setOnAction(new EventHandler<ActionEvent>() {
 				@Override
 				public void handle(ActionEvent event) {
 					if (((CheckBox) event.getSource()).isSelected()) {
-						fs.enableFunction(index);
+						functionSet.enableFunction(index);
 					} else {
-						fs.disableFunction(index);
+						functionSet.disableFunction(index);
 					}
 					gui.updateFunctionSelector();
 					revalidateParameters();
 				}
 			});
-			nodeFunctions.getChildren().add(cb);
-			
-			gui.updateFunctionSelector();
+			// add the new checkbox
+			nodeFunctions.getChildren().add(checkBox);
 		}
+		// make sure function selector has all functions
+		gui.updateFunctionSelector();
 	}
 	
+	/**
+	 * @return true if the experiment is currently evolving something, false otherwise.
+	 */
 	public boolean isExperimentRunning() {
 		return gui.isWorking();
 	}
@@ -450,6 +506,9 @@ public class SettingsPane extends AnchorPane {
 	 * Calls validate() on every parameter. This is called whenever a parameter changes,
 	 * so that other parameters update their status in case they were dependent on the
 	 * changed parameter.
+	 * <br><br>
+	 * This also disables the controls if a reset is necessary, preventing the experiment
+	 * from running until it has happened.
 	 */
 	public void revalidateParameters() {
 		boolean disableControls = false;
@@ -470,6 +529,8 @@ public class SettingsPane extends AnchorPane {
 	/**
 	 * Calls applyValue() on every parameter. This is called when a reset occurs, so that
 	 * the new value will be used as a reference instead of the old reference value.
+	 * <br><br>
+	 * It also closes the test case table, just in case.
 	 */
 	public void applyParameters() {
 		for (GUIParameter<?> parameter : parameters) {
@@ -486,8 +547,8 @@ public class SettingsPane extends AnchorPane {
 	 * experiment, in order to prevent inappropriate operations if the experiment is
 	 * running or finished.
 	 * 
-	 * @param running true if the experiment is running
-	 * @param finished true if the experiment is finished
+	 * @param running true if the experiment is running.
+	 * @param finished true if the experiment is finished.
 	 */
 	public void updateControls(boolean running, boolean finished) {
 		baseParameterPane.setDisable(running);