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/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 ++++++++++++++++++++++++++++--------- 10 files changed, 160 insertions(+), 21 deletions(-) (limited to 'src/jrummikub/model') 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) { -- cgit v1.2.3