Document GomokuCell class file

src/GomokuCell.java

@@ -1,160 +1,247 @@
 import java.util.EnumMap;
-import java.util.HashMap;
 import java.util.Map;
 
 /**
- * This class is cell of the board of the Gomoku game.
+ * A cell of a Gomoku board.
+ * 
+ * This class represents a cell of a Gomoku board.
+ * It contains the state of the cell (empty, black or white) and its neighbours,
+ * as well as various methods to manipulate the cell.
  */
-public class GomokuCell{
+public class GomokuCell {
 
-    public static final String RESET = "\u001B[0m";
+    /** The neighbours of the cell.
-    public static final String ROUGE = "\u001B[31m";
+     * 
-    public static final String VERT = "\u001B[32m";
+     * Each neighbour of the cell is stored in the EnumMap with the direction to
-    /** Enumerate neighbor with key in Cardinal direction and key representing the cell in that direction. */
+     * that neighbour as the key.
-    private EnumMap<Cardinal,GomokuCell> neighbour;
+     */
-    /** The state of the cell represented by the enumerate Color, Nil is empty, white and black for the color of a token */
+    private EnumMap<Cardinal,GomokuCell> neighbours;
-    private Color state; 
 
-    //------------------Constructors--------------------------
+    /** The state of the cell.
+     * 
+     * Represented by the enumerate Color where NIL is empty and
+     * BLACK and WHITE are the two players.
+     */
+    private Color state;
+
+    // - Constructors -------------------------------------
 
     /**
      * The constructor of the cell.
-     * @param state The state by default of the cell.
+     * 
+     * This constructor creates a cell with the given state
+     * and an empty list of neighbours.
+     * 
+     * @param state The initial state of the cell.
      */
-    public GomokuCell(Color state){
+    public GomokuCell(Color state) {
-        this.neighbour = new EnumMap<>(Cardinal.class);
+        this.neighbours = new EnumMap<>(Cardinal.class);
         this.state = state;
     }
 
-    //------------------Gets--------------------------
+    // - Getters ------------------------------------------
 
     /**
-     * Return one neighbour.
+     * Return the state of the cell.
-     * @param car The Cardinal direction.
+     * 
-     * @return The GomokuCell at the direction.
+     * This method returns the state of the cell.
+     * 
+     * @return The state of the current cell.
      */
-    public GomokuCell getNeighbour(Cardinal car){
+    public Color getState() {
-        return this.neighbour.get(car);
-    }
-    
-    /**
-     * Return neighbours.
-     * @return The EnumMap of neighbours.
-     */
-    public EnumMap<Cardinal, GomokuCell> getAllNeighbour(){
-        return neighbour;
-    }
-
-    /**
-    * Return the number of same colored neighbours in all direction.
-    * @return The Map of neighbours.
-    */
-    public Map<Cardinal, Integer> getSameColorNeighbour(){
-
-        Map<Cardinal, Integer> map = new HashMap<>();
-        map.put(Cardinal.N, 0);
-        map.put(Cardinal.W,0);
-        map.put(Cardinal.NW, 0);
-        map.put(Cardinal.SW, 0);
-        map.put(Cardinal.S, 0);
-        map.put(Cardinal.SE, 0);
-        map.put(Cardinal.E, 0);
-        map.put(Cardinal.NE, 0);
-
-        for (Map.Entry<Cardinal, Integer> entry : map.entrySet()) {
-
-            GomokuCell actualcell = this;
-            while(this.getState() == actualcell.getNeighbour(entry.getKey()).getState())
-            {
-                entry.setValue(entry.getValue()+1);
-                actualcell=actualcell.getNeighbour(entry.getKey());
-            }
-        }
-        return map;
-    }
-    
-    /**
-     * Return the state.
-     * @return The state of the current cell with one Color.
-     */
-    public Color getState(){
         return this.state;
     }
 
-    //------------------Sets--------------------------
-    
     /**
-     * Change state of the current cell.
+     * Return the neighbour in specified direction.
-     * @param c The color of the token played.
+     * 
-     * @throws IllegalStateException If the cell is not playable.
+     * This method returns the neighbour of the cell in the specified direction.
+     * If the neighbour does not exist, it returns null.
+     * 
+     * @param dir The Cardinal direction.
+     * @return The GomokuCell in the specified the direction, or null if it
+     *         does not exist.
      */
-    public void setState(Color c){
+    public GomokuCell getNeighbour(Cardinal dir) {
+        return this.neighbours.get(dir);
+    }
+
+    /**
+     * Return all neighbours of the cell.
+     * 
+     * This method returns all the neighbours of the cell in an EnumMap.
+     * The keys of the map are the Cardinal directions and the values are the
+     * GomokuCells in that direction, or null if the neighbour does not exist.
+     * 
+     * @return The EnumMap of neighbours.
+     */
+    public EnumMap<Cardinal, GomokuCell> getAllNeighbours() {
+        return neighbours;
+    }
+
+    /**
+     * Return the number of same colored neighbours in each direction.
+     * 
+     * This method returns the number of same colored neighbours in each
+     * direction in a Map. The keys of the map are the Cardinal directions and
+     * the values are the number of same colored neighbours in that direction.
+     * The method iterates through each neighbour and counts the number of
+     * same colored neighbours in that direction until it reaches a neighbour
+     * that is not the same color as the current cell.
+     * 
+     * @return The Map indicating the number of same colored neighbours in each
+     *         direction.
+     */
+    public Map<Cardinal, Integer> getSameColorNeighbours() {
+
+        Map<Cardinal, Integer> map = new EnumMap<>(Cardinal.class);
+        int count;
+
+        // Iterate through each direction
+        for (Cardinal direction : Cardinal.values()) {
+            count = 0;
+            // Get the neighbour in the specified direction
+            GomokuCell neighbour = this.getNeighbour(direction);
+
+            // While the neighbour is not null and has the same state as the current cell
+            while (neighbour != null && neighbour.getState() == this.getState()) {
+                count++;
+                // Move to the next neighbour in the same direction
+                neighbour = neighbour.getNeighbour(direction);
+            }
+
+            // Store the count in the map
+            map.put(direction, count);
+        }
+
+        return map;
+    }
+
+    // - Setters ------------------------------------------
+
+    /**
+     * Set the state of the cell.
+     * 
+     * This method sets the state of the cell to the given color.
+     * 
+     * @param c The color to set the cell to.
+     */
+    public void setState(Color c) {
         this.state = c;
     }
-    
 
-    //------------------Booleans--------------------------
+    // - Cell State Methods ---------------------------
 
     /**
-     * This method returns if the current cell is empty
+     * Return true if the cell is empty.
-     * @return True if is empty, False if is not.
+     * 
+     * This method checks if the cell is empty and returns true if it is,
+     * false if it contains a color (and thus has been played).
+     * @return true if the cell is empty, false otherwise.
+     * @see #isPlayed()
      */
-    public boolean isEmpty(){
+    public boolean isEmpty() {
         return this.state == Color.NIL;
     }
-    
+
     /**
-     * This method returns if the cell has already played.
+     * Return true if the cell has been played.
-     * @return True if the cell is already played, False if is not.
+     * 
+     * This method returns true if the cell has been played
+     * (i.e. it is not empty), false otherwise.
+     * @return true if the cell has been played, false otherwise.
+     * @see #isEmpty()
      */
-    public boolean isPlayed(){
+    public boolean isPlayed() {
         return !this.isEmpty();
     }
     
     /**
-     * Return if the cell is playable.
+     * Return true if the cell can be played.
-     * @return True if the current cell can be played with the condition of the gomoku.
+     * 
+     * This method checks if the cell can be played with the condition of the
+     * Gomoku game. A cell can be played if it is empty and at least one of its
+     * neighbours has been played. This is to ensure that the player is not
+     * playing in an empty area of the board.
+     * 
+     * @return true if the cell can be played, false otherwise.
+     * @see #isEmpty()
+     * @see #isPlayed()
      */
-    public boolean isPlayable(){
+    public boolean isPlayable() {
-        if (!this.isEmpty()) return false;
+        // Check if the cell has been played, if so, it cannot be played
+        if (this.isPlayed()) return false;
+
+        // Check if at least one neighbour has been played
         for (Cardinal c : Cardinal.values()) {
             GomokuCell current = this.getNeighbour(c);
             if (current != null && current.isPlayed()) return true;
         }
+
+        // If no neighbours have been played, the cell cannot be played
         return false;
     }
 
-    
+    // - Methods ------------------------------------------
-    //------------------Methods--------------------------
 
     /**
-     * This method link the cell at the Cardinal position on the current cell.
+     * Link the current cell to the given cell, in the specified direction.
-     * @param car The Cardinal direction of the cell to link.
+     * 
-     * @param cell The GomokuCell to link.
+     * This method adds a mapping between the current cell and the given cell in
+     * the specified direction in the neighbours map. This is used to create a
+     * link between the two cells, allowing for easy access to the neighbours of
+     * each cell.
+     * 
+     * @param dir The Cardinal direction of the cell to link.
+     * @param cell The cell to link to.
+     * @see #getNeighbour(Cardinal)
+     * @see #link(GomokuCell, GomokuCell, Cardinal)
      */
-    public void linkCell(Cardinal car, GomokuCell cell){
+    public void linkCell(Cardinal dir, GomokuCell cell) {
-        this.neighbour.put(car, cell);
+        this.neighbours.put(dir, cell);
     }
 
-    
+    // - Static Methods -----------------------------------
-    //------------------Statics--------------------------
 
-    public static void link(GomokuCell c1, GomokuCell c2, Cardinal c1Toc2){
+    /**
-        if (c1 == null || c2 == null) return ;
+     * Link two cells together in the specified direction.
+     * 
+     * This method links two cells together in the specified direction. It
+     * creates a bidirectional link between the two cells. The first cell is
+     * linked to the second cell in the specified direction, and the second cell
+     * is linked to the first cell in the inverse direction.
+     * 
+     * If either of the cells is null, the method does nothing.
+     * 
+     * @param c1 The first cell to link.
+     * @param c2 The second cell to link.
+     * @param c1Toc2 The Cardinal direction from the first cell
+     *               to the second cell.
+     */
+    public static void link(GomokuCell c1, GomokuCell c2, Cardinal c1Toc2) {
+        if (c1 == null || c2 == null) return;
+        // Link the first cell to the second cell in the specified direction
         c1.linkCell(c1Toc2, c2);
+        // Link the second cell to the first cell in the inverse direction
         c2.linkCell(c1Toc2.inverse(), c1);
     }
 
-    //------------------Overides--------------------------
+    // - Override Methods ---------------------------------
+
+    /**
+     * Return a string representation of the cell.
+     * 
+     * This method returns a string representation of the cell. The string
+     * representation is based on the state of the cell.
+     * 
+     * @return The string representation of the cell.
+     */
     @Override
     public String toString() {
         switch (this.getState()) {
-            case Color.NIL:
+            case Color.NIL:   return ".";
-                return ".";
+            case Color.BLACK: return "X";
-            case Color.BLACK:
+            case Color.WHITE: return "O";
-                return "X";
-            case Color.WHITE:
-                return "O";
             default:
                 throw new IllegalStateException("Unexpected value: " + this.getState());
         }