Moves AlphaBetaState to transposition package. Adds javadoc

Author: fathzer

pom.xml

@@ -50,7 +50,7 @@
 		<dependency>
 			<groupId>org.mockito</groupId>
 			<artifactId>mockito-junit-jupiter</artifactId>
-			<version>5.1.1</version>
+			<version>5.16.0</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
@@ -66,4 +66,31 @@
 			<scope>test</scope>
 		</dependency>
 	</dependencies>
+	
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>3.6.3</version>
+				<configuration>
+					<source>8</source>
+					<docencoding>UTF-8</docencoding>
+					<overview>${basedir}/overview.html</overview>
+					<header>${project.version}</header>
+					<bottom>${project.version}</bottom>
+					<excludePackageNames>:*.experimental</excludePackageNames>
+				</configuration>
+				<executions>
+					<execution>
+						<id>javadoc_generation</id>
+						<phase>package</phase>
+						<goals>
+							<goal>jar</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
 </project>

src/main/java/com/fathzer/games/Status.java

@@ -3,7 +3,14 @@
 /** The status of a game (playing, draw, white or black won).
  */
 public enum Status {
-	PLAYING, DRAW, WHITE_WON, BLACK_WON;
+	/** The game is still playing */
+	PLAYING, 
+	/** The game ends with a draw */
+	DRAW, 
+	/** The white player has won */
+	WHITE_WON, 
+	/** The black player has won */
+	BLACK_WON;
 
 	/** Gets the winner's color.
 	 * @return A color or null if there's no winner

src/main/java/com/fathzer/games/ai/AlphaBetaState.java

@@ -9,6 +9,7 @@
 import com.fathzer.games.ai.evaluation.EvaluatedMove;
 import com.fathzer.games.ai.evaluation.Evaluator;
 import com.fathzer.games.ai.evaluation.QuiesceEvaluator;
+import com.fathzer.games.ai.transposition.AlphaBetaState;
 import com.fathzer.games.ai.transposition.EntryType;
 import com.fathzer.games.ai.transposition.TTAi;
 import com.fathzer.games.ai.transposition.TranspositionTable;
@@ -24,6 +25,9 @@ public class Negamax<M,B extends MoveGenerator<M>> extends AbstractAI<M,B> imple
     private TranspositionTable<M, B> transpositionTable;
     private QuiesceEvaluator<M,B> quiesceEvaluator;
 
+	/** Constructor
+	 * @param exec The execution context
+	 */
 	public Negamax(ExecutionContext<SearchContext<M,B>> exec) {
 		super(exec);
 		quiesceEvaluator = (ctx, depth, alpha, beta) -> {

src/main/java/com/fathzer/games/ai/Negamax.java

@@ -22,18 +22,32 @@ private SearchContext(B gamePosition, Evaluator<M, B> evaluator, SearchStatistic
 		this.statistics = statistics;
 	}
 
+	/** Gets the game position.
+	 * @return a {@link MoveGenerator} instance
+	 */
 	public B getGamePosition() {
 		return gamePosition;
 	}
 
+	/** Gets the evaluator.
+	 * @return an evaluator instance
+	 */
 	public Evaluator<M, B> getEvaluator() {
 		return evaluator;
 	}
 
+	/** Gets the search statistics.
+	 * @return a {@link SearchStatistics} instance
+	 */
 	public SearchStatistics getStatistics() {
 		return statistics;
 	}
 
+	/** Makes a move.
+	 * @param move The move to make
+	 * @param confidence The confidence of the move
+	 * @return true if the move was made, false otherwise (if it was illegal)
+	 */
 	public boolean makeMove(M move, MoveGenerator.MoveConfidence confidence) {
 		evaluator.prepareMove(gamePosition, move);
 		if (gamePosition.makeMove(move, confidence)) {
@@ -43,6 +57,7 @@ public boolean makeMove(M move, MoveGenerator.MoveConfidence confidence) {
 		return false;
 	}
 
+	/** Unmakes the last move. */
 	public void unmakeMove() {
 		evaluator.unmakeMove();
 		gamePosition.unmakeMove();
@@ -56,6 +71,13 @@ public SearchContext<M, B> fork() {
 		return new SearchContext<>(mg, ev, statistics);
 	}
 
+	/** Gets a new search context.
+	 * @param board The game position
+	 * @param evaluatorBuilder A supplier that can create an evaluator
+	 * @param <M> The type of moves
+	 * @param <B> The type of the move generator
+	 * @return a new search context
+	 */
 	public static <M, B extends MoveGenerator<M>> SearchContext<M, B> get(B board, Supplier<Evaluator<M, B>> evaluatorBuilder) {
 		@SuppressWarnings("unchecked")
 		final B b = (B) board.fork();

src/main/java/com/fathzer/games/ai/SearchContext.java

@@ -8,6 +8,7 @@
 import com.fathzer.games.util.SortedUtils;
 
 /** The result of a best move search.
+ * @param <M> The type of moves
  */
 public final class SearchResult<M> {
 	private final LinkedList<EvaluatedMove<M>> result;

src/main/java/com/fathzer/games/ai/SearchResult.java

@@ -6,6 +6,12 @@
 
 import com.fathzer.games.MoveGenerator;
 
+/**
+ * A spy that can be used to monitor the search process of {@link Negamax3}.
+ * <br>It is called by the search process at various points.
+ * @param <M> The type of the moves
+ * @param <B> The type of the {@link MoveGenerator} to use
+ */
 public abstract class KeyBasedNegaMaxSpyFilter<M,B extends MoveGenerator<M>> {
 	private int enteringDepth=-1;
 	private final long searchedKey;

src/main/java/com/fathzer/games/ai/experimental/KeyBasedNegaMaxSpyFilter.java

@@ -8,13 +8,13 @@
 import com.fathzer.games.MoveGenerator.MoveConfidence;
 import com.fathzer.games.HashProvider;
 import com.fathzer.games.MoveGenerator;
-import com.fathzer.games.ai.AlphaBetaState;
 import com.fathzer.games.ai.Negamax;
 import com.fathzer.games.ai.SearchContext;
 import com.fathzer.games.ai.DepthFirstSearchParameters;
 import com.fathzer.games.ai.SearchResult;
 import com.fathzer.games.ai.evaluation.EvaluatedMove;
 import com.fathzer.games.ai.evaluation.Evaluator;
+import com.fathzer.games.ai.transposition.AlphaBetaState;
 import com.fathzer.games.ai.transposition.EntryType;
 import com.fathzer.games.ai.transposition.TranspositionTableEntry;
 import com.fathzer.games.util.exec.ExecutionContext;

src/main/java/com/fathzer/games/ai/experimental/Negamax3.java

@@ -3,17 +3,73 @@
 import java.util.List;
 
 import com.fathzer.games.MoveGenerator;
-import com.fathzer.games.ai.AlphaBetaState;
+import com.fathzer.games.ai.transposition.AlphaBetaState;
+import com.fathzer.games.ai.transposition.TranspositionTablePolicy;
 
+/** A spy that can be used to monitor the search process of {@link Negamax3}.
+ * <br>It is called by the search process at various points.
+ * @param <M> The type of the moves
+ * @param <B> The type of the {@link MoveGenerator} to use
+ */
 public interface Spy<M, B extends MoveGenerator<M>> {
-	public enum Event {EVAL, END_GAME, EXIT, TT}
+	/** The events that triggers the end of search at a depth. */
+	public enum Event {
+		/** The search process reached the max depth and computed a new evaluation. */
+		EVAL,
+		/** The search process has reached a terminal game state. */
+		END_GAME,
+		/** The search process has exited because there are no more moves to play. */
+		EXIT,
+		/** The search process has found an evaluation from the transposition table. */
+		TT
+	}
 
+	/** Called when the search process enters a new depth.
+	 * @param state The state of the search process
+	 */
 	default void enter(TreeSearchStateStack<M,B> state) {}
+	
+	/** Called when alpha/beta value is found in the transposition table.
+	 * @param state The state of the search process
+	 * @param abState The alpha/beta state
+	 */
 	default void alphaBetaFromTT(TreeSearchStateStack<M,B> state, AlphaBetaState<M> abState) {}
+	
+	/** Called when a state was sent to the transposition table (even if it is rejected by its {@link TranspositionTablePolicy}
+	 * @param state The state of the search process
+	 * @param abState The alpha/beta state
+	 * @param store true if the state is stored, false if it is rejected by the policy
+	 */
 	default void storeTT(TreeSearchStateStack<M,B> state, AlphaBetaState<M> abState, boolean store) {}
+	
+	/** Called when a tree cut occurs.
+	 * @param state The state of the search process
+	 * @param move The move that triggered the cut
+	 */
 	default void cut(TreeSearchStateStack<M,B> state, M move) {}
+	
+	/** Called when the search process exits a depth.
+	 * @param state The state of the search process
+	 * @param evt The event that triggered the exit
+	 */
 	default void exit(TreeSearchStateStack<M,B> state, Event evt) {}
+	
+	/** Called when a move is unmade.
+	 * @param state The state of the search process
+	 * @param moves The list of moves
+	 * @param move The move that was unmade
+	 */
 	default void moveUnmade(TreeSearchStateStack<M, B> state, List<M> moves, M move) {}
+	
+	/** Called when the moves are computed.
+	 * @param searchStack The search stack
+	 * @param moves The list of moves
+	 */
 	default void movesComputed(TreeSearchStateStack<M, B> searchStack, List<M> moves) {}
+	
+	/** Called when an exception is thrown.
+	 * @param searchStack The search stack
+	 * @param e The exception
+	 */
 	default void exception(TreeSearchStateStack<M, B> searchStack, RuntimeException e) {}
 }