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

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,
+		stoneColors = new HashSet<StoneColor>(Arrays.asList(BLACK, BLUE, ORANGE,
-				ORANGE, RED));
+				RED));
 	}
 
 	/**
@@ -186,10 +186,25 @@ 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
 	 * 
@@ -200,10 +215,6 @@ public class GameSettings implements Serializable {
 		this.noLimits = noLimits;
 	}
 
-	public void setSeeHandSize(boolean see) {
-		seeHandSize = see;
-	}
-
 	/**
 	 * Get stone colors used
 	 * 
@@ -264,7 +275,7 @@ public class GameSettings implements Serializable {
 	 * @return total number of stones
 	 */
 	public int getTotalStones() {
-		return getHighestValue() * getStoneSetNumber()
+		return getHighestValue() * getStoneSetNumber() * getStoneColors().size()
-				* getStoneColors().size() + getJokerNumber();
+				+ getJokerNumber();
 	}
 }

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;

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,
+	protected Pair<Position, Direction> fixInvalidDrop(Stone stone, Position pos,
-			Position pos, Direction dir) {
+			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),
+				return new Pair<Position, Direction>(new Position(0, y + 1), RIGHT);
-						RIGHT);
 			} else {
-				return new Pair<Position, Direction>(
+				return new Pair<Position, Direction>(new Position(WIDTH - 1, y), LEFT);
-						new Position(WIDTH - 1, y), LEFT);
 			}
 		}
 	}
@@ -97,7 +95,13 @@ public class Hand extends StoneTray<Stone> implements IHand {
 		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,
@@ -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
+		for (Iterator<Pair<Stone, Position>> iter = this.iterator(); iter.hasNext();) {
-				.hasNext();) {
 			stones.add(iter.next().getFirst());
 		}
 

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();
 
 	/**

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;

src/jrummikub/model/StoneSet.java

@@ -62,13 +62,13 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	}
 
 	/**
-	 * Test for rule conflict within the StoneSet and determine whether the set
+	 * Test for rule conflict within the StoneSet and determine whether the set is
-	 * is a group or a run
+	 * a group or a run
 	 * 
 	 * @param settings
 	 *          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()) {
@@ -128,6 +135,8 @@ public class StoneSet implements Iterable<Stone>, Sizeable, Serializable {
 	 * @param referencePosition
 	 *          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()) {
@@ -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,
+		StoneSet secondSet = new StoneSet(stones.subList(position, stones.size()));
-				stones.size()));
 		return new Pair<StoneSet, StoneSet>(firstSet, secondSet);
 	}
 

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));
@@ -71,8 +92,7 @@ public class StoneTray<E extends Sizeable> implements IStoneTray<E> {
 						+ object.getHeight());
 				break;
 			case LEFT:
-					newPosition = new Position(
+				newPosition = new Position(position.getX() - currentObject.getWidth(),
-							position.getX() - currentObject.getWidth(),
 						currentPosition.getY());
 				break;
 			case RIGHT:
@@ -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() {

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;