Merge pull request #388 from CS2103-AY1819S2-W14-3/esther-battle-v1.4

Update javadocs for Battle component

src/main/java/seedu/address/logic/battle/AttackDefeatedEnemy.java

@@ -13,10 +13,10 @@ public AttackDefeatedEnemy(Player attacker, Player target, Coordinates cell, Str
         super(attacker, target, cell);
         this.destroyedShipName = destroyedShipName;
 
-        succeeds = true;
-        hitsShip = true;
-        destroysShip = true;
-        winsGame = true;
+        succeeds(true);
+        hitsShip(true);
+        destroysShip(true);
+        winsGame(true);
     }
 
     @Override

src/main/java/seedu/address/logic/battle/AttackDestroyedShip.java

@@ -13,10 +13,10 @@ public AttackDestroyedShip(Player attacker, Player target, Coordinates cell, Str
         super(attacker, target, cell);
         this.destroyedShipName = destroyedShipName;
 
-        succeeds = true;
-        hitsShip = true;
-        destroysShip = true;
-        winsGame = false;
+        succeeds(true);
+        hitsShip(true);
+        destroysShip(true);
+        winsGame(false);
     }
 
     @Override

src/main/java/seedu/address/logic/battle/AttackFailed.java

@@ -13,15 +13,12 @@ public AttackFailed(Player attacker, Player target, Coordinates cell, String rea
         super(attacker, target, cell);
         this.reason = reason;
 
-        succeeds = false;
-        hitsShip = false;
-        destroysShip = false;
-        winsGame = false;
+        succeeds(false);
+        hitsShip(false);
+        destroysShip(false);
+        winsGame(false);
     }
 
-    /**
-     * Returns a String representation of the attack result.
-     */
     @Override
     public String resultString() {
         return String.format("failed: %s", reason);

src/main/java/seedu/address/logic/battle/AttackHit.java

@@ -10,10 +10,10 @@ public class AttackHit extends AttackResult {
     public AttackHit(Player attacker, Player target, Coordinates cell) {
         super(attacker, target, cell);
 
-        succeeds = true;
-        hitsShip = true;
-        destroysShip = false;
-        winsGame = false;
+        succeeds(true);
+        hitsShip(true);
+        destroysShip(false);
+        winsGame(false);
     }
 
     @Override

src/main/java/seedu/address/logic/battle/AttackMissed.java

@@ -10,10 +10,10 @@ public class AttackMissed extends AttackResult {
     public AttackMissed(Player attacker, Player target, Coordinates cell) {
         super(attacker, target, cell);
 
-        succeeds = true;
-        hitsShip = false;
-        destroysShip = false;
-        winsGame = false;
+        succeeds(true);
+        hitsShip(false);
+        destroysShip(false);
+        winsGame(false);
     }
 
     @Override

src/main/java/seedu/address/logic/battle/AttackResult.java

@@ -6,18 +6,26 @@
 
 /**
  * An AttackResult represents the end result of an attack.
+ * <br>
+ * Attributes of an {@code AttackResult} should be accessed by the getter methods, e.g. {@code isSuccessful}.
+ * Subclasses of {@code AttackResult} should call the setter methods in their constructor.
+ * For example, see the code of {@link AttackMissed}.
  */
 public abstract class AttackResult {
+    /**
+     * Format string for printing the details of an attack.
+     */
     public static final String ATTACK = "Attack by player %s on cell %s of player %s ";
 
-    protected Player attacker;
-    protected Player target;
-    protected Coordinates coords;
     // refactoring the way of handling attributes to enable a declarative style
-    protected boolean succeeds;
-    protected boolean hitsShip;
-    protected boolean destroysShip;
-    protected boolean winsGame;
+    private boolean succeeds;
+    private boolean hitsShip;
+    private boolean destroysShip;
+    private boolean winsGame;
+
+    private Player attacker;
+    private Player target;
+    private Coordinates coords;
 
     protected AttackResult(Player attacker, Player target, Coordinates coords) {
         this.attacker = attacker;
@@ -26,61 +34,102 @@ protected AttackResult(Player attacker, Player target, Coordinates coords) {
     }
 
     /**
-     * Checks if this AttackResult actually succeeds in hitting a cell
+     * Sets whether this AttackResult represents the result of a successful attack.
+     * @param succeeds whether the attack was a success
+     */
+    protected void succeeds(boolean succeeds) {
+        this.succeeds = succeeds;
+    }
+
+    /**
+     * Sets whether this AttackResult represents the result of an attack that hit a ship.
+     * @param hitsShip whether the attack hit an enemy ship
+     */
+    protected void hitsShip(boolean hitsShip) {
+        this.hitsShip = hitsShip;
+    }
+
+    /**
+     * Sets whether this AttackResult represents the result of an attack that destroyed an enemy ship
+     * @param destroysShip whether the attack destroyed an enemy ship
+     */
+    protected void destroysShip(boolean destroysShip) {
+        this.destroysShip = destroysShip;
+    }
+
+    /**
+     * Sets whether this AttackResult represents the result of an attack that
+     * caused the attacker to win.
+     * @param winsGame whether the attack was a winning attack
+     */
+    protected void winsGame(boolean winsGame) {
+        this.winsGame = winsGame;
+    }
+
+    /**
+     * Checks if this AttackResult is of an attack which succeeded
+     * @return {@code true} if the attack was successful (managed to hit a cell), {@code false otherwise}
      */
     public final boolean isSuccessful() {
         return succeeds;
     }
 
     /**
-     * Checks if this AttackResult is a hit or a miss
+     * Checks if this AttackResult is of an attack which hit or miss
      * (guess they never miss, huh?)
+     * @return {@code true} if the attack damaged a ship, {@code false otherwise}
      */
     public final boolean isHit() {
         return hitsShip;
     }
 
     /**
-     * Checks if this AttackResult is of the destruction of a ship
+     * Checks if this AttackResult is of an attack which destroyed a ship
+     * @return {@code true} if the attack destroyed a ship, {@code false otherwise}
      */
     public final boolean isDestroy() {
         return destroysShip;
     }
 
     /**
      * Checks if this AttackResult is of a winning attack
+     * @return {@code true} if the attack caused the attacker to win the game, {@code false otherwise}
      */
     public final boolean isWin() {
         return winsGame;
     }
 
+    /**
+     * Gets the {@code Status} of the cell which was hit, if any.
+     * @return the {@code Status} of the hit cell
+     * @see Status
+     */
     public Status getStatus() {
         return attacker.getMapGrid().getCellStatus(coords);
     }
 
     /**
-     * Returns a short form of the attack result, without the front portion
-     * "Player __ attacked __ __"
+     * Returns a concise String representation of the attack result.
      */
     public abstract String resultString();
 
     /**
-     * Returns a String representation of the attack result.
+     * Returns a verbose String representation of the attack result.
      */
     @Override
     public String toString() {
         return String.format(ATTACK, attacker.getName(), coords, target.getName()) + resultString();
     }
 
     /**
-     * Formats the string as if the user attacked.
+     * Formats this AttackResult as if a human user was the attacker.
      */
     public String formatAsUserAttack() {
         return String.format("You attacked %s and ", coords) + resultString();
     }
 
     /**
-     * Formats the string as if the enemy attacked.
+     * Formats this AttackResult as if a computer enemy was the attacker.
      */
     public String formatAsEnemyAttack() {
         return String.format("Enemy attacked %s and ", coords) + resultString();

src/main/java/seedu/address/logic/battle/Battle.java

@@ -8,33 +8,37 @@
 
 /**
  * API of the Battle component
- *
+ * <br>
  * The Battle component manages the battle between a human player and an enemy player.
  */
 public interface Battle {
     /**
-     * Begins the game and gives all players a Map View.
+     * Begins the battle.
      */
-    public void beginGame();
+    void beginGame();
 
     /**
-     * Handles the human player attacking another player.
+     * Handles the human player attacking the computer enemy.
+     * @param coord The coordinate that the human attacks
      * @return Result of the player attack.
      */
-    public AttackResult humanPerformAttack(Coordinates coord);
+    AttackResult humanPerformAttack(Coordinates coord);
 
     /**
-     * Ends the player turn and causes the AI to make its attack.
+     * Causes the AI to make its attack(s).
+     * @return a list of the results of the computer's attacks, in order
      */
-    public List<AttackResult> takeComputerTurns();
+    List<AttackResult> takeComputerTurns();
 
     /**
      * Returns the human player.
+     * @return the human player
      */
     Player getHumanPlayer();
 
     /**
-     * Returns the computer player.
+     * Returns the computer enemy player.
+     * @return the enemy player
      */
     Enemy getEnemyPlayer();
 }

src/main/java/seedu/address/logic/battle/state/BattleState.java

@@ -21,15 +21,15 @@ public enum BattleState {
      */
     PLAYER_ATTACK("You are currently planning attack..."),
     /**
-     * The human player is currently planning their attack.
+     * The enemy player is currently planning their attack.
      */
     ENEMY_ATTACK("Enemy is currently planning attack..."),
     /**
      * The human player has won the game.
      */
     PLAYER_WIN("You have won!"),
     /**
-     * The human player has lost the game..
+     * The enemy player has won the game.
      */
     ENEMY_WIN("You have lost...");
     /**
@@ -42,7 +42,16 @@ public enum BattleState {
         this.description = description;
     }
 
+    /**
+     * Gets a human-readable description of the battle state.
+     * @return a human-readable description of the battle state
+     */
     public String getDescription() {
         return description;
     }
+
+    @Override
+    public String toString() {
+        return description;
+    }
 }