From 1e7cdb33f5bfce2d3fb174abd778788108557078 Mon Sep 17 00:00:00 2001 From: Jannis Harder Date: Mon, 2 May 2011 04:46:00 +0200 Subject: More javadocs for the model git-svn-id: svn://sunsvr01.isp.uni-luebeck.de/swproj13/trunk@64 72836036-5685-4462-b002-a69064685172 --- src/jrummikub/model/Position.java | 30 +++++++++++++++---- src/jrummikub/model/Sizeable.java | 15 +++++++++- src/jrummikub/model/Stone.java | 40 +++++++++++++++++++++---- src/jrummikub/model/StoneHeap.java | 13 +++++--- src/jrummikub/model/StoneSet.java | 21 ++++++++++++- src/jrummikub/model/StoneTray.java | 22 +++++++++----- src/jrummikub/model/Table.java | 2 +- src/jrummikub/util/Pair.java | 61 ++++++++++++++++++++++---------------- 8 files changed, 153 insertions(+), 51 deletions(-) (limited to 'src/jrummikub') diff --git a/src/jrummikub/model/Position.java b/src/jrummikub/model/Position.java index f7e53e6..35cf45e 100644 --- a/src/jrummikub/model/Position.java +++ b/src/jrummikub/model/Position.java @@ -9,22 +9,40 @@ public class Position { private float x; private float y; + /** + * Create a new position by specifying the coordinates + * + * @param x + * x coordinate + * @param y + * y coordinate + */ public Position(float x, float y) { - this.x = x; + this.x = x; this.y = y; } + /** + * Get the x coordinate of the position + * + * @return x coordinate + */ public float getX() { - return x; - } + return x; + } + /** + * Get the y coordinate of the position + * + * @return y coordinate + */ public float getY() { return y; } - + @Override - public String toString(){ - return "Position[x="+x+",y="+y+"]"; + public String toString() { + return "Position[x=" + x + ",y=" + y + "]"; } } diff --git a/src/jrummikub/model/Sizeable.java b/src/jrummikub/model/Sizeable.java index fa022cc..3c78e5c 100644 --- a/src/jrummikub/model/Sizeable.java +++ b/src/jrummikub/model/Sizeable.java @@ -1,9 +1,22 @@ package jrummikub.model; /** - * Objects that have a size + * Objects that have a size. This interface has to be implemented for objects + * placed on a @{link StoneTray} to make detection of overlapping objects + * possible. */ public interface Sizeable { + /** + * Get the width of the object + * + * @return object width + */ public float getWidth(); + + /** + * Get the height of the object + * + * @return object height + */ public float getHeight(); } diff --git a/src/jrummikub/model/Stone.java b/src/jrummikub/model/Stone.java index 9721602..6c2fd54 100644 --- a/src/jrummikub/model/Stone.java +++ b/src/jrummikub/model/Stone.java @@ -7,37 +7,67 @@ public class Stone implements Sizeable { private StoneColor color; private final boolean joker; - public Stone(StoneColor color) { + /** + * Creates a joker of the given color. The color is only used for + * displaying. + * + * @param color + * joker color + */ + public Stone(StoneColor color) { this.value = 0; this.color = color; this.joker = true; } - - public Stone(int value, StoneColor color) { + + /** + * Creates a normal stone of a given color and value + * + * @param value + * stone value + * @param color + * stone color + */ + public Stone(int value, StoneColor color) { this.value = value; this.color = color; this.joker = false; } - + + @Deprecated public Stone(int value, StoneColor color, boolean joker) { this.value = value; this.color = color; this.joker = joker; } + /** + * Returns the color of the stone. + * + * @return stone color + */ public StoneColor getColor() { return color; } + /** + * Returns whether the stone is a joker or not. + * + * @return true when the stone is a joker + */ public boolean isJoker() { return joker; } + /** + * Returns the value of the stone. Don't use this value for jokers. + * + * @return stone value + */ public int getValue() { return value; } - @Override public float getWidth() { return 1; diff --git a/src/jrummikub/model/StoneHeap.java b/src/jrummikub/model/StoneHeap.java index d921c6b..e74844e 100644 --- a/src/jrummikub/model/StoneHeap.java +++ b/src/jrummikub/model/StoneHeap.java @@ -20,16 +20,20 @@ public class StoneHeap { for (int i = 1; i <= 13; i++) { for (int j = 0; j < 2; j++) { for (StoneColor c : EnumSet.allOf(StoneColor.class)) { - heap.add(new Stone(i, c, false)); + heap.add(new Stone(i, c)); } } } // Joker - heap.add(new Stone(0, StoneColor.BLACK, true)); - heap.add(new Stone(0, StoneColor.RED, true)); + heap.add(new Stone(StoneColor.BLACK)); + heap.add(new Stone(StoneColor.RED)); } - /** Removes random {@link Stone} from the heap and returns it */ + /** + * Removes random {@link Stone} from the heap and returns it + * + * @return the drawn stone + */ public Stone drawStone() { return heap.remove(generator.nextInt(heap.size())); } @@ -39,6 +43,7 @@ public class StoneHeap { * * @param number * number of requested Stones + * @return list of drawn stones */ public List drawStones(int number) { List drawnStones = new ArrayList(); diff --git a/src/jrummikub/model/StoneSet.java b/src/jrummikub/model/StoneSet.java index 465692a..d0615fc 100644 --- a/src/jrummikub/model/StoneSet.java +++ b/src/jrummikub/model/StoneSet.java @@ -24,7 +24,11 @@ public class StoneSet implements Iterable, Sizeable { this.stones = new ArrayList(stones); } - /** Test for rule conflict within the StoneSet */ + /** + * Test for rule conflict within the StoneSet + * + * @return true when the set is valid according to the rules + */ public boolean isValid() { if (stones.size() < 3) { return false; @@ -80,6 +84,7 @@ public class StoneSet implements Iterable, Sizeable { } return true; } + /** * Test for rule conflict within the StoneSet, assuming we have a group */ @@ -107,6 +112,7 @@ public class StoneSet implements Iterable, Sizeable { * * @param position * Splitting {@link Position} + * @return A pair of StoneSets, one for each split part */ public Pair splitAt(int position) { // Exception in case of wrong index @@ -124,6 +130,7 @@ public class StoneSet implements Iterable, Sizeable { * * @param other * StoneSet to be joined to active StoneSet + * @return the combined StoneSet */ public StoneSet join(StoneSet other) { List joinedList = new ArrayList(); @@ -132,10 +139,22 @@ public class StoneSet implements Iterable, Sizeable { return new StoneSet(joinedList); } + /** + * Returns the number of stones in the set. + * + * @return number of stones + */ public int size() { return stones.size(); } + /** + * Returns the i-th stone of the set (starting with 0) + * + * @param i + * number of the stone to return + * @return the i-th stone + */ public Stone get(int i) { return stones.get(i); } diff --git a/src/jrummikub/model/StoneTray.java b/src/jrummikub/model/StoneTray.java index 0d48bf5..07719cf 100644 --- a/src/jrummikub/model/StoneTray.java +++ b/src/jrummikub/model/StoneTray.java @@ -9,6 +9,9 @@ import jrummikub.util.Pair; /** * A StoneTray is a collection of positioned objects (for example {@link Stone}s * or {@link StoneSet}s. + * + * @param + * Type of positioned objects (must implement Sizeable) */ public class StoneTray implements Iterable> { @@ -20,12 +23,12 @@ public class StoneTray implements LEFT, RIGHT, TOP, BOTTOM; } - /** * Removes object from tray and returns it * * @param position * position of the object that will be removed + * @return the picked up stone */ public E pickUp(Position position) { for (Pair i : objects) { @@ -69,8 +72,8 @@ public class StoneTray implements for (Pair i : objects) { Position currentPosition = i.getSecond(); E currentObject = i.getFirst(); - if (!objectsOverlap(object, position, - currentObject, currentPosition)) { + if (!objectsOverlap(object, position, currentObject, + currentPosition)) { continue; } // Object would be placed inside the current object @@ -113,12 +116,10 @@ public class StoneTray implements if (position1.getY() + object1.getHeight() <= position2.getY()) { return false; } - if (position1.getX() >= position2.getX() - + object2.getWidth()) { + if (position1.getX() >= position2.getX() + object2.getWidth()) { return false; } - if (position1.getY() >= position2.getY() - + object2.getHeight()) { + if (position1.getY() >= position2.getY() + object2.getHeight()) { return false; } return true; @@ -169,6 +170,13 @@ public class StoneTray implements return overlapX > overlapY; } + /** + * Returns the position of an object that is already on the tray + * + * @param object + * 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) { for (Pair i : objects) { if (object.equals(i.getFirst())) { diff --git a/src/jrummikub/model/Table.java b/src/jrummikub/model/Table.java index 591b04e..6ae0c4b 100644 --- a/src/jrummikub/model/Table.java +++ b/src/jrummikub/model/Table.java @@ -31,7 +31,7 @@ public class Table extends StoneTray { return null; } - /** Tests the Table for rule conflicts by checking all the {@link StoneSets} */ + /** Tests the Table for rule conflicts by checking all the {@link StoneSet} */ public boolean isValid() { // TODO implement this method return false; diff --git a/src/jrummikub/util/Pair.java b/src/jrummikub/util/Pair.java index 76eea4f..7083bc3 100644 --- a/src/jrummikub/util/Pair.java +++ b/src/jrummikub/util/Pair.java @@ -2,36 +2,45 @@ package jrummikub.util; /** * A pair of objects - * @param the first type of the pair - * @param the second type of the pair + * + * @param + * Type of first component + * @param + * Type of second component */ public class Pair { - private final T1 first; - private final T2 second; + private final T1 first; + private final T2 second; - /** - * Create a new pair - * - * @param first the first value - * @param second the second value - */ - public Pair(T1 first, T2 second) { - this.first = first; - this.second = second; - } + /** + * Create a new pair from two values + * + * @param first + * the first pair component + * @param second + * the second pair component + */ + public Pair(T1 first, T2 second) { + this.first = first; + this.second = second; + } - /** - * @return the first value - */ - public T1 getFirst() { - return first; - } + /** + * Extract the first component of a pair + * + * @return the first pair component + */ + public T1 getFirst() { + return first; + } - /** - * @return the first value - */ - public T2 getSecond() { - return second; - } + /** + * Extract the second component of a pair + * + * @return the second pair component + */ + public T2 getSecond() { + return second; + } } -- cgit v1.2.3