From d2c08d60c587aab6288ab014426d0ee9a15eef51 Mon Sep 17 00:00:00 2001
From: djib <me@djib.fr>
Date: Tue, 10 Jan 2006 15:39:55 +0000
Subject: [PATCH] Perfecting comments to be able to create a javadoc.

---
 src/suicideChess/Board.java        | 69 +++++++++++++++---------
 src/suicideChess/Move.java         | 85 +++++++++++++++++++++++-------
 src/suicideChess/Piece.java        | 46 ++++++++++------
 src/suicideChess/Square.java       | 33 +++++++++---
 src/suicideChess/SuicideChess.java | 33 ++++++------
 5 files changed, 186 insertions(+), 80 deletions(-)

diff --git a/src/suicideChess/Board.java b/src/suicideChess/Board.java
index b415e28..e5c298d 100644
--- a/src/suicideChess/Board.java
+++ b/src/suicideChess/Board.java
@@ -3,25 +3,23 @@ package suicideChess;
 import suicideChess.Square.NotAValidSquare;
 
 /**
- * @author djib
- * 
- * This file contains the board representation.
+ * This class contains the board representation.
  * The board is represented using bitboards.
- * a1 is square 0
- * h8 is square 7
- * a2 is square 8
- * ... and so on 
+ * <ul><li>a1 is square 0</li>
+ * <li>h8 is square 7</li>
+ * <li>a2 is square 8</li>
+ * <li>... and so on</li> 
+ * 
+ * @author Jean-Baptiste H&eacute;tier
+ * @version $LastChangedRevision$, $LastChangedDate$
  * 
- * $LastChangedDate$
- * $LastChangedRevision$
- * $LastChangedBy$
  */
 
 public class Board {
 
-	/*************
+	/*===========*
 	 * CONSTANTS *
-	 *************/
+	 *===========*/
 	
 	//Some constants to make code more readable
 	public static final int NB_OF_RANKS = 8;
@@ -31,7 +29,7 @@ public class Board {
 	private static final int NB_OF_BITBOARDS = 14;
 	
 	public class NoPieceOnSquare extends Exception {
-		/**
+		/*
 		 * Added by Eclipse
 		 */
 		private static final long serialVersionUID = -2750943856086117656L;
@@ -40,9 +38,9 @@ public class Board {
 	}
 	
 		
-	/********
+	/*======*
 	 * DATA *
-	 ********/
+	 *======*/
 	
 	//The following table is used to map squares to bits
 	protected static long mapSquaresToBits[];
@@ -58,10 +56,17 @@ public class Board {
 	//The following table contains all the bit boards
 	protected long bitBoards[];
 	
-	/***************
+	
+	
+	
+	/*=============*
 	 * CONSTRUCTOR *
-	 * @throws NotAValidSquare 
-	 ***************/
+	 *=============*/
+	
+	/**
+	 * Constructor of the class Board
+	 * @throws NotAValidSquare
+	 */
 	
 	public Board() throws NotAValidSquare {
 		bitBoards = new long[NB_OF_BITBOARDS];
@@ -104,9 +109,16 @@ public class Board {
 	}
 	
 	
-	/******************
+	/*================*
 	 * PUBLIC METHODS *
-	 ******************/
+	 *================*/
+	
+	/**
+	 * This methods takes a {@link Move} and applies it (updating the bitboard)
+	 * @param move The move that is to be done
+	 * @throws NoPieceOnSquare If a piece is trying to be moved from a square that does not exist.
+	 * @see Move
+	 */
 	
 	public void doMove(Move move) throws NoPieceOnSquare {
 		if (move.isCaptureMove()) {
@@ -120,7 +132,13 @@ public class Board {
         }
 	}
 
-	//this function searchs for what piece is on a square
+	/**
+	 * This function searchs for what piece is on a square.
+	 * @param onSquare The Square on which we will look for a piece.
+	 * @return a {@link Piece}
+	 * @see Square
+	 * @see Piece
+	 */
 	public Piece getPiece(Square onSquare) {
 		//if there is a corresponding white piece.
 		if (!isEmpty(onSquare, new Piece(Piece.WHITE_PIECES))) {
@@ -143,7 +161,10 @@ public class Board {
 	}
 
 	
-	//this function can be used to display the board
+	/**
+	 * This function can be used to display the board
+	 * Black pieces are displayed in uppercase letters.
+	 */
 	public void display(){
 		for (int file = NB_OF_FILES; file >= 1; file--) {
 			System.out.println("+---+---+---+---+---+---+---+---+");
@@ -209,9 +230,9 @@ public class Board {
 	}
 
 	
-	/*******************
+	/*=================*
 	 * PRIVATE METHODS *
-	 *******************/
+	 *=================*/
 
 	
 /*	private long getBitBoard(int bitboard_number) {
diff --git a/src/suicideChess/Move.java b/src/suicideChess/Move.java
index c3114d1..946b139 100644
--- a/src/suicideChess/Move.java
+++ b/src/suicideChess/Move.java
@@ -3,20 +3,17 @@ package suicideChess;
 import suicideChess.Square.NotAValidSquare;
 
 /**
- * @author djib
+ * This class is used for moves representation.
  * 
- * This file contains the moves representation.
- * 
- * $LastChangedDate$
- * $LastChangedRevision$
- * $LastChangedBy$
+ * @author Jean-Baptiste H&eacute;tier
+ * @version $LastChangedRevision$, $LastChangedDate$
  */
 
 public class Move {
 
-	/********
+	/*======*
 	 * DATA *
-	 ********/
+	 *======*/
 	
 	//integers 
 	private Piece movingPiece;
@@ -38,11 +35,20 @@ public class Move {
 		NotAValidMoveException(String s) { super(s); };
 	}
 	
-	/***************
+	/*=============*
 	 * CONSTRUCTOR *
-	 ***************/
-	
-	//The string is of type e2e4 (4 chars), b7b8q (5 chars) for promotions
+	 *=============*/
+
+	/**
+	 * This is the constructor of the class.
+	 * 
+	 * @param move A String containing of type "e2e4" (4 chars), "b7b8q" (5 chars) for promotions.
+	 * It is the standard algebraic notation used for chess.
+	 * @param board A {@link Board} to be able to locate the pieces.
+	 * @throws NotAValidMoveException When the String is not legal (too long or too short).
+	 * @throws NotAValidSquare It the String is not legal (not standard algebraic notation).
+	 * @see Board
+	 */
 	public Move(String move, Board board) throws NotAValidMoveException, NotAValidSquare {
 		isPromotion = false;
 		
@@ -73,9 +79,9 @@ public class Move {
 	}
 	
 	
-	/*********************************************
+	/*===========================================*
 	 * Those two constructors are no longer used *
-	 *********************************************/
+	 *===========================================*/
 	/*
 	//non capture move
 	public Move(String move, Piece pieceToMove) throws NotAValidMoveException, NotAValidSquare {
@@ -121,19 +127,41 @@ public class Move {
 	*/
 	
 	
-	/***********
+	/*=========*
 	 * METHODS *
-	 ***********/
+	 *=========*/
 	
+	/**
+	 * Returns the {@link Square} to move from in a Move
+	 * @return Square
+	 * @see Square 
+	 */
 	public Square fromSquare() {
 		return fromSquare;
 	}
+
+	/**
+	 * Returns the {@link Square} to move to in a Move
+	 * @return Square
+	 * @see Square 
+	 */
 	public Square toSquare() {
 		return toSquare;
 	}
+	
+	/**
+	 * Returns a boolean saying if a Move is a promotion or not.
+	 * @return boolean
+	 */
 	public boolean isPromotionMove() {
 		return isPromotion;
 	}
+	
+	/**
+	 * Returns the promotion {@link Piece} of a Move
+	 * @return Piece
+	 * @see Piece
+	 */
 	public Piece getPromotionPiece() {
 		if (isPromotion) {
 			return promotionPiece;
@@ -142,23 +170,42 @@ public class Move {
 		}
 	}
 	
+	/**
+	 * Returns the moving {@link piece} of a Move.
+	 * @return Piece
+	 * @see Piece
+	 */
 	public Piece getMovingPiece() {
 		return movingPiece;
 	}
 	
+	/** 
+	 * Returns a boolean saying if a Move is a capture move
+	 * @return boolean
+	 */
 	public boolean isCaptureMove() {
 		return isCapture;
 	}
 	
+	/**
+	 * Returns the {@link Piece} to be captured in a Move 
+	 * @return Piece
+	 */
 	public Piece getCapturedPiece() {
 		return capturePiece;
 	}
 	
+	/**
+	 * Converts a Move into a String.
+	 * @return String 
+	 */
 	public String toString() {
 		return fromSquare.toString()+toSquare+promotionPiece;
 	}
 
-	//Used for debugging mainly
+	/**
+	 * Displays a move in great details.
+	 */
 	public void display() {
 		System.out.println(" ");
 		System.out.println("==== Move ====");
@@ -173,9 +220,9 @@ public class Move {
 	}
 	
 	
-	/****************************************
+	/*======================================*
 	 * I do not use those functions anymore *
-	 ****************************************
+	 *======================================*
 	
 	public void setFromSquare(Square square) {
 		fromSquare = square;
diff --git a/src/suicideChess/Piece.java b/src/suicideChess/Piece.java
index 2890006..2b70751 100644
--- a/src/suicideChess/Piece.java
+++ b/src/suicideChess/Piece.java
@@ -4,22 +4,19 @@
 package suicideChess;
 
 /**
- * @author djib
+ * This class is used for piece representation.
  * 
- * This file contains the moves representation.
- * 
- * $LastChangedDate$
- * $LastChangedRevision$
- * $LastChangedBy$
+ * @author Jean-Baptiste H&eacute;tier
+ * @version $LastChangedRevision$, $LastChangedDate$  
  */
 
 public class Piece {
-	/*************
+	/*===========*
 	 * CONSTANTS *
-	 *************/
+	 *===========*/
 	
 	
-	/**
+	/*
 	 * Take really good care if you want to change those values
 	 * Class BitBoard makes intensive use of those
 	 */
@@ -59,20 +56,31 @@ public class Piece {
 	//may be useful
 	public static final char PAWN_CHAR='p';
 	
-	/****************
+	/*==============*
 	 * PRIVATE DATA *
-	 ****************/
+	 *==============*/
 	
 	private int pieceNumber;
 	
-	/***************
+	/*=============*
 	 * CONSTRUCTOR *
-	 ***************/
+	 *=============*/
 	
+	/**
+	 * Construcs a Piece given a piece number. You should use the constants
+	 * declared in this class.
+	 * @param piece An integer corresponding to a Piece code.
+	 */
 	public Piece(int piece) {
 		pieceNumber = piece;
 	}
 	
+	/**
+	 * Construcs a Piece given its color and its standard algebaic name
+	 * (declared as constants in this file)
+	 * @param piece A character used to represent the Piece.
+	 * @param color The color of the piece. (See declared constants)
+	 */
 	public Piece(char piece, int color) {
 		pieceNumber = NONE;
 		switch (piece) {
@@ -97,14 +105,22 @@ public class Piece {
 		}
 	}
 		
-	/***********
+	/*=========*
 	 * METHODS *
-	 ***********/
+	 *=========*/
 	
+	/**
+	 * Returns an integer representing the color of the Piece.
+	 * @return An integer.
+	 */
 	public int getColor() {
 		return pieceNumber%2; //cf declaration of BLACK and WHITE above and the pieces above.
 	}
 	
+	/**
+	 * Returns an integer representing the Piece
+	 * @return An integer.
+	 */
 	public int getPieceNumber() {
 		return pieceNumber;
 	}
diff --git a/src/suicideChess/Square.java b/src/suicideChess/Square.java
index ea61dc6..8819cd9 100644
--- a/src/suicideChess/Square.java
+++ b/src/suicideChess/Square.java
@@ -1,13 +1,10 @@
 package suicideChess;
 
 /**
- * @author djib
+ * This class is used for square representation
  * 
- * This class avoids the use of strings for squares
- * 
- * $LastChangedDate$
- * $LastChangedRevision$
- * $LastChangedBy$
+ * @author Jean-Baptiste H&eacute;tier
+ * @version $LastChangedRevision$, $LastChangedDate$
  */
 
 
@@ -25,6 +22,11 @@ public class Square {
 		NotAValidSquare(String s) { super(s); };
 	}
 	
+	/**
+	 * Construcs a Square given a String ("a1", "b7", "g5", ...)
+	 * @param square A string representing the Square. 
+	 */
+	
 	public Square(String square) throws NotAValidSquare {
 		if (square.length()!=2 || !(Character.isLetter(square.toCharArray()[0])) || 
 				!(Character.isDigit(square.toCharArray()[1]))) {
@@ -45,16 +47,35 @@ public class Square {
 		}
 	}
 	
+	/**
+	 * Returns the file of a Square.
+	 * @return char representing the file
+	 */
+	
 	public char getFile() {
 		return file;
 	}
+	
+	/**
+	 * Returns the number of the Rank
+	 * @return int representing the rank
+	 */
 	public int getRank() {
 		return rank;
 	}
+	
+	/**
+	 * Returns the number of the File
+	 * @return int representing the file
+	 */
 	public int getFileNb() {
 		return fileNb;
 	}
 	
+	/**
+	 * Converts a Square back to a String
+	 * @return String
+	 */
 	public String toString() {
 		return String.valueOf(file)+String.valueOf(rank);
 	}
diff --git a/src/suicideChess/SuicideChess.java b/src/suicideChess/SuicideChess.java
index f4480d9..cc8fa27 100644
--- a/src/suicideChess/SuicideChess.java
+++ b/src/suicideChess/SuicideChess.java
@@ -7,33 +7,34 @@ import suicideChess.Move.NotAValidMoveException;
 import suicideChess.Square.NotAValidSquare;
 
 /**
- * @author djib
- * 
- * Main File
- * 
- * $LastChangedDate$
- * $LastChangedRevision$
- * $LastChangedBy$
+ * Main file (the game in itself)
+ * @author Jean-Baptiste H&eacute;tier
+ * @version $LastChangedRevision$, $LastChangedDate$
  */
 
 public class SuicideChess {
 
-	/**
+	/*
 	 * Those flags are used to perform extra checks during the debugging of the
 	 * program. They may be safely all set to false once the program is stable.
 	 * It should improve performance a lot.
 	 */
-	//does BitBoard.class removePiece function checks if removing piece is legal ? 
+	/**
+	 * does BitBoard.class removePiece function checks if removing piece is legal ?
+	 */ 
 	public static final boolean BITBOARD_REMOVEPIECE_CHECK_REMOVE = true;
-	//does Square.class checks if the strings are valid (is "z9" a valid square ?
+	/**
+	 * does Square.class checks if the strings are valid (is "z9" a valid square ? 
+	 */
 	public static final boolean SQUARE_CHECK_INVALID = true;
+
+	private static final int MAIN_VERSION_NUMBER = 0;
+	private static final int REVISION_NUMBER = 15;
 	
-	public static final int MAIN_VERSION_NUMBER = 0;
-	public static final int REVISION_NUMBER = 15;
-	
-	/*****************
-	 * MAIN FUNCTION *
-	 *****************/
+	/**
+	 * The main function
+	 * @param args No parameters should be transmitted to this function.
+	 */
 	public static void main(String[] args) {
 		System.out.println("Welcome to SuicideChess v"+MAIN_VERSION_NUMBER+"."+REVISION_NUMBER+"!");
 		BufferedReader moveInput = new BufferedReader(new InputStreamReader(System.in));