More javadocs for the model

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

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;
+	}
 
 }