Added Javadoc comments to private methods in the model

git-svn-id: svn://sunsvr01.isp.uni-luebeck.de/swproj13/trunk@522 72836036-5685-4462-b002-a69064685172

8 files changed, 175 insertions, 80 deletions

diff --git a/src/jrummikub/model/GameSettings.java b/src/jrummikub/model/GameSettings.java
index 2446333..8291cfb 100644
--- a/src/jrummikub/model/GameSettings.java
+++ b/src/jrummikub/model/GameSettings.java
@@ -50,8 +50,8 @@ public class GameSettings implements Serializable {
 		totalTime = 60;
 		noLimits = false;
 		seeHandSize = false;
-		stoneColors = new HashSet<StoneColor>(Arrays.asList(BLACK, BLUE,
-				ORANGE, RED));
+		stoneColors = new HashSet<StoneColor>(Arrays.asList(BLACK, BLUE, ORANGE,
+				RED));
 	}
 
 	/**
@@ -67,7 +67,7 @@ public class GameSettings implements Serializable {
 	 * Sets the initial meld threshold
 	 * 
 	 * @param value
-	 *            the value to set
+	 *          the value to set
 	 */
 	public void setInitialMeldThreshold(int value) {
 		initialMeldThreshold = value;
@@ -86,7 +86,7 @@ public class GameSettings implements Serializable {
 	 * Sets the points counted for a joker
 	 * 
 	 * @param value
-	 *            the value to set
+	 *          the value to set
 	 */
 	public void setJokerPoints(int value) {
 		jokerPoints = value;
@@ -105,7 +105,7 @@ public class GameSettings implements Serializable {
 	 * Sets the number of jokers in game
 	 * 
 	 * @param value
-	 *            how many jokers will be used
+	 *          how many jokers will be used
 	 */
 	public void setJokerNumber(int value) {
 		jokerNumber = value;
@@ -133,7 +133,7 @@ public class GameSettings implements Serializable {
 	 * Set the highest stone value in use
 	 * 
 	 * @param highestValue
-	 *            highest stone value
+	 *          highest stone value
 	 */
 	public void setHighestValue(int highestValue) {
 		this.highestValue = highestValue;
@@ -152,7 +152,7 @@ public class GameSettings implements Serializable {
 	 * Set the number of sets of stones in use
 	 * 
 	 * @param stoneSets
-	 *            sets of stones in use
+	 *          sets of stones in use
 	 */
 	public void setStoneSetNumber(int stoneSets) {
 		this.stoneSetNumber = stoneSets;
@@ -171,7 +171,7 @@ public class GameSettings implements Serializable {
 	 * Setter for the time for a turn
 	 * 
 	 * @param totalTime
-	 *            for a turn
+	 *          for a turn
 	 */
 	public void setTotalTime(int totalTime) {
 		this.totalTime = totalTime;
@@ -186,24 +186,35 @@ public class GameSettings implements Serializable {
 		return noLimits;
 	}
 
-	public boolean doSeeHandSize() {
+	/**
+	 * Returns the visibility of the hand size
+	 * 
+	 * @return whether the hand size is visible
+	 */
+	public boolean getSeeHandSize() {
 		return seeHandSize;
 	}
 
 	/**
+	 * Set whether the hand size is visible
+	 * 
+	 * @param see
+	 *          whether the hand size is visible
+	 */
+	public void setSeeHandSize(boolean see) {
+		seeHandSize = see;
+	}
+
+	/**
 	 * Set whether "No-Limits" rules are used
 	 * 
 	 * @param noLimits
-	 *            use no limit rules
+	 *          use no limit rules
 	 */
 	public void setNoLimits(boolean noLimits) {
 		this.noLimits = noLimits;
 	}
 
-	public void setSeeHandSize(boolean see) {
-		seeHandSize = see;
-	}
-
 	/**
 	 * Get stone colors used
 	 * 
@@ -217,7 +228,7 @@ public class GameSettings implements Serializable {
 	 * Set stone colors used
 	 * 
 	 * @param stoneColors
-	 *            used stone colors
+	 *          used stone colors
 	 */
 	public void setStoneColors(Set<StoneColor> stoneColors) {
 		this.stoneColors = new HashSet<StoneColor>(stoneColors);
@@ -236,7 +247,7 @@ public class GameSettings implements Serializable {
 	 * Set number of stones dealt at game start
 	 * 
 	 * @param number
-	 *            how many Stones will be dealt initially
+	 *          how many Stones will be dealt initially
 	 */
 	public void setNumberOfStonesDealt(int number) {
 		numberOfStonesDealt = number;
@@ -264,7 +275,7 @@ public class GameSettings implements Serializable {
 	 * @return total number of stones
 	 */
 	public int getTotalStones() {
-		return getHighestValue() * getStoneSetNumber()
-				* getStoneColors().size() + getJokerNumber();
+		return getHighestValue() * getStoneSetNumber() * getStoneColors().size()
+				+ getJokerNumber();
 	}
 }
diff --git a/src/jrummikub/model/GameState.java b/src/jrummikub/model/GameState.java
index 8311977..ee5c2d3 100644
--- a/src/jrummikub/model/GameState.java
+++ b/src/jrummikub/model/GameState.java
@@ -42,6 +42,13 @@ public class GameState implements Serializable {
 		return scores;
 	}
 
+	/**
+	 * Returns whether players have won
+	 * 
+	 * @param points the player's points 
+	 * @param wins the number of wins per player
+	 * @return whether a player has won
+	 */
 	private Boolean[] getWinners(Integer[] points, int[] wins) {
 		int playerCount = scores.get(0).getPoints().size();
 		int maxWins = 0, maxPoints = 0;
diff --git a/src/jrummikub/model/Hand.java b/src/jrummikub/model/Hand.java
index 69d659b..3e6bfeb 100644
--- a/src/jrummikub/model/Hand.java
+++ b/src/jrummikub/model/Hand.java
@@ -47,8 +47,8 @@ public class Hand extends StoneTray<Stone> implements IHand {
 	}
 
 	@Override
-	protected Pair<Position, Direction> fixInvalidDrop(Stone stone,
-			Position pos, Direction dir) {
+	protected Pair<Position, Direction> fixInvalidDrop(Stone stone, Position pos,
+			Direction dir) {
 		double x = pos.getX();
 		double y = pos.getY();
 
@@ -59,11 +59,9 @@ public class Hand extends StoneTray<Stone> implements IHand {
 			return new Pair<Position, Direction>(new Position(0, y), RIGHT);
 		} else {
 			if (getFreeRowSpace((int) y) == 0) {
-				return new Pair<Position, Direction>(new Position(0, y + 1),
-						RIGHT);
+				return new Pair<Position, Direction>(new Position(0, y + 1), RIGHT);
 			} else {
-				return new Pair<Position, Direction>(
-						new Position(WIDTH - 1, y), LEFT);
+				return new Pair<Position, Direction>(new Position(WIDTH - 1, y), LEFT);
 			}
 		}
 	}
@@ -96,8 +94,14 @@ public class Hand extends StoneTray<Stone> implements IHand {
 		turnLogic.needIntialMeldThreshold();
 		return turnLogic.solve();
 	}
-	
-	
+
+	/**
+	 * Increments the count of a stone in the list of all stones
+	 * 
+	 * @param stones
+	 *          all stones and their respective numbers
+	 * @param stone
+	 */
 	private static void incrementStoneCount(
 			TreeMap<Pair<Integer, StoneColor>, Integer> stones,
 			Pair<Integer, StoneColor> stone) {
@@ -108,6 +112,9 @@ public class Hand extends StoneTray<Stone> implements IHand {
 		}
 	}
 
+	/**
+	 * The measure to compare the stones by
+	 */
 	private final static Comparator<Pair<Integer, StoneColor>> comparator = new Comparator<Pair<Integer, StoneColor>>() {
 		@Override
 		public int compare(Pair<Integer, StoneColor> o1,
@@ -120,7 +127,7 @@ public class Hand extends StoneTray<Stone> implements IHand {
 			}
 		}
 	};
-	
+
 	/**
 	 * Counts the numbers of stones
 	 * 
@@ -152,8 +159,7 @@ public class Hand extends StoneTray<Stone> implements IHand {
 	public int getIdenticalStoneCount() {
 		List<Stone> stones = new ArrayList<Stone>();
 
-		for (Iterator<Pair<Stone, Position>> iter = this.iterator(); iter
-				.hasNext();) {
+		for (Iterator<Pair<Stone, Position>> iter = this.iterator(); iter.hasNext();) {
 			stones.add(iter.next().getFirst());
 		}
 
diff --git a/src/jrummikub/model/IRoundState.java b/src/jrummikub/model/IRoundState.java
index 1ac0ac2..6d43f02 100644
--- a/src/jrummikub/model/IRoundState.java
+++ b/src/jrummikub/model/IRoundState.java
@@ -96,6 +96,11 @@ public interface IRoundState extends Serializable {
 	 */
 	public void setActivePlayerNumber(int i);
 
+	/**
+	 * Returns the game state
+	 * 
+	 * @return the game state
+	 */
 	public GameState getGameState();
 
 	/**
diff --git a/src/jrummikub/model/RoundState.java b/src/jrummikub/model/RoundState.java
index 2c50089..04a977d 100644
--- a/src/jrummikub/model/RoundState.java
+++ b/src/jrummikub/model/RoundState.java
@@ -21,6 +21,8 @@ public class RoundState implements IRoundState {
 	 * 
 	 * @param gameSettings
 	 *          the game settings
+	 * @param gameState
+	 *          the game state
 	 */
 	public RoundState(GameSettings gameSettings, GameState gameState) {
 		this.gameSettings = gameSettings;
diff --git a/src/jrummikub/model/StoneSet.java b/src/jrummikub/model/StoneSet.java
index 02fd797..7755a3a 100644
--- a/src/jrummikub/model/StoneSet.java
+++ b/src/jrummikub/model/StoneSet.java
@@ -23,7 +23,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Create a new single stone stone set
 	 * 
 	 * @param stone
-	 *            single stone of the set
+	 *          single stone of the set
 	 */
 	public StoneSet(Stone stone) {
 		stones = new ArrayList<Stone>(Collections.singletonList(stone));
@@ -33,7 +33,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Create a stone set from a list of stones
 	 * 
 	 * @param stones
-	 *            list of stones to build a set of
+	 *          list of stones to build a set of
 	 */
 	public StoneSet(List<Stone> stones) {
 		this.stones = new ArrayList<Stone>(stones);
@@ -53,7 +53,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Test for rule conflict within the StoneSet
 	 * 
 	 * @param settings
-	 *            GameSettings
+	 *          GameSettings
 	 * 
 	 * @return true when the set is valid according to the rules
 	 */
@@ -62,13 +62,13 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	}
 
 	/**
-	 * Test for rule conflict within the StoneSet and determine whether the set
-	 * is a group or a run
+	 * Test for rule conflict within the StoneSet and determine whether the set is
+	 * a group or a run
 	 * 
 	 * @param settings
-	 *            GameSettings
+	 *          GameSettings
 	 * 
-	 * @return GROUP or RUN for valid sets, INVALID otherwise
+	 * @return GROUP or RUN for valid sets, INVALID otherwise and the points
 	 */
 
 	public Pair<Type, Integer> classify(GameSettings settings) {
@@ -84,7 +84,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 		}
 
 		if (nonJoker == -1) {
-			return classifyJokersOnly(settings, nonJoker);
+			return classifyJokersOnly(settings);
 		}
 
 		int runScore = isValidRun(nonJoker, settings);
@@ -99,8 +99,15 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 		}
 	}
 
-	private Pair<Type, Integer> classifyJokersOnly(GameSettings settings,
-			int nonJoker) {
+	/**
+	 * Test for rule conflict within a StoneSet with jokers only and determine
+	 * whether the set is a group or a run
+	 * 
+	 * @param settings
+	 *          the game settings
+	 * @return GROUP or RUN for valid sets, INVALID otherwise and the points
+	 */
+	private Pair<Type, Integer> classifyJokersOnly(GameSettings settings) {
 		if (stones.size() > settings.getHighestValue()
 				&& stones.size() > settings.getStoneColors().size()
 				&& !settings.isNoLimits()) {
@@ -126,8 +133,10 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Test for rule conflict within the StoneSet, assuming we have a run
 	 * 
 	 * @param referencePosition
-	 *            position of stone used as reference (any non-joker stone)
+	 *          position of stone used as reference (any non-joker stone)
 	 * @param settings
+	 *          the game settings
+	 * @return the set's points
 	 */
 	private int isValidRun(int referencePosition, GameSettings settings) {
 		StoneColor runColor = stones.get(referencePosition).getColor();
@@ -167,7 +176,12 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	/**
 	 * Test for rule conflict within the StoneSet, assuming we have a group
 	 * 
+	 * @param value
+	 *          the value of the stones (all have the same in a group)
+	 * 
 	 * @param settings
+	 *          the game settings
+	 * @return the set's points
 	 */
 	private int isValidGroup(int value, GameSettings settings) {
 		if (stones.size() > settings.getStoneColors().size()) {
@@ -195,7 +209,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Stone Sets
 	 * 
 	 * @param position
-	 *            Splitting {@link Position}
+	 *          Splitting {@link Position}
 	 * @return A pair of StoneSets, one for each split part
 	 */
 	public Pair<StoneSet, StoneSet> splitAt(int position) {
@@ -205,8 +219,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 			return new Pair<StoneSet, StoneSet>(this, null);
 		}
 		StoneSet firstSet = new StoneSet(stones.subList(0, position));
-		StoneSet secondSet = new StoneSet(stones.subList(position,
-				stones.size()));
+		StoneSet secondSet = new StoneSet(stones.subList(position, stones.size()));
 		return new Pair<StoneSet, StoneSet>(firstSet, secondSet);
 	}
 
@@ -214,7 +227,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Joins StoneSet to another StoneSet and returns the resulting new StoneSet
 	 * 
 	 * @param other
-	 *            StoneSet to be joined to active StoneSet
+	 *          StoneSet to be joined to active StoneSet
 	 * @return the combined StoneSet
 	 */
 	public StoneSet join(StoneSet other) {
@@ -237,7 +250,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * Returns the i-th stone of the set (starting with 0)
 	 * 
 	 * @param i
-	 *            number of the stone to return
+	 *          number of the stone to return
 	 * @return the i-th stone
 	 */
 	public Stone get(int i) {
diff --git a/src/jrummikub/model/StoneTray.java b/src/jrummikub/model/StoneTray.java
index a5f023d..f2f1151 100644
--- a/src/jrummikub/model/StoneTray.java
+++ b/src/jrummikub/model/StoneTray.java
@@ -31,6 +31,17 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		}
 	}
 
+	/**
+	 * Subroutine to "drop" to consider and determine the direction the objects
+	 * dropped one collides with position-wise evade in
+	 * 
+	 * @param object
+	 *          the object to add to Hand
+	 * @param position
+	 *          {@link Position} to put the object
+	 * @param direction
+	 *          the direction the other stones evade in
+	 */
 	private void drop(E object, Position position, Direction direction) {
 		Pair<Position, Direction> update = fixInvalidDrop(object, position,
 				direction);
@@ -42,6 +53,16 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		dropUnchecked(object, position, direction);
 	}
 
+	/**
+	 * Subroutine to "drop" to execute the actual drop
+	 * 
+	 * @param object
+	 *          the object to add to Hand
+	 * @param position
+	 *          {@link Position} to put the object
+	 * @param direction
+	 *          the direction the other stones evade in
+	 */
 	@SuppressWarnings("unchecked")
 	private void dropUnchecked(E object, Position position, Direction direction) {
 		objects.put(object, new Pair<E, Position>(object, position));
@@ -62,23 +83,22 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 			Position newPosition = null;
 			// Move object to avoid overlap
 			switch (newDirection) {
-				case TOP:
-					newPosition = new Position(currentPosition.getX(), position.getY()
-							- currentObject.getHeight());
-					break;
-				case BOTTOM:
-					newPosition = new Position(currentPosition.getX(), position.getY()
-							+ object.getHeight());
-					break;
-				case LEFT:
-					newPosition = new Position(
-							position.getX() - currentObject.getWidth(),
-							currentPosition.getY());
-					break;
-				case RIGHT:
-					newPosition = new Position(position.getX() + object.getWidth(),
-							currentPosition.getY());
-					break;
+			case TOP:
+				newPosition = new Position(currentPosition.getX(), position.getY()
+						- currentObject.getHeight());
+				break;
+			case BOTTOM:
+				newPosition = new Position(currentPosition.getX(), position.getY()
+						+ object.getHeight());
+				break;
+			case LEFT:
+				newPosition = new Position(position.getX() - currentObject.getWidth(),
+						currentPosition.getY());
+				break;
+			case RIGHT:
+				newPosition = new Position(position.getX() + object.getWidth(),
+						currentPosition.getY());
+				break;
 			}
 
 			objects.remove(currentObject);
@@ -102,6 +122,16 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		return null;
 	}
 
+	/**
+	 * Static method for determining a less or equal relation considering a small
+	 * fuzziness
+	 * 
+	 * @param d
+	 *          the value to be less or equal
+	 * @param e
+	 *          than the other one
+	 * @return if d is less or equal e
+	 */
 	private static boolean lessOrEqual(double d, double e) {
 		if (-0.000001 < e && e < 0.000001) {
 			return (d < e + 0.000001);
@@ -115,7 +145,20 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		return d < e;
 	}
 
-	/** Tests whether two objects overlap **/
+	/**
+	 * Tests whether two objects overlap
+	 * 
+	 * @param object1
+	 *          first object
+	 * @param position1
+	 *          first object's position
+	 * @param object2
+	 *          second object
+	 * @param position2
+	 *          second object's position
+	 * 
+	 * @return whether they overlap
+	 **/
 	private boolean objectsOverlap(E object1, Position position1, E object2,
 			Position position2) {
 		// Tests if position is left of, above ... the current object
@@ -134,6 +177,17 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		return true;
 	}
 
+	/**
+	 * Returns the direction to move the object in
+	 * 
+	 * @param object
+	 *          the object
+	 * @param position
+	 *          the object's position
+	 * @param blocking
+	 *          the object thats blocking
+	 * @return the direction
+	 */
 	private Direction getMoveDirection(E object, Position position,
 			Pair<E, Position> blocking) {
 		boolean isVertical = getMoveOrientation(object, position, blocking);
@@ -161,6 +215,13 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 	/**
 	 * Will the object be moved horizontally or vertically
 	 * 
+	 * @param object
+	 *          the object
+	 * @param position
+	 *          the objects position
+	 * @param blocking
+	 *          the object thats blocking
+	 * 
 	 * @return boolean vertical movement
 	 */
 	private boolean getMoveOrientation(E object, Position position,
@@ -177,16 +238,9 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		double overlapBottom = Math.min(objectBottom, blockingBottom);
 		double overlapTop = Math.max(position.getY(), blocking.getSecond().getY());
 		double overlapY = overlapBottom - overlapTop;
-		// vertical or horizontal Shift
-		// TODO magic factor
 		return overlapX > overlapY;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * 
-	 * @see jrummikub.model.IStoneTray#getPosition(E)
-	 */
 	@Override
 	public Position getPosition(E object) {
 		Pair<E, Position> entry = objects.get(object);
@@ -206,21 +260,11 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 		return objects.values().iterator();
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * 
-	 * @see jrummikub.model.IStoneTray#pickUp(E)
-	 */
 	@Override
 	public boolean pickUp(E object) {
 		return null != objects.remove(object);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * 
-	 * @see jrummikub.model.IStoneTray#clone()
-	 */
 	@SuppressWarnings("unchecked")
 	@Override
 	public IStoneTray<E> clone() {
diff --git a/src/jrummikub/model/Table.java b/src/jrummikub/model/Table.java
index 1f07f97..1b355db 100644
--- a/src/jrummikub/model/Table.java
+++ b/src/jrummikub/model/Table.java
@@ -46,6 +46,13 @@ public class Table extends StoneTray<StoneSet> implements ITable {
 		}
 	}
 
+	/**
+	 * Finds {@link StoneInfo}
+	 * 
+	 * @param stone
+	 *          the stone
+	 * @return the info
+	 */
 	private StoneInfo findStoneInfo(Stone stone) {
 		// Find the set of the stone
 		StoneInfo info;