Merge remote-tracking branch 'origin/master' into reflect

src/org/ggp/base/player/gamer/statemachine/StateMachineGamer.java

@@ -24,9 +24,9 @@
  * Almost every player should subclass this class, since it provides the common
  * methods for interpreting the match history as transitions in a state machine,
  * and for keeping an up-to-date view of the current state of the game.
- * 
+ *
  * See @SimpleSearchLightGamer, @HumanGamer, and @RandomGamer for examples.
- * 
+ *
  * @author evancox
  * @author Sam
  */
@@ -41,17 +41,17 @@ public abstract class StateMachineGamer extends Gamer
      * Defines which state machine this gamer will use.
      * @return
      */
-    public abstract StateMachine getInitialStateMachine();    
-    
+    public abstract StateMachine getInitialStateMachine();
+
     /**
      * Defines the metagaming action taken by a player during the START_CLOCK
      * @param timeout time in milliseconds since the era when this function must return
      * @throws TransitionDefinitionException
      * @throws MoveDefinitionException
      * @throws GoalDefinitionException
-     */    
+     */
     public abstract void stateMachineMetaGame(long timeout) throws TransitionDefinitionException, MoveDefinitionException, GoalDefinitionException;
-    
+
     /**
      * Defines the algorithm that the player uses to select their move.
      * @param timeout time in milliseconds since the era when this function must return
@@ -66,45 +66,41 @@ public abstract class StateMachineGamer extends Gamer
      * Defines any actions that the player takes upon the game cleanly ending.
      */
     public abstract void stateMachineStop();
-    
+
     /**
      * Defines any actions that the player takes upon the game abruptly ending.
      */
     public abstract void stateMachineAbort();
-    
+
     // =====================================================================
     // Next, methods which can be used by subclasses to get information about
     // the current state of the game, and tweak the state machine on the fly.
-    
+
 	/**
-	 * Returns the current state
-	 * @return the current state
+	 * Returns the current state of the game.
 	 */
 	public final MachineState getCurrentState()
 	{
 		return currentState;
 	}
-	
+
 	/**
-	 * Returns the current role
-	 * @return the current role
+	 * Returns the role that this gamer is playing as in the game.
 	 */
 	public final Role getRole()
 	{
 		return role;
 	}
-	
+
 	/**
-	 * Returns the state machine.  This is used for calculating the next state and other operations such as computing
-	 * the legal moves for all players
-	 * 
-	 * @return a state machine
+	 * Returns the state machine.  This is used for calculating the next state and other operations, such as computing
+	 * the legal moves for all players, whether states are terminal, and the goal values of terminal states.
 	 */
 	public final StateMachine getStateMachine()
 	{
 		return stateMachine;
 	}
-	
+
     /**
      * Cleans up the role, currentState and stateMachine. This should only be
      * used when a match is over, and even then only when you really need to
@@ -113,24 +109,24 @@ public final StateMachine getStateMachine()
      */
     protected final void cleanupAfterMatch() {
         role = null;
-        currentState = null;        
+        currentState = null;
         stateMachine = null;
         setMatch(null);
         setRoleName(null);
     }
-    
+
     /**
      * Switches stateMachine to newStateMachine, playing through the match
      * history to the current state so that currentState is expressed using
      * a MachineState generated by the new state machine.
-     * 
+     *
      * This is not done in a thread-safe fashion with respect to the rest of
      * the gamer, so be careful when using this method.
-     * 
+     *
      * @param newStateMachine the new state machine
      */
     protected final void switchStateMachine(StateMachine newStateMachine) {
-        try {        
+        try {
             MachineState newCurrentState = newStateMachine.getInitialState();
             Role newRole = newStateMachine.getRoleFromConstant(getRoleName());
 
@@ -139,32 +135,32 @@ protected final void switchStateMachine(StateMachine newStateMachine) {
             for(List<GdlTerm> nextMove : theMoveHistory) {
                 List<Move> theJointMove = new ArrayList<Move>();
                 for(GdlTerm theSentence : nextMove)
-                    theJointMove.add(newStateMachine.getMoveFromTerm(theSentence));                    
+                    theJointMove.add(newStateMachine.getMoveFromTerm(theSentence));
                 newCurrentState = newStateMachine.getNextStateDestructively(newCurrentState, theJointMove);
             }
-            
+
             // Finally, switch over if everything went well.
             role = newRole;
-            currentState = newCurrentState;            
+            currentState = newCurrentState;
             stateMachine = newStateMachine;
         } catch (Exception e) {
             GamerLogger.log("GamePlayer", "Caught an exception while switching state machine!");
             GamerLogger.logStackTrace("GamePlayer", e);
         }
-    }	
+    }
 
     // =====================================================================
     // Finally, methods which are overridden with proper state-machine-based
 	// semantics. These basically wrap a state-machine-based view of the world
 	// around the ordinary metaGame() and selectMove() functions, calling the
 	// new stateMachineMetaGame() and stateMachineSelectMove() functions after
 	// doing the state-machine-related book-keeping.
-	
+
 	/**
 	 * A wrapper function for stateMachineMetaGame. When the match begins, this
 	 * initializes the state machine and role using the match description, and
 	 * then calls stateMachineMetaGame.
-	 */	
+	 */
 	@Override
 	public final void metaGame(long timeout) throws MetaGamingException
 	{
@@ -184,7 +180,7 @@ public final void metaGame(long timeout) throws MetaGamingException
 			throw new MetaGamingException(e);
 		}
 	}
-	
+
 	/**
 	 * A wrapper function for stateMachineSelectMove. When we are asked to
 	 * select a move, this advances the state machine up to the current state
@@ -219,7 +215,7 @@ public final GdlTerm selectMove(long timeout) throws MoveSelectionException
 			throw new MoveSelectionException(e);
 		}
 	}
-	
+
 	@Override
 	public void stop() throws StoppingException {
 		try {
@@ -247,7 +243,7 @@ public void stop() throws StoppingException {
 			throw new StoppingException(e);
 		}
 	}
-	
+
 	@Override
 	public void abort() throws AbortingException {
 		try {
@@ -258,10 +254,10 @@ public void abort() throws AbortingException {
 			GamerLogger.logStackTrace("GamePlayer", e);
 			throw new AbortingException(e);
 		}
-	}	
-    
+	}
+
     // Internal state about the current state of the state machine.
     private Role role;
     private MachineState currentState;
-    private StateMachine stateMachine;          
+    private StateMachine stateMachine;
 }

src/org/ggp/base/util/statemachine/Move.java

@@ -4,7 +4,14 @@
 
 import org.ggp.base.util.gdl.grammar.GdlTerm;
 
-
+/**
+ * A Move represents a possible move that can be made by a role. Each
+ * player makes exactly one move on every turn. This includes moves
+ * that represent passing, or taking no action.
+ * <p>
+ * Note that Move objects are not intrinsically tied to a role. They
+ * only express the action itself.
+ */
 @SuppressWarnings("serial")
 public class Move implements Serializable
 {

src/org/ggp/base/util/statemachine/Role.java

@@ -9,6 +9,12 @@
 import org.ggp.base.util.gdl.grammar.GdlRelation;
 
 
+/**
+ * A Role represents the name used for a player in a game description.
+ * <p>
+ * The list of roles defined in a game description can be extracted
+ * using the {@link #computeRoles(List)} method.
+ */
 @SuppressWarnings("serial")
 public class Role implements Serializable
 {
@@ -47,10 +53,10 @@ public String toString()
     {
         return name.toString();
     }
-    
+
     /**
      * Compute all of the roles in a game, in the correct order.
-     * 
+     * <p>
      * Order matters, because a joint move is defined as an ordered list
      * of moves, in which the order determines which player took which of
      * the moves. This function will give an ordered list in which the roles
@@ -61,12 +67,12 @@ public static List<Role> computeRoles(List<? extends Gdl> description)
         List<Role> roles = new ArrayList<Role>();
         for (Gdl gdl : description) {
             if (gdl instanceof GdlRelation) {
-                GdlRelation relation = (GdlRelation) gdl;               
+                GdlRelation relation = (GdlRelation) gdl;
                 if (relation.getName().getValue().equals("role")) {
                     roles.add(new Role((GdlConstant) relation.get(0)));
                 }
             }
         }
         return roles;
-    }    
+    }
 }