Checkstyle

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

@@ -90,7 +90,7 @@ public enum Card implements RequireDice {
     }
 
     /**
-     * Get the number of cards of this type needed in a stack.
+     * Get the number of cards of this type needed to {@link CardGame#start start} a game.
      *
      * @return amount of cards needed in a card deck
      */

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

@@ -1,23 +1,32 @@
 package edu.kit.informatik.cardgame.model;
 
 /**
- * Card category. Game cards are categorized into three categories depending on their properties.
+ * Card category. {@link Card Game cards} are categorized into three categories depending on their properties.
  *
- * @see Card
  * @author Arne Keller
  * @version 1.0
  */
 public enum CardCategory {
     /**
      * Basic resource card, harmless.
+     *
+     * @see Card#WOOD
+     * @see Card#METAL
+     * @see Card#PLASTIC
      */
     RESOURCE,
     /**
      * Animal card, can attack player.
+     *
+     * @see Card#SNAKE
+     * @see Card#SPIDER
+     * @see Card#TIGER
      */
     ANIMAL,
     /**
      * Catastrophic card, can not harm player.
+     *
+     * @see Card#THUNDERSTORM
      */
     CATASTROPHE
 }

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

@@ -1,6 +1,7 @@
 package edu.kit.informatik.cardgame.model;
 
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.Deque;
 import java.util.List;
@@ -8,7 +9,15 @@ import java.util.Set;
 import java.util.stream.Collectors;
 
 /**
- * Card game.
+ * Card game. Features:
+ * <ul>
+ *     <li>100% deterministic</li>
+ *     <li>64! different card stacks</li>
+ *     <li>8 buildable items</li>
+ *     <li>7 exciting card types</li>
+ *     <li>3 dice needed</li>
+ *     <li>0 skill required</li>
+ * </ul>
  *
  * @author Arne Keller
  * @version 1.0
@@ -27,7 +36,7 @@ public class CardGame {
      */
     private Phase phase;
     /**
-     * Object currently requiring dice roll.
+     * Object currently requiring dice roll, null if not awaiting dice roll.
      */
     private RequireDice requireDice;
 
@@ -61,16 +70,16 @@ public class CardGame {
      */
     public Card draw() throws LogicException {
         if (cardStack == null) {
-            throw new LogicException("no card to draw exists");
+            throw new LogicException("no card stack to draw from exists");
         } else if (phase != Phase.SCAVENGE) {
             throw new LogicException("can only draw cards in scavenge phase");
         }
         final Card card = cardStack.draw().orElseThrow(() -> new LogicException("no card to draw exists"));
         switch (card.category()) {
-            case RESOURCE:
+            case RESOURCE: // simply add resource cards to the player's inventory
                 inventory.addResource(card);
                 break;
-            case ANIMAL:
+            case ANIMAL: // animal cards trigger an encounter
                 requireDice = card;
                 phase = Phase.ENCOUNTER;
                 break;
@@ -97,8 +106,8 @@ public class CardGame {
         if (requireDice == null) {
             throw new LogicException("not expecting dice roll");
         }
-        int sizeNeeded = requireDice.diceSizeNeeded().get();
+        final int sizeNeeded = requireDice.diceSizeNeeded().get();
-        int minimumNeeded = requireDice.minimumDiceRollNeeded().get();
+        final int minimumNeeded = requireDice.minimumDiceRollNeeded().get();
         if (sizeNeeded != size) {
             throw new LogicException("unexpected dice size");
         } else if (roll > sizeNeeded || roll < 1) {
@@ -106,6 +115,7 @@ public class CardGame {
         }
         requireDice = null;
         if (phase == Phase.ENCOUNTER) {
+            // calculate fighting bonus, selecting the most powerful item the player owns
             final int bonus = inventory.itemStream().mapToInt(Item::fightingBonus).max().orElse(0);
             phase = Phase.SCAVENGE;
             checkLost();
@@ -138,15 +148,14 @@ public class CardGame {
      */
     public String build(Item item) throws LogicException {
         if (item == null) {
-            throw new LogicException("can not build item");
+            throw new LogicException("can not build null item");
         } else if (phase != Phase.SCAVENGE) {
             throw new LogicException("can only build in scavenge phase");
         } else if (inventory.contains(item)) {
             throw new LogicException("already built");
         } else if (inventory.canBuild(item)) {
             inventory.build(item);
-            switch (item.category()) {
+            if (item.category() == ItemCategory.ESCAPE) {
-                case ESCAPE:
                 if (item.diceSizeNeeded().isPresent()) {
                     // player needs to roll dice to escape
                     requireDice = item;
@@ -157,12 +166,8 @@ public class CardGame {
                     phase = Phase.WON;
                     return "win";
                 }
-                    break;
-                default:
-                    checkLost();
-                    break;
-
             }
+            checkLost();
             return "OK";
         } else {
             return null;
@@ -216,7 +221,7 @@ public class CardGame {
      * @return resources available
      * @throws LogicException if no game is active
      */
-    public Deque<Card> getResources() throws LogicException {
+    public Collection<Card> getResources() throws LogicException {
         if (!gameStarted()) {
             throw new LogicException("can not get resources: game not started");
         }

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

@@ -4,6 +4,12 @@ import java.util.ArrayDeque;
 import java.util.Deque;
 import java.util.Optional;
 
+/**
+ * Simple card stack that remembers its initial state and can be {@link #reset} on demand.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public class CardStack {
     /**
      * Copy of the card stack used to initialize the stack.
@@ -14,24 +20,44 @@ public class CardStack {
      */
     private Deque<Card> activeStack;
 
+    /**
+     * Construct a new card stack with the specified card collection.
+     * The first element will be {@link #draw drawn} first.
+     *
+     * @param cards card stack
+     */
     public CardStack(Deque<Card> cards) {
         // copy stack to avoid modifications
         this.stack = new ArrayDeque<>(cards);
         reset();
     }
 
+    /**
+     * Draw the next card.
+     *
+     * @return the card (empty if stack is empty)
+     */
     public Optional<Card> draw() {
         return Optional.ofNullable(activeStack.pollFirst());
     }
 
+    /**
+     * Clear the currently active stack.
+     */
     public void clearActiveStack() {
         activeStack.clear();
     }
 
+    /**
+     * Reset the currently active stack.
+     */
     public void reset() {
         activeStack = new ArrayDeque<>(stack);
     }
 
+    /**
+     * @return whether the active card stack is empty
+     */
     public boolean isEmpty() {
         return activeStack.isEmpty();
     }

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

@@ -17,6 +17,9 @@ public class Inventory {
         resources.add(resourceCard);
     }
 
+    /**
+     * @return resources owned by the player
+     */
     public Deque<Card> getResources() {
         // have to copy here: caller does not expect an auto-updating collection
         return new ArrayDeque<>(resources);

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

@@ -9,27 +9,26 @@ import static edu.kit.informatik.cardgame.model.Card.PLASTIC;
 import static edu.kit.informatik.cardgame.model.Card.WOOD;
 
 /**
- * Game item.
+ * Game item that can be built by the player. Categorized into several {@link ItemCategory categories}.
  *
- * @see ItemCategory
  * @author Arne Keller
  * @version 1.0
  */
 public enum Item implements RequireDice {
     /**
-     * Axe. Provides an attack bonus of two.
+     * Axe. Provides an {@link #fightingBonus attack bonus} of two.
      */
     AXE,
     /**
-     * Club. Provides an attack bonus of one.
+     * Club. Provides an {@link #fightingBonus attack bonus} of one.
      */
     CLUB,
     /**
-     * Shack. Can 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 animal attacks or catastrophic events.
      */
     SHACK,
     /**
-     * Fireplace. Required for some advanced items.
+     * Fireplace. {@link #itemsNeededToBuild Required} for some advanced items.
      */
     FIREPLACE,
     /**
@@ -51,7 +50,7 @@ public enum Item implements RequireDice {
     BALLON;
 
     /**
-     * Resources needed to build this item, in no particular order.
+     * Get the resources needed to build this item, in no particular order.
      *
      * @return resources needed to build this item
      */

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

@@ -1,19 +1,28 @@
 package edu.kit.informatik.cardgame.model;
 
 /**
- * Item category. Game items are categorized into two categories: normal items and items used to escape.
+ * Item category. {@link Item Game items} are categorized into two categories: normal items and items used to escape.
  *
- * @see Item
  * @author Arne Keller
  * @version 1.0
  */
 public enum ItemCategory {
     /**
      * Normal item, can not be used to escape.
+     *
+     * @see Item#AXE
+     * @see Item#CLUB
+     * @see Item#SHACK
+     * @see Item#FIREPLACE
      */
     DEFAULT,
     /**
      * Item that can be used to escape.
+     *
+     * @see Item#SAILING_RAFT
+     * @see Item#HANG_GLIDER
+     * @see Item#STEAMBOAT
+     * @see Item#BALLON
      */
     ESCAPE;
 }

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

@@ -1,7 +1,7 @@
 package edu.kit.informatik.cardgame.model;
 
 /**
- * Thrown on semantically invalid user input.
+ * Thrown on semantically invalid user input, usually in the {@link CardGame game}.
  *
  * @author Arne Keller
  * @version 1.0

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

@@ -16,7 +16,6 @@ public interface RequireDice {
      */
     Optional<Integer> diceSizeNeeded();
 
-
     /**
      * Get the minimum dice roll needed to activate this object.
      *

src/edu/kit/informatik/cardgame/ui/InvalidInputException.java

@@ -1,7 +1,9 @@
 package edu.kit.informatik.cardgame.ui;
 
+import edu.kit.informatik.cardgame.ui.command.Command;
+
 /**
- * Thrown on syntactically invalid user input.
+ * Thrown on syntactically invalid user input, usually in the {@link Command#parse command parsers}.
  *
  * @author Arne Keller
  * @version 1.0

src/edu/kit/informatik/cardgame/ui/command/ListBuildings.java

@@ -22,7 +22,7 @@ public final class ListBuildings extends Command {
 
     @Override
     public void apply(CardGame game) throws LogicException {
-        List<Item> items = game.getItems();
+        final List<Item> items = game.getItems();
         if (items.isEmpty()) {
             Terminal.printLine("EMPTY");
         } else {

src/edu/kit/informatik/cardgame/ui/command/ListResources.java

@@ -6,7 +6,7 @@ import edu.kit.informatik.cardgame.model.CardGame;
 import edu.kit.informatik.cardgame.model.LogicException;
 import edu.kit.informatik.cardgame.ui.InvalidInputException;
 
-import java.util.Deque;
+import java.util.Collection;
 
 /**
  * list-resources command. Prints all of the {@link Card resources} collected by the player,
@@ -23,7 +23,7 @@ public final class ListResources extends Command {
 
     @Override
     public void apply(CardGame game) throws LogicException {
-        final Deque<Card> resources = game.getResources();
+        final Collection<Card> resources = game.getResources();
         if (resources.isEmpty()) {
             Terminal.printLine("EMPTY");
         } else {