From 9e75ca37a3e52a7e759b7168cff2045aeba93957 Mon Sep 17 00:00:00 2001 From: Arne Keller Date: Sat, 14 Mar 2020 23:03:47 +0100 Subject: [PATCH] Document code --- .../informatik/cardgame/model/CardGame.java | 53 +++++++++++++++++-- .../kit/informatik/cardgame/model/Item.java | 30 +++++++++-- .../cardgame/model/LogicException.java | 11 ++++ .../informatik/cardgame/ui/CommandLine.java | 6 --- .../cardgame/ui/InvalidInputException.java | 11 ++++ 5 files changed, 97 insertions(+), 14 deletions(-) diff --git a/src/edu/kit/informatik/cardgame/model/CardGame.java b/src/edu/kit/informatik/cardgame/model/CardGame.java index 4923731..2a89a2d 100644 --- a/src/edu/kit/informatik/cardgame/model/CardGame.java +++ b/src/edu/kit/informatik/cardgame/model/CardGame.java @@ -10,13 +10,34 @@ import java.util.Objects; import java.util.Set; import java.util.stream.Collectors; +/** + * Card game. + * + * @author Arne Keller + * @version 1.0 + */ public class CardGame { + /** + * Copy of the card stack used to start the game. + */ private Deque cardStack; + /** + * Currently active card stack. + */ private Deque currentCardStack; + /** + * Resources collected by the player. + */ private final Deque resources = new ArrayDeque<>(); + /** + * Items built by the player. + */ private final List items = new ArrayList<>(); private Integer awaitedDiceSize = null; private Integer minimumDiceRoll = null; + /** + * Current game phase. + */ private Phase phase = null; /** @@ -116,6 +137,9 @@ public class CardGame { } } + /** + * Clear player resources, keeping a few items in the shack if one is built. + */ private void clearResources() { final int keepLastResources = items.stream().mapToInt(Item::itemsSecured).sum(); while (resources.size() > keepLastResources) { @@ -140,6 +164,7 @@ public class CardGame { } else if (canBuild(item)) { // remove used resources for (final Card resource : item.resourcesNeeded()) { + // resources picked up last get used up first resources.removeLastOccurrence(resource); } items.add(item); @@ -168,11 +193,19 @@ public class CardGame { } } + /** + * Check whether the player can build the specified item with the currently available resources and items. + * + * @param item item to build + * @return whether that item can be built + */ private boolean canBuild(Item item) { - if (!items.containsAll(item.itemsNeededToBuild())) { + // check whether item is already built + if (items.contains(item)) { return false; } - if (items.contains(item)) { + // make sure all of the required items are already built + if (!items.containsAll(item.itemsNeededToBuild())) { return false; } final Card[] resourcesNeeded = item.resourcesNeeded(); @@ -187,18 +220,28 @@ public class CardGame { return Arrays.stream(resourcesNeeded).allMatch(Objects::isNull); } + /** + * @return whether the game was ever started + */ private boolean gameStarted() { return phase != null; } + /** + * @return whether the game is currently active + */ private boolean gameActive() { return gameStarted() && phase != Phase.WON && phase != Phase.LOST; } + /** + * Check whether the player lost, updating the game state accordingly. + * + * @see CardGame#gameLost + */ private void checkLost() { - if (phase != Phase.LOST - // can not draw new cards - && currentCardStack != null && currentCardStack.isEmpty() + // can not draw new cards + if (currentCardStack != null && currentCardStack.isEmpty() // can not roll dice && phase != Phase.ENCOUNTER && phase != Phase.ENDEAVOR // can not build item diff --git a/src/edu/kit/informatik/cardgame/model/Item.java b/src/edu/kit/informatik/cardgame/model/Item.java index 8b85bec..fc0054a 100644 --- a/src/edu/kit/informatik/cardgame/model/Item.java +++ b/src/edu/kit/informatik/cardgame/model/Item.java @@ -1,6 +1,5 @@ package edu.kit.informatik.cardgame.model; -import java.util.Arrays; import java.util.Collection; import java.util.Collections; @@ -25,7 +24,7 @@ public enum Item { */ CLUB, /** - * Shack. Can save the last five items. + * Shack. Can save the last five items in case of animal attacks or catastrophic events. */ SHACK, /** @@ -87,7 +86,7 @@ public enum Item { switch (this) { case BALLON: case STEAMBOAT: - return Arrays.asList(FIREPLACE); + return Collections.singletonList(FIREPLACE); default: return Collections.emptyList(); } @@ -109,10 +108,20 @@ public enum Item { } } + /** + * Get the amount of resources this item can save in case of an animal attack or a catastrophic event. + * + * @return amount of resources this item protects + */ public int itemsSecured() { return this == Item.SHACK ? 5 : 0; } + /** + * Check whether this item requires rolling a dice to take effect. + * + * @return whether the player has to roll a dice after building this item + */ public boolean requiresDice() { switch (this) { case HANG_GLIDER: @@ -123,6 +132,11 @@ public enum Item { } } + /** + * Get the size of the dice to roll after building this item. + * + * @return size of the dice to roll, or 0 if not necessary + */ public int diceSizeNeeded() { switch (this) { case HANG_GLIDER: @@ -133,6 +147,11 @@ public enum Item { } } + /** + * Get the minimum dice roll needed to activate this item if it needs a dice roll. + * + * @return minimum dice roll needed to use this item + */ public int minimumDiceRollNeeded() { switch (this) { case HANG_GLIDER: @@ -143,6 +162,11 @@ public enum Item { } } + /** + * Get the category of this item. + * + * @return category of this item + */ public ItemCategory category() { switch (this) { case BALLON: diff --git a/src/edu/kit/informatik/cardgame/model/LogicException.java b/src/edu/kit/informatik/cardgame/model/LogicException.java index 7d1a703..d6d1736 100644 --- a/src/edu/kit/informatik/cardgame/model/LogicException.java +++ b/src/edu/kit/informatik/cardgame/model/LogicException.java @@ -1,6 +1,17 @@ package edu.kit.informatik.cardgame.model; +/** + * Thrown on semantically invalid user input. + * + * @author Arne Keller + * @version 1.0 + */ public class LogicException extends Exception { + /** + * Construct a new {@link LogicException} with the specified message. + * + * @param message error message + */ public LogicException(String message) { super(message); } diff --git a/src/edu/kit/informatik/cardgame/ui/CommandLine.java b/src/edu/kit/informatik/cardgame/ui/CommandLine.java index 8b04ecd..e0ba216 100644 --- a/src/edu/kit/informatik/cardgame/ui/CommandLine.java +++ b/src/edu/kit/informatik/cardgame/ui/CommandLine.java @@ -38,12 +38,6 @@ public final class CommandLine { while (true) { String input = Terminal.readLine(); - if (input.startsWith("startn")) { - // TODO remove - StringJoiner j = new StringJoiner(","); - IntStream.range(0, 64).mapToObj(x -> Terminal.readLine()).forEach(j::add); - input = "start " + j.toString(); - } if (input.startsWith(QUIT)) { if (input.length() != QUIT.length()) { diff --git a/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java b/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java index f0a4aec..18458d6 100644 --- a/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java +++ b/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java @@ -1,6 +1,17 @@ package edu.kit.informatik.cardgame.ui; +/** + * Thrown on syntactically invalid user input. + * + * @author Arne Keller + * @version 1.0 + */ public class InvalidInputException extends Exception { + /** + * Construct a new {@link InvalidInputException} with the specified message. + * + * @param message error message + */ public InvalidInputException(String message) { super(message); }