From 3b49b2053e9f9d26b73db0ffc8380a60706ee095 Mon Sep 17 00:00:00 2001 From: Jannis Harder Date: Tue, 10 May 2011 03:54:48 +0200 Subject: Added all missing comments git-svn-id: svn://sunsvr01.isp.uni-luebeck.de/swproj13/trunk@213 72836036-5685-4462-b002-a69064685172 --- src/jrummikub/control/ITurnTimer.java | 14 +++++++++++ src/jrummikub/control/RoundControl.java | 14 +++++++++++ src/jrummikub/control/TurnControl.java | 22 ++++++++++++++++++ src/jrummikub/control/TurnTimer.java | 12 +++++++--- src/jrummikub/model/GameState.java | 4 +++- src/jrummikub/model/IGameState.java | 36 +++++++++++++++++++++++++++++ src/jrummikub/model/IHand.java | 3 +++ src/jrummikub/model/IPlayer.java | 18 +++++++++++++++ src/jrummikub/model/IStoneTray.java | 31 +++++++++++++++++++++---- src/jrummikub/model/ITable.java | 16 +++++++++++-- src/jrummikub/model/Player.java | 10 ++++++-- src/jrummikub/model/StoneColor.java | 9 +++++++- src/jrummikub/model/StoneHeap.java | 13 ++++++++++- src/jrummikub/model/StoneSet.java | 41 +++++++++++++++++++++++++-------- src/jrummikub/view/IHandPanel.java | 12 ++++++++++ 15 files changed, 231 insertions(+), 24 deletions(-) (limited to 'src') 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 connections = new ArrayList(); + /** + * 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 connections = new ArrayList(); + /** + * 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()); } + /** + * 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(); @@ -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 { } 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 + * Objects held by the IStoneTray + */ public interface IStoneTray extends Iterable>, Cloneable { @@ -9,7 +15,7 @@ public interface IStoneTray 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 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 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 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 { /** * 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 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 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 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, Sizeable { static final float HORIZONTAL_BORDER = 0.125f; private List 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 stones) { this.stones = new ArrayList(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, 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, 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, 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, Sizeable { * Stone Sets * * @param position - * Splitting {@link Position} + * Splitting {@link Position} * @return A pair of StoneSets, one for each split part */ public Pair splitAt(int position) { @@ -140,7 +160,8 @@ public class StoneSet implements Iterable, Sizeable { return new Pair(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(firstSet, secondSet); } @@ -148,7 +169,7 @@ public class StoneSet implements Iterable, 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, 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> 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); } -- cgit v1.2.3