[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    KDE/kdegames/kjumpingcube
From:       Ian Wadham <iandw.au () gmail ! com>
Date:       2012-07-29 7:30:18
Message-ID: 20120729073018.CB94EAC7A9 () svn ! kde ! org
[Download RAW message or body]

SVN commit 1308252 by ianw:

Add API documentation for the Kepler, Newton and base AI classes.

 M  +4 -8      ai_base.h  
 M  +30 -10    ai_kepler.h  
 M  +28 -10    ai_newton.h  


--- trunk/KDE/kdegames/kjumpingcube/ai_base.h #1308251:1308252
@@ -30,17 +30,13 @@
 class AI_Base
 {
 public:
-   /**
-   * @param initValue value to initialize the random number generator with
-   *        if no value is given a truly random value is used
-   */
    AI_Base()          {};
    virtual ~AI_Base() {};
 
    /**
    * Assess the priority of playing a cube at a particular position.  The
-   * highest priority cubes are used in look-ahead moves and calculating the
-   * values of the positions reached.
+   * highest priority cubes are used by the Brain class for look-ahead moves
+   * and calculating the values of the positions reached.
    *
    * @param row      The row-position of the cube
    * @param col      The column-position of the cube
@@ -55,8 +51,8 @@
 
    /**
     * Assess the value of a position reached after trying a move.  The move that
-    * leads to the highest value is chosen by the caller or a random choice is
-    * made among moves leading to positions of equal value.
+    * leads to the highest value is chosen by the Brain class or a random choice
+    * is made among moves leading to positions of equal value.
     *
     * @param player  The player whose position is to be assessed
     * @param box     The state of the whole grid of cubes in the box
--- trunk/KDE/kdegames/kjumpingcube/ai_kepler.h #1308251:1308252
@@ -28,29 +28,49 @@
 class CubeBox;
 
 /**
-* Class AI_Kepler computes a (good) possibility to move
-* for a given playingfield.
+* Class AI_Kepler computes the value of moving a cube and the value of the
+* resulting position.  It assists the Brain class and contains the original
+* algorithms from the Brain and CubeBox classes.
 *
-* It puts a value on every cube by looking at its neighbours
-* and searches the best cubes to move. It then simulates what would
-* happen, if you would click on these cubes. This is done recursively
-* to a certain depth and the playingfield will be valued.
-*
-* @short The games brain
+* @short The Kepler AI algorithms
 */
 class AI_Kepler : public AI_Base
 {
 public:
    /**
-   * @param initValue value to initialize the random number generator with
-   *        if no value is given a truly random value is used
+   * The Kepler AI constructor.
    */
    AI_Kepler();
 
+   /**
+   * Assess the value of playing a cube at a particular position.  The
+   * lowest-value cubes are used by the Brain class for look-ahead moves
+   * and calculating the values of the positions reached.
+   *
+   * @param row      The row-position of the cube
+   * @param col      The column-position of the cube
+   * @param player   The player who is to move
+   * @param box      The whole grid of cubes in the box
+   *
+   * @return         < 0 - The move is invalid or wasteful
+   *                 > 0 - The value of a useful move (1 is best)
+   */
    int    assessCube (int row,int column,CubeBox::Player,CubeBox& box) const;
+
+   /**
+    * Assess the value of a position reached after trying a move.  The move that
+    * leads to the highest value is chosen by the Brain class or a random choice
+    * is made among moves leading to positions of equal value.
+    *
+    * @param player  The player whose position is to be assessed
+    * @param box     The state of the whole grid of cubes in the box
+    *
+    * @return        The value of the position
+    */
    double assessField (CubeBox::Player forWhom, CubeBox& box) const;
 
 private:
+   // A helper method for assessCube().
    int getDiff(int row,int column, CubeBox::Player player, CubeBox& box) const;
 };
 
--- trunk/KDE/kdegames/kjumpingcube/ai_newton.h #1308251:1308252
@@ -28,26 +28,44 @@
 class CubeBox;
 
 /**
-* Class AI_Newton computes a (good) possibility to move
-* for a given playingfield.
+* Class AI_Newton computes the priority of moving a cube and the value of the
+* resulting position.  It assists the Brain class.
 *
-* It puts a value on every cube by looking at its neighbours
-* and searches the best cubes to move. It then simulates what would
-* happen, if you would click on these cubes. This is done recursively
-* to a certain depth and the playingfield will be valued.
-*
-* @short The games brain
+* @short The Newton AI algorithms
 */
 class AI_Newton : public AI_Base
 {
 public:
    /**
-   * @param initValue value to initialize the random number generator with
-   *        if no value is given a truly random value is used
+   * The Newton AI constructor.
    */
    AI_Newton();
 
+   /**
+   * Assess the priority of playing a cube at a particular position.  The
+   * highest priority cubes are used by the Brain class for look-ahead moves
+   * and calculating the values of the positions reached.
+   *
+   * @param row      The row-position of the cube
+   * @param col      The column-position of the cube
+   * @param player   The player who is to move
+   * @param box      The whole grid of cubes in the box
+   *
+   * @return         < 0 - The move is invalid or wasteful
+   *                 > 0 - The priority of a useful move (1 is highest)
+   */
    int    assessCube (int row,int column,CubeBox::Player,CubeBox& box) const;
+
+   /**
+    * Assess the value of a position reached after trying a move.  The move that
+    * leads to the highest value is chosen by the Brain class or a random choice
+    * is made among moves leading to positions of equal value.
+    *
+    * @param player  The player whose position is to be assessed
+    * @param box     The state of the whole grid of cubes in the box
+    *
+    * @return        The value of the position
+    */
    double assessField (CubeBox::Player forWhom, CubeBox& box) const;
 };
 
[prev in list] [next in list] [prev in thread] [next in thread]