WIP: Report part 1

src/host/labyrinth/Board.java

@@ -1,11 +1,13 @@
 /**
  * @file Board.java
  *
- * @author Christos Choutouridis AEM:8997
+ * @author
- * @email  cchoutou@ece.auth.gr
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
  */
 
-package net.hoo2.auth.labyrinth;
+package host.labyrinth;
 
 import java.util.ArrayList;
 import java.util.function.IntFunction;
@@ -131,7 +133,8 @@ class Board {
    }
 
    /**
-    * Predicate to check if a direction is Walkable
+    * Predicate to check if a direction is Walkable.
+    *
     * @param tileId     The starting tileId.
     * @param direction  The desired direction.
     * @return           True if it is walkable.
@@ -142,9 +145,10 @@ class Board {
    }
 
    /**
-    * Predicate to check if a direction is Walkable
+    * Predicate to check if a direction is Walkable.
+    *
     * @param row        Row position of the starting tile.
-    * @param column     Column position of the starting tile.
+    * @param col        Column position of the starting tile.
     * @param direction  The desired direction.
     * @return           True if it is walkable.
     */
@@ -175,7 +179,7 @@ class Board {
     * @return  A random direction;
     */
    int dice () {
-      ShuffledRange d = new ShuffledRange(Direction.Begin, Direction.End, Direction.Step);
+      ShuffledRange d = new ShuffledRange(DirRange.Begin, DirRange.End, DirRange.Step);
       return d.get();
    }
 
@@ -205,6 +209,13 @@ class Board {
     */
    Supply[] getSupplies() { return supplies; }
 
+   /**
+    * @note Use it with care. Any use of this function results to what Sean Parent calls "incidental data-structure".
+    * <a href="https://github.com/sean-parent/sean-parent.github.io/blob/master/better-code/03-data-structures.md"> see also here</a>
+    * @return  Reference to inner walls array.
+    */
+   ArrayList<Edge> getWalls() { return walls; }
+
    void setN(int N)  { this.N = N; }
    void setS(int S)  { this.S = S; }
    void setW(int W)  { this.W = W; }
@@ -221,6 +232,14 @@ class Board {
     * Any call to this function will probably add memory for the garbage collector.
     */
    void setSupplies(Supply[] supplies)   { this.supplies= supplies; }
+
+   /**
+    * @param walls   Reference to walls that we want to act as replacement for the inner walls vector.
+    * @note    Use with care.
+    * Any call to this function will probably add memory for the garbage collector.
+    */
+   void setWalls (ArrayList<Edge> walls) { this.walls= walls; }
+
    /** @} */
 
 
@@ -269,16 +288,16 @@ class Board {
    /**
     * Predicate to check if a wall creates a closed room.
     *
-    * This algorithm has a complexity of O(N^2logN) where N represents the total
+    * This algorithm has a complexity of @f$ O(N^2logN) @f$ where N represents the total
     * number of tiles.
     * It should be used with care.
     *
-    * @param tileId     The tileId of the wall where the wall is.
+    * @param tileId     The tileId of the wall.
-    * @param direction  The wall's relative direction from the tile. 
+    * @param direction  The wall's relative direction. 
     * @return           True if the wall creates a closed room, false otherwise.
     */
    private boolean makesClosedRoom (int tileId, int direction) {
-      // Get a snapshot list of all the walls (all the walls on the board)
+      // Clone the list of all the walls locally.
       ArrayList<Edge> w = new ArrayList<Edge>();
       for (Edge it : walls)
          w.add(new Edge(it));
@@ -288,14 +307,14 @@ class Board {
       int size;
       do {
          size = w.size();                       // mark the size (before the pass)
-         for (int i =0, S=w.size() ; i<S ; ++i)
+         for (int i =0, S=w.size() ; i<S ; ++i) // for each edge(wall) on the local wall list
-            if (g.attach(w.get(i))) {           // Can we attach the edge(wall) to the graph ?
+            if (g.attach(w.get(i))) {           // can we attach the edge(wall) to the graph ?
-               w.remove(i);                     // If yes remove it from the wall list
+               w.remove(i);                     // if yes remove it from the local wall list
                --i; --S;                        // decrease iterator and size to match ArrayList's new values
             }
       } while (size != w.size());               // If the size hasn't change(no new graph leafs) exit
 
-      // Search if a vertex is attached more than once.
+      // Search if a vertex is attached to the graph more than once.
       // This means that there is at least 2 links to the same node
       // so the graph has a closed loop
       for (Edge it : walls) {
@@ -365,7 +384,7 @@ class Board {
          return false;
       if (tiles[tileId].hasWalls() >= Const.maxTileWalls)
          return false;
-      Range dirs = new Range(Direction.Begin, Direction.End, Direction.Step);
+      Range dirs = new Range(DirRange.Begin, DirRange.End, DirRange.Step);
       for (int dir ; (dir = dirs.get()) != Const.noTileId ; )
          if (isWallableDir(tileId, dir))
             return true;
@@ -388,6 +407,7 @@ class Board {
          boolean right = isRightSentinel(i);
          wallCount += ((up?1:0) + (down?1:0) + (left?1:0) + (right?1:0));
          tiles[i] = new Tile (i, up, down, left, right);
+         // If we have loopGuard enable we populate walls also.
          if (Session.loopGuard) {
             if (up)     walls.add(new Edge(i, Direction.UP));
             if (down)   walls.add(new Edge(i, Direction.DOWN));
@@ -404,14 +424,16 @@ class Board {
     */
    private void createInnerWall(int tileId) {
       // Randomly pick a wallable direction in that tile.
-      ShuffledRange randDirections = new ShuffledRange(Direction.Begin, Direction.End, Direction.Step);
+      ShuffledRange randDirections = new ShuffledRange(DirRange.Begin, DirRange.End, DirRange.Step);
       int dir;
       do
          dir = randDirections.get();
       while (!isWallableDir(tileId, dir));
+      // Add wall to tileId and the adjacent tileId
       Position neighbor = new Position(Position.toRow(tileId), Position.toCol(tileId), dir);
       tiles[tileId].setWall(dir);
       tiles[neighbor.getId()].setWall(Direction.opposite(dir));
+      // If we have loopGuard enable we populate walls also.
       if (Session.loopGuard)
          walls.add(new Edge(tileId, dir));
    }
@@ -419,7 +441,6 @@ class Board {
    /**
     * This utility creates the inner walls of the board.
     *
-    * @param walls   The number of walls to create   
     * @return        The number of walls failed to create.
     */
    private int createInnerWalls () {

src/host/labyrinth/Common.java

@@ -1,10 +1,12 @@
 /**
  * @file Common.java
  *
- * @author Christos Choutouridis AEM:8997
+ * @author
- * @email  cchoutou@ece.auth.gr
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
  */
-package net.hoo2.auth.labyrinth;
+package host.labyrinth;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -36,16 +38,31 @@ class Direction {
    static final int  RIGHT =3;   /**< East direction */
    static final int  DOWN  =5;   /**< South direction */
    static final int  LEFT  =7;   /**< West direction */
-   static final int  Begin =1;   /**< Iterator style begin of range direction (starting north) */
-   static final int  End   =8;   /**< Iterator style end of range direction (one place after the last) */
-   static final int  Step  =2;   /**< Step for iterator style direction */
 
    /**
-    * Utility to get the opposite 
+    * Utility to get the opposite direction.
     * @param direction  Input direction
     * @return           The opposite direction
     */
-   static int opposite (int direction) { return (direction+4)%End; }
+   static int opposite (int direction) { return (direction+4)%DirRange.End; }
+}
+
+/**
+ * Helper C++ like enumerator class for direction ranged loops.
+ *
+ * We can make use of this in loops like:
+ * <pre>
+ * for (int i=DirRange.Begin ; i<DirRange.End ; i += DirRange.Step) { }
+ * 
+ * or
+ * 
+ * Range directions = new Range(DirRange.Begin, DirRange.End, DirRange.Step);
+ * </pre>
+ */
+class DirRange {
+   static final int  Begin =1;   /**< Iterator style begin of range direction (starting north) */
+   static final int  End   =8;   /**< Iterator style end of range direction (one place after the last) */
+   static final int  Step  =2;   /**< Step for iterator style direction */
 }
 
 /**
@@ -55,7 +72,7 @@ class Direction {
  * Position is a helper class to enable us cope with the redundant position data (id and coordinates).
  * This class provide both static conversion functionalities between id and coordinates
  * and data representation in the coordinates system.
- * For clarity we adopt a row-column naming convention.
+ * For clarity we adopt a tileId convention.
  */
 class Position {
 
@@ -219,18 +236,21 @@ class ShuffledRange extends Range {
  * This class is the wall representation we use in the room preventing algorithm.
  * In this algorithm we represent the crosses between tiles as nodes (V) of a graph and the
  * walls as edges. So for example:
+ * <pre>
+ *   12--13--14---15
+ *    |           |
+ *    8   9--10   11
+ *    |       |   |
+ *    4   5   6   7
+ *    |   |       |
+ *    0   1---2---3
+ * </pre>
+ * In this example we have a 4x4=16 vertices board(nodes) and 14 edges(walls).
+ * To represent the vertices on the board we use the same trick as the tileId
  *
- *                  _ V = 15 
+ * V = Row*(N+1) + Column, where N is the board's tile size.
- *                 /
+ *
- *    +---+---+---+     We have a 4x4=16 vertices board(nodes) and 14 edges(walls).
+ * The edges are represented as vertices pairs. For example (0, 4) or (13, 14).
- *    |           |     To represent the vertices on the board we use the
- *    +   +---+   +     same trick as the tileId.
- *    |       |   |     The edges are represented as vertices pairs.
- *    +   +   +   + <.
- *    |   |       |   \_ V = 7
- *    +   +---+---+
- *    ^           ^
- *   V = 0      V = 3
  *
  * @note
  *    Beside the fact that we prefer this kind of representation of the walls in
@@ -242,7 +262,7 @@ class ShuffledRange extends Range {
  */
 class Edge {
    /**
-    * This constructor as as the interface between the application's wall
+    * This constructor acts as the interface between the application's wall
     * representation and the one based on graph.
     * @param tileId     The tile id of the wall.
     * @param direction  The direction of the tile where the wall should be.
@@ -286,13 +306,13 @@ class Edge {
  * @brief
  *    Provides a graph functionality for the room preventing algorithm.
  * We use a graph to represent the wall structure of the walls. This way
- * is easy to find any closed loops. Using graph we transform the problem
+ * its easy to find any closed loops. Using graph we transform the problem
- * of the closed room in the problem of finding a non simple graph.
+ * of the closed room into the problem of finding a non simple graph.
  *
- * If the board has non connected wall structure then we need more than
+ * If the board has non connected wall structure then we would need more than
  * one graph to represent it.
  * 
- * An example graph from a board, starting from V=1 is:
+ * An example graph we can create from the board bellow, starting from V=1 is:
  * <pre>
  *    6---7   8                (1)
  *    |       |               /  \
@@ -327,7 +347,7 @@ class Graph {
 
    /**
     * Attach an edge into a graph IFF the graph already has a vertex
-    * with the same value of one of the vertices of the edge.
+    * with the same value as one of the vertices of the edge.
     * @param e    The edge to attach.
     * @return     The status of the operation.
     *    @arg     True on success
@@ -348,17 +368,18 @@ class Graph {
 
    /**
     * Recursive algorithm that tries to attach an edge into a graph
-    * IFF the graph already has a vertex.
+    * IFF the graph already has a vertex with the same value as one
-    * with the same value of one of the vertices of the edge.
+    * of the vertices of the edge.
+    *
     * @param e       The edge to attach.
-    * @param count   An initial count value to feed to the algorithm.
+    * @param count   An initial count value to feed the algorithm.
     * @return     The status of the operation.
     *    @arg     True on success
     *    @arg     False on failure
     */
    private int tryAttach (Edge e, int count) {
       for (Graph n: E)
-         count += n.tryAttach (e, count);
+         count = n.tryAttach (e, count);
       if (V == e.getV1()) {
          E.add(new Graph(e.getV2()));
          ++count;
@@ -372,7 +393,8 @@ class Graph {
 
    /**
     * Recursive algorithm that tries to count the number of vertices
-    * on the graph with the value of `v`
+    * on the graph with the same value as `v`.
+    *
     * @param v       The vertex to count
     * @param count   An initial count value to feed to the algorithm.
     * @return     The number of vertices with value `v`
@@ -384,6 +406,7 @@ class Graph {
          return ++count;
       return count;
    }
+
    private int V;                /**< The value of the current vertex/node */
    private ArrayList<Graph> E;   /**< A list of all the child nodes */
 }

src/host/labyrinth/Game.java

@@ -1,11 +1,22 @@
 /**
  * @file Game.java
  *
- * @author Christos Choutouridis AEM:8997
+ * @author
- * @email  cchoutou@ece.auth.gr
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
  */
 
-package net.hoo2.auth.labyrinth;
+/** 
+ * @mainpage A labyrinth board game
+ *
+ * @section intro_sec Introduction
+ *
+ * This is the introduction.
+ *
+ * etc...
+ */
+package host.labyrinth;
 
 import java.util.Scanner;
 

src/host/labyrinth/Player.java

@@ -1,5 +1,13 @@
-package net.hoo2.auth.labyrinth;
+/**
+ * @file Player.java
+ *
+ * @author
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
+ */
 
+package host.labyrinth;
 
 /**
  * @brief
@@ -13,7 +21,10 @@ class Player {
     * Create a new player and put him at the row-column coordinates 
     * @param id         The id of the player
     * @param name       The name of the player
+    * @param champion   Flag to indicate if a player is a `champion`
     * @param board      Reference to the board of the game
+    * @param row        The row coordinate of initial player position
+    * @param column     The column coordinate of initial player's position
     */
    Player(int id, String name, boolean champion, Board board, int row, int column) {
       this.playerId  = id;
@@ -29,7 +40,9 @@ class Player {
     * Create a new player and put him at the row-column coordinates 
     * @param id         The id of the player
     * @param name       The name of the player
+    * @param champion   Flag to indicate if a player is a `champion`
     * @param board      Reference to the board of the game
+    * @param tileId     The tileId coordinate of player's initial position
     */
    Player(int id, String name, boolean champion, Board board, int tileId) {
       this.playerId  = id;
@@ -105,6 +118,7 @@ class Player {
    int getScore ()      { return score; }
    int getX()           { return x; }
    int getY()           { return y; }
+   boolean getChampion(){ return champion; }
 
    void setPlayerId(int id)   { playerId = id; }
    void setName(String name)  { this.name = name; }
@@ -118,6 +132,10 @@ class Player {
       assert (y >= 0 && y< Session.boardSize) : "Y(row) coordinate must be in the range [0, Session.boardSize)";
       this.y = y;
    }
+   void setChampion (boolean champion) {
+      this.champion = champion;
+   }
+
    /** @} */
    
    /** @name Class data */

src/host/labyrinth/Supply.java

@@ -1,11 +1,13 @@
 /**
  * @file Supply.java
  *
- * @author Christos Choutouridis AEM:8997
+ * @author
- * @email  cchoutou@ece.auth.gr
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
  */
 
-package net.hoo2.auth.labyrinth;
+package host.labyrinth;
 
 /**
  * @brief
@@ -76,7 +78,7 @@ class Supply {
    int supplyId ()        { return supplyId; }
    /**
     * Set the supplyId
-    * @param   sId   The Id to set
+    * @param   sID   The Id to set
     * @return  The supplyId
     * @note    This function also returns the supplyId to help in chained expressions.
     */

src/host/labyrinth/Tile.java

@@ -1,11 +1,13 @@
 /**
  * @file Tile.java
  *
- * @author Christos Choutouridis AEM:8997
+ * @author
- * @email  cchoutou@ece.auth.gr
+ *    Christos Choutouridis
+ *    <cchoutou@ece.auth.gr>
+ *    AEM:8997
  */
 
-package net.hoo2.auth.labyrinth;
+package host.labyrinth;
 
 /**
  * @brief
@@ -132,7 +134,7 @@ class Tile {
 
    /**
     * Sets the tile's wall in the requested direction.
-    * @param up      The direction for the wall.
+    * @param direction  The direction for the wall.
     */
    void setWall (int direction) {
       switch (direction) {
@@ -145,7 +147,7 @@ class Tile {
 
    /**
     * Clears the tile's wall in the requested direction.
-    * @param up      The direction for the wall 
+    * @param direction  The direction for the wall 
     */
    void clearWall (int direction) {
       switch (direction) {