Added all missing comments

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

15 files changed, 231 insertions, 24 deletions

diff --git a/src/jrummikub/control/ITurnTimer.java b/src/jrummikub/control/ITurnTimer.java
index 54f00b5..175d95f 100644
--- a/src/jrummikub/control/ITurnTimer.java
+++ b/src/jrummikub/control/ITurnTimer.java
@@ -2,12 +2,26 @@ package jrummikub.control;
 
 import jrummikub.util.IEvent;
 
+/**
+ * Interface for the {@link TurnTimer}
+ */
 public interface ITurnTimer {
 
+	/**
+	 * Starts the timer
+	 */
 	public abstract void startTimer();
 
+	/**
+	 * Stops the timer. Stopping an already stopped timer is a no-op.
+	 */
 	public abstract void stopTimer();
 
+	/**
+	 * Returns the event that is emitted if the timer timed out.
+	 * 
+	 * @return time out event
+	 */
 	public abstract IEvent getTimeRunOutEvent();
 
 }
\ No newline at end of file
diff --git a/src/jrummikub/control/RoundControl.java b/src/jrummikub/control/RoundControl.java
index 490873a..fc27f9b 100644
--- a/src/jrummikub/control/RoundControl.java
+++ b/src/jrummikub/control/RoundControl.java
@@ -18,6 +18,9 @@ import jrummikub.util.IListener;
 import jrummikub.util.Pair;
 import jrummikub.view.IView;
 
+/**
+ * Controller that manages a single round of rummikub
+ */
 public class RoundControl {
 	private IGameState gameState;
 	private IView view;
@@ -25,6 +28,14 @@ public class RoundControl {
 	private Event endRoundEvent = new Event();
 	private List<Connection> connections = new ArrayList<Connection>();
 
+	/**
+	 * Create a new RoundControl using the given gameState and view
+	 * 
+	 * @param gameState
+	 *            initial game state
+	 * @param view
+	 *            view used for user interaction
+	 */
 	public RoundControl(IGameState gameState, IView view) {
 		this.gameState = gameState;
 		this.view = view;
@@ -34,6 +45,9 @@ public class RoundControl {
 		return endRoundEvent;
 	}
 
+	/**
+	 * Begin the round
+	 */
 	public void startRound() {
 		deal();
 
diff --git a/src/jrummikub/control/TurnControl.java b/src/jrummikub/control/TurnControl.java
index 32e6379..ace201e 100644
--- a/src/jrummikub/control/TurnControl.java
+++ b/src/jrummikub/control/TurnControl.java
@@ -21,6 +21,9 @@ import jrummikub.util.IListener2;
 import jrummikub.util.Pair;
 import jrummikub.view.IView;
 
+/**
+ * Controller for a single turn made by a human player
+ */
 public class TurnControl {
 	private IHand hand;
 	private ITable table;
@@ -32,6 +35,17 @@ public class TurnControl {
 	private Event endOfTurnEvent = new Event();
 	private List<Connection> connections = new ArrayList<Connection>();
 
+	/**
+	 * Create a new TurnControl using a given hand (of the active player), a
+	 * given table and a given view for user interaction.
+	 * 
+	 * @param hand
+	 *            active player's hand
+	 * @param table
+	 *            current table
+	 * @param view
+	 *            view for user interaction.
+	 */
 	public TurnControl(IHand hand, ITable table, IView view) {
 		this.hand = hand;
 		this.table = table;
@@ -47,6 +61,9 @@ public class TurnControl {
 		this.timer = testTimer;
 	}
 
+	/**
+	 * Start the turn
+	 */
 	public void startTurn() {
 
 		IListener endOfTurnListener = new IListener() {
@@ -408,6 +425,11 @@ public class TurnControl {
 		view.setSelectedStones(new ArrayList<Stone>());
 	}
 
+	/**
+	 * Get the event that is emitted when the turn is over
+	 * 
+	 * @return end of turn event
+	 */
 	public IEvent getEndOfTurnEvent() {
 		return endOfTurnEvent;
 	}
diff --git a/src/jrummikub/control/TurnTimer.java b/src/jrummikub/control/TurnTimer.java
index 789bf1a..17bdf0f 100644
--- a/src/jrummikub/control/TurnTimer.java
+++ b/src/jrummikub/control/TurnTimer.java
@@ -9,12 +9,21 @@ import jrummikub.util.Event;
 import jrummikub.util.IEvent;
 import jrummikub.view.IView;
 
+/**
+ * Count-down timer used to limit the turn time
+ */
 public class TurnTimer implements ActionListener, ITurnTimer {
 	private IView view;
 	private int timeLeft = 60;
 	private Timer timer;
 	private Event timeRunOutEvent = new Event();
 
+	/**
+	 * Create a new timer using a given view to display the current time left
+	 * 
+	 * @param view
+	 *            view to display
+	 */
 	public TurnTimer(IView view) {
 		this.view = view;
 		timer = new Timer(1000, this);
@@ -23,19 +32,16 @@ public class TurnTimer implements ActionListener, ITurnTimer {
 		view.getPlayerPanel().setTimeLeft(timeLeft);
 	}
 
-	
 	@Override
 	public void startTimer() {
 		timer.start();
 	}
 
-	
 	@Override
 	public void stopTimer() {
 		timer.stop();
 	}
 
-	
 	@Override
 	public void actionPerformed(ActionEvent arg0) {
 		timeLeft--;
diff --git a/src/jrummikub/model/GameState.java b/src/jrummikub/model/GameState.java
index 6f1bad3..69c5570 100644
--- a/src/jrummikub/model/GameState.java
+++ b/src/jrummikub/model/GameState.java
@@ -11,6 +11,9 @@ public class GameState implements IGameState {
 	private int activePlayer;
 	private StoneHeap gameHeap;
 
+	/** 
+	 * Create a new GameState with an empty table and (currntly) 4 new players.
+	 */
 	public GameState() {
 		table = new Table();
 		players = new ArrayList<Player>();
@@ -37,7 +40,6 @@ public class GameState implements IGameState {
 		return players.size();
 	}
 
-	/** Changes the activePlayer to the next {@link Player} in the list */
 	@Override
 	public void nextPlayer() {
 		activePlayer = (activePlayer + 1) % players.size();
diff --git a/src/jrummikub/model/IGameState.java b/src/jrummikub/model/IGameState.java
index 8e64bc4..ebc31c5 100644
--- a/src/jrummikub/model/IGameState.java
+++ b/src/jrummikub/model/IGameState.java
@@ -1,20 +1,56 @@
 package jrummikub.model;
 
+/**
+ * Interface for {@link GameState} model
+ */
 public interface IGameState {
 
+	/**
+	 * Get the current {@link Table}
+	 * 
+	 * @return The current Table
+	 */
 	public ITable getTable();
 
+	/**
+	 * Sets the current {@link Table}
+	 * 
+	 * @param table
+	 *            The new Table
+	 */
 	public void setTable(ITable table);
 
+	/**
+	 * Returns the number of players
+	 * 
+	 * @return number of players
+	 */
 	public int getPlayerCount();
 
 	/** Changes the activePlayer to the next {@link Player} in the list */
 	public void nextPlayer();
 
+	/**
+	 * Returns the currently active player
+	 * 
+	 * @return currently active player
+	 */
 	public IPlayer getActivePlayer();
 
+	/**
+	 * Returns the heap of stones to draw from
+	 * 
+	 * @return heap of stones
+	 */
 	public StoneHeap getGameHeap();
 
+	/**
+	 * Returns the player that would be the active player after i turns
+	 * 
+	 * @param i
+	 *            number of turns
+	 * @return player active after i turns
+	 */
 	public IPlayer getNthNextPlayer(int i);
 
 }
\ No newline at end of file
diff --git a/src/jrummikub/model/IHand.java b/src/jrummikub/model/IHand.java
index 8bc7e7f..f5234d1 100644
--- a/src/jrummikub/model/IHand.java
+++ b/src/jrummikub/model/IHand.java
@@ -1,5 +1,8 @@
 package jrummikub.model;

 

+/**

+ * Interface for the {@link Hand} model

+ */

 public interface IHand extends IStoneTray<Stone> {

 

 }

diff --git a/src/jrummikub/model/IPlayer.java b/src/jrummikub/model/IPlayer.java
index 17e37e7..3eca44b 100644
--- a/src/jrummikub/model/IPlayer.java
+++ b/src/jrummikub/model/IPlayer.java
@@ -2,12 +2,30 @@ package jrummikub.model;
 
 import java.awt.Color;
 
+/**
+ * Interface for {@link Player} model
+ */
 public interface IPlayer {
 
+	/**
+	 * Get the current hand of the player
+	 * 
+	 * @return the player's hand
+	 */
 	public IHand getHand();
 
+	/**
+	 * Return the player's color
+	 * 
+	 * @return the player's color
+	 */
 	public Color getColor();
 
+	/**
+	 * Return the name of the player
+	 * 
+	 * @return the player's name
+	 */
 	public String getName();
 
 }
\ No newline at end of file
diff --git a/src/jrummikub/model/IStoneTray.java b/src/jrummikub/model/IStoneTray.java
index 11fcbbb..c1ed05d 100644
--- a/src/jrummikub/model/IStoneTray.java
+++ b/src/jrummikub/model/IStoneTray.java
@@ -2,6 +2,12 @@ package jrummikub.model;
 

 import jrummikub.util.Pair;

 

+/**

+ * Interface for the {@link StoneTray} model

+ * 

+ * @param <E>

+ *            Objects held by the IStoneTray

+ */

 public interface IStoneTray<E extends Sizeable> extends

 		Iterable<Pair<E, Position>>, Cloneable {

 

@@ -9,7 +15,7 @@ public interface IStoneTray<E extends Sizeable> extends
 	 * Removes object from tray and returns it

 	 * 

 	 * @param position

-	 *          position of the object that will be removed

+	 *            position of the object that will be removed

 	 * @return the picked up stone

 	 */

 	public E pickUp(Position position);

@@ -18,9 +24,9 @@ public interface IStoneTray<E extends Sizeable> extends
 	 * Adds object to the tray

 	 * 

 	 * @param object

-	 *          object to add to Hand

+	 *            object to add to Hand

 	 * @param position

-	 *          {@link Position} to put the object

+	 *            {@link Position} to put the object

 	 */

 	public void drop(E object, Position position);

 

@@ -28,15 +34,32 @@ public interface IStoneTray<E extends Sizeable> extends
 	 * Returns the position of an object that is already on the tray

 	 * 

 	 * @param object

-	 *          object whose position is requested

+	 *            object whose position is requested

 	 * @return position of the object or null when the object is not on the tray

 	 */

 	public Position getPosition(E object);

 

+	/**

+	 * Tries to pick up (remove) a given object

+	 * 

+	 * @param object

+	 *            object to pick up

+	 * @return true when the object was successfully removed

+	 */

 	public boolean pickUp(E object);

 

+	/**

+	 * Create a clone of the StoneTray

+	 * 

+	 * @return cloned StoneTray

+	 */

 	public IStoneTray<E> clone();

 

+	/**

+	 * Return the number of objects on the tray

+	 * 

+	 * @return number of objects

+	 */

 	public int getSize();

 

 }
\ No newline at end of file
diff --git a/src/jrummikub/model/ITable.java b/src/jrummikub/model/ITable.java
index 1c3fd9f..3b0032f 100644
--- a/src/jrummikub/model/ITable.java
+++ b/src/jrummikub/model/ITable.java
@@ -2,20 +2,32 @@ package jrummikub.model;
 

 import jrummikub.util.Pair;

 

+/**

+ * Interface for the {@link Table} model

+ */

 public interface ITable extends IStoneTray<StoneSet> {

 

 	/**

 	 * Removes {@link Stone} from the Table

 	 * 

 	 * @param stone

-	 *          stone to pick up

+	 *            stone to pick up

 	 * @return the stone sets that are created by taking pickung the the stone

 	 */

 	public Pair<StoneSet, StoneSet> pickUpStone(Stone stone);

 

-	/** Tests the Table for rule conflicts by checking all the {@link StoneSet} */

+	/**

+	 * Tests the Table for rule conflicts by checking all the {@link StoneSet}

+	 * 

+	 * @return whether all sets on the table are valid

+	 */

 	public boolean isValid();

 

+	/**

+	 * Finds the {@link StoneSet} containing the given {@link Stone}

+	 * @param stone stone whose set we're searching

+	 * @return the set containing the stone or null if no set was found

+	 */

 	StoneSet findStoneSet(Stone stone);

 

 }
\ No newline at end of file
diff --git a/src/jrummikub/model/Player.java b/src/jrummikub/model/Player.java
index 623915d..ddd10e4 100644
--- a/src/jrummikub/model/Player.java
+++ b/src/jrummikub/model/Player.java
@@ -9,8 +9,14 @@ public class Player implements IPlayer {
 	private String name;
 	private Color color;
 
-	// private String name;
-
+	/**
+	 * Create a new player with a given name and color
+	 * 
+	 * @param name
+	 *            player name
+	 * @param color
+	 *            player's color
+	 */
 	public Player(String name, Color color) {
 		hand = new Hand();
 		this.name = name;
diff --git a/src/jrummikub/model/StoneColor.java b/src/jrummikub/model/StoneColor.java
index 23f66a0..6b1807b 100644
--- a/src/jrummikub/model/StoneColor.java
+++ b/src/jrummikub/model/StoneColor.java
@@ -2,5 +2,12 @@ package jrummikub.model;
 
 /** Class specifying possible StoneColors */
 public enum StoneColor {
-	BLACK, ORANGE, BLUE, RED
+	/** */
+	BLACK,
+	/** */
+	ORANGE,
+	/** */
+	BLUE,
+	/** */
+	RED
 }
diff --git a/src/jrummikub/model/StoneHeap.java b/src/jrummikub/model/StoneHeap.java
index ae84cef..d9d754f 100644
--- a/src/jrummikub/model/StoneHeap.java
+++ b/src/jrummikub/model/StoneHeap.java
@@ -43,7 +43,7 @@ public class StoneHeap {
 	 * Removes several {@link Stone}s from the heap and returns them
 	 * 
 	 * @param number
-	 *          number of requested Stones
+	 *            number of requested Stones
 	 * @return list of drawn stones
 	 */
 	public List<Stone> drawStones(int number) {
@@ -54,10 +54,21 @@ public class StoneHeap {
 		return drawnStones;
 	}
 
+	/**
+	 * Get the number of stones left
+	 * 
+	 * @return number of stones on the heap
+	 */
 	public int getSize() {
 		return heap.size();
 	}
 
+	/**
+	 * Put stones back on the heap
+	 * 
+	 * @param stones
+	 *            collection of stones to put back
+	 */
 	public void putBack(Collection<Stone> stones) {
 		heap.addAll(stones);
 	}
diff --git a/src/jrummikub/model/StoneSet.java b/src/jrummikub/model/StoneSet.java
index 3723e75..83ce767 100644
--- a/src/jrummikub/model/StoneSet.java
+++ b/src/jrummikub/model/StoneSet.java
@@ -18,16 +18,34 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	static final float HORIZONTAL_BORDER = 0.125f;
 	private List<Stone> stones;
 
+	/**
+	 * Create a new single stone stone set
+	 * 
+	 * @param stone
+	 *            single stone of the set
+	 */
 	public StoneSet(Stone stone) {
 		stones = Collections.singletonList(stone);
 	}
 
+	/**
+	 * Create a stone set from a list of stones
+	 * 
+	 * @param stones
+	 *            list of stones to build a set of
+	 */
 	public StoneSet(List<Stone> stones) {
 		this.stones = new ArrayList<Stone>(stones);
 	}
 
+	/** Validity type of the set */
 	public enum Type {
-		GROUP, RUN, INVALID
+		/** Set is a valid group */
+		GROUP,
+		/** Set is a valid run */
+		RUN,
+		/** Set is invalid */
+		INVALID
 	}
 
 	/**
@@ -40,8 +58,8 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	}
 
 	/**
-	 * 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
 	 * 
 	 * @return GROUP or RUN for valid sets, INVALID otherwise
 	 */
@@ -62,13 +80,15 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 			return GROUP;
 		}
 		// is run
-		if (stones.get(nonJoker1).getColor() == stones.get(nonJoker2).getColor()) {
+		if (stones.get(nonJoker1).getColor() == stones.get(nonJoker2)
+				.getColor()) {
 			return isValidRun(nonJoker1) ? RUN : INVALID;
 
 		}
 		// is group
 		else {
-			return isValidGroup(stones.get(nonJoker1).getValue()) ? GROUP : INVALID;
+			return isValidGroup(stones.get(nonJoker1).getValue()) ? GROUP
+					: INVALID;
 		}
 	}
 
@@ -76,7 +96,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	 * 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)
 	 */
 	private boolean isValidRun(int referencePosition) {
 		StoneColor runColor = stones.get(referencePosition).getColor();
@@ -130,7 +150,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	 * 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) {
@@ -140,7 +160,8 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 			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);
 	}
 
@@ -148,7 +169,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	 * 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) {
@@ -171,7 +192,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
 	 * 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/view/IHandPanel.java b/src/jrummikub/view/IHandPanel.java
index 3436062..3a76780 100644
--- a/src/jrummikub/view/IHandPanel.java
+++ b/src/jrummikub/view/IHandPanel.java
@@ -16,7 +16,19 @@ public interface IHandPanel extends IStonePanel, IClickable {
 	 */
 	public void setStones(Iterable<Pair<Stone, Position>> stones);
 
+	/**
+	 * Set the number of stones that fit on the hand horizontally
+	 * 
+	 * @param width
+	 *            number of stones
+	 */
 	public void setHandWidth(int width);
 
+	/**
+	 * Set the number of stones that fit on the hand vertically
+	 * 
+	 * @param height
+	 *            number of stones
+	 */
 	public void setHandHeight(int height);
 }