Merge pull request #172 from ken-ruster/doc-update

Update documentation and fix comments by TA

docs/diagrams/ChessMasterSequence.puml

@@ -15,27 +15,27 @@ activate storage
 storage --> chessMaster : prevBoard:ChessBoard
 deactivate storage
 
-alt [. Previous board exists]
+alt Previous board exists
 
     chessMaster -> ui : shouldStartNewGame()
     activate ui
     user -> ui : "yes/no"
     ui --> chessMaster : :boolean
     deactivate ui
 
-    opt [startNewGame]
+    opt startNewGame
 
-        chessMaster -> ui : chooseColor
+        chessMaster -> ui : chooseColor()
         activate ui
         user -> ui : "black/white"
         ui --> chessMaster : playerColor:Color
         deactivate ui
 
     end
 
-else [. No previous board]
+else No previous board
 
-    chessMaster -> ui : chooseColor
+    chessMaster -> ui : chooseColor()
     activate ui
     user -> ui : "black/white"
     ui --> chessMaster : playerColor:Color

docs/diagrams/GameSequence.puml

@@ -10,22 +10,22 @@ participant ":Storage" as storage #PaleTurquoise
 
 activate game #AliceBlue
 
-loop [hasGameEnded]
+loop hasGameEnded
 
-    game -> ui : getUserCommand()
+    game -> ui : getUserInput()
     activate ui
-    user -> ui : "a2 a3"
-    ui --> game : :String
+    user -> ui : input
+    ui --> game : userInputString :String
     deactivate ui
 
-    game -> parser : parseCommand("a2 a3")
+    game -> parser : parseCommand(userInputString)
     activate parser
     parser --> game : :Command
     deactivate parser
 
-    opt [isMoveCommand]
+    opt isMoveCommand
 
-        game -> parser : parseMove("a2 a3")
+        game -> parser : parseMove(input)
         activate parser
         parser --> game : humanMove:Move
         deactivate parser

docs/diagrams/MiniMaxSequence.puml

@@ -14,7 +14,7 @@ user -> MM : getBestMove()
 
 MM -> MM : mostPoints()
 
-loop ["depth < maxDepth"]
+loop "depth < maxDepth"
 
     MM -> CB : getBoard()
     deactivate MM
@@ -49,7 +49,7 @@ loop ["depth < maxDepth"]
     deactivate CB
     CB -> MM : Continue loop
     deactivate CB
-    loop ["depth < maxDepth"]
+    loop "depth < maxDepth"
         activate MM
         MM -> MM : Recursively call mostPoints() while incrementing depth
         MM --> MM : bestTuple

docs/diagrams/OverallArchitecture.puml

@@ -21,4 +21,8 @@ game -u-> ui
 
 storage .up.> board
 
+game .right.> parser
+storage .> parser
+board .> parser
+
 @enduml

docs/diagrams/ParseCommandSequence.puml

@@ -5,43 +5,43 @@ participant ":Game" as Game
 participant ":Parser" as Parser
 participant ":Command" as Command
 participant ":CommandResult" as CommandResult
-participant "coord:Coordinate" as Coordinate
-participant "board:ChessBoard" as ChessBoard
-participant "promoteFrom: ChessPiece" as ChessPiece
+participant "coord :Coordinate" as Coordinate
+participant "board :ChessBoard" as ChessBoard
+participant "promoteFrom :ChessPiece" as ChessPiece
 
-Game -> Parser: parseCommand
+Game -> Parser: parseCommand()
 activate Parser
 create Command
 Parser -> Command ++
-Command --> Parser --: Command
-Game <-- Parser --: Command
+Command --> Parser --: :Command
+Game <-- Parser --: :Command
 
 Game -> Command ++: execute
 alt MoveCommand
-    Command -> Parser ++: parseMove
-    Parser --> Command --: Move
+    Command -> Parser ++: parseMove()
+    Parser --> Command --: :Move
 else ShowMoveCommand
     create Coordinate
-    Command -> Coordinate ++: parseAlgebraicCoor
-    Coordinate --> Command --: coord
-    Command -> ChessBoard ++: showAvailableCoordinates
+    Command -> Coordinate ++: parseAlgebraicCoor()
+    Coordinate --> Command --: coord :Coordinate
+    Command -> ChessBoard ++: showAvailableCoordinates()
     ChessBoard --
-    Command -> ChessBoard ++: getAvailableCoordinatesString
-    ChessBoard --> Command --: String
+    Command -> ChessBoard ++: getAvailableCoordinatesString()
+    ChessBoard --> Command --: :String
     destroy Coordinate
 end
 Command -> CommandResult**
 activate CommandResult
 CommandResult --> Command--
-Game <-- Command --: CommandResult
+Game <-- Command --: :CommandResult
 
 opt canPromote
-Game -> Parser ++: parsePromote
-Parser -> ChessPiece ++: getColour
-ChessPiece --> Parser --: Color
-Parser -> ChessPiece ++: getPosition
-ChessPiece --> Parser --: Coordinate
-Game <-- Parser --: ChessPiece
+Game -> Parser ++: parsePromote()
+Parser -> ChessPiece ++: getColour()
+ChessPiece --> Parser --: :Color
+Parser -> ChessPiece ++: getPosition()
+ChessPiece --> Parser --: :Coordinate
+Game <-- Parser --: :ChessPiece
 end
 
 

docs/diagrams/ParserCommandDiagram.puml

@@ -1,5 +1,7 @@
 @startuml
 'https://plantuml.com/class-diagram
+hide circle
+skinparam classAttributeIconSize 0
 package command{
     abstract class Command {
     +execute()

docs/diagrams/StorageClass.puml

@@ -1,4 +1,6 @@
 @startuml
+hide circle
+skinparam classAttributeIconSize 0
 class Storage {
   - filePathString: String
 

docs/team/ken-ruster.md

@@ -0,0 +1,33 @@
+# Project: ChessMaster v2.1
+
+ChessMaster is a desktop application targeted at chess beginners 
+for them to be able to learn chess on the go. Users interact with it using the CLI,
+and its simplicity means that even low-end machines should be able to run it.
+
+Given below are my contributions to the project:
+- **New Feature**: Checking for the validity of the save file.
+  - Justification: To make sure that the move history and current board state match. Prevents the user from making 
+    illegal moves via changing the save file.
+  - Highlights: The implementation required a revision to the structure used to save the file. 
+    It required implementing a `PromoteMove` class as well to store possible promotions.
+- **New feature**: Displaying valid moves for a piece
+  - Justification: New players may not be able to tell how certain pieces move.
+    This feature assists them in learning how the game works in an accessible manner.
+  - Highlights: Doing this posed a challenge on how best to display the different possibilities for moves
+    , eg capturable pieces, current position of the piece and empty tiles it could move to.
+    Some difficulty arose while learning to go formatting for text highlighting which works
+    for both Windows and Mac.
+- **New feature**: Handling promotion
+  - Justification: Promotion is an essential mechanic of Chess.
+  - Highlights: Handling promotion required extensive modification of several classes relating to game function.
+- **Project Management**:
+  - Managed bug testing and checkStyle adherence for releases `1.0` and `2.0`
+- **Enhancements to existing features**:
+  - Added additional tests for existing features
+- **Documentation**:
+  - Developer Guide:
+    - Added documentation for the `Parser` and `Command` subclasses
+  - User Guide:
+    - Added documentation for the Features section
+    - Updated the Command Summary
+    - Added the FAQ section

src/main/java/chessmaster/game/ChessBoard.java

@@ -420,7 +420,12 @@ public ChessBoard clone() {
     }
 
 
-
+    /**
+     * Converts a String representing a board into a new ChessBoard.
+     *
+     * @param board String representing the board
+     * @return ChessBoard generated from input string
+     */
     public ChessBoard toBoard(String board) {
         ChessTile[][] boardTiles = new ChessTile[SIZE][SIZE];
         int row = 0;
@@ -444,6 +449,16 @@ public ChessBoard toBoard(String board) {
     }
 
     //@@author ken-ruster
+
+    /**
+     * Takes in an array of multiple moves, and executes them in order. Also updates the move history
+     * stored in the human and CPU objects.
+     *
+     * @param moves ArrayList of moves to be executed
+     * @param human Object representing the human player
+     * @param cpu Object representing the CPU player
+     * @throws ChessMasterException
+     */
     public void executeMoveArray(ArrayList<String> moves, Human human, CPU cpu) throws ChessMasterException {
         boolean isPlayersTurn = playerColor.isWhite();
 

src/main/java/chessmaster/game/Game.java

@@ -108,6 +108,14 @@ public boolean run() {
         return hasEnded || RestartCommand.isRestart(command);
     }
 
+    /**
+     * Represents main part of gameplay loop for the human user. Responsible for
+     * taking in the user's input and discerning the user's intention based on the input.
+     * Also executes and handles all commands except `MoveCommand`.
+     *
+     * @return Command corresponding to the user's input
+     * @throws ChessMasterException
+     */
     private Command getAndExecuteUserCommand() throws ChessMasterException {
         String userInputString = ui.getUserInput(true);
         this.command = Parser.parseCommand(userInputString);
@@ -117,6 +125,15 @@ private Command getAndExecuteUserCommand() throws ChessMasterException {
         return this.command;
     }
 
+    /**
+     * Handles the user input in the case that a move was made by the player.
+     * Extracts the move from the current command, and reflects the move on the chessboard.
+     * When the move is done, it also handles any possible promotions which can be made.
+     * Returns the move which has been made to be printed in the run()  function.
+     *
+     * @return Move which has been executed
+     * @throws ChessMasterException
+     */
     private Move handleHumanMove() throws ChessMasterException {
         Move humanMove = ((MoveCommand) this.command).getMove();
         board.executeMoveWithCheck(humanMove);
@@ -133,6 +150,14 @@ private Move handleHumanMove() throws ChessMasterException {
         return humanMove;
     }
 
+    /**
+     * Obtains and executes the CPU's move in response to the current board state.
+     * Also prints a message informing the player of the CPU thinking as it may take some time
+     * to compute the most optimal move in higher difficulty levels.
+     *
+     * @return The move that the CPU made
+     * @throws ChessMasterException
+     */
     private Move handleCPUMove() throws ChessMasterException {
         ui.printCPUThinkingMessage();
 
@@ -146,6 +171,13 @@ private Move handleCPUMove() throws ChessMasterException {
         return cpuMove;
     }
 
+    /**
+     * Checks whether the current state of the board qualifies as the game having ended.
+     * If the game has ended, prints a message signalling the end of the game, and resets the saved board.
+     *
+     * @return Whether the game has ended
+     * @throws ChessMasterException
+     */
     private boolean checkEndState() throws ChessMasterException {
         boolean end = board.isEndGame();
         if (end) {

src/main/java/chessmaster/game/PromoteMove.java

@@ -13,7 +13,7 @@ public PromoteMove (Coordinate coord, ChessPiece piece) {
      * Converts the move to a format to be saved in the .txt file.
      * Only called after the piece has been promoted to
      *
-     * @return
+     * @return String representing the move
      */
     @Override
     public String toFileString() {

src/main/java/chessmaster/parser/Parser.java

@@ -140,6 +140,15 @@ public static ChessPiece parseChessPiece(String pieceString, int row, int col) {
     }
     //@@author
 
+    /**
+     * Parses the user's input to return the appropriate Command.
+     * Returns an InvalidCommand if the input does not match any of the expected patterns.
+     * Used to discern the program's appropriate response to the user's input.
+     *
+     * @param in User's input, stored as a String
+     * @return A command corresponding to user input, or InvalidCommand if the input is not recognised
+     */
+
     public static Command parseCommand(String in) {
         String[] splitInputStrings = in.split("\\s+", 2);
         String commandString = splitInputStrings[0];

src/main/java/chessmaster/pieces/ChessPiece.java

@@ -148,6 +148,13 @@ public void setEnPassant() {
     }
 
     //@@author ken-ruster
+    /**
+     * Convert all the possible moves of the piece into a String.
+     * Returns a message saying that there are no moves available if there are no legal moves the piece can make.
+     *
+     * @param board Board the piece is located on
+     * @return A String containing the coordinates the piece is able to move to
+     */
     public String[] getAvailableCoordinatesString(ChessBoard board) {
         StringBuilder out = new StringBuilder();
         Coordinate[] legalCoordinates = getLegalCoordinates(board);

src/main/java/chessmaster/storage/Storage.java

@@ -21,7 +21,9 @@
 import java.util.Scanner;
 
 public class Storage {
-
+    //@@author ken_ruster
+    private static final String LOAD_BOARD_MISMATCH_STRING =
+            "Board state does not match state dictated by move history!";
     //@@author TriciaBK
     private String filePathString;
     private File storageFile;
@@ -210,6 +212,16 @@ public ChessTile[][] loadBoard() throws ChessMasterException {
         return boardTiles;
     }
 
+    /**
+     * Executes moves saved in the txt file so that it can be checked against the save board state.
+     * Also stores the saved move history of both the human and CPU.
+     *
+     * @param playerColor The color which the player is playing as
+     * @param otherBoard A temporary board to be compared with the board saved in the .txt file
+     * @param human Object representing information about the human player
+     * @param cpu Object representing information about the computer-controlled player
+     * @throws ChessMasterException
+     */
     public void executeSavedMoves(Color playerColor,
                                   ChessBoard otherBoard,
                                   Human human,
@@ -246,7 +258,7 @@ public void executeSavedMoves(Color playerColor,
 
         // Check obtained board with loaded board state
         if (!board.equals(otherBoard)) {
-            throw new LoadBoardException("Board state does not match state dictated by move history!");
+            throw new LoadBoardException(LOAD_BOARD_MISMATCH_STRING);
         }
     }
 
@@ -393,6 +405,13 @@ public String getFilePath() {
         return this.filePathString;
     }
 
+    /**
+     * Loads the history of moves made by the human player in the saved game.
+     * Parses the moves into Move objects, and returns a null array if no moves were found.
+     *
+     * @return ArrayList containing the move history of the human player
+     * @throws ChessMasterException
+     */
     public ArrayList<String> loadHumanMoves() throws ChessMasterException {
         createChessMasterFile();
 
@@ -423,6 +442,13 @@ public ArrayList<String> loadHumanMoves() throws ChessMasterException {
         return out;
     }
 
+    /**
+     * Loads the history of moves made by the CPU player in the saved game.
+     * Parses the moves into Move objects, and returns a null array if no moves were found.
+     *
+     * @return ArrayList containing the move history of the CPU player
+     * @throws ChessMasterException
+     */
     public ArrayList<String> loadCPUMoves() throws ChessMasterException {
         createChessMasterFile();