Checkstyle + Javadoc

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

@@ -3,7 +3,6 @@ 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;
 import java.util.Set;
 import java.util.stream.Collectors;
@@ -41,13 +40,14 @@ public class CardGame {
     private RequireDice requireDice;
 
     /**
-     * Start a new game with the specified stack of cards.
+     * Start a new game with the specified stack of cards. First checks whether the specified stack is correctly
+     * composed: every card should exist exactly as often as {@link Card#requiredAmount required}.
      *
      * @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
+     * @return whether a game was started
      */
-    public boolean start(Deque<Card> cardStack) throws LogicException {
+    public boolean start(Collection<Card> cardStack) throws LogicException {
         if (gameActive()) {
             return false;
         }
@@ -116,7 +116,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);
+            final int bonus = inventory.getItems().stream().mapToInt(Item::fightingBonus).max().orElse(0);
             phase = Phase.SCAVENGE;
             checkLost();
             if (roll + bonus >= minimumNeeded) {
@@ -153,8 +153,10 @@ public class CardGame {
             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);
+        } else {
+            if (!inventory.build(item)) {
+                throw new LogicException("can not build item: missing resources/items");
+            }
             if (item.category() == ItemCategory.ESCAPE) {
                 if (item.diceSizeNeeded().isPresent()) {
                     // player needs to roll dice to escape
@@ -169,8 +171,6 @@ public class CardGame {
             }
             checkLost();
             return "OK";
-        } else {
-            return null;
         }
     }
 
@@ -216,7 +216,7 @@ public class CardGame {
     }
 
     /**
-     * Get the resources available for building.
+     * Get the resources available for building in chronological order.
      *
      * @return resources available
      * @throws LogicException if no game is active
@@ -229,7 +229,7 @@ public class CardGame {
     }
 
     /**
-     * Get the items already built.
+     * Get the items already built in reverse chronological order.
      *
      * @return items owned by the player
      * @throws LogicException if no game is active

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

@@ -1,6 +1,7 @@
 package edu.kit.informatik.cardgame.model;
 
 import java.util.ArrayDeque;
+import java.util.Collection;
 import java.util.Deque;
 import java.util.Optional;
 
@@ -13,10 +14,12 @@ import java.util.Optional;
 public class CardStack {
     /**
      * Copy of the card stack used to initialize the stack.
+     * {@link #reset Resetting} the card stack will restore this stack.
      */
     private final Deque<Card> stack;
     /**
      * Currently active card stack.
+     * {@link #draw Drawing a card} will remove the first element.
      */
     private Deque<Card> activeStack;
 
@@ -24,10 +27,9 @@ public class CardStack {
      * Construct a new card stack with the specified card collection.
      * The first element will be {@link #draw drawn} first.
      *
-     * @param cards card stack
+     * @param cards (ordered) card collection
      */
-    public CardStack(Deque<Card> cards) {
-        // copy stack to avoid modifications
+    public CardStack(Collection<Card> cards) {
         this.stack = new ArrayDeque<>(cards);
         reset();
     }

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

@@ -1,7 +1,12 @@
 package edu.kit.informatik.cardgame.model;
 
-import java.util.*;
-import java.util.stream.Stream;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Deque;
+import java.util.List;
+import java.util.Objects;
 
 /**
  * Player inventory. Contains {@link CardCategory#RESOURCE resources} and {@link Item items}.
@@ -33,19 +38,22 @@ public class Inventory {
     }
 
     /**
+     * Get the resources stored in this inventory in chronological order.
+     *
      * @return resources owned by the player
      */
-    public Deque<Card> getResources() {
+    public Collection<Card> getResources() {
         // have to copy here: caller does not expect an auto-updating collection
         return new ArrayDeque<>(resources);
     }
 
     /**
-     * Clear player resources, keeping a few items in the shack if one is built.
+     * Clear player resources, {@link Item#itemsSecured keeping} a few items
+     * in the {@link Item#SHACK shack} if one is built.
      */
     public void clearResources() {
         // calculate the resources saved by player items
-        final int keepLastResources = this.itemStream().mapToInt(Item::itemsSecured).sum();
+        final int keepLastResources = items.stream().mapToInt(Item::itemsSecured).sum();
         while (resources.size() > keepLastResources) {
             // remove resources that were picked up earlier first
             resources.removeFirst();
@@ -53,14 +61,14 @@ public class Inventory {
     }
 
     /**
-     * Build the specified item.
+     * Attempt to build the specified item.
      *
      * @param item item to build
-     * @throws IllegalArgumentException if there are not enough resources to build the item
+     * @return whether the item could be built
      */
-    public void build(Item item) throws IllegalArgumentException {
+    public boolean build(Item item) {
         if (!canBuild(item)) {
-            throw new IllegalArgumentException("can not build item");
+            return false;
         }
         // remove used resources
         for (final Card resource : item.resourcesNeeded()) {
@@ -68,23 +76,19 @@ public class Inventory {
             resources.removeLastOccurrence(resource);
         }
         items.add(item);
+        return true;
     }
 
     /**
-     * @return items in the inventory
+     * Get the items stored in this inventory in reverse chronological order.
+     *
+     * @return items owned by the player
      */
     public List<Item> getItems() {
         // have to copy here: caller does not expect an auto-updating list
         return new ArrayList<>(items);
     }
 
-    /**
-     * @return stream of items in the inventory
-     */
-    public Stream<Item> itemStream() {
-        return items.stream();
-    }
-
     /**
      * Check whether this inventory contains a specified item.
      *