Checkstyle

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

@@ -26,7 +26,7 @@ public class CardGame {
      */
     private Deque<Card> currentCardStack;
     /**
-     * Resources collected by the player.
+     * Resources collected by the player. Obviously only contains {@link CardCategory#RESOURCE resource} cards.
      */
     private final Deque<Card> resources = new ArrayDeque<>();
     /**
@@ -34,7 +34,7 @@ public class CardGame {
      */
     private final List<Item> items = new ArrayList<>();
     /**
-     * Current game phase.
+     * Current game phase, null if game not yet started.
      */
     private Phase phase;
     /**
@@ -143,8 +143,10 @@ public class CardGame {
      * Clear player resources, keeping a few items in the shack if one is built.
      */
     private void clearResources() {
+        // calculate the resources saved by player items
         final int keepLastResources = items.stream().mapToInt(Item::itemsSecured).sum();
         while (resources.size() > keepLastResources) {
+            // remove resources that were picked up earlier first
             resources.removeFirst();
         }
     }
@@ -173,7 +175,7 @@ public class CardGame {
             switch (item.category()) {
                 case ESCAPE:
                     if (item.diceSizeNeeded().isPresent()) {
-                        // need at least a 4/d6
+                        // player needs to roll dice to escape
                         requireDice = item;
                         phase = Phase.ENDEAVOR;
                     } else {
@@ -209,6 +211,7 @@ public class CardGame {
         if (!items.containsAll(item.itemsNeededToBuild())) {
             return false;
         }
+        // get the needed resources and overwrite entries with null if available
         final Card[] resourcesNeeded = item.resourcesNeeded();
         for (final Card resource : resources) {
             for (int j = 0; j < resourcesNeeded.length; j++) {
@@ -272,7 +275,7 @@ public class CardGame {
         if (!gameStarted()) {
             throw new LogicException("can not get resources: game not started");
         }
-        // do not allow caller to modify internal queue
+        // have to copy here: caller does not expect an auto-updating collection
         return new ArrayDeque<>(resources);
     }
 
@@ -305,12 +308,15 @@ public class CardGame {
         return Arrays.stream(Item.values()).filter(this::canBuild).collect(Collectors.toSet());
     }
 
+    /**
+     * End the current game, deleting the active card stack.
+     */
     private void endGame() {
         currentCardStack = null;
     }
 
     /**
-     * Reset the game, restoring the original card stack.
+     * Reset the game, restoring the {@link #cardStack original card stack}.
      *
      * @throws LogicException if game was never started
      */
@@ -327,19 +333,31 @@ public class CardGame {
     }
 
     /**
-     * Game phase.
+     * Game phase. A game starts in the {@link Phase#SCAVENGE scavenge} phase and ends with the player
+     * {@link Phase#WON winning} or {@link Phase#LOST losing}.
+     *
+     * @author Arne Keller
+     * @version 1.1
      */
     enum Phase {
         /**
-         * Player can draw cards and build.
+         * Player can draw cards and build items.
+         *
+         * @see #draw
+         * @see #build
+         * @see #getBuildableItems
          */
         SCAVENGE,
         /**
          * Player has to fight an animal.
+         *
+         * @see CardCategory#ANIMAL
          */
         ENCOUNTER,
         /**
          * Player is attempting to escape.
+         *
+         * @see ItemCategory#ESCAPE
          */
         ENDEAVOR,
         /**

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

@@ -9,7 +9,16 @@ import edu.kit.informatik.cardgame.ui.InvalidInputException;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Build command. Allows the player to build a single item.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class Build extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "build";
     private static final Pattern BUILD_ARGUMENT = Pattern.compile(" (\\w+)");
 

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

@@ -9,7 +9,16 @@ import edu.kit.informatik.cardgame.ui.InvalidInputException;
 import java.util.Comparator;
 import java.util.Set;
 
+/**
+ * Command used to print a list of items the player can currently {@link Build build}.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class Buildable extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "build?";
 
     @Override

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

@@ -5,7 +5,16 @@ import edu.kit.informatik.cardgame.model.CardGame;
 import edu.kit.informatik.cardgame.model.LogicException;
 import edu.kit.informatik.cardgame.ui.InvalidInputException;
 
+/**
+ * Draw command used to take a card from the stack.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class Draw extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "draw";
 
     @Override

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

@@ -8,7 +8,16 @@ import edu.kit.informatik.cardgame.ui.InvalidInputException;
 
 import java.util.List;
 
+/**
+ * list-buildings command. Prints buildings of the player, starting with the most recently built {@link Item}.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class ListBuildings extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "list-buildings";
 
     @Override

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

@@ -8,12 +8,22 @@ import edu.kit.informatik.cardgame.ui.InvalidInputException;
 
 import java.util.Deque;
 
+/**
+ * list-resources command. Prints all of the {@link Card resources} collected by the player,
+ * starting with the first picked up resource.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class ListResources extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "list-resources";
 
     @Override
     public void apply(CardGame game) throws LogicException {
-        Deque<Card> resources = game.getResources();
+        final Deque<Card> resources = game.getResources();
         if (resources.isEmpty()) {
             Terminal.printLine("EMPTY");
         } else {

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

@@ -5,7 +5,16 @@ import edu.kit.informatik.cardgame.model.CardGame;
 import edu.kit.informatik.cardgame.model.LogicException;
 import edu.kit.informatik.cardgame.ui.InvalidInputException;
 
+/**
+ * Reset command. Removes player progress and restores the original card stack.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class Reset extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "reset";
 
     @Override

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

@@ -8,7 +8,16 @@ import edu.kit.informatik.cardgame.ui.InvalidInputException;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Roll dice command. Passes dice results to the game.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class RollDice extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "rollD";
     private static final Pattern ROLL_DICE_ARGUMENTS = Pattern.compile(NAME + "\\+?(\\d+) \\+?(\\d+)");
 

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

@@ -11,7 +11,16 @@ import java.util.Deque;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Start command. Initializes the game with a card stack.
+ *
+ * @author Arne Keller
+ * @version 1.0
+ */
 public final class Start extends Command {
+    /**
+     * Name of this command.
+     */
     public static final String NAME = "start";
     private static final Pattern START_ARGUMENTS = Pattern.compile("start ((\\w+,){63}(\\w+))");
 
@@ -44,20 +53,4 @@ public final class Start extends Command {
             cards.add(card);
         }
     }
-    /*
-    Dieser Befehl ermöglicht es dem Benutzer, ein neues Spiel zu starten. Dieser Befehl kann nur
-    dann ausgeführt werden, wenn kein Spiel aktiv ist. Zu jedem Zeitpunkt soll höchstens (den Regeln
-    entsprechend) ein Spiel aktiv sein. Zum Programmstart ist kein Spiel aktiv.
-    Es gibt einen Kartenstapel, von dem der Spieler sukzessiv Karten ziehen kann. Hierbei wird die
-    Reihenfolge der 64 Spielkarten im Stapel festgelegt beginnend mit der oberen aufgelegten Karte.
-    Es werden die englischsprachigen Bezeichner der Spielkarten, wie oben angegeben, verwendet.
-    Die sieben Spielkartenbezeichner (wood,metal,plastic,spider,snake,tiger,thunderstorm)
-    werden bei der Eingabe durch exakt ein Komma getrennt.<cards>repräsentiert in dem hier
-    angegebenen Eingabeformat einen Platzhalter.Eingabeformatstart <cards>
-    Ausgabeformat
-    Falls die Parameter den Spezifikationen entsprochen haben und den Regel entsprechend ein neues
-    Kartenspiel gestartet werden konnte, wirdOKausgegeben. Falls ein oder mehrere falsche Parameter
-    dem Befehl übergeben wurden, wird kein Spiel gestartet und nur eine Fehlermeldung beginnendmit
-    Error,ausgegeben
-     */
 }