Changeset 8108 for code/trunk/src/modules

Timestamp:

Mar 23, 2011, 9:57:54 PM (13 years ago)

Author:

dafrick

Message:

Merging changes from tetris branch into trunk, since they are also useful, there.

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/modules/designtools/ScreenshotManager.cc (modified) (1 diff)
• src/modules/pickup/Pickup.h (modified) (1 diff)
• src/modules/pong/Pong.cc (modified) (16 diffs)
• src/modules/pong/Pong.h (modified) (2 diffs)
• src/modules/pong/PongAI.cc (modified) (12 diffs)
• src/modules/pong/PongAI.h (modified) (2 diffs)
• src/modules/pong/PongBall.cc (modified) (13 diffs)
• src/modules/pong/PongBall.h (modified) (4 diffs)
• src/modules/pong/PongBat.cc (modified) (9 diffs)
• src/modules/pong/PongBat.h (modified) (1 diff)
• src/modules/pong/PongBot.cc (modified) (2 diffs)
• src/modules/pong/PongBot.h (modified) (2 diffs)
• src/modules/pong/PongCenterpoint.cc (modified) (4 diffs)
• src/modules/pong/PongCenterpoint.h (modified) (2 diffs)
• src/modules/pong/PongScore.cc (modified) (8 diffs)
• src/modules/pong/PongScore.h (modified) (3 diffs)

code/trunk/src/modules/designtools/ScreenshotManager.cc

@@ -61 +61 @@
     @brief
         Creates a screenshot with the given camera.
-    @param camera
-        Pointer to the camera "looking at" the scene of interest
-    @param fileName
-        the filename of the screenshot file.
     */
     void ScreenshotManager::makeScreenshot() const

code/trunk/src/modules/pickup/Pickup.h

@@ -81 +81 @@
         The Pickup class offers (useful) base functionality for a wide range of pickups.
 
-        Pickups ingeriting from this class can choose an activation type and a duration type.
+        Pickups inheriting from this class can choose an activation type and a duration type.
         - The <b>activationType</b> deals with what happens to the Pickup as soon as it is picked up. It can either be set to <em>immediate</em>, which means that the Pickup is activated/used immediately upon being picked up. Or to <em>onUse</em>, which means, that the Pickup will be activated/used if some outside entity (most commonly the player through the PickupInventory) decides to use it. Default is <em>immediate</em>.
         - The <b>durationType</b> deals with whether the Pickup has a continuous effect or whether its effect is focused on a singular instant. It can either be set to <em>once</em>, which means, that the Pickup just has an effect (at a singular instant in time) and is done once that effect has been applied. Or to <em>continuous</em>, which means that the effect of the Pickup unfolds over some timespan. Default is <em>once</em>.

code/trunk/src/modules/pong/Pong.cc

@@ -27 +27 @@
  */
 
+/**
+    @file Pong.cc
+    @brief Implementation of the Pong class.
+*/
+
 #include "Pong.h"
 
@@ -32 +37 @@
 #include "core/EventIncludes.h"
 #include "core/command/Executor.h"
+
+#include "gamestates/GSLevel.h"
+
 #include "PongCenterpoint.h"
 #include "PongBall.h"
@@ -40 +48 @@
 namespace orxonox
 {
+    // Events to allow to react to scoring of a player, in the level-file.
     CreateEventName(PongCenterpoint, right);
     CreateEventName(PongCenterpoint, left);
@@ -45 +54 @@
     CreateUnloadableFactory(Pong);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     Pong::Pong(BaseObject* creator) : Deathmatch(creator)
     {
@@ -56 +69 @@
         this->setHUDTemplate("PongHUD");
 
+        // Pre-set the timer, but don't start it yet.
         this->starttimer_.setTimer(1.0, false, createExecutor(createFunctor(&Pong::startBall, this)));
         this->starttimer_.stopTimer();
 
+        // Set the type of Bots for this particular Gametype.
         this->botclass_ = Class(PongBot);
     }
 
+    /**
+    @brief
+        Destructor. Cleans up, if initialized.
+    */
     Pong::~Pong()
     {
@@ -68 +87 @@
     }
 
+    /**
+    @brief
+        Cleans up the Gametype by destroying the ball and the bats.
+    */
     void Pong::cleanup()
     {
-        if (this->ball_)
+        if (this->ball_ != NULL) // Destroy the ball, if present.
         {
             this->ball_->destroy();
@@ -76 +99 @@
         }
 
+        // Destroy both bats, if present.
         for (size_t i = 0; i < 2; ++i)
         {
-            if (this->bat_[0])
+            if (this->bat_[0] != NULL)
             {
                 this->bat_[0]->destroy();
@@ -86 +110 @@
     }
 
+    /**
+    @brief
+        Starts the Pong minigame.
+    */
     void Pong::start()
     {
-        if (this->center_)
-        {
-            if (!this->ball_)
+        if (this->center_ != NULL) // There needs to be a PongCenterpoint, i.e. the area the game takes place.
+        {
+            if (this->ball_ == NULL) // If there is no ball, create a new ball.
             {
                 this->ball_ = new PongBall(this->center_);
+                // Apply the template for the ball specified by the centerpoint.
                 this->ball_->addTemplate(this->center_->getBalltemplate());
             }
 
+            // Attach the ball to the centerpoint and set the parameters as specified in the centerpoint, the ball is attached to.
             this->center_->attach(this->ball_);
             this->ball_->setPosition(0, 0, 0);
@@ -103 +133 @@
             this->ball_->setBatLength(this->center_->getBatLength());
 
-            if (!this->bat_[0])
+            // If one of the bats is missing, create it. Apply the template for the bats as specified in the centerpoint.
+            for (size_t i = 0; i < 2; ++i)
             {
-                this->bat_[0] = new PongBat(this->center_);
-                this->bat_[0]->addTemplate(this->center_->getBattemplate());
+                if (this->bat_[i] == NULL)
+                {
+                    this->bat_[i] = new PongBat(this->center_);
+                    this->bat_[i]->addTemplate(this->center_->getBattemplate());
+                }
             }
-            if (!this->bat_[1])
-            {
-                this->bat_[1] = new PongBat(this->center_);
-                this->bat_[1]->addTemplate(this->center_->getBattemplate());
-            }
-
+
+            // Attach the bats to the centerpoint and set the parameters as specified in the centerpoint, the bats are attached to.
             this->center_->attach(this->bat_[0]);
             this->center_->attach(this->bat_[1]);
@@ -127 +157 @@
             this->bat_[1]->setLength(this->center_->getBatLength());
 
+            // Set the bats for the ball.
             this->ball_->setBats(this->bat_);
         }
-        else
+        else // If no centerpoint was specified, an error is thrown and the level is exited.
         {
             COUT(1) << "Error: No Centerpoint specified." << std::endl;
-        }
-
+            GSLevel::startMainMenu();
+            return;
+        }
+
+        // Start the timer. After it has expired the ball is started.
         this->starttimer_.startTimer();
 
-
+        // Set variable to temporarily force the player to spawn.
         bool temp = this->bForceSpawn_;
         this->bForceSpawn_ = true;
 
+        // Call start for the parent class.
         Deathmatch::start();
 
+        // Reset the variable.
         this->bForceSpawn_ = temp;
     }
 
+    /**
+    @brief
+        Ends the Pong minigame.
+    */
     void Pong::end()
     {
         this->cleanup();
 
+        // Call end for the parent class.
         Deathmatch::end();
     }
 
+    /**
+    @brief
+        Spawns players, and fills the rest up with bots.
+    */
     void Pong::spawnPlayersIfRequested()
     {
@@ -164 +209 @@
     }
 
+    /**
+    @brief
+        Spawns the input player.
+    @param player
+        The player to be spawned.
+    */
     void Pong::spawnPlayer(PlayerInfo* player)
     {
-        if (!this->bat_[0]->getPlayer())
+        assert(player);
+
+        // If the first (left) bat has no player.
+        if (this->bat_[0]->getPlayer() == NULL)
         {
             player->startControl(this->bat_[0]);
             this->players_[player].state_ = PlayerState::Alive;
         }
-        else if (!this->bat_[1]->getPlayer())
+        // If the second (right) bat has no player.
+        else if (this->bat_[1]->getPlayer() == NULL)
         {
             player->startControl(this->bat_[1]);
             this->players_[player].state_ = PlayerState::Alive;
         }
+        // If both bats are taken.
         else
             return;
 
-        if (player && player->getController() && player->getController()->isA(Class(PongAI)))
+        // If the player is an AI, it receives a pointer to the ball.
+        if (player->getController() != NULL && player->getController()->isA(Class(PongAI)))
         {
             PongAI* ai = orxonox_cast<PongAI*>(player->getController());
@@ -186 +243 @@
     }
 
+    /**
+    @brief
+        Is called when the player scored.
+    */
     void Pong::playerScored(PlayerInfo* player)
     {
         Deathmatch::playerScored(player);
 
-        if (this->center_)
-        {
+        if (this->center_ != NULL) // If there is a centerpoint.
+        {
+            // Fire an event for the player that has scored, to be able to react to it in the level, e.g. by displaying fireworks.
             if (player == this->getRightPlayer())
                 this->center_->fireEvent(FireEventName(PongCenterpoint, right));
@@ -197 +259 @@
                 this->center_->fireEvent(FireEventName(PongCenterpoint, left));
 
-            if (player)
+            // Also announce, that the player has scored.
+            if (player != NULL)
                 this->gtinfo_->sendAnnounceMessage(player->getName() + " scored");
         }
 
-        if (this->ball_)
+        // If there is a ball present, reset its position, velocity and acceleration.
+        if (this->ball_ != NULL)
         {
             this->ball_->setPosition(Vector3::ZERO);
@@ -209 +273 @@
         }
 
-        if (this->bat_[0] && this->bat_[1])
+        // If there are bats reset them to the middle position.
+        if (this->bat_[0] != NULL && this->bat_[1] != NULL)
         {
             this->bat_[0]->setPosition(-this->center_->getFieldDimension().x / 2, 0, 0);
@@ -215 +280 @@
         }
 
+        // Restart the timer to start the ball.
         this->starttimer_.startTimer();
     }
 
+    /**
+    @brief
+        Starts the ball with some default speed.
+    */
     void Pong::startBall()
     {
-        if (this->ball_ && this->center_)
+        if (this->ball_ != NULL && this->center_ != NULL)
             this->ball_->setSpeed(this->center_->getBallSpeed());
     }
 
+    /**
+    @brief
+        Get the left player.
+    @return
+        Returns a pointer to the player playing on the left. If there is no left player, NULL is returned.
+    */
     PlayerInfo* Pong::getLeftPlayer() const
     {
-        if (this->bat_ && this->bat_[0])
+        if (this->bat_ != NULL && this->bat_[0] != NULL)
             return this->bat_[0]->getPlayer();
         else
@@ -232 +308 @@
     }
 
+    /**
+    @brief
+        Get the right player.
+    @return
+        Returns a pointer to the player playing on the right. If there is no right player, NULL is returned.
+    */
     PlayerInfo* Pong::getRightPlayer() const
     {
-        if (this->bat_ && this->bat_[1])
+        if (this->bat_ != NULL && this->bat_[1] != NULL)
             return this->bat_[1]->getPlayer();
         else

code/trunk/src/modules/pong/Pong.h

@@ -27 +27 @@
  */
 
+/**
+    @file Pong.h
+    @brief Declaration of the Pong class.
+    @ingroup Pong
+*/
+
 #ifndef _Pong_H__
 #define _Pong_H__
@@ -33 +39 @@
 
 #include "tools/Timer.h"
+
 #include "gametypes/Deathmatch.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        Implements a Pong minigame (<a href="http://en.wikipedia.org/wiki/Pong">Wikipedia::Pong</a>).
+        It connects the different entities present in a game of Pong.
+
+        - The @ref orxonox::PongCenterpoint "PongCenterpoint" is the playing field for the Pong minigame, it allows for configuration of the minigame, e.g. by setting the size of the playing field, or the length of the @ref orxonox::PongBat "PongBats". The playing field is always in the x,y-plane, the x-axis being the horizontal and the z-axis being the vertical axis.<br />
+        The Pong class redistributes the important parameters defined in @ref orxonox::PongCenterpoint "PongCenterpoint" to the other entities, that need to know them, e.g. the @ref orxonox::PongBall "PongBall" and the @ref orxonox::PongBat "PongBats".<br />
+        The @ref orxonox::PongCenterpoint "PongCenterpoint" needs to exist in a level with the @ref orxonox::Gametype "Gametype" <em>Pong</em>.
+        - The @ref orxonox::PongBall "PongBall" is the ball both players play with. The @ref orxonox::PongBall "PongBall" both implements the movement of the ball, as well as the influence of the boundaries and consequently, also the bouncing (off the upper and lower delimiters, and as off the @ref orxonox::PongBat "PongBats") of the ball and the effects of the failure of a player to catch the ball (i.e. the scoring of the other player).
+        - The two @ref orxonox::PongBat "PongBats" are the entities through which the players can actively participate in the game, by controlling them. The @ref orxonox::PongBat "PongBat" class manages the movement (and restrictions thereof) and the influence of the players on the bats.
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport Pong : public Deathmatch
     {
         public:
-            Pong(BaseObject* creator);
-            virtual ~Pong();
+            Pong(BaseObject* creator); //!< Constructor. Registers and initializes the object.
+            virtual ~Pong(); //!< Destructor. Cleans up, if initialized.
 
-            virtual void start();
-            virtual void end();
+            virtual void start(); //!< Starts the Pong minigame.
+            virtual void end(); ///!< Ends the Pong minigame.
 
-            virtual void spawnPlayer(PlayerInfo* player);
+            virtual void spawnPlayer(PlayerInfo* player); //!< Spawns the input player.
 
-            virtual void playerScored(PlayerInfo* player);
+            virtual void playerScored(PlayerInfo* player); //!< Is called when the player scored.
 
+            /**
+            @brief Set the PongCenterpoint (the playing field).
+            @param center A pointer to the PongCenterpoint to be set.
+            */
             void setCenterpoint(PongCenterpoint* center)
                 { this->center_ = center; }
 
-            PlayerInfo* getLeftPlayer() const;
-            PlayerInfo* getRightPlayer() const;
+            PlayerInfo* getLeftPlayer() const; //!< Get the left player.
+            PlayerInfo* getRightPlayer() const; //!< Get the right player.
 
         protected:
-            virtual void spawnPlayersIfRequested();
+            virtual void spawnPlayersIfRequested(); //!< Spawns players, and fills the rest up with bots.
 
-            void startBall();
-            void cleanup();
+            void startBall(); //!< Starts the ball with some default speed.
+            void cleanup(); //!< Cleans up the Gametype by destroying the ball and the bats.
 
-            WeakPtr<PongCenterpoint> center_;
-            WeakPtr<PongBall> ball_;
-            WeakPtr<PongBat> bat_[2];
-            Timer starttimer_;
+            WeakPtr<PongCenterpoint> center_; //!< The playing field.
+            WeakPtr<PongBall> ball_; //!< The Pong ball.
+            WeakPtr<PongBat> bat_[2]; //!< The two bats.
+            Timer starttimer_; //!< A timer to delay the start of the game.
     };
 }

code/trunk/src/modules/pong/PongAI.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongAI.cc
+    @brief Implementation of the PongAI class.
+*/
+
 #include "PongAI.h"
 
@@ -32 +37 @@
 #include "core/ConfigValueIncludes.h"
 #include "tools/Timer.h"
+
 #include "worldentities/ControllableEntity.h"
+
 #include "PongBall.h"
 
@@ -41 +48 @@
     const static float MAX_REACTION_TIME = 0.4f;
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongAI::PongAI(BaseObject* creator) : Controller(creator)
     {
@@ -59 +70 @@
     }
 
+    /**
+    @brief
+        Destructor. Cleans up the list fo reaction timers.
+    */
     PongAI::~PongAI()
     {
@@ -65 +80 @@
     }
 
+    /**
+    @brief
+        Sets config values.
+    */
     void PongAI::setConfigValues()
     {
+        // Sets the strength of the PongAi as a config value.
         SetConfigValue(strength_, 0.5).description("A value from 0 to 1 where 0 is weak and 1 is strong.");
     }
 
+    /**
+    @brief
+        Is called each tick.
+        Implements the behavior of the PongAI (i.e. its intelligence).
+    @param dt
+        The time that has elapsed since the last tick.
+    */
     void PongAI::tick(float dt)
     {
-        if (!this->ball_ || !this->getControllableEntity())
+        // If either the ball, or the controllable entity (i.e. the bat) don't exist (or aren't set).
+        if (this->ball_  == NULL || this->getControllableEntity() == NULL)
             return;
 
@@ -109 +137 @@
             if (this->ballDirection_.x != 1)
             {
-                // The ball just startet to approach, initialize all values
+                // The ball just started to approach, initialize all values
                 this->ballDirection_.x = 1;
                 this->ballDirection_.y = sgn(ballvel.z);
@@ -158 +186 @@
             {
                 // We had to correct our position because we moved too far
-                // (and delay ist false, so we're not in the wrong place because of a new end-position prediction)
+                // (and delay is false, so we're not in the wrong place because of a new end-position prediction)
                 if (fabs(mypos.z - this->ballEndPosition_) < 0.5 * this->ball_->getBatLength() * this->ball_->getFieldDimension().y)
                 {
@@ -173 +201 @@
     }
 
+    /**
+    @brief
+        Calculates the random offset, that accounts for random errors the AI makes in order to be beatable.
+        The higher the strength of the AI, the smaller the (expected value of the) error.
+        The result of this method is stored in this->randomOffset_.
+    */
     void PongAI::calculateRandomOffset()
     {
@@ -184 +218 @@
                                           // exp < 1 -> position is more likely a large number
 
-        // The position shouln't be larger than 0.5 (50% of the bat-length from the middle is the end)
+        // The position shouldn't be larger than 0.5 (50% of the bat-length from the middle is the end)
         position *= 0.48f;
 
@@ -194 +228 @@
     }
 
+    /**
+    @brief
+        Calculate the end position the ball will be in.
+        The result of this calculation is stored in this->ballEndPosition_.
+    */
     void PongAI::calculateBallEndPosition()
     {
@@ -295 +334 @@
     }
 
+    /**
+    @brief
+        Determine the movement the AI will undertake. (Either -1, 0 or 1)
+        The result of this calculation is stored in this->movement_;
+    @param direction
+        The current direction of movement.
+    @param bUseDelay
+        The time by which this move is delayed. (Again, to make the AI less efficient)
+    */
     void PongAI::move(char direction, bool bUseDelay)
     {
@@ -321 +369 @@
     }
 
+    /**
+    @brief
+        Is called, when a delayed move takes effect.
+    */
     void PongAI::delayedMove()
     {

code/trunk/src/modules/pong/PongAI.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongAI.h
+    @brief Declaration of the PongAI class.
+    @ingroup Pong
+*/
+
 #ifndef _PongAI_H__
 #define _PongAI_H__
@@ -33 +39 @@
 
 #include <list>
+
 #include "util/Math.h"
 #include "tools/interfaces/Tickable.h"
+
 #include "controllers/Controller.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        The PongAI is an artificial intelligence for the @ref orxonox::Pong "Pong" gametype.
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongAI : public Controller, public Tickable
     {
         public:
-            PongAI(BaseObject* creator);
+            PongAI(BaseObject* creator); //!< Constructor. Registers and initializes the object.
             virtual ~PongAI();
 
             void setConfigValues();
 
-            virtual void tick(float dt);
+            virtual void tick(float dt); //!< Implements the behavior of the PongAI (i.e. its intelligence).
 
+            /**
+            @brief Set the ball for the AI.
+            @param ball A pointer to the ball.
+            */
             void setPongBall(PongBall* ball)
                 { this->ball_ = ball; }
 
         protected:
-            void calculateRandomOffset();
-            void calculateBallEndPosition();
-            void move(char direction, bool bUseDelay);
-            void delayedMove();
+            void calculateRandomOffset(); //!< Calculates the random offset, that accounts for random errors the AI makes in order to be beatable.
+            void calculateBallEndPosition(); //!< Calculate the end position the ball will be in.
+            void move(char direction, bool bUseDelay); //!< Determine the movement the AI will undertake.
+            void delayedMove(); //!< Is called, when a delayed move takes effect.
 
-            PongBall* ball_;
-            Vector2 ballDirection_;
-            float ballEndPosition_;
-            float randomOffset_;
-            bool bChangedRandomOffset_;
-            float relHysteresisOffset_;
-            float strength_;
+            PongBall* ball_; //!< A pointer to the ball.
+            Vector2 ballDirection_; //!< Vector to store the (x,z) direction in which the ball is flying.
+            float ballEndPosition_; //!< The calculated end position of the ball.
+            float randomOffset_; //!< A random offset to introduce random errors (weighted by the strength of the AI) into the AI's behavior.
+            bool bChangedRandomOffset_; //!< Helper boolean, to change the random offset more often.
+            float relHysteresisOffset_; //!< A hysteresis offset.
+            float strength_; //!< The strength of the AI. Ranging from 0 to 1.
 
-            std::list<std::pair<Timer*, char> > reactionTimers_;
-            char movement_;
-            char oldMove_;
-            bool bOscillationAvoidanceActive_;
+            std::list<std::pair<Timer*, char> > reactionTimers_; //!< A list of reaction timers and the directions that take effect when their timer expires.
+            char movement_; //!< The planned movement.
+            char oldMove_; //!< The previous movement.
+            bool bOscillationAvoidanceActive_; //!< Boolean, to avoid oscillations.
     };
 }

code/trunk/src/modules/pong/PongBall.cc

@@ -27 +27 @@
  */
 
+/**
+    @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 +47 @@
     const float PongBall::MAX_REL_Z_VELOCITY = 1.5;
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongBall::PongBall(BaseObject* creator)
         : MovableEntity(creator)
@@ -57 +68 @@
     }
 
+    /**
+    @brief
+        Destructor.
+    */
     PongBall::~PongBall()
     {
@@ -68 +83 @@
     }
 
+    /**
+    @brief
+        Register variables to synchronize over the network.
+    */
     void PongBall::registerVariables()
     {
@@ -79 +98 @@
     }
 
+    /**
+    @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 +128 @@
         }
 
+        // 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 +152 @@
                         this->fireEvent();
                     }
+                    // If the left player scores.
                     else if (GameMode::isMaster() && position.x > this->fieldWidth_ / 2 * (1 + this->relMercyOffset_))
                     {
@@ -125 +162 @@
                     }
                 }
-                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 +179 @@
                         this->fireEvent();
                     }
+                    // If the right player scores.
                     else if (GameMode::isMaster() && position.x < -this->fieldWidth_ / 2 * (1 + this->relMercyOffset_))
                     {
@@ -149 +192 @@
         }
 
+        // Set the position, velocity and acceleration of the ball, if they have changed.
         if (acceleration != this->getAcceleration())
             this->setAcceleration(acceleration);
@@ -157 +201 @@
     }
 
+    /**
+    @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 +224 @@
     }
 
+    /**
+    @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 +239 @@
 
         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];

code/trunk/src/modules/pong/PongBall.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongBall.h
+    @brief Declaration of the PongBall class.
+    @ingroup Pong
+*/
+
 #ifndef _PongBall_H__
 #define _PongBall_H__
@@ -33 +39 @@
 
 #include "util/Math.h"
+
 #include "worldentities/MovableEntity.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        This class manages the ball for @ref orxonox::Pong "Pong".
+
+        It is responsible for both the movement of the ball in the x,z-plane as well as its interaction with the boundaries of the playing field (defined by the @ref orxonox::PongCenterpoint "PongCenterpoint") and the @ref orxonox::PongBat "PongBats". Or more precisely, it makes the ball bounce off then upper and lower delimiters of the playing field, it makes the ball bounce off the bats and also detects when a player scores and takes appropriate measures.
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongBall : public MovableEntity
     {
@@ -45 +64 @@
             virtual void tick(float dt);
 
+            /**
+            @brief Set the dimensions of the playing field.
+            @param width The width of the playing field.
+            @param height The height of the playing field.
+            */
             void setFieldDimension(float width, float height)
                 { this->fieldWidth_ = width; this->fieldHeight_ = height; }
+            /**
+            @brief Get the dimensions of the playing field.
+            @param dimension A vector with the width as the first and height as the second component.
+            */
             void setFieldDimension(const Vector2& dimension)
                 { this->setFieldDimension(dimension.x, dimension.y); }
+            /**
+            @brief Get the dimensions of the playing field.
+            @return Returns a vector with the width as the first and height as the second component.
+            */
             Vector2 getFieldDimension() const
                 { return Vector2(this->fieldWidth_, this->fieldHeight_); }
 
-            void setSpeed(float speed);
+            void setSpeed(float speed); //!< Set the speed of the ball (in x-direction).
+            /**
+            @brief Get the speed of the ball (in x-direction).
+            @return Returns the speed of the ball (in x-direction).
+            */
             float getSpeed() const
                 { return this->speed_; }
 
+            /**
+            @brief Set the acceleration factor of the ball.
+            @param factor The factor the acceleration of the ball is set to.
+            */
             void setAccelerationFactor(float factor)
                 { this->accelerationFactor_ = factor; }
+            /**
+            @brief Get the acceleration factor of the ball.
+            @return Returns the acceleration factor of the ball.
+            */
             float getAccelerationFactor() const
                 { return this->accelerationFactor_; }
 
+            /**
+            @brief Set the length of the bats.
+            @param batlength The length of the bats (in z-direction) as percentage of the height of the playing field.
+            */
             void setBatLength(float batlength)
                 { this->batlength_ = batlength; }
+            /**
+            @brief Get the length of the bats.
+            @return Returns the length of the bats (in z-direction) as percentage of the height of the playing field.
+            */
             float getBatLength() const
                 { return this->batlength_; }
 
-            void setBats(WeakPtr<PongBat>* bats);
-            void applyBats();
+            void setBats(WeakPtr<PongBat>* bats); //!< Set the bats for the ball.
+            void applyBats(); //!< Get the bats over the network.
 
             static const float MAX_REL_Z_VELOCITY;
@@ -74 +126 @@
             void registerVariables();
 
-            float fieldWidth_;
-            float fieldHeight_;
-            float speed_;
-            float accelerationFactor_;
-            float batlength_;
-            WeakPtr<PongBat>* bat_;
-            bool bDeleteBats_;
-            unsigned int* batID_;
-            float relMercyOffset_;
+            float fieldWidth_; //!< The width of the playing field.
+            float fieldHeight_; //!< The height of the playing field.
+            float speed_; //!< The speed (in x-direction) of the ball.
+            float accelerationFactor_; //!< The acceleration factor of the ball.
+            float batlength_; //!< The length of the bats (in z-direction) as percentage of the height of the playing field.
+            WeakPtr<PongBat>* bat_; //!< An array with the two bats.
+            bool bDeleteBats_; //!< Bool, to keep track, of whether this->bat_ exists or not.
+            unsigned int* batID_; //!< The object IDs of the bats, to be able to synchronize them over the network.
+            float relMercyOffset_; //!< Offset, that makes the player not loose, when, in all fairness, he would have.
     };
 }

code/trunk/src/modules/pong/PongBat.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongBat.cc
+    @brief Implementation of the PongBat class.
+*/
+
 #include "PongBat.h"
 
@@ -36 +41 @@
     CreateFactory(PongBat);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongBat::PongBat(BaseObject* creator) : ControllableEntity(creator)
     {
@@ -50 +59 @@
     }
 
+    /**
+    @brief
+        Registers variables to be synchronized over the network.
+    */
     void PongBat::registerVariables()
     {
@@ -57 +70 @@
     }
 
+    /**
+    @brief
+        Is called each tick.
+        Moves the bat.
+    @param dt
+        The time since last tick.
+    */
     void PongBat::tick(float dt)
     {
+        // If the bat is controlled (but not over the network).
         if (this->hasLocalController())
         {
             if (this->movement_ != 0)
             {
+                // The absolute value of the movement is restricted to be lesser or equal than the speed of the bat.
                 this->movement_ = clamp(this->movement_, -1.0f, 1.0f) * this->speed_;
 
+                // If moveRightLeft() is used the movement is dependento on wehther it is the right or the left bat, so, it is i.e. dependent on the orientation of the bat.
                 if (this->bMoveLocal_)
                     this->setVelocity(this->getOrientation() * Vector3(this->movement_, 0, 0));
@@ -73 +96 @@
                 this->bSteadiedPosition_ = false;
             }
+            // If there is no movement but the position has not been steadied, the velocity is set to zero and the position is reaffirmed.
             else if (!this->bSteadiedPosition_)
             {
@@ -84 +108 @@
         SUPER(PongBat, tick, dt);
 
+        // Restrict the position of the bats, for them to always be between the upper and lower delimiters. i.e. the bats stall if they reach the upper or lower boundary.
         Vector3 position = this->getPosition();
         if (position.z > this->fieldHeight_ / 2 - this->fieldHeight_ * this->length_ / 2)
@@ -96 +121 @@
     }
 
+    /**
+    @brief
+        Overloaded the function to steer the bat up and down.
+    @param value
+        A vector whose first component is the inverse direction in which we want to steer the bat.
+    */
     void PongBat::moveFrontBack(const Vector2& value)
     {
@@ -102 +133 @@
     }
 
+    /**
+    @brief
+        Overloaded the function to steer the bat up and down.
+    @param value
+        A vector whose first component is the direction in which we wnat to steer the bat.
+    */
     void PongBat::moveRightLeft(const Vector2& value)
     {
@@ -108 +145 @@
     }
 
+    /**
+    @brief
+        Is called when the player changed.
+    */
     void PongBat::changedPlayer()
     {

code/trunk/src/modules/pong/PongBat.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongBat.h
+    @brief Declaration of the PongBat class.
+    @ingroup Pong
+*/
+
 #ifndef _PongBat_H__
 #define _PongBat_H__
 
 #include "pong/PongPrereqs.h"
+
 #include "worldentities/ControllableEntity.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        The PongBat class manages the bats for @ref orxonox::Pong "Pong", which are the elements controlled by the players.
+
+        It is responsible for the movement (controlled by the players) of the bat.
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongBat : public ControllableEntity
     {
         public:
-            PongBat(BaseObject* creator);
+            PongBat(BaseObject* creator); //!< Constructor. Registers and initializes the object.
             virtual ~PongBat() {}
 
             virtual void tick(float dt);
 
-            virtual void moveFrontBack(const Vector2& value);
-            virtual void moveRightLeft(const Vector2& value);
+            virtual void moveFrontBack(const Vector2& value); //!< Overloaded the function to steer the bat up and down.
+            virtual void moveRightLeft(const Vector2& value); //!< Overloaded the function to steer the bat up and down.
 
-            virtual void changedPlayer();
+            virtual void changedPlayer(); //!< Is called when the player changed.
 
+            /**
+            @brief Set the speed of the bat.
+            @param speed The speed to be set.
+            */
             void setSpeed(float speed)
                 { this->speed_ = speed; }
+            /**
+            @brief Get the speed of the bat.
+            @return Returns the speed of the bat.
+            */
             float getSpeed() const
                 { return this->speed_; }
 
+            /**
+            @brief Set the height of the playing field.
+            @param height The height of the playing field.
+            */
             void setFieldHeight(float height)
                 { this->fieldHeight_ = height; }
+            /**
+            @brief Get the height of the playing field.
+            @return Returns the height of the playing field.
+            */
             float getFieldHeight() const
                 { return this->fieldHeight_; }
 
+            /**
+            @brief Set the length of the bat.
+            @param length The length of the bat (in z-direction) as percentage of the height of the playing field.
+            */
             void setLength(float length)
                 { this->length_ = length; }
+            /**
+            @brief get the length of the bat.
+            @return Returns the length of the bat (in z-direction) as percentage of the height of the playing field.
+            */
             float getLength() const
                 { return this->length_; }
 
         private:
-            void registerVariables();
+            void registerVariables(); //!< Registers variables to be synchronized over the network.
 
-            float movement_;
-            bool bMoveLocal_;
-            float speed_;
-            float length_;
-            float fieldHeight_;
-            bool bSteadiedPosition_;
+            float movement_; //!< The amount (and direction), in z-direction, of movement of the bat.
+            bool bMoveLocal_; //!< Helper to know whether the movement is caused by moveFrontBack() or moveRightLeft().
+            float speed_; //!< The movement speed of the bat.
+            float length_; //!< The length of the bat (in z-direction) as percentage of the height of the playing field.
+            float fieldHeight_; //!< The height of the playing field.
+            bool bSteadiedPosition_; //!< Helper boolean, to keep track of when to steady the position, to ensure network synchronicity.
     };
 }

code/trunk/src/modules/pong/PongBot.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongBot.cc
+    @brief Implementation of the PongBot class.
+*/
+
 #include "PongBot.h"
 
@@ -36 +41 @@
     CreateFactory(PongBot);
 
+    /**
+    @brief
+        Constructor. Registers the object and creates a PongAI controller.
+    */
     PongBot::PongBot(BaseObject* creator) : Bot(creator)
     {

code/trunk/src/modules/pong/PongBot.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongBot.h
+    @brief Declaration of the PongBot class.
+    @ingroup Pong
+*/
+
 #ifndef _PongBot_H__
 #define _PongBot_H__
@@ -35 +41 @@
 namespace orxonox
 {
+
+    /**
+    @brief
+        A bot especially for @ref orxonox::Pong "Pong".
+
+        Uses the @ref orxonox::PongAI "PongAI".
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongBot : public Bot
     {

code/trunk/src/modules/pong/PongCenterpoint.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongCenterpoint.cc
+    @brief Implementation of the PongCenterpoint class.
+*/
+
 #include "PongCenterpoint.h"
 
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
+
 #include "Pong.h"
 
@@ -37 +43 @@
     CreateFactory(PongCenterpoint);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object and checks whether the gametype is actually Pong.
+    */
     PongCenterpoint::PongCenterpoint(BaseObject* creator) : StaticEntity(creator)
     {
@@ -51 +61 @@
     }
 
+    /**
+    @brief
+        Method to create a PongCenterpoint through XML.
+    */
     void PongCenterpoint::XMLPort(Element& xmlelement, XMLPort::Mode mode)
     {
@@ -64 +78 @@
     }
 
+    /**
+    @brief
+        Is called when the gametype has changed.
+    */
     void PongCenterpoint::changedGametype()
     {
         SUPER(PongCenterpoint, changedGametype);
 
+        // Check, whether it's still Pong.
         this->checkGametype();
     }
 
+    /**
+    @brief
+        Checks whether the gametype is Pong and if it is, sets its centerpoint.
+    */
     void PongCenterpoint::checkGametype()
     {
-        if (this->getGametype() && this->getGametype()->isA(Class(Pong)))
+        if (this->getGametype() != NULL && this->getGametype()->isA(Class(Pong)))
         {
-            Pong* pong_gametype = orxonox_cast<Pong*>(this->getGametype().get());
-            pong_gametype->setCenterpoint(this);
+            Pong* pongGametype = orxonox_cast<Pong*>(this->getGametype().get());
+            pongGametype->setCenterpoint(this);
         }
     }

code/trunk/src/modules/pong/PongCenterpoint.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongCenterpoint.h
+    @brief Declaration of the PongCenterpoint class.
+    @ingroup Pong
+*/
+
 #ifndef _PongCenterpoint_H__
 #define _PongCenterpoint_H__
@@ -33 +39 @@
 
 #include <string>
+
 #include <util/Math.h>
+
 #include "worldentities/StaticEntity.h"
 
 namespace orxonox
 {
+    
+    /**
+    @brief
+        The PongCenterpoint implements the playing field @ref orxonox::Pong "Pong" takes place in and allows for many parameters of the minigame to be set.
+        The playing field resides in the x,z-plane, with the x-axis being the horizontal axis and the z-axis being the vertical axis.
+        
+        Various parameters can be set:
+        - The <b>dimension</b> is a vector, that defines the width and height of the playing field. The default is <em>(200, 120)</em>.
+        - The <b>balltemplate</b> is a template that is applied to the @ref orxonox::PongBall "PongBall", it can be used to attach different things to it, e.g. its @ref orxonox::Model "Model". See below for a usage example.
+        - The <b>battemplate</b> is a template that is applied to the @ref orxonox::PongBall "PongBat", it can be used to attach different things to it, e.g. its @ref orxonox::Model "Model". See below for a usage example.
+        - The <b>ballspeed</b> is the speed with which the @ref orxonox::PongBall "PongBall" moves. The default is <em>100</em>.
+        - The <b>ballaccfactor</b> is the acceleration factor for the @ref orxonox::PongBall "PongBall". The default is <em>1.0</em>.
+        - The <b>batspeed</b> is the speed with which the @ref orxonox::PongBat "PongBats" move. The default is <em>60</em>.
+        - The <b>batlength</b> is the length of the @ref orxonox::PongBat "PongBats" as the percentage of the height of the playing field. The default is <em>0.25</em>.
+        
+        An example in XML of the PongCenterpoint would be:
+        
+        First the needed templates:
+        The template for the @ref orxonox::PongBall "PongBall".
+        @code
+        <Template name="pongball">
+          <PongBall>
+            <attached>
+              <Model mesh="sphere.mesh" scale="2" />
+              <ParticleSpawner name="hiteffect" position="0,0,0" source="Orxonox/sparks2" lifetime="0.01" autostart="0" mainstate="spawn" />
+            </attached>
+            <eventlisteners>
+              <EventTarget target="hiteffect" />
+            </eventlisteners>
+          </PongBall>
+        </Template>
+        @endcode
+        As can be seen, a sphere is attached as the @ref orxonox::Model "Model" for the @ref orxonox::PongBall "PongBall", and also an @ref orxonox::EventListener "EventListener" that triggers a @ref orxonox::ParticleSpawner "ParticleSpawner", whenever the ball hits the boundaries is attached.
+        
+        Additionally the template for the @ref orxonox::PongBat "PongBat".
+        @code
+        <Template name="pongbatcameras" defaults="0">
+          <PongBat>
+            <camerapositions>
+              <CameraPosition position="0,200,0" pitch="-90" absolute="true" />
+            </camerapositions>
+          </PongBat>
+        </Template>
+
+        <Template name="pongbat">
+          <PongBat camerapositiontemplate=pongbatcameras>
+            <attached>
+              <Model position="0,0,3" mesh="cube.mesh" scale3D="14,2,2" />
+            </attached>
+          </PongBat>
+        </Template>
+        @endcode
+        As can be seen, there are actually two templates. The first template is needed to set the camera for the @ref orxonox::PongBat "PongBat". The second template ist the actual template for the @ref orxonox::PongBat "PongBat", the template for the camera position is added and a @ref orxonox::Model "Model" for the @ref orxonox::PongBat "PongBat" is attached.
+        
+        Finally the PongCenterpoint is created.
+        @code
+        <PongCenterpoint name="pongcenter" dimension="200,120" balltemplate="pongball" battemplate="pongbat" ballspeed="200" ballaccfactor="1.0" batspeed="130" batlength="0.25">
+          <attached>
+            <Model position="0,0,60" mesh="cube.mesh" scale3D="105,1,1" />
+            <Model position="0,0,-60" mesh="cube.mesh" scale3D="105,1,1" />
+          </attached>
+        </PongCenterpoint>
+        @endcode
+        All parameters are specified. And also two @ref orxonox::Model "Models" (for the upper and lower boundary) are attached.
+        
+        For a more elaborate example, have a look at the <code>pong.oxw</code> level file.
+    
+    @author
+        Fabian 'x3n' Landau
+        
+    @ingroup Pong
+    */
     class _PongExport PongCenterpoint : public StaticEntity
     {
         public:
-            PongCenterpoint(BaseObject* creator);
+            PongCenterpoint(BaseObject* creator); //!< Constructor. Registers and initializes the object and checks whether the gametype is actually Pong.
             virtual ~PongCenterpoint() {}
 
-            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
-
-            virtual void changedGametype();
-
+            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode); //!< Method to create a PongCenterpoint through XML.
+
+            virtual void changedGametype(); //!< Is called when the gametype has changed.
+
+            /**
+            @brief Set the template for the ball. (e.g. to attach the model of the ball, but also to attach an EventListener to it to detect, when it hits the boundaries, and e.g. display some ParticleEffets, when it does.)
+            @param balltemplate The name of the template to be set.
+            */
             void setBalltemplate(const std::string& balltemplate)
                 { this->balltemplate_ = balltemplate; }
+            /**
+            @brief Get the template of the ball.
+            @return Returns the name of the template of the ball. 
+            */
             const std::string& getBalltemplate() const
                 { return this->balltemplate_; }
 
+            /**
+            @brief Set the template for the bats. (e.g. to attach the model of the bat, but also to attach CameraPositions to it, to be able to view the game from the bats perspective)
+            @param battemplate The name of the template to be set.
+            */
             void setBattemplate(const std::string& battemplate)
                 { this->battemplate_ = battemplate; }
+            /**
+            @brief Get the template of the bats.
+            @return Returns the name of the template of the bats.
+            */
             const std::string& getBattemplate() const
                 { return this->battemplate_; }
 
+            /**
+            @brief Set the dimensions of the playing field.
+            @param dimension A vector with the width of the playing field as first component and the height as second.
+            */
             void setFieldDimension(const Vector2& dimension)
                 { this->width_ = dimension.x; this->height_ = dimension.y; }
+            /**
+            @brief Get the dimensions of the playing field.
+            @return Returns a vector with the width of the playing field as first component and the height as second.
+            */
             Vector2 getFieldDimension() const
                 { return Vector2(this->width_, this->height_); }
 
+            /**
+            @brief Set the speed of the ball.
+            @param ballspeed The speed of the ball.
+            */
             void setBallSpeed(float ballspeed)
                 { this->ballspeed_ = ballspeed; }
+            /**
+            @brief Get the speed of the ball.
+            @return Returns the speed of the ball.
+            */
             float getBallSpeed() const
                 { return this->ballspeed_; }
 
+            /**
+            @brief Set the ball's acceleration factor.
+            @param ballaccfactor The ball's acceleration factor.
+            */
             void setBallAccelerationFactor(float ballaccfactor)
                 { this->ballaccfactor_ = ballaccfactor; }
+            /**
+            @brief Get the ball's acceleration factor
+            @return Returns the ball's acceleration factor.
+            */
             float getBallAccelerationFactor() const
                 { return this->ballaccfactor_; }
 
+            /**
+            @brief Set the speed of the bats.
+            @param batspeed The speed of the bats.
+            */
             void setBatSpeed(float batspeed)
                 { this->batspeed_ = batspeed; }
+            /**
+            @brief Get the speed of the bats.
+            @return Returns the speed of the bats.
+            */
             float getBatSpeed() const
                 { return this->batspeed_; }
 
+            /**
+            @brief Set the length of the bats.
+            @param batlength The length of the bats (in z-direction) as a percentage of the height of the playing field.
+            */
             void setBatLength(float batlength)
                 { this->batlength_ = batlength; }
+            /**
+            @brief Get the length of the bats.
+            @return Returns the length of the bats (in z-direction) as a percentage of the height of the playing field.
+            */
             float getBatLength() const
                 { return this->batlength_; }
 
         private:
-            void checkGametype();
-
-            std::string balltemplate_;
-            std::string battemplate_;
-
-            float ballspeed_;
-            float ballaccfactor_;
-            float batspeed_;
-            float batlength_;
-
-            float width_;
-            float height_;
+            void checkGametype(); //!< Checks whether the gametype is Pong and if it is, sets its centerpoint.
+
+            std::string balltemplate_; //!< The template for the ball.
+            std::string battemplate_; //!< The template for the bats.
+
+            float ballspeed_; //!< The speed of then ball.
+            float ballaccfactor_; //!< The acceleration factor of the ball.
+            float batspeed_; //!< The speed of the bat.
+            float batlength_; //!< The length of the bat (in z-direction) as a percentage of the height of the playing field.
+
+            float width_; //!< The height of the playing field.
+            float height_; //!< The width of the playing field.
     };
 }

code/trunk/src/modules/pong/PongScore.cc

@@ -27 +27 @@
  */
 
+/**
+    @file PongScore.cc
+    @brief Implementation of the PongScore class.
+*/
+
 #include "PongScore.h"
 
-#include "util/Convert.h"
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
+#include "util/Convert.h"
+
+#include "infos/PlayerInfo.h"
+
 #include "Pong.h"
-#include "infos/PlayerInfo.h"
 
 namespace orxonox
@@ -39 +46 @@
     CreateFactory(PongScore);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    */
     PongScore::PongScore(BaseObject* creator) : OverlayText(creator)
     {
@@ -51 +62 @@
     }
 
+    /**
+    @brief
+        Destructor.
+    */
     PongScore::~PongScore()
     {
     }
 
+    /**
+    @brief
+        Method to create a PongScore through XML.
+    */
     void PongScore::XMLPort(Element& xmlelement, XMLPort::Mode mode)
     {
@@ -65 +84 @@
     }
 
+    /**
+    @brief
+        Is called each tick.
+        Creates and sets the caption to be displayed by the PongScore.
+    @param dt
+        The time that has elapsed since the last tick.
+    */
     void PongScore::tick(float dt)
     {
         SUPER(PongScore, tick, dt);
 
-        if (this->owner_)
+        // If the owner is set. The owner being a Pong game.
+        if (this->owner_ != NULL)
         {
+            // Get the two players.
             PlayerInfo* player1 = this->owner_->getLeftPlayer();
             PlayerInfo* player2 = this->owner_->getRightPlayer();
@@ -80 +108 @@
             std::string score2("0");
 
-            if (player1)
+            // Save the name and score of each player as a string.
+            if (player1 != NULL)
             {
                 name1 = player1->getName();
                 score1 = multi_cast<std::string>(this->owner_->getScore(player1));
             }
-
-            if (player2)
+            if (player2 != NULL)
             {
                 name2 = player2->getName();
@@ -92 +120 @@
             }
 
+            // Assemble the strings, depending on what should all be displayed.
             std::string output1;
             if (this->bShowLeftPlayer_)
             {
-                if (this->bShowName_ && this->bShowScore_ && player1)
+                if (this->bShowName_ && this->bShowScore_ && player1 != NULL)
                     output1 = name1 + " - " + score1;
                 else if (this->bShowScore_)
@@ -106 +135 @@
             if (this->bShowRightPlayer_)
             {
-                if (this->bShowName_ && this->bShowScore_ && player2)
+                if (this->bShowName_ && this->bShowScore_ && player2 != NULL)
                     output2 = score2 + " - " + name2;
                 else if (this->bShowScore_)
@@ -127 +156 @@
     }
 
-
+    /**
+    @brief
+        Is called when the owner changes.
+        Sets the owner to NULL, if it is not a pointer to a Pong game.
+    */
     void PongScore::changedOwner()
     {
         SUPER(PongScore, changedOwner);
 
-        if (this->getOwner() && this->getOwner()->getGametype())
+        if (this->getOwner() != NULL && this->getOwner()->getGametype())
             this->owner_ = orxonox_cast<Pong*>(this->getOwner()->getGametype().get());
         else

code/trunk/src/modules/pong/PongScore.h

@@ -27 +27 @@
  */
 
+/**
+    @file PongScore.h
+    @brief Declaration of the PongScore class.
+    @ingroup Pong
+*/
+
 #ifndef _PongScore_H__
 #define _PongScore_H__
@@ -33 +39 @@
 
 #include "tools/interfaces/Tickable.h"
+
 #include "overlays/OverlayText.h"
 
 namespace orxonox
 {
+
+    /**
+    @brief
+        The PongScore class displays the score for a game of @ref orxonox::Pong "Pong".
+
+    @author
+        Fabian 'x3n' Landau
+
+    @ingroup Pong
+    */
     class _PongExport PongScore : public OverlayText, public Tickable
     {
@@ -43 +60 @@
             virtual ~PongScore();
 
-            virtual void tick(float dt);
+            virtual void tick(float dt); //!< Creates and sets the caption to be displayed by the PongScore.
             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
-            virtual void changedOwner();
+            virtual void changedOwner(); //!< Is called when the owner changes.
 
+            /**
+            @brief Set whether the PongScore displays the players' names.
+            @param value If true the players' names are displayed.
+            */
             inline void setShowName(bool value)
                 { this->bShowName_ = value; }
+            /**
+            @brief Get whether the PongScore displays the players' names.
+            @return Returns true if the players' names are displayed, false otherwise.
+            */
             inline bool getShowName() const
                 { return this->bShowName_; }
 
+            /**
+            @brief Set whether the PongScore displays the players' scores.
+            @param value If true the players' scores are displayed.
+            */
             inline void setShowScore(bool value)
                 { this->bShowScore_ = value; }
+            /**
+            @brief Get whether the PongScore displays the players' scores.
+            @return Returns true if the players' scores are displayed, false otherwise.
+            */
             inline bool getShowScore() const
                 { return this->bShowScore_; }
 
+            /**
+            @brief Set whether the PongScore displays the left player.
+            @param value If true the left player is displayed.
+            */
             inline void setShowLeftPlayer(bool value)
                 { this->bShowLeftPlayer_ = value; }
+            /**
+            @brief Get whether the PongScore displays the left player.
+            @return Returns true if the left player is displayed, false otherwise.
+            */
             inline bool getShowLeftPlayer() const
                 { return this->bShowLeftPlayer_; }
 
+            /**
+            @brief Set whether the PongScore displays the right player.
+            @param value If true the right player is displayed.
+            */
             inline void setShowRightPlayer(bool value)
                 { this->bShowRightPlayer_ = value; }
+            /**
+            @brief Get whether the PongScore displays the right player.
+            @return Returns true if the right player is displayed, false otherwise.
+            */
             inline bool getShowRightPlayer() const
                 { return this->bShowRightPlayer_; }
 
         private:
-            Pong* owner_;
-            bool bShowName_;
-            bool bShowScore_;
-            bool bShowLeftPlayer_;
-            bool bShowRightPlayer_;
+            Pong* owner_; //!< The Pong game that owns this PongScore.
+            bool bShowName_; //!< Whether the names of the players are shown.
+            bool bShowScore_; //!< Whether the score of the players is shown.
+            bool bShowLeftPlayer_; //!< Whether the left player is shown.
+            bool bShowRightPlayer_; //!< Whether the right player is shown.
     };
 }