Some documenttion.

refs #1.

Author: portnov

src/AI/AlphaBeta.hs

@@ -4,6 +4,12 @@
 {-# LANGUAGE DeriveDataTypeable #-}
 {-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE FlexibleInstances #-}
+
+{-
+ - This module contains an implementation of alpha-beta-pruning algorithm
+ - with small improvements.
+ -}
+
 module AI.AlphaBeta where
 
 import Control.Monad
@@ -101,6 +107,7 @@ putMoves First board moves memo =
 putMoves Second board moves memo =
   memo {mmSecond = putBoardMap board moves (mmSecond memo)}
 
+-- | Calculate score of the board
 doScore :: (GameRules rules, Evaluator eval) => rules -> eval -> AICacheHandle rules -> AlphaBetaParams -> Side -> DepthParams -> Board -> Checkers Score
 doScore rules eval var params side dp board =
     fixSign <$> evalStateT (cachedScoreAB var params side dp (-max_score) max_score board) initState
@@ -150,13 +157,15 @@ instance HasLogContext (StateT (ScoreState rules eval) Checkers) where
     put st'
     return result
 
+-- | Calculate score of the board. 
+-- This uses the cache. It is called in the recursive call also.
 cachedScoreAB :: forall rules eval. (GameRules rules, Evaluator eval)
               => AICacheHandle rules
               -> AlphaBetaParams
               -> Side
               -> DepthParams
-              -> Score
-              -> Score
+              -> Score        -- ^ Alpha
+              -> Score        -- ^ Beta
               -> Board
               -> ScoreM rules eval Score
 cachedScoreAB var params side dp alpha beta board = do
@@ -179,6 +188,12 @@ cachedScoreAB var params side dp alpha beta board = do
 isTargetDepth :: DepthParams -> Bool
 isTargetDepth dp = dpCurrent dp >= dpTarget dp
 
+-- | Increase current depth as necessary.
+-- If there is only 1 move currently possible, this can increase
+-- the target depth, up to dpMax.
+-- If there are a lot of moves possible, this can decrease the
+-- target depth, down to dpMin.
+-- Otherwise, this just increases dpCurrent by 1.
 updateDepth :: (Monad m, HasLogging m, MonadIO m) => Int -> DepthParams -> m DepthParams
 updateDepth nMoves dp
   | nMoves == 1 = do
@@ -195,17 +210,19 @@ updateDepth nMoves dp
                 return $ dp {dpCurrent = dpCurrent dp + 1, dpTarget = target}
   | otherwise = return $ dp {dpCurrent = dpCurrent dp + 1}
 
+-- | Calculate score for the board
 scoreAB :: forall rules eval. (GameRules rules, Evaluator eval)
         => AICacheHandle rules
         -> AlphaBetaParams
         -> Side
         -> DepthParams
-        -> Score
-        -> Score
+        -> Score        -- ^ Alpha
+        -> Score        -- ^ Beta
         -> Board
         -> ScoreM rules eval (Score, [Move])
 scoreAB var params side dp alpha beta board
   | isTargetDepth dp = do
+      -- target depth is achieved, calculate score of current board directly
       evaluator <- gets ssEvaluator
       let score0 = evalBoard evaluator First side board
       $trace "    X Side: {}, A = {}, B = {}, score0 = {}" (show side, alpha, beta, score0)
@@ -216,6 +233,7 @@ scoreAB var params side dp alpha beta board
       $trace "{}V Side: {}, A = {}, B = {}" (indent, show side, alpha, beta)
       moves <- possibleMoves' board
 
+      -- this actually means that corresponding side lost.
       when (null moves) $
         $trace "{}| No moves left." (Single indent)
 

src/AI/AlphaBeta/Cache.hs

@@ -33,6 +33,8 @@ import Core.Parallel
 import AI.AlphaBeta.Types
 import AI.AlphaBeta.Persistent
 
+-- | Prepare AI storage instance.
+-- This also contains Processor instance with several threads.
 loadAiCache :: GameRules rules
             => (ScoreMoveInput rules -> Checkers (Move, Score))
             -> AlphaBeta rules
@@ -164,6 +166,8 @@ normalize bsize (bc,bk,side) =
         then (bc', bk', opposite side)
         else (bc, bk, side)
 
+-- | Look up for item in the cache. First lookup in the memory,
+-- then in the file (if it is open).
 lookupAiCache :: GameRules rules => AlphaBetaParams -> Board -> Int -> Side -> AICacheHandle rules -> Checkers (Maybe CacheItemSide)
 lookupAiCache params board depth side handle = do
     -- let bsize = boardSize (aichRules handle)
@@ -215,6 +219,9 @@ lookupAiCache params board depth side handle = do
                                  Second -> return $ ciSecond item
         else return Nothing
 
+-- | Put an item to the cache.
+-- It is always writen to the memory,
+-- and it is writen to the file if it is open.
 putAiCache' :: GameRules rules => AlphaBetaParams -> (BoardCounts,BoardKey) -> Int -> Side -> StorageValue -> AICacheHandle rules -> Checkers ()
 putAiCache' params (bc,bk) depth side sideItem handle = do
   let bsize = boardSize (aichRules handle)

src/AI/AlphaBeta/Types.hs

@@ -47,11 +47,12 @@ instance Default AlphaBetaParams where
         , abCombinationDepth = 8
         }
 
+-- Calculation depth parameters
 data DepthParams = DepthParams {
-    dpTarget :: Int
-  , dpCurrent :: Int
-  , dpMax :: Int
-  , dpMin :: Int
+    dpTarget :: Int     -- ^ Target depth: how deep we currently want to calculate the tree
+  , dpCurrent :: Int    -- ^ Currently achieved depth
+  , dpMax :: Int        -- ^ Maximum allowed depth
+  , dpMin :: Int        -- ^ Minimum allowed depth
   }
   deriving (Eq, Show)
 
@@ -104,6 +105,8 @@ data Locks = Locks {
   , lBlockLocks :: TVar (M.Map IndexBlockNumber RWL.RWLock)
   }
 
+-- | Handle to the instance of AI storage
+-- and related structures
 data AICacheHandle rules = AICacheHandle {
     aichRules :: rules
   , aichData :: TVar (AICache rules)
@@ -118,6 +121,7 @@ type WriteQueue = TChan (BoardKey, Int, Side, StorageValue)
 
 type CleanupQueue = TVar (PQ.HashPSQ QueueKey TimeSpec ())
 
+-- | File handle
 data FHandle = FHandle {
     fhOffset :: FileOffset
   , fhHandle :: Fd