Index: code/trunk/src/modules/pong/PongBall.cc
===================================================================
--- code/trunk/src/modules/pong/PongBall.cc	(revision 7886)
+++ code/trunk/src/modules/pong/PongBall.cc	(revision 8108)
@@ -27,9 +27,16 @@
  */
 
+/**
+    @file PongBall.cc
+    @brief Implementation of the PongBall class.
+*/
+
 #include "PongBall.h"
 
 #include "core/CoreIncludes.h"
 #include "core/GameMode.h"
+
 #include "gametypes/Gametype.h"
+
 #include "PongBat.h"
 
@@ -40,4 +47,8 @@
     const float PongBall::MAX_REL_Z_VELOCITY = 1.5;
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongBall::PongBall(BaseObject* creator)
         : MovableEntity(creator)
@@ -57,4 +68,8 @@
     }
 
+    /**
+    @brief
+        Destructor.
+    */
     PongBall::~PongBall()
     {
@@ -68,4 +83,8 @@
     }
 
+    /**
+    @brief
+        Register variables to synchronize over the network.
+    */
     void PongBall::registerVariables()
     {
@@ -79,15 +98,26 @@
     }
 
+    /**
+    @brief
+        Is called every tick.
+        Handles the movement of the ball and its interaction with the boundaries and bats.
+    @param dt
+        The time since the last tick.
+    */
     void PongBall::tick(float dt)
     {
         SUPER(PongBall, tick, dt);
 
+        // Get the current position, velocity and acceleration of the ball.
         Vector3 position = this->getPosition();
         Vector3 velocity = this->getVelocity();
         Vector3 acceleration = this->getAcceleration();
 
+        // If the ball has gone over the top or bottom boundary of the playing field (i.e. the ball has hit the top or bottom delimiters).
         if (position.z > this->fieldHeight_ / 2 || position.z < -this->fieldHeight_ / 2)
         {
+            // Its velocity in z-direction is inverted (i.e. it bounces off).
             velocity.z = -velocity.z;
+            // And its position is set as to not overstep the boundary it has just crossed.
             if (position.z > this->fieldHeight_ / 2)
                 position.z = this->fieldHeight_ / 2;
@@ -98,17 +128,23 @@
         }
 
+        // If the ball has crossed the left or right boundary of the playing field (i.e. a player has just scored, if the bat isn't there to parry).
         if (position.x > this->fieldWidth_ / 2 || position.x < -this->fieldWidth_ / 2)
         {
             float distance = 0;
 
-            if (this->bat_)
+            if (this->bat_ != NULL) // If there are bats.
             {
-                if (position.x > this->fieldWidth_ / 2 && this->bat_[1])
+                // If the right boundary has been crossed.
+                if (position.x > this->fieldWidth_ / 2 && this->bat_[1] != NULL)
                 {
+                    // Calculate the distance (in z-direction) between the ball and the center of the bat, weighted by half of the effective length of the bat (with additional 10%)
                     distance = (position.z - this->bat_[1]->getPosition().z) / (this->fieldHeight_ * (this->batlength_ * 1.10f) / 2);
-                    if (fabs(distance) <= 1)
-                    {
+                    if (fabs(distance) <= 1) // If the bat is there to parry.
+                    {
+                        // Set the ball to be exactly at the boundary.
                         position.x = this->fieldWidth_ / 2;
+                        // Invert its velocity in x-direction (i.e. it bounces off).
                         velocity.x = -velocity.x;
+                        // Adjust the velocity in the z-direction, depending on where the ball hit the bat.
                         velocity.z = distance * distance * sgn(distance) * PongBall::MAX_REL_Z_VELOCITY * this->speed_;
                         acceleration = this->bat_[1]->getVelocity() * this->accelerationFactor_ * -1;
@@ -116,4 +152,5 @@
                         this->fireEvent();
                     }
+                    // If the left player scores.
                     else if (GameMode::isMaster() && position.x > this->fieldWidth_ / 2 * (1 + this->relMercyOffset_))
                     {
@@ -125,11 +162,16 @@
                     }
                 }
-                if (position.x < -this->fieldWidth_ / 2 && this->bat_[0])
+                // If the left boundary has been crossed.
+                else if (position.x < -this->fieldWidth_ / 2 && this->bat_[0] != NULL)
                 {
+                    // Calculate the distance (in z-direction) between the ball and the center of the bat, weighted by half of the effective length of the bat (with additional 10%)
                     distance = (position.z - this->bat_[0]->getPosition().z) / (this->fieldHeight_ * (this->batlength_ * 1.10f) / 2);
-                    if (fabs(distance) <= 1)
-                    {
+                    if (fabs(distance) <= 1) // If the bat is there to parry.
+                    {
+                        // Set the ball to be exactly at the boundary.
                         position.x = -this->fieldWidth_ / 2;
+                        // Invert its velocity in x-direction (i.e. it bounces off).
                         velocity.x = -velocity.x;
+                        // Adjust the velocity in the z-direction, depending on where the ball hit the bat.
                         velocity.z = distance * distance * sgn(distance) * PongBall::MAX_REL_Z_VELOCITY * this->speed_;
                         acceleration = this->bat_[0]->getVelocity() * this->accelerationFactor_ * -1;
@@ -137,4 +179,5 @@
                         this->fireEvent();
                     }
+                    // If the right player scores.
                     else if (GameMode::isMaster() && position.x < -this->fieldWidth_ / 2 * (1 + this->relMercyOffset_))
                     {
@@ -149,4 +192,5 @@
         }
 
+        // Set the position, velocity and acceleration of the ball, if they have changed.
         if (acceleration != this->getAcceleration())
             this->setAcceleration(acceleration);
@@ -157,14 +201,21 @@
     }
 
+    /**
+    @brief
+        Set the speed of the ball (in x-direction).
+    @param speed
+        The speed to be set.
+    */
     void PongBall::setSpeed(float speed)
     {
-        if (speed != this->speed_)
+        if (speed != this->speed_) // If the speed changes
         {
             this->speed_ = speed;
 
+            // Set the speed in the direction of the balls current velocity.
             Vector3 velocity = this->getVelocity();
             if (velocity.x != 0)
                 velocity.x = sgn(velocity.x) * this->speed_;
-            else
+            else // If the balls current velocity is zero, the speed is set in a random direction.
                 velocity.x = this->speed_ * sgn(rnd(-1,1));
 
@@ -173,7 +224,13 @@
     }
 
+    /**
+    @brief
+        Set the bats for the ball.
+    @param bats
+        An array (of size 2) of weak pointers, to be set as the new bats.
+    */
     void PongBall::setBats(WeakPtr<PongBat>* bats)
     {
-        if (this->bDeleteBats_)
+        if (this->bDeleteBats_) // If there are already some bats, delete them.
         {
             delete[] this->bat_;
@@ -182,11 +239,17 @@
 
         this->bat_ = bats;
+        // Also store their object IDs, for synchronization.
         this->batID_[0] = this->bat_[0]->getObjectID();
         this->batID_[1] = this->bat_[1]->getObjectID();
     }
 
+    /**
+    @brief
+        Get the bats over the network.
+    */
     void PongBall::applyBats()
     {
-        if (!this->bat_)
+        // Make space for the bats, if they don't exist, yet.
+        if (this->bat_ == NULL)
         {
             this->bat_ = new WeakPtr<PongBat>[2];
