Document part of the GomokuBoard class file

src/GomokuBoard.java

@@ -4,52 +4,87 @@ import java.util.Map;
 import java.util.ArrayList;
 
 /**
- * The board of the game Gomoku.
+ * The board of Gomoku.
+ * 
+ * This class represents a board of the Gomoku game.
+ * It contains a grid of cells, each of which can be empty or occupied by a
+ * player's piece.
+ * The class provides methods to create the board, access its cells, and perform
+ * various operations on the cells and the board itself.
  */
 public class GomokuBoard {
-    /** The firstcell in the board, at the top left of the board. */
-    private GomokuCell firstCell;
-    /** The width of the GomokuBoard. */
-    private int boardWidth;
-    /** The height of the GomokuBoard. */
-    private int boardHeight;
 
-    // ------------------Constructors--------------------------
+    /** The top-left cell of the board. */
+    private GomokuCell topLeftCell;
+    /** The width of the Gomoku board. */
+    private int width;
+    /** The height of the Gomoku board. */
+    private int height;
+
+    // - Constructors -------------------------------------
 
     /**
-     * This constructor take the width and the height to creat a board of gomoku.
+     * Gomoku board constructor.
      * 
-     * @param width  Size of width.
+     * This constructor takes the width, height, and an array of colors as
-     * @param height Size of height.
+     * parameters to create a board of Gomoku with the specified dimensions and
+     * fill it with the given colors. The colors array should be of the same
+     * dimensions as the board. If the colors array is null, the board will be
+     * initialized with empty cells.
+     * 
+     * @param width  Width of the board.
+     * @param height Height of the board.
+     * @param colors Array of Color to fill the board.
+     * @throws IllegalArgumentException if the dimensions are invalid or if the
+     *                                  colors array is not of the correct size.
+     * @see GomokuBoard#GomokuBoard(int, int)
+     */
+    public GomokuBoard(int width, int height, Color[][] colors) {
+        // Check if the dimensions are valid
+        if (width <= 0 || height <= 0) {
+            throw new IllegalArgumentException("Invalid dimensions for the board.");
+        }
+        // Check if the colors array is of the correct size
+        if (colors != null && (colors.length != height || colors[0].length != width)) {
+            throw new IllegalArgumentException("Invalid colors array size.");
+        }
+        // Initialize the board dimensions
+        this.width = width;
+        this.height = height;
+        // Generate the cells and link them together
+        this.generateCells(width, height, colors);
+    }
+
+    /**
+     * Gomoku empty board constructor.
+     * 
+     * This constructor takes the width and the height as parameters to create a
+     * board of Gomoku with the specified dimensions, initializing all cells to
+     * the empty state.
+     * 
+     * @param width  Width of the board.
+     * @param height Height of the board.
+     * @throws IllegalArgumentException if the dimensions are invalid.
+     * @see GomokuBoard#GomokuBoard(int, int, Color[][])
      */
     public GomokuBoard(int width, int height) {
         this(width, height, null);
     }
 
     /**
-     * This constructor take the width and the height to creat a board of gomoku.
+     * Generate the cells of the board.
      * 
-     * @param width  Size of width.
+     * Creates the cells of the board and links them together in a grid.
-     * @param height Size of height.
+     * The cells are initialized with the specified colors, or to the empty state
-     * @param colors Is colors of cells after load a game.
+     * if the colors array is null.
-     */
-    public GomokuBoard(int width, int height, Color[][] colors) {
-        this.firstCell = new GomokuCell(Color.NIL);
-        this.boardWidth = width;
-        this.boardHeight = height;
-        this.generateCells(width, height, colors);
-    }
-
-    /**
-     * This method generate all cells in the board and link each other.
      * 
-     * @param width  Size of width.
+     * @param width  Width of the board.
-     * @param height Size of height.
+     * @param height Height of the board.
-     * @param colors Array of Color.
+     * @param colors Array of Color to fill the board.
      */
     private void generateCells(int width, int height, Color[][] colors) {
-        this.firstCell = new GomokuCell(colors == null ? Color.NIL : colors[0][0]);
+        this.topLeftCell = new GomokuCell(colors == null ? Color.NIL : colors[0][0]);
-        GomokuCell act = this.firstCell;
+        GomokuCell act = this.topLeftCell;
         GomokuCell top = null;
 
         for (int i = 0; i < height; i++) {
@@ -87,7 +122,7 @@ public class GomokuBoard {
      * @return The width of the board.
      */
     public int getWidth() {
-        return this.boardWidth;
+        return this.width;
     }
 
     /**
@@ -96,7 +131,7 @@ public class GomokuBoard {
      * @return The height of the board.
      */
     public int getHeight() {
-        return this.boardHeight;
+        return this.height;
     }
 
     /**
@@ -107,12 +142,12 @@ public class GomokuBoard {
      * @return GomokuCell in the position.
      */
     public GomokuCell get(int x, int y) {
-        if (x < 0 || x >= this.boardWidth)
+        if (x < 0 || x >= this.width)
             return null;
-        if (y < 0 || y >= this.boardHeight)
+        if (y < 0 || y >= this.height)
             return null;
         int i = 0, j = 0;
-        GomokuCell act = this.firstCell;
+        GomokuCell act = this.topLeftCell;
         while (i != x || j != y) {
             Cardinal c = Cardinal.SE;
             if (i < x)
@@ -145,11 +180,11 @@ public class GomokuBoard {
      * @return All cells with a array 2D.
      */
     private GomokuCell[][] getAllCells() {
-        GomokuCell[][] cells = new GomokuCell[this.boardHeight][this.boardWidth];
+        GomokuCell[][] cells = new GomokuCell[this.height][this.width];
-        GomokuCell act = this.firstCell;
+        GomokuCell act = this.topLeftCell;
-        GomokuCell nextLine = this.firstCell.getNeighbour(Cardinal.S);
+        GomokuCell nextLine = this.topLeftCell.getNeighbour(Cardinal.S);
-        for (int i = 0; i < this.boardHeight; i++) {
+        for (int i = 0; i < this.height; i++) {
-            for (int j = 0; j < this.boardWidth; j++) {
+            for (int j = 0; j < this.width; j++) {
                 cells[i][j] = act;
                 act = act.getNeighbour(Cardinal.E);
             }
@@ -188,7 +223,7 @@ public class GomokuBoard {
      * @param width The new width of the board.
      */
     public void setWidth(int width) {
-        this.boardWidth = width;
+        this.width = width;
     }
 
     /**
@@ -197,7 +232,7 @@ public class GomokuBoard {
      * @param height The new height of the board.
      */
     public void setHeight(int height) {
-        this.boardHeight = height;
+        this.height = height;
     }
 
     // ------------------Methods--------------------------
@@ -280,7 +315,7 @@ public class GomokuBoard {
 
         // move to the corner cell
         // go to the center of the board
-        GomokuCell cornerCell = this.get(this.boardWidth / 2, this.boardHeight / 2);
+        GomokuCell cornerCell = this.get(this.width / 2, this.height / 2);
         GomokuCell nextCell;
         // move while possible to the desired corner of the board
         do {
@@ -333,15 +368,15 @@ public class GomokuBoard {
 
         // update the board dimensions;
         if (direction == Cardinal.N || direction == Cardinal.S) {
-            this.boardHeight++;
+            this.height++;
         } else {
-            this.boardWidth++;
+            this.width++;
         }
 
         // for the North and West expansions, update the first cell
         // (top-left cell reference) of the entire board
         if (direction == Cardinal.N || direction == Cardinal.W) {
-            this.firstCell = this.firstCell.getNeighbour(direction);
+            this.topLeftCell = this.topLeftCell.getNeighbour(direction);
         }
     }