Add doxygen for Soccer and SpareTire AI

src/karts/controller/battle_ai.cpp

@@ -139,22 +139,22 @@ void BattleAI::findTarget()
     bool find_sta = false;
     if (m_world->spareTireKartsSpawned())
     {
-       switch (m_cur_difficulty)
+        switch (m_cur_difficulty)
-       {
+        {
-          case RaceManager::DIFFICULTY_EASY:
+            case RaceManager::DIFFICULTY_EASY:
-          case RaceManager::DIFFICULTY_MEDIUM:
+            case RaceManager::DIFFICULTY_MEDIUM:
-          {
+            {
-              find_sta = m_world->getKartLife(m_kart->getWorldKartId()) == 1;
+                find_sta = m_world->getKartLife(m_kart->getWorldKartId()) == 1;
-              break;
+                break;
-          }
+            }
-          case RaceManager::DIFFICULTY_HARD:
+            case RaceManager::DIFFICULTY_HARD:
-          case RaceManager::DIFFICULTY_BEST:
+            case RaceManager::DIFFICULTY_BEST:
-          {
+            {
-              find_sta = m_world->getKartLife(m_kart->getWorldKartId()) != 3;
+                find_sta = m_world->getKartLife(m_kart->getWorldKartId()) != 3;
-              break;
+                break;
-          }
+            }
-          default: assert(false);
+            default: assert(false);
-       }
+        }
     }
 
     bool consider_difficulty = !find_sta;

src/karts/controller/soccer_ai.cpp

@@ -71,7 +71,6 @@ SoccerAI::SoccerAI(AbstractKart *kart)
 }   // SoccerAI
 
 //-----------------------------------------------------------------------------
-
 SoccerAI::~SoccerAI()
 {
 #ifdef AI_DEBUG
@@ -103,6 +102,10 @@ void SoccerAI::reset()
 }   // reset
 
 //-----------------------------------------------------------------------------
+/** Update \ref m_front_transform for ball aiming functions, also make AI stop
+ *  after goal.
+ *  \param dt Time step size.
+ */
 void SoccerAI::update(float dt)
 {
 #ifdef BALL_AIM_DEBUG
@@ -129,6 +132,11 @@ void SoccerAI::update(float dt)
 }   // update
 
 //-----------------------------------------------------------------------------
+/** Find the closest kart around this AI, it won't find the kart with same
+ *  team, consider_difficulty and find_sta are not used here.
+ *  \param consider_difficulty If take current difficulty into account.
+ *  \param find_sta If find \ref SpareTireAI only.
+ */
 void SoccerAI::findClosestKart(bool consider_difficulty, bool find_sta)
 {
     float distance = 99999.9f;
@@ -163,6 +171,13 @@ void SoccerAI::findClosestKart(bool consider_difficulty, bool find_sta)
 }   // findClosestKart
 
 //-----------------------------------------------------------------------------
+/** Find a suitable target to follow, it will first call
+ *  \ref SoccerWorld::getBallChaser to check if this AI should go chasing the
+ *  ball and try to score, otherwise it will call \ref tryCollectItem if
+ *  needed. After that it will call \ref SoccerWorld::getAttacker to see if
+ *  this AI should attack the kart in opposite team which is chasing the ball,
+ *  if not go for the closest kart found by \ref findClosestKart.
+ */
 void SoccerAI::findTarget()
 {
     findClosestKart(true/*consider_difficulty*/, false/*find_sta*/);
@@ -201,6 +216,11 @@ void SoccerAI::findTarget()
 }   // findTarget
 
 //-----------------------------------------------------------------------------
+/** Determine the point for aiming when try to steer or overtake the ball.
+ *  AI will overtake the ball if the aiming position calculated by world is
+ *  non-reachable.
+ *  \return The coordinates to aim at.
+ */
 Vec3 SoccerAI::determineBallAimingPosition()
 {
 #ifdef BALL_AIM_DEBUG
@@ -276,6 +296,11 @@ Vec3 SoccerAI::determineBallAimingPosition()
 }   // determineBallAimingPosition
 
 //-----------------------------------------------------------------------------
+/** Used in \ref determineBallAimingPosition to test if AI can overtake the
+ *  ball by testing distance.
+ *  \param ball_lc Local coordinates of the ball.
+ *  \return False if the kart is too close to the ball which can't overtake
+ */
 bool SoccerAI::isOvertakable(const Vec3& ball_lc)
 {
     // No overtake if ball is behind
@@ -298,6 +323,13 @@ bool SoccerAI::isOvertakable(const Vec3& ball_lc)
 }   // isOvertakable
 
 //-----------------------------------------------------------------------------
+/** Used in \ref determineBallAimingPosition to pick a correct point to
+ *  overtake the ball
+ *  \param ball_lc Local coordinates of the ball.
+ *  \param aim_lc Local coordinates of the aiming position.
+ *  \param[out] overtake_lc Local coordinates of the overtaking position.
+ *  \return True if overtaking is possible.
+ */
 bool SoccerAI::determineOvertakePosition(const Vec3& ball_lc,
                                          const Vec3& aim_lc,
                                          Vec3* overtake_lc)
@@ -434,6 +466,12 @@ bool SoccerAI::determineOvertakePosition(const Vec3& ball_lc,
 }   // determineOvertakePosition
 
 //-----------------------------------------------------------------------------
+/** Used in \ref determineOvertakePosition to adjust the overtake position
+ *  which is calculated by slope of line if it's too close.
+ *  \param old_slope Old slope calculated.
+ *  \param rotate_up If adjust the slope upwards.
+ *  \return A newly calculated slope.
+ */
 float SoccerAI::rotateSlope(float old_slope, bool rotate_up)
 {
     const float theta = atan(old_slope) + (old_slope < 0 ? M_PI : 0);

src/karts/controller/soccer_ai.hpp

@@ -45,41 +45,68 @@ private:
     /** Keep a pointer to world. */
     SoccerWorld *m_world;
 
+    /** Save the team this AI belongs to. */
     SoccerTeam m_cur_team;
+
+    /** Save the opposite team of this AI team. */
     SoccerTeam m_opp_team;
 
     /** Define which way to handle to ball, either steer with it,
-     *  or overtake it (Denfense).
+     *  or overtake it (Defense). */
-     */
     bool m_overtake_ball;
+
+    /** True if \ref forceBraking() is needed to be called. */
     bool m_force_brake;
+
+    /** True if AI should steer with the ball. */
     bool m_chasing_ball;
 
+    /** The front point of kart with the same rotation of center mass, used
+     *  to determine point for aiming with ball */
     btTransform m_front_transform;
 
+    // ------------------------------------------------------------------------
     Vec3  determineBallAimingPosition();
+    // ------------------------------------------------------------------------
     bool  determineOvertakePosition(const Vec3& ball_lc, const Vec3& aim_lc,
                                     Vec3* overtake_lc);
+    // ------------------------------------------------------------------------
     bool  isOvertakable(const Vec3& ball_lc);
+    // ------------------------------------------------------------------------
     float rotateSlope(float old_slope, bool rotate_up);
-
+    // ------------------------------------------------------------------------
     virtual bool  canSkid(float steer_fraction) OVERRIDE
-           { return m_mini_skid && !(m_overtake_ball || m_chasing_ball); }
+                { return m_mini_skid && !(m_overtake_ball || m_chasing_ball); }
-    virtual void  findClosestKart(bool consider_difficulty, bool find_sta) OVERRIDE;
+    // ------------------------------------------------------------------------
+    virtual void  findClosestKart(bool consider_difficulty,
+                                  bool find_sta) OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual void  findTarget() OVERRIDE;
-    virtual bool  forceBraking() OVERRIDE { return m_force_brake; }
+    // ------------------------------------------------------------------------
+    virtual bool  forceBraking() OVERRIDE             { return m_force_brake; }
+    // ------------------------------------------------------------------------
     virtual int   getCurrentNode() const OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual float getKartDistance(const AbstractKart* kart) const OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual bool  ignorePathFinding() OVERRIDE
-                            { return  m_overtake_ball || m_chasing_ball; }
+                                 { return  m_overtake_ball || m_chasing_ball; }
+    // ------------------------------------------------------------------------
     virtual bool  isKartOnRoad() const OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual bool  isWaiting() const OVERRIDE;
-    virtual void  resetAfterStop() OVERRIDE   { m_overtake_ball = false; }
+    // ------------------------------------------------------------------------
+    virtual void  resetAfterStop() OVERRIDE        { m_overtake_ball = false; }
+
 public:
                  SoccerAI(AbstractKart *kart);
+    // ------------------------------------------------------------------------
                 ~SoccerAI();
+    // ------------------------------------------------------------------------
     virtual void update  (float delta) OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual void reset   () OVERRIDE;
+
 };
 
 #endif

src/karts/controller/spare_tire_ai.cpp

@@ -61,6 +61,10 @@ void SpareTireAI::reset()
 }   // reset
 
 //-----------------------------------------------------------------------------
+/** Besides calling update from parent class, it will auto \ref unspawn if
+ *  \ref m_timer reaches zero which it will be decreased here.
+ *  \param dt Time step size.
+ */
 void SpareTireAI::update(float dt)
 {
     BattleAI::update(dt);
@@ -71,9 +75,11 @@ void SpareTireAI::update(float dt)
 }   // update
 
 //-----------------------------------------------------------------------------
+/** Randomly find a start node for spare tire kart to move, called after \ref
+ *  spawn.
+ */
 void SpareTireAI::findDefaultPath()
 {
-    // Randomly find a start node for spare tire kart to move
     assert(m_idx == -1);
 
     RandomGenerator random;
@@ -83,6 +89,9 @@ void SpareTireAI::findDefaultPath()
 }   // findDefaultPath
 
 //-----------------------------------------------------------------------------
+/** For SpareTireAI, it will pick next node in \ref m_fixed_target_nodes after
+ *  reach the one in \ref m_idx, or the first one if it's the last.
+ */
 void SpareTireAI::findTarget()
 {
     assert(m_idx != -1 && m_idx < 4);
@@ -95,6 +104,10 @@ void SpareTireAI::findTarget()
 }   // findTarget
 
 //-----------------------------------------------------------------------------
+/** Spawn the SpareTireAI, it will start appearing in the battle mode and
+ *  moving around.
+ *  \param time_to_last Time before calling \ref unspawn.
+ */
 void SpareTireAI::spawn(float time_to_last)
 {
     findDefaultPath();
@@ -108,6 +121,9 @@ void SpareTireAI::spawn(float time_to_last)
 }   // spawn
 
 //-----------------------------------------------------------------------------
+/** Unspawn the SpareTireAI, it will be hidden in the battle mode but not
+ *  deleted, so it can be called with \ref spawn again later.
+ */
 void SpareTireAI::unspawn()
 {
     m_idx = -1;
@@ -115,6 +131,10 @@ void SpareTireAI::unspawn()
 }   // unspawn
 
 //-----------------------------------------------------------------------------
+/** Callback function when a kart crashes into the SpareTireAI, the kart will
+ *  increase one life if its life is not equal 3. A message will be shown too.
+ *  \param k \ref AbstractKart this SpareTireAI crashed.
+ */
 void SpareTireAI::crashed(const AbstractKart *k)
 {
     // Nothing happen when two spare tire karts crash each other

src/karts/controller/spare_tire_ai.hpp

@@ -27,22 +27,38 @@
 class SpareTireAI : public BattleAI
 {
 private:
+    /** The 4 bounding boxes \ref ArenaNode to follow. */
     int m_fixed_target_nodes[4];
 
+    /** The current index of \ref ArenaNode in \ref m_fixed_target_nodes to
+     *  follow, if it's -1, \ref update is not needed to be called. */
     int m_idx;
 
+    /** Store the time before calling \ref unspawn. */
     float m_timer;
 
+    // ------------------------------------------------------------------------
     virtual void  findTarget() OVERRIDE;
+    // ------------------------------------------------------------------------
     void          findDefaultPath();
+
 public:
                  SpareTireAI(AbstractKart *kart);
+    // ------------------------------------------------------------------------
     virtual void crashed(const AbstractKart *k) OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual void update(float delta) OVERRIDE;
+    // ------------------------------------------------------------------------
     virtual void reset() OVERRIDE;
+    // ------------------------------------------------------------------------
     void         spawn(float time_to_last);
+    // ------------------------------------------------------------------------
     void         unspawn();
-    bool         isMoving() const { return m_idx != -1; }
+    // ------------------------------------------------------------------------
+    /** Return true if this AI needed to be called \ref update by \ref World,
+     *  ie it is spawned. */
+    bool         isMoving() const                       { return m_idx != -1; }
+
 };
 
 #endif