Add classes and method documentation

src/classes/Engines.py

@@ -1,6 +1,17 @@
 import random, math, time, signal
 
+"""
+Base player engine
+"""
 class PlayerEngine:
+
+    """
+    init
+    @param player: black or white player
+    @param logger: loggig object (display verbose / debug messages
+    @param heuristic: HeuristicClass object to calculate tree heuristic
+    @param options: hashtable containing options
+    """
     def __init__(self, player, logger, heuristic, options: dict = {}):
         # init logger do display informations
         self.player = player
@@ -12,30 +23,66 @@ class PlayerEngine:
             self.__class__.__name__,
             self.options
         ))
-
+    
+    """
+    get move
+    @param board: Board
+    """
     def get_move(self, board):
         self.logger.info("engine: {} - player:{}".format(
             self.__class__.__name__, 
             self.get_player_name(self.player)
         ))
     
+    """
+    Get possibles player move an apply a Random.shuffle on it (if needed)
+    @param none
+    @return: array
+    """
     def get_player_moves(self, board):
         moves = board.legal_moves()
         if self.options['randomize_moves'] is True:
             random.shuffle(moves)
         return moves
-
+    
+    """
+    Get player name based on his number
+    @param player: int
+    @return: string
+    """
     @staticmethod
     def get_player_name(player):
         return 'White (O)' if player == 2 else 'Black (X)'
 
+
+"""
+Random game engine
+"""
 class RandomPlayerEngine(PlayerEngine):
+
+
+    """
+    Get move return a random move based on Board.legal_moves
+    @param player: int
+    @return: array
+    """
     def get_move(self, board):
         super().get_move(board)
         moves = board.legal_moves()
         return random.choice(moves)
 
+
+"""
+Human player engine.
+"""
 class HumanPlayerEngine(PlayerEngine):
+
+
+    """
+    Get move return a move based on user input
+    @param board: Board
+    @return: array
+    """
     def get_move(self, board):
         super()
         move = None
@@ -46,6 +93,12 @@ class HumanPlayerEngine(PlayerEngine):
             move = self.validate_input(user_input, board)
         return move
 
+    
+    """
+    Validate user input an verify than the move is possible
+    @param input: string
+    @return: array
+    """
     @staticmethod
     def validate_input(input, board):
         if input == 'print':
@@ -66,13 +119,31 @@ class HumanPlayerEngine(PlayerEngine):
 
         return [board._nextPlayer, x, y]
 
+
+"""
+MinMax player engine
+"""
 class MinmaxPlayerEngine(PlayerEngine):
 
+
+    """
+    Get move based on minmax algorithm
+    @param board: Board
+    @return: array
+    """
     def get_move(self, board):
         super().get_move(board)
         move, score = self._call(board, self.options['depth'])
         return move
 
+
+    """
+    First part of the minmax algorithm, it get the best player move based on
+    max value
+    @param board: Board
+    @param depth: search depth
+    @return: move and max heuristic
+    """
     def _call(self, board, depth):
         value = -math.inf
         nodes = 1
@@ -100,6 +171,13 @@ class MinmaxPlayerEngine(PlayerEngine):
         ))
         return move, value
 
+    """
+    recursive function to apply minmax
+    @param board: Board
+    @param friend_move: boolean does function maximise (player turn) or not (opponent turn)
+    @param depth: search depth
+    @return: heuristic score, nodes ans leafs processed 
+    """
     def checkMinMax(self, board, friend_move:bool, depth :int = 2):
         nodes = 1
         leafs = 0
@@ -140,6 +218,13 @@ class AlphabetaPlayerEngine(PlayerEngine):
         move, heuristic = self._call(board, self.options['depth'])
         return move
 
+    """
+    First part of the alphabeta algorithm, it get the best player move based on
+    max value
+    @param board: Board
+    @param depth: search depth
+    @return: move and max heuristic
+    """
     def _call(self, board, depth):
         self.logger.debug("Enter AlphaBeta function")
         alpha = -math.inf
@@ -169,7 +254,13 @@ class AlphabetaPlayerEngine(PlayerEngine):
         ))
         return move, alpha
 
-
+    """
+    recursive function to apply alphabeta
+    @param board: Board
+    @param friend_move: boolean does function maximise (player turn) or not (opponent turn)
+    @param depth: search depth
+    @return: heuristic score, nodes ans leafs processed 
+    """
     def checkAlphaBeta(self, board, friend_move : bool, depth, alpha, beta):
         nodes = 1
         leafs = 0
@@ -206,7 +297,11 @@ class AlphabetaPlayerEngine(PlayerEngine):
 
 
 class MinmaxDeepeningPlayerEngine(MinmaxPlayerEngine):
-
+    """
+    Get move based on minmax algorithm with iterative deepening
+    @param board: Board
+    @return: array
+    """
     def get_move(self, board):
         super().get_move(board)
         self.interrupt_search = False
@@ -251,7 +346,11 @@ class MinmaxDeepeningPlayerEngine(MinmaxPlayerEngine):
 
 class AlphaBetaDeepeningPlayerEngine(AlphabetaPlayerEngine):
 
-
+    """
+    Get move based on alphabeta algorithm with iterative deepening
+    @param board: Board
+    @return: array
+    """
     def get_move(self, board):
         self.interrupt_search = False
         
@@ -284,6 +383,9 @@ class AlphaBetaDeepeningPlayerEngine(AlphabetaPlayerEngine):
         ))
         return move
 
+    """
+    define an handler for the alarm signal
+    """
     def alarm_handler(self, signal, frame):
         self.logger.debug("Raise SIGALMR Signal")
         self.interrupt_search = True