summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJannis Harder <harder@informatik.uni-luebeck.de>2011-05-02 04:46:00 +0200
committerJannis Harder <harder@informatik.uni-luebeck.de>2011-05-02 04:46:00 +0200
commit1e7cdb33f5bfce2d3fb174abd778788108557078 (patch)
tree7ef56ce60b813402eabff2bc1aee77ba6142cbd8
parent91b921248f4a74bddd8434bcad65c45fd8486549 (diff)
downloadJRummikub-1e7cdb33f5bfce2d3fb174abd778788108557078.tar
JRummikub-1e7cdb33f5bfce2d3fb174abd778788108557078.zip
More javadocs for the model
git-svn-id: svn://sunsvr01.isp.uni-luebeck.de/swproj13/trunk@64 72836036-5685-4462-b002-a69064685172
-rw-r--r--src/jrummikub/model/Position.java30
-rw-r--r--src/jrummikub/model/Sizeable.java15
-rw-r--r--src/jrummikub/model/Stone.java40
-rw-r--r--src/jrummikub/model/StoneHeap.java13
-rw-r--r--src/jrummikub/model/StoneSet.java21
-rw-r--r--src/jrummikub/model/StoneTray.java22
-rw-r--r--src/jrummikub/model/Table.java2
-rw-r--r--src/jrummikub/util/Pair.java61
8 files changed, 153 insertions, 51 deletions
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<Stone> drawStones(int number) {
List<Stone> drawnStones = new ArrayList<Stone>();
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<Stone>, Sizeable {
this.stones = new ArrayList<Stone>(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<Stone>, Sizeable {
}
return true;
}
+
/**
* Test for rule conflict within the StoneSet, assuming we have a group
*/
@@ -107,6 +112,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
*
* @param position
* Splitting {@link Position}
+ * @return A pair of StoneSets, one for each split part
*/
public Pair<StoneSet, StoneSet> splitAt(int position) {
// Exception in case of wrong index
@@ -124,6 +130,7 @@ public class StoneSet implements Iterable<Stone>, Sizeable {
*
* @param other
* StoneSet to be joined to active StoneSet
+ * @return the combined StoneSet
*/
public StoneSet join(StoneSet other) {
List<Stone> joinedList = new ArrayList<Stone>();
@@ -132,10 +139,22 @@ public class StoneSet implements Iterable<Stone>, 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 <E>
+ * Type of positioned objects (must implement Sizeable)
*/
public class StoneTray<E extends Sizeable> implements
Iterable<Pair<E, Position>> {
@@ -20,12 +23,12 @@ public class StoneTray<E extends Sizeable> 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<E, Position> i : objects) {
@@ -69,8 +72,8 @@ public class StoneTray<E extends Sizeable> implements
for (Pair<E, Position> 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<E extends Sizeable> 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<E extends Sizeable> 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<E, Position> 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<StoneSet> {
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 <T1> the first type of the pair
- * @param <T2> the second type of the pair
+ *
+ * @param <T1>
+ * Type of first component
+ * @param <T2>
+ * Type of second component
*/
public class Pair<T1, T2> {
- 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;
+ }
}