Javadoc + code style

src/edu/kit/informatik/cardgame/model/Card.java

@@ -3,11 +3,12 @@ package edu.kit.informatik.cardgame.model;
 import java.util.Optional;
 
 /**
- * Game card.
+ * Game card. These can be used to {@link Inventory#build build items},
+ * start a fight with an {@link CardCategory#ANIMAL animal} or clear some of the player's belongings.
  *
  * @see CardCategory
  * @author Arne Keller
- * @version 1.0
+ * @version 1.1
  */
 public enum Card implements RequireDice {
     /**
@@ -35,7 +36,7 @@ public enum Card implements RequireDice {
      */
     TIGER,
     /**
-     * Thunderstorm. Lifts up items and blows them away.
+     * Thunderstorm. Lifts up items and takes them away. Also blows out the fireplace.
      */
     THUNDERSTORM;
 
@@ -77,10 +78,10 @@ public enum Card implements RequireDice {
     }
 
     @Override
-    public Optional<String> activate(CardGame game, int diceSize, int roll) {
+    public Optional<String> activate(CardGame game, int size, int roll) {
         if (!this.diceSizeNeeded().isPresent()) {
             throw new IllegalStateException("can not process dice roll");
-        } else if (this.diceSizeNeeded().get() != diceSize || roll > diceSize || roll < 1) {
+        } else if (this.diceSizeNeeded().get() != size || roll > size || roll < 1) {
             return Optional.empty();
         }
 
@@ -114,8 +115,7 @@ public enum Card implements RequireDice {
         }
     }
 
-    @Override
-    public Optional<Integer> diceSizeNeeded() {
+    private Optional<Integer> diceSizeNeeded() {
         switch (this) {
             case SPIDER:
                 return Optional.of(4);
@@ -128,8 +128,7 @@ public enum Card implements RequireDice {
         }
     }
 
-    @Override
-    public Optional<Integer> minimumDiceRollNeeded() {
+    private Optional<Integer> minimumDiceRollNeeded() {
         switch (this) {
             case SPIDER:
                 return Optional.of(3);

src/edu/kit/informatik/cardgame/model/CardGame.java

@@ -10,8 +10,8 @@ import java.util.stream.Collectors;
 /**
  * Simple card game. Features:
  * <ul>
- *     <li>100% deterministic</li>
- *     <li>64! different card stacks</li>
+ *     <li>100% deterministic (user tells game dice roll results)</li>
+ *     <li>64! different card stacks (including functionally equivalent stacks)</li>
  *     <li>8 buildable {@link Item} items</li>
  *     <li>7 exciting {@link Card card} types</li>
  *     <li>3 dice needed</li>
@@ -100,9 +100,6 @@ public class CardGame {
      * @param requireDice something that requires a dice roll
      */
     public void startDiceRoll(RequireDice requireDice) {
-        if (!requireDice.diceSizeNeeded().isPresent()) {
-            throw new IllegalArgumentException("object does not require dice");
-        }
         this.requireDice = requireDice;
         phase = Phase.AWAITING_DICE_ROLL;
     }

src/edu/kit/informatik/cardgame/model/Item.java

@@ -10,13 +10,18 @@ import static edu.kit.informatik.cardgame.model.Card.WOOD;
 
 /**
  * Game item that can be built by the player. Categorized into several {@link ItemCategory categories}.
+ * An item can give a {@link #fightingBonus fighting bonus} against {@link CardCategory#ANIMAL animals},
+ * {@link #itemsSecured secure items} or let the player {@link ItemCategory#ESCAPE escape}.
+ * Some items require a dice to be rolled (see {@link #activate(CardGame, int, int)}).
  *
+ * @see ItemCategory
  * @author Arne Keller
- * @version 1.0
+ * @version 1.1
  */
 public enum Item implements RequireDice {
     /**
      * Axe. Provides an {@link #fightingBonus attack bonus} of two.
+     * Should be used in preference to the {@link #CLUB club} if available.
      */
     AXE,
     /**
@@ -24,7 +29,8 @@ public enum Item implements RequireDice {
      */
     CLUB,
     /**
-     * Shack. Can {@link #itemsSecured save} the last five items in case of animal attacks or catastrophic events.
+     * Shack. Can {@link #itemsSecured save} the last five items in case of {@link CardCategory#ANIMAL animal} attacks
+     * or {@link CardCategory#CATASTROPHE catastrophic events}.
      */
     SHACK,
     /**
@@ -32,7 +38,7 @@ public enum Item implements RequireDice {
      */
     FIREPLACE,
     /**
-     * Sailing raft. Can be used to attempt an escape.
+     * Sailing raft. Can be used to {@link #activate(CardGame, int, int) attempt} an escape.
      */
     SAILING_RAFT,
     /**
@@ -40,14 +46,14 @@ public enum Item implements RequireDice {
      */
     HANG_GLIDER,
     /**
-     * Steam boat. Can be used to escape.
+     * Steam boat. Can be used to escape. Requires a fireplace to build.
      */
     STEAMBOAT,
     /**
-     * Ballon: making it seem as though a [stranded person] effortlessly becomes airborne,
-     * floats in the air, and lands softly.
+     * A misspelled hot-air balloon. Requires a fireplace to build.
      */
     BALLON;
+    // note: new items require changes in resourcesNeeded, parse and toString
 
     /**
      * Return value indicating success.
@@ -91,10 +97,10 @@ public enum Item implements RequireDice {
     }
 
     @Override
-    public Optional<String> activate(CardGame game, int diceSize, int roll) {
+    public Optional<String> activate(CardGame game, int size, int roll) {
         if (!this.diceSizeNeeded().isPresent()) {
             throw new IllegalStateException("can not process dice roll");
-        } else if (this.diceSizeNeeded().get() != diceSize || roll > diceSize || roll < 1) {
+        } else if (this.diceSizeNeeded().get() != size || roll > size || roll < 1) {
             return Optional.empty();
         }
 
@@ -174,8 +180,7 @@ public enum Item implements RequireDice {
         return this == Item.SHACK ? 5 : 0;
     }
 
-    @Override
-    public Optional<Integer> diceSizeNeeded() {
+    private Optional<Integer> diceSizeNeeded() {
         switch (this) {
             case HANG_GLIDER:
             case SAILING_RAFT:
@@ -185,8 +190,7 @@ public enum Item implements RequireDice {
         }
     }
 
-    @Override
-    public Optional<Integer> minimumDiceRollNeeded() {
+    private Optional<Integer> minimumDiceRollNeeded() {
         switch (this) {
             case HANG_GLIDER:
             case SAILING_RAFT:

src/edu/kit/informatik/cardgame/model/RequireDice.java

@@ -6,30 +6,16 @@ import java.util.Optional;
  * Objects of classes implementing this optionally require a dice to be rolled.
  *
  * @author Arne Keller
- * @version 1.0
+ * @version 2.0
  */
 public interface RequireDice {
     /**
-     * Get the size of the dice needed to activate this object.
-     *
-     * @return dice size needed to use this item (empty if dice not required)
-     */
-    Optional<Integer> diceSizeNeeded();
-
-    /**
-     * Get the minimum dice roll needed to activate this object.
-     *
-     * @return minimum dice roll needed to use this item (empty if dice not required)
-     */
-    Optional<Integer> minimumDiceRollNeeded();
-
-    /**
-     * Activate this object in a game, if the dice roll is good enough.
+     * Activate this object in a game if the dice roll is good enough.
      *
      * @param game card game to use
-     * @param diceSize size of the dice rolled
+     * @param size size of the dice rolled
      * @param roll result of the dice roll
      * @return activation result (empty if dice roll is incorrect)
      */
-    Optional<String> activate(CardGame game, int diceSize, int roll);
+    Optional<String> activate(CardGame game, int size, int roll);
 }