Javadocs and comments (#84)

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java
 - created/edited javadocs for
 HomeScreenController.java

FIX
 - fixed onKeyPressed() in HomeScreenController so that the game will start when space is pressed

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java
 - created/edited javadocs for
 HomeScreenController.java
  - created/edited javadocs for
  GameBoard.java

FIX
 - fixed onKeyPressed() in HomeScreenController so that the game will start when space is pressed

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java
 - created/edited javadocs for
 HomeScreenController.java
 - created/edited javadocs for
 GameBoard.java
 - created/edited javadocs for
 GameControls.java

FIX
 - fixed onKeyPressed() in HomeScreenController so that the game will start when space is pressed

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java
 - created/edited javadocs for
 HomeScreenController.java
 - created/edited javadocs for
 GameBoard.java
 - created/edited javadocs for
 GameControls.java
 - created/edited javadocs for
 GameInstance.java

FIX
 - fixed onKeyPressed() in HomeScreenController so that the game will start when space is pressed

* Javadocs + comments
 - created/edited javadocs for GameBoardController.java
 - created/edited javadocs for HomeScreenController.java
 - created/edited javadocs for GameBoard.java
 - created/edited javadocs for GameControls.java
 - created/edited javadocs for GameInstance.java
 - created/edited javadocs for
 SceneManager.java and ScoreRecorder.java

FIX
 - fixed onKeyPressed() in HomeScreenController so that the game will start when space is pressed

src/main/java/com/stackedsuccess/GameBoard.java

@@ -28,21 +28,27 @@ public class GameBoard {
 
   private GameBoardController controller;
 
+  /**
+   * Initialises a new instance of the Game Board class with the default board dimensions.
+   *
+   * <p>This constructor sets up the game board by creating a 2D array with the default width and height.
+   * It then calls the initializeBoard() method to prepare the board for gameplay.</p>
+   */
   public GameBoard() {
+    //creates the boards default dimensions
     board = new int[DEFAULT_BOARD_HEIGHT][DEFAULT_BOARD_WIDTH];
     this.width = DEFAULT_BOARD_WIDTH;
     this.height = DEFAULT_BOARD_HEIGHT;
     initializeBoard();
   }
 
-  public GameBoard(int width, int height) {
-    board = new int[width][height];
-    this.width = width;
-    this.height = height;
-    initializeBoard();
-  }
-
-  /** Setup initial tetrimino pieces and board metrics. */
+  /**
+   * Sets up the initial Tetrimino pieces and initialises board-related metrics.
+   *
+   * <p>This method is responsible for creating the current and next Tetrimino pieces
+   * using the Tetrimino factory. It also initialises the frame count and
+   * game speed to their starting values.</p>
+   */
   private void initializeBoard() {
     currentTetrimino = TetriminoFactory.createRandomTetrimino();
     nextTetrimino = TetriminoFactory.createRandomTetrimino();
@@ -69,12 +75,19 @@ public GameBoardController getController() {
     return controller;
   }
 
-  /** Update the state of the board. */
+  /**
+   * Updates the state of the game board. This method is called once per frame.
+   * It handles the timing of tetrimino movement and updates the display.
+   *
+   * @throws IOException if an error occurs during display update
+   */
   public void update() throws IOException {
     frameCount++;
     controller.updateDisplay(board);
 
     // Stagger automatic tetrimino movement based on frame count
+    // Moves the tetrimino down if the framecount is a multiple of the gamespeed
+    // Or if the forceUpdate (such as hard drop) is true
     if (frameCount % gameSpeed == 0 || forceUpdate) {
       forceUpdate = false;
       if (currentTetrimino.canMoveDown(this)) {
@@ -180,26 +193,34 @@ private void handleTetriminoPlacement() throws IOException {
   }
 
   /**
-   * Appends new tetrimino to the game board.
+   * Appends a new tetrimino to the game board at its current position.
+   * This method places the blocks of the tetrimino onto the game board.
    *
-   * @param tetrimino the tetrimino to place on the game board.
+   * @param tetrimino the tetrimino to place on the game board
    */
   private void placeTetrimino(Tetrimino tetrimino) {
     int[][] layout = tetrimino.getTetriminoLayout();
     for (int layoutY = 0; layoutY < tetrimino.getHeight(); layoutY++) {
       for (int layoutX = 0; layoutX < tetrimino.getWidth(); layoutX++) {
+        // checks if the current pos is occupied
         if (layout[layoutY][layoutX] != 0) {
-
+          // then calculates the position on the board where it will be placed
           int spawnX = tetrimino.getXPos() + layoutX;
           int spawnY = tetrimino.getYPos() + layoutY;
-
+          // then places the piece at the calculated position
           board[spawnY][spawnX] = layout[layoutY][layoutX];
         }
       }
     }
   }
 
-  /** Check top two rows of the board for pieces visually out of bounds. */
+  /**
+   * Checks the top two rows of the game board to determine if any pieces are
+   * out of bounds, indicating a game-over condition.
+   *
+   * @return true if the game is over due to pieces in the top rows, false otherwise
+   * @throws IOException if an error occurs while handling the game over condition
+   */
   private boolean checkGameOver() throws IOException {
     for (int x = 0; x < width; x++) {
       for (int y = 0; y <= 1; y++) {
@@ -212,11 +233,18 @@ private boolean checkGameOver() throws IOException {
     return false;
   }
 
-  /** Clears full rows and moves rows above downwards. */
+  /**
+   * Method to clear any full rows on the board
+   *
+   * <p>Clears full rows on the game board and shifts the rows above downward.
+   * It also updates the score, the total number of cleared lines, and adjusts
+   * the game level and speed accordingly.</p>
+   */
   private void clearFullRows() {
     int newLinesCleared = 0;
     for (int y = 0; y < board.length; y++) {
       if (isRowFull(y, board[y])) {
+        //moves all the rows that are above, down one
         newLinesCleared++;
         shiftRowsDown(y);
       }
@@ -229,7 +257,11 @@ private void clearFullRows() {
     changeGameSpeed();
   }
 
-  /** Updates the level based on the number of lines cleared. */
+  /** Updates the level based on the number of lines cleared.
+   *
+   * <p>For every 10 lines that are cleared, the game will increase
+   * by one level</p>
+   */
   private void updateLevel() {
     level = (totalLinesCleared / 10) + baseLevel;
     controller.updateLevel(level);
@@ -243,6 +275,7 @@ private void updateLevel() {
    */
   private void calculateScore(int linesCleared) {
     switch (linesCleared) {
+      // the different calculations of scores, whether 1,2,3, or 4 lines are cleared at once
       case 1:
         score += 40;
         break;
@@ -311,17 +344,20 @@ private boolean isRowFull(int rowY, int[] row) {
   }
 
   /**
-   * Hold the current tetrimino and swap with the hold tetrimino if available. Block the user from
-   * holding if they are already used it
+   * Holds the current tetrimino and swaps it with the held tetrimino if one is already held.
+   * The user is blocked from holding another tetrimino until the current one is placed.
    */
   public void holdTetrimino() {
+    // check if a player is already holding a piece
     if (holdUsed) return;
 
+    // if there is no tetrimino being currently held, store the current one
     if (holdTetrimino == null) {
       holdTetrimino = currentTetrimino;
       currentTetrimino = nextTetrimino;
       nextTetrimino = TetriminoFactory.createRandomTetrimino();
     } else {
+      //if a tetriminio is already being held swap the current with the held
       Tetrimino temp = holdTetrimino;
       holdTetrimino = currentTetrimino;
       currentTetrimino = temp;
@@ -335,8 +371,10 @@ public void holdTetrimino() {
   }
 
   /**
-   * Varies game speed based on level. Levels are easier up to 10, with difficulty jump at 10, and
-   * 15, and kill screen at level 20
+   * Adjusts the game speed based on the current level. The game speed decreases (game gets faster) as
+   * the player progresses through the levels, with noticeable difficulty jumps at levels 10 and 15.
+   * At level 20, the game reaches a "kill screen" speed where it becomes extremely difficult to continue.
+   * Essentially creating a hard cap to the game.
    */
   private void changeGameSpeed() {
 

src/main/java/com/stackedsuccess/GameControls.java

@@ -14,8 +14,14 @@ public GameControls() {
     initializeControls();
   }
 
-  /** Bind default controls to actions. */
-  private void initializeControls() {
+  /**
+   * Initialises the default key bindings for various actions in the game.
+   *
+   * <p>This method assigns specific keys to actions such as moving left, right,
+   * down, performing a hard drop, rotating pieces, pausing the game, and holding
+   * a piece</p>
+   */
+   private void initializeControls() {
     controls.put(Action.MOVE_LEFT, KeyCode.LEFT);
     controls.put(Action.MOVE_RIGHT, KeyCode.RIGHT);
     controls.put(Action.MOVE_DOWN, KeyCode.DOWN);

src/main/java/com/stackedsuccess/GameInstance.java

@@ -21,28 +21,55 @@ public class GameInstance {
   private Tetrimino currentTetrimino;
   private TetriminoUpdateListener tetriminoUpdateListener;
 
+  /**
+   * Constructs a new instance of the game with default initial settings.
+   *
+   * <p>This constructor initialises the game state by setting the initial score,
+   * game delay, and flags for pause and game over status</p>
+   */
   public GameInstance() {
     score = 0;
     gameDelay = 10;
     isPaused = false;
     isGameOver = false;
   }
 
+  /**
+   * An interface for listening to updates of a Tetrimino.
+   */
   public interface TetriminoUpdateListener {
     void onTetriminoUpdate(Tetrimino tetrimino);
   }
 
+  /**
+   * Sets the listener for Tetrimino updates
+   *
+   * @param listener The TetriminoUpdateListener to be notified of updates.
+   */
   public void setTetriminoUpdateListener(TetriminoUpdateListener listener) {
     this.tetriminoUpdateListener = listener;
   }
 
+  /**
+   * Notifies the registered listener that the current Tetrimino has been updated
+   *
+   * <p>This method is called whenever the Tetrimino's state changes. It checks if a
+   * listener has been registered, and if so, it triggers the listener's
+   * onTetriminoUpdate() method, passing the updated Tetrimino as an argument.</p>
+   */
   private void notifyTetriminoUpdate() {
     if (tetriminoUpdateListener != null) {
       tetriminoUpdateListener.onTetriminoUpdate(currentTetrimino);
     }
   }
 
-  /** Starts the game instance to periodically update the game board and handle game movement. */
+  /**
+   * Starts the game instance to periodically update the game board and handle game movement.
+   *
+   * <p>This method initialises the game board, retrieves the current Tetrimino, and sets up the
+   * game controls. It also creates a timer that periodically triggers the game loop, which updates
+   * the game state, handles Tetrimino movements, and checks whether the game is paused or over.</p>
+   */
   public void start() {
     gameBoard = new GameBoard();
     currentTetrimino = gameBoard.getCurrentTetrimino();
@@ -146,6 +173,11 @@ public void setGameOver(boolean isGameOver) {
     this.isPaused = isGameOver;
   }
 
+  /**
+   * This method checks whether the game is currently paused
+   *
+   * @return if the game is currently paused
+   */
   public boolean isPaused() {
     return isPaused;
   }

src/main/java/com/stackedsuccess/SceneManager.java

@@ -11,10 +11,22 @@ public enum AppUI {
 
   private static HashMap<AppUI, Parent> sceneMap = new HashMap<AppUI, Parent>();
 
+  /**
+   * Adds a scene and its associated parent node to the scene map
+   *
+   * @param scene the AppUI scene to be added to the map
+   * @param parent the Parent node associated with the scene
+   */
   public static void addScene(AppUI scene, Parent parent) {
     sceneMap.put(scene, parent);
   }
 
+  /**
+   * Retrieves the parent node associated with a given scene.
+   *
+   * @param scene the AppUI scene whose associated parent node is to be retrieved.
+   * @return the Parent node associated with the given scene
+   */
   public static Parent getScene(AppUI scene) {
     return sceneMap.get(scene);
   }

src/main/java/com/stackedsuccess/ScoreRecorder.java

@@ -81,7 +81,13 @@ private static void writeScores(List<Integer> scores) throws IOException {
     }
   }
 
-  /** Create a score file if it does not exist. */
+  /**
+   * Creates a score file if it does not already exist.
+   *
+   * <p>This method checks if the score file exists. If the file does not exist, it attempts to create a new one.
+   * If the file creation fails on the first attempt, the method retries. If the file creation fails again, an
+   * IOException is thrown to indicate that the score file could not be created</p>
+   */
   public static void createScoreFile() {
     File scoreFile = new File(SCOREFILE);
     if (!scoreFile.exists()) {