Fixed formatting, removed commented out code, added comments to handlers and locking stuff.

9 files changed, 112 insertions, 46 deletions

diff --git a/src/jcgp/gui/constants/Position.java b/src/jcgp/gui/constants/Position.java
index 144ba6d..cba5373 100644
--- a/src/jcgp/gui/constants/Position.java
+++ b/src/jcgp/gui/constants/Position.java
@@ -71,8 +71,6 @@ public final class Position {
 		output.getLine().setStartY(output.getLayoutY());
 	}
 	
-	
-	
 	/**
 	 * Connects the end of a specified line to the specified gene.
 	 * 
diff --git a/src/jcgp/gui/handlers/InputHandlers.java b/src/jcgp/gui/handlers/InputHandlers.java
index 6be4e7e..1d18ef5 100644
--- a/src/jcgp/gui/handlers/InputHandlers.java
+++ b/src/jcgp/gui/handlers/InputHandlers.java
@@ -6,13 +6,21 @@ import jcgp.gui.population.GUIGene.GUIGeneState;
 import jcgp.gui.population.GUIInput;
 
 /**
- * 
+ * Holds the handlers that define the behaviour of {@code GUIInput}.
+ * <br><br>
+ * The handlers are instantiated here statically and added to {@code GUIInput}
+ * instances using {@code InputHandlers.addHandlers(...)}. This guarantees that
+ * all inputs behave the same way without instantiating a new set of handlers for
+ * each input instance.
  * 
  * @author Eduardo Pedroni
  *
  */
 public final class InputHandlers {
 
+	/**
+	 * Inputs don't do much; set state to hover when mouse enters.
+	 */
 	private static EventHandler<MouseEvent> mouseEnteredHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
@@ -20,6 +28,9 @@ public final class InputHandlers {
 		}
 	};
 	
+	/**
+	 * Inputs don't do much; set state to neutral when mouse exits.
+	 */
 	private static EventHandler<MouseEvent> mouseExitedHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
@@ -27,6 +38,11 @@ public final class InputHandlers {
 		}
 	};
 	
+	/**
+	 * Adds all handlers to the specified input.
+	 * 
+	 * @param input the {@code GUIInput} to which the handlers will be added.
+	 */
 	public static void addHandlers(GUIInput input) {
 		input.addEventHandler(MouseEvent.MOUSE_ENTERED, mouseEnteredHandler);
 		input.addEventHandler(MouseEvent.MOUSE_EXITED, mouseExitedHandler);
diff --git a/src/jcgp/gui/handlers/NodeHandlers.java b/src/jcgp/gui/handlers/NodeHandlers.java
index 8c9c465..10a334a 100644
--- a/src/jcgp/gui/handlers/NodeHandlers.java
+++ b/src/jcgp/gui/handlers/NodeHandlers.java
@@ -8,21 +8,38 @@ import jcgp.gui.population.GUIGene;
 import jcgp.gui.population.GUIGene.GUIGeneState;
 import jcgp.gui.population.GUINode;
 
+/**
+ * Holds the handlers that define the behaviour of {@code GUINode}.
+ * <br><br>
+ * The handlers are instantiated here statically and added to {@code GUINode}
+ * instances using {@code NodeHandlers.addHandlers(...)}. This guarantees that
+ * all nodes behave the same way without instantiating a new set of handlers for
+ * each node instance.
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
 public final class NodeHandlers {
 
+	/**
+	 * Set the node to {@code GUIGeneState.HOVER} state, and set its immediate connections to {@code GUIGeneState.EXTENDED_HOVER}.
+	 */
 	private static EventHandler<MouseEvent> mouseEnteredHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
 			// acquire the source, we can safely cast it to GUINode
 			GUINode source = (GUINode) event.getSource();
+			
 			source.setState(GUIGeneState.HOVER);
-
 			for (int i = 0; i < GUI.resources.arity(); i++) {
 				((GUIGene) ((Gene) source.getNode().getConnection(i)).getGUIObject()).setState(GUIGeneState.EXTENDED_HOVER);
 			}
 		}
 	};
 
+	/**
+	 * Set the node and its immediate connections to {@code GUIGeneState.NEUTRAL} state.
+	 */
 	private static EventHandler<MouseEvent> mouseExitedHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
@@ -30,13 +47,17 @@ public final class NodeHandlers {
 			GUINode source = (GUINode) event.getSource();
 
 			source.setState(GUIGeneState.NEUTRAL);
-
 			for (int i = 0; i < GUI.resources.arity(); i++) {
 				((GUIGene) ((Gene) source.getNode().getConnection(i)).getGUIObject()).setState(GUIGeneState.NEUTRAL);
 			}
 		}
 	};
 
+	/**
+	 * Adds all handlers to the specified node.
+	 * 
+	 * @param node the {@code GUINode} to which the handlers will be added.
+	 */
 	public static void addHandlers(GUINode node) {
 		node.addEventHandler(MouseEvent.MOUSE_ENTERED, mouseEnteredHandler);
 		node.addEventHandler(MouseEvent.MOUSE_EXITED, mouseExitedHandler);
diff --git a/src/jcgp/gui/handlers/OutputHandlers.java b/src/jcgp/gui/handlers/OutputHandlers.java
index 7399e50..f72e430 100644
--- a/src/jcgp/gui/handlers/OutputHandlers.java
+++ b/src/jcgp/gui/handlers/OutputHandlers.java
@@ -7,55 +7,69 @@ import jcgp.gui.population.GUIConnection;
 import jcgp.gui.population.GUIGene.GUIGeneState;
 import jcgp.gui.population.GUIOutput;
 
+/**
+ * Holds the handlers that define the behaviour of {@code GUIOutput}.
+ * <br><br>
+ * The handlers are instantiated here statically and added to {@code GUIOutput}
+ * instances using {@code OutputHandlers.addHandlers(...)}. This guarantees that
+ * all outputs behave the same way without instantiating a new set of handlers for
+ * each output instance.
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
 public final class OutputHandlers {
 
+	/**
+	 * Set the output to {@code GUIGeneState.HOVER} state, and recursively set its active genes
+	 * to {@code GUIGeneState.ACTIVE_HOVER}.
+	 */
 	private static EventHandler<MouseEvent> mouseEnteredHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
 			// acquire the source, we can safely cast it to GUIOutput
 			GUIOutput source = (GUIOutput) event.getSource();
 
-			//if (!source.isLocked()) {
-				source.setState(GUIGeneState.HOVER);
-				((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setStateRecursively(GUIGeneState.ACTIVE_HOVER);
-			//}
+			source.setState(GUIGeneState.HOVER);
+			((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setStateRecursively(GUIGeneState.ACTIVE_HOVER);
 		}
 	};
 
+	/**
+	 * Set the output and all of its active genes to {@code GUIGeneState.NEUTRAL} state.
+	 */
 	private static EventHandler<MouseEvent> mouseExitedHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
 			// acquire the source, we can safely cast it to GUIOutput
 			GUIOutput source = (GUIOutput) event.getSource();
-
-			//if (!source.isLocked()) {
-				source.setState(GUIGeneState.NEUTRAL);
-				((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setStateRecursively(GUIGeneState.NEUTRAL);
-			//}
-
+			
+			source.setState(GUIGeneState.NEUTRAL);
+			((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setStateRecursively(GUIGeneState.NEUTRAL);
 		}
 	};
 
+	/**
+	 * If the output is locked, unlock it and all of its associated genes recursively. If it is unlocked, 
+	 * lock it and its active genes.
+	 */
 	private static EventHandler<MouseEvent> mouseClickHandler = new EventHandler<MouseEvent>() {
 		@Override
 		public void handle(MouseEvent event) {
 			// acquire the source, we can safely cast it to GUIOutput
 			GUIOutput source = (GUIOutput) event.getSource();
 
-			if (source.isLocked()) {
-				source.setLock(false);
-				((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setLockRecursively(false);
-			} else {
-				source.setLock(true);
-				((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setLockRecursively(true);
-			}
-			
-//			source.setState(GUIGeneState.HOVER);
-//			((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setStateRecursively(GUIGeneState.ACTIVE_HOVER);
-			
+			boolean lock = !source.isLocked();
+			source.setLock(lock);
+			((GUIConnection) ((Gene) source.getOutput().getSource()).getGUIObject()).setLockRecursively(lock);
 		}
 	};
 
+	/**
+	 * Adds all handlers to the specified output.
+	 * 
+	 * @param output the {@code GUIOutput} to which the handlers will be added.
+	 */
 	public static void addHandlers(GUIOutput output) {
 		output.addEventHandler(MouseEvent.MOUSE_ENTERED, mouseEnteredHandler);
 		output.addEventHandler(MouseEvent.MOUSE_EXITED, mouseExitedHandler);
diff --git a/src/jcgp/gui/population/GUIConnection.java b/src/jcgp/gui/population/GUIConnection.java
index 3a0ad67..dc7fcc8 100644
--- a/src/jcgp/gui/population/GUIConnection.java
+++ b/src/jcgp/gui/population/GUIConnection.java
@@ -21,6 +21,12 @@ public interface GUIConnection {
 	 */
 	public void setStateRecursively(GUIGeneState state);
 	
+	/**
+	 * Add or remove a lock, but also recursively propagate that change
+	 * all the way back to the inputs.
+	 * 
+	 * @param value true to lock, false to unlock.
+	 */
 	public void setLockRecursively(boolean value);
 	
 }
diff --git a/src/jcgp/gui/population/GUIGene.java b/src/jcgp/gui/population/GUIGene.java
index 02b87e7..f0fd568 100644
--- a/src/jcgp/gui/population/GUIGene.java
+++ b/src/jcgp/gui/population/GUIGene.java
@@ -14,7 +14,14 @@ import jcgp.gui.constants.Constants;
  * <br><br>
  * In practice, this is subclass of {@code javafx.scene.Group} containing a {@code Circle}
  * object and a {@code Text} object. Subclasses may add further elements to the group, for
- * instance to display connection input and output sockets. 
+ * instance to display connection input and output sockets.
+ * <br><br>
+ * Genes also contain a locked property. When locked, some gene states behave slightly
+ * differently. This is used so genes remain highlighted even in the neutral state. The
+ * gene lock is in fact recursive; a gene can be locked multiple times and only unlocking
+ * it as many times will actually revert it back to its unlocked state. This allows multiple
+ * pathways to lock the same gene independently without affecting each other; the gene remains
+ * locked until no pathways are locking it.
  * 
  * @author Eduardo Pedroni
  *
@@ -55,6 +62,10 @@ public abstract class GUIGene extends Group {
 	private Text text;
 	private Circle mainCircle;
 	
+	/**
+	 * Recursive lock; lock == 0 means unlocked, lock > 0 means locked.
+	 * Accessing using {@code setLock(...)}.
+	 */
 	private int lock = 0;
 
 	/**
@@ -134,10 +145,21 @@ public abstract class GUIGene extends Group {
 	 */
 	protected abstract void setLinesVisible(boolean value);
 	
+	/**
+	 * @return true if the gene is locked, false otherwise.
+	 */
 	public boolean isLocked() {
 		return lock > 0;
 	}
 	
+	/**
+	 * Locks or unlocks the gene once. Locked genes
+	 * behave slightly differently in some states. 
+	 * <br>
+	 * Unlocking an already unlocked gene does nothing.
+	 * 
+	 * @param value true to lock, false to unlock;
+	 */
 	public void setLock(boolean value) {
 		if (value) {
 			lock++;
diff --git a/src/jcgp/gui/population/GUIInput.java b/src/jcgp/gui/population/GUIInput.java
index d899585..3db7416 100644
--- a/src/jcgp/gui/population/GUIInput.java
+++ b/src/jcgp/gui/population/GUIInput.java
@@ -55,17 +55,11 @@ public class GUIInput extends GUIGene implements GUIConnection {
 		this.input = input;
 	}
 
-	/* (non-Javadoc)
-	 * @see jcgp.gui.population.GUIConnection#setStateRecursively(jcgp.gui.population.GUIGene.GUIGeneState)
-	 */
 	@Override
 	public void setStateRecursively(GUIGeneState state) {
 		setState(state);
 	}
 
-	/* (non-Javadoc)
-	 * @see jcgp.gui.population.GUIGene#setLinesVisible(boolean)
-	 */
 	@Override
 	protected void setLinesVisible(boolean value) {}
 
diff --git a/src/jcgp/gui/population/GUIMutable.java b/src/jcgp/gui/population/GUIMutable.java
index 61a8f48..b210672 100644
--- a/src/jcgp/gui/population/GUIMutable.java
+++ b/src/jcgp/gui/population/GUIMutable.java
@@ -9,8 +9,4 @@ package jcgp.gui.population;
  * @author Eduardo Pedroni
  *
  */
-public interface GUIMutable {
-
-	
-	
-}
+public interface GUIMutable {}
diff --git a/src/jcgp/gui/population/GUIOutput.java b/src/jcgp/gui/population/GUIOutput.java
index 9ffef1d..3bc81d9 100644
--- a/src/jcgp/gui/population/GUIOutput.java
+++ b/src/jcgp/gui/population/GUIOutput.java
@@ -47,6 +47,13 @@ public class GUIOutput extends GUIGene implements GUIMutable {
 	}
 
 	/**
+	 * @return the {@code Output} instance associated with this object.
+	 */
+	public Output getOutput() {
+		return output;
+	}
+	
+	/**
 	 * Associates this instance with a new output.
 	 * 
 	 * @param output the new output.
@@ -56,14 +63,6 @@ public class GUIOutput extends GUIGene implements GUIMutable {
 	}
 
 	/**
-	 * @return the {@code Output} instance associated with this object.
-	 */
-	public Output getOutput() {
-		return output;
-	}
-
-	
-	/**
 	 * @return this output's single connection line.
 	 */
 	public Line getLine() {