Javadoc + allow various command during game end phase

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

@@ -1,5 +1,12 @@
 package edu.kit.informatik.cardgame.model;
 
+/**
+ * Game card.
+ *
+ * @see CardCategory
+ * @author Arne Keller
+ * @version 1.0
+ */
 public enum Card {
     /**
      * Wood. Basic resource.

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

@@ -1,7 +1,23 @@
 package edu.kit.informatik.cardgame.model;
 
+/**
+ * Card category. 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.
+     */
     RESOURCE,
+    /**
+     * Animal card, can attack player.
+     */
     ANIMAL,
+    /**
+     * Catastrophic card, can not harm player.
+     */
     CATASTROPHE
 }

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

@@ -21,6 +21,7 @@ public class CardGame {
 
     /**
      * Start a new game with the specified stack of cards.
+     *
      * @param cardStack stack of cards to use, where the first element is the first to take
      * @throws LogicException if card stack has wrong distribution of cards
      * @return whether the game could be successfully started
@@ -38,6 +39,13 @@ public class CardGame {
         return true;
     }
 
+    /**
+     * Draw a new card. Will automatically add the card to the players resources, start an encounter or let the
+     * thunderstorm do its work.
+     *
+     * @return the card
+     * @throws LogicException if no card to draw exists or phase is not scavenge
+     */
     public Card draw() throws LogicException {
         if (currentCardStack == null || currentCardStack.isEmpty()) {
             throw new LogicException("no card to draw exists");
@@ -65,6 +73,14 @@ public class CardGame {
         return card;
     }
 
+    /**
+     * Roll a dice with the specified size and result.
+     *
+     * @param size dice size
+     * @param roll dice result
+     * @return result of the throw (survived, lose or win)
+     * @throws LogicException if not expecting dice roll or dice roll is invalid
+     */
     public String rollDice(int size, int roll) throws LogicException {
         if (phase != Phase.ENDEAVOR && phase != Phase.ENCOUNTER) {
             throw new LogicException("not expecting dice roll");
@@ -100,13 +116,20 @@ public class CardGame {
         }
     }
 
-    public void clearResources() {
+    private void clearResources() {
         final int keepLastResources = items.stream().mapToInt(Item::itemsSecured).sum();
         while (resources.size() > keepLastResources) {
             resources.removeFirst();
         }
     }
 
+    /**
+     * Attempt to build the specified item.
+     *
+     * @param item item to build
+     * @return building result (OK or win), or null if item can not be built
+     * @throws LogicException if in wrong phase or item already built
+     */
     public String build(Item item) throws LogicException {
         if (item == null) {
             throw new LogicException("can not build item");
@@ -134,7 +157,7 @@ public class CardGame {
                         return "win";
                     }
                     break;
-                case DEFAULT:
+                default:
                     checkLost();
                     break;
 
@@ -174,39 +197,65 @@ public class CardGame {
 
     private void checkLost() {
         if (phase != Phase.LOST
+                // can not draw new cards
                 && currentCardStack != null && currentCardStack.isEmpty()
+                // can not roll dice
                 && phase != Phase.ENCOUNTER && phase != Phase.ENDEAVOR
-                && !Arrays.stream(Item.values()).anyMatch(this::canBuild)) {
+                // can not build item
+                && Arrays.stream(Item.values()).noneMatch(this::canBuild)) {
             endGame();
             phase = Phase.LOST;
         }
     }
 
+    /**
+     * Check whether the active game is lost. The game is lost if no cards to draw exist and no further actions are
+     * possible.
+     *
+     * @return whether the active game is lost
+     */
     public boolean gameLost() {
         return phase == Phase.LOST;
     }
 
+    /**
+     * Get the resources available for building.
+     *
+     * @return resources available
+     * @throws LogicException if no game is active
+     */
     public Deque<Card> getResources() throws LogicException {
-        if (!gameActive()) {
+        if (!gameStarted()) {
             throw new LogicException("can not get resources: game not started");
         }
         // do not allow caller to modify internal queue
         return new ArrayDeque<>(resources);
     }
 
+    /**
+     * Get the items already built.
+     *
+     * @return items owned by the player
+     * @throws LogicException if no game is active
+     */
     public List<Item> getItems() throws LogicException {
-        if (!gameActive()) {
+        if (!gameStarted()) {
             throw new LogicException("can not get buildings: game not started");
         }
-        // do not allow caller to modify internal list
+        // have to copy here: caller does not expect an auto-updating list
         return new ArrayList<>(items);
     }
 
+    /**
+     * Get the currently buildable items.
+     *
+     * @return set of items currently buildable
+     * @throws LogicException if game not in scavenge phase
+     */
     public Set<Item> getBuildableItems() throws LogicException {
-        if (!gameActive()) {
+        if (!gameStarted()) {
             throw new LogicException("can not get buildable items: game not started");
-        }
+        } else if (phase != Phase.SCAVENGE) {
-        if (phase != Phase.SCAVENGE) {
             throw new LogicException("can not get buildable items: awaiting dice roll");
         }
         return Arrays.stream(Item.values()).filter(this::canBuild).collect(Collectors.toSet());
@@ -216,6 +265,11 @@ public class CardGame {
         currentCardStack = null;
     }
 
+    /**
+     * Reset the game, restoring the original card stack.
+     *
+     * @throws LogicException if game was never started
+     */
     public void reset() throws LogicException {
         if (cardStack == null) {
             throw new LogicException("can not reset a game that is not started!");
@@ -229,11 +283,29 @@ public class CardGame {
         this.phase = Phase.SCAVENGE;
     }
 
+    /**
+     * Game phase.
+     */
     enum Phase {
+        /**
+         * Player can draw cards and build.
+         */
         SCAVENGE,
+        /**
+         * Player has to fight an animal.
+         */
         ENCOUNTER,
+        /**
+         * Player is attempting to escape.
+         */
         ENDEAVOR,
+        /**
+         * Player won.
+         */
         WON,
+        /**
+         * Player lost.
+         */
         LOST
     }
 }

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

@@ -8,6 +8,13 @@ import static edu.kit.informatik.cardgame.model.Card.METAL;
 import static edu.kit.informatik.cardgame.model.Card.PLASTIC;
 import static edu.kit.informatik.cardgame.model.Card.WOOD;
 
+/**
+ * Game item.
+ *
+ * @see ItemCategory
+ * @author Arne Keller
+ * @version 1.0
+ */
 public enum Item {
     /**
      * Axe. Provides an attack bonus of two.

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

@@ -1,6 +1,19 @@
 package edu.kit.informatik.cardgame.model;
 
+/**
+ * Item category. 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.
+     */
     DEFAULT,
+    /**
+     * Item that can be used to escape.
+     */
     ESCAPE;
 }