Changeset 7541

Timestamp:

Oct 14, 2010, 12:55:59 PM (14 years ago)

Author:

dafrick

Message:

Some more documentation.

Location:

code/trunk/src/modules/pickup/items

Files:

• DronePickup.cc (modified) (5 diffs)
• DronePickup.h (modified) (4 diffs)
• HealthPickup.cc (modified) (6 diffs)
• HealthPickup.h (modified) (3 diffs)
• InvisiblePickup.cc (modified) (5 diffs)
• InvisiblePickup.h (modified) (1 diff)

code/trunk/src/modules/pickup/items/DronePickup.cc

@@ -33 +33 @@
 
 #include "DronePickup.h"
-#include "worldentities/Drone.h"
-#include "controllers/DroneController.h"
+
+#include <sstream>
 
 #include "core/CoreIncludes.h"
@@ -40 +40 @@
 #include "util/StringUtils.h"
 
+#include "controllers/DroneController.h"
+#include "pickup/PickupIdentifier.h"
 #include "worldentities/pawns/Pawn.h"
-#include "pickup/PickupIdentifier.h"
-
-#include <sstream>
+#include "worldentities/Drone.h"
+#include "worldentities/StaticEntity.h"
 
 namespace orxonox
@@ -104 +105 @@
     }
 
+    /**
+    @brief
+        Set the droneTemplate.
+    @param templatename
+        The name of the Template to e set.
+    */
     void DronePickup::setDroneTemplate(std::string templatename){
         droneTemplate_ = templatename;
     }
 
+    /**
+    @brief
+        Get the name of the droneTemplate.
+    @return
+        Returns the name of the droneTemplate.
+    */
     const std::string& DronePickup::getDroneTemplate() const
     {
@@ -121 +134 @@
         SUPER(DronePickup, changedUsed);
 
-        //! If the pickup is not picked up nothing must be done.
+        // If the pickup is not picked up nothing must be done.
         if(!this->isPickedUp())
             return;
 
-        //! If the pickup has transited to used.
+        // If the pickup has transited to used.
         if(this->isUsed())
         {
 
                 Pawn* pawn = this->carrierToPawnHelper();
-                if(pawn == NULL) //!< If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
+                if(pawn == NULL) // If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
                     this->Pickupable::destroy();
 
@@ -147 +160 @@
                 drone->setPosition(spawnPosition);
 
-                //! The pickup has been used up.
+                // The pickup has been used up.
                 this->setUsed(false);
         }
         else
         {
-            //! If either the pickup can only be used once or it is continuous and used up, it is destroyed upon setting it to unused.
+            // If either the pickup can only be used once or it is continuous and used up, it is destroyed upon setting it to unused.
             if(this->isOnce() || (this->isContinuous() ))
             {

code/trunk/src/modules/pickup/items/DronePickup.h

@@ -39 +39 @@
 
 #include <string>
-#include <worldentities/pawns/Pawn.h>
-#include <worldentities/Drone.h>
-
-#include "worldentities/StaticEntity.h"
 
 #include "pickup/Pickup.h"
@@ -49 +45 @@
 namespace orxonox {
 
+    /**
+    @brief
+        The DronePickup adds a Drone to the Pawn upon being picked up.
+        It can be used in XML as follows:
+        @code
+        <DronePickup droneTemplate="myDroneTemplate" />
+        @endcode
+        Where <em>droneTemplate</em> specifies a @ref orxonox::Template "Template" based on which the Drone is created.
 
+    @author
+        Lukas Gassner
+
+    @ingroup PickupItems
+    */
     class _PickupExport DronePickup : public Pickup, public Tickable
     {
@@ -62 +71 @@
             virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
 
-            void setDroneTemplate(std::string templatename);
-            const std::string& getDroneTemplate() const;
+            void setDroneTemplate(std::string templatename); //!< Set the droneTemplate.
+            const std::string& getDroneTemplate() const; //!< Get the name of the droneTemplate.
 
         protected:
@@ -70 +79 @@
         private:
             void initialize(void); //!< Initializes the member variables.
-            std::string droneTemplate_;
+            std::string droneTemplate_; //!< The name of the template, based upon which the Drone is created.
             Pawn* carrierToPawnHelper(void); //!< Helper to transform the PickupCarrier to a Pawn, and throw an error message if the conversion fails.
 

code/trunk/src/modules/pickup/items/HealthPickup.cc

@@ -142 +142 @@
         {
             Pawn* pawn = this->carrierToPawnHelper();
-            if(pawn == NULL) //!< If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
+            if(pawn == NULL) // If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
                 this->Pickupable::destroy();
 
-            //! Calculate the health that is added this tick.
+            // Calculate the health that is added this tick.
             float health = dt*this->getHealthRate();
             if(health > this->getHealth())
                 health = this->getHealth();
-            //! Calculate the health the Pawn will have once the health is added.
+            // Calculate the health the Pawn will have once the health is added.
             float fullHealth = pawn->getHealth() + health;
             this->setHealth(this->getHealth()-health);
@@ -174 +174 @@
             }
 
-            //! If all health has been transfered.
+            // If all health has been transferred.
             if(this->getHealth() == 0)
             {
@@ -190 +190 @@
         SUPER(HealthPickup, changedUsed);
 
-        //! If the pickup is not picked up nothing must be done.
+        // If the pickup is not picked up nothing must be done.
         if(!this->isPickedUp()) //TODO: Needed?
             return;
 
-        //! If the pickup has transited to used.
+        // If the pickup has transited to used.
         if(this->isUsed())
         {
@@ -200 +200 @@
             {
                 Pawn* pawn = this->carrierToPawnHelper();
-                if(pawn == NULL) //!< If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
+                if(pawn == NULL) // If the PickupCarrier is no Pawn, then this pickup is useless and therefore is destroyed.
                     this->Pickupable::destroy();
 
@@ -227 +227 @@
                 }
 
-                //! The pickup has been used up.
+                // The pickup has been used up.
                 this->setUsed(false);
             }
@@ -253 +253 @@
             }
 
-            //! If either the pickup can only be used once or it is continuous and used up, it is destroyed upon setting it to unused.
+            // If either the pickup can only be used once or it is continuous and used up, it is destroyed upon setting it to unused.
             if(this->isOnce() || (this->isContinuous() && this->getHealth() == 0))
             {

code/trunk/src/modules/pickup/items/HealthPickup.h

@@ -47 +47 @@
 namespace orxonox {
 
-    //! Enum for the type of the HealthPickup
+    /**
+    @brief
+        Enum for the type of the @ref orxonox::HealthPickup "HealthPickup".
+
+    @ingroup PickupItems
+    */
     namespace pickupHealthType
     {
         enum Value
         {
-            limited,
-            temporary,
-            permanent
+            limited, //!< Means that the @ref orxonox::HealthPickup "HealthPickup" only increases the users health to its maximum health.
+            temporary, //!< Means that the @ref orxonox::HealthPickup "HealthPickup" temporarily increases the users health even above its maximum health, but only as long as it is in use.
+            permanent //!< Means that the @ref orxonox::HealthPickup "HealthPickup" increases the users health even above its maximum health and increases the maximum health permanently such that it matches the new health.
         };
     }
@@ -60 +65 @@
     /**
     @brief
-        A pickup that can do (dependent upon the parameters) lots of different things to the health of a Pawn.
+        The Health Pickup is a Pickupable that can do (dependent upon the parameters) lots of different things to the health of a Pawn.
         There are 4 parameters that can be chosen:
-        - The @b health The amount of health that (in a way dependent on the other parameters) is transfered to the Pawn.
-        - The @b activation @b type It can be chosen to be either 'immediate' or 'onUse'. The activation type essentially (as indicated by the name) defines when the health is transfered, either immediately after being picked up or only after the player uses it.
-        - The @b duration @b type It can be chosen to be either 'once' or 'continuous'. For 'once' the specified health is transfered once to the Pawn, for 'continuous' the set health is transfered over a span of time at a rate defined by the health rate parameter.
-        - The @b health @b type The health type can be chosen to be 'limited', 'temporary' or 'permanent'. 'limited' means that the health is increased only to the maximum health of the Pawn. 'temporary' means that the maximum health is temporarily elevated but will be set back as soon as the pickup is no longer in use. 'permanent' means that the maximum health of the Pawn is increased such that the health provided by the pickup will fit in and the maximum health stays that way.
+        - The <b>health</b> The amount of health that (in a way dependent on the other parameters) is transferred to the Pawn.
+        - The <b>activation type</b> It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the health is transferred, either immediately after being picked up or only after the player uses it.
+        - The <b>duration type</b> It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the specified health is transferred once to the Pawn, for <em>continuous</em> the set health is transferred over a span of time at a rate defined by the health rate parameter.
+        - The <b>health type</b> The health type can be chosen to be <em>limited</em>, <em>temporary</em> or <em>permanent</em>. <em>limited</em> means that the health is increased only to the maximum health of the Pawn. 'temporary' means that the maximum health is temporarily elevated but will be set back as soon as the pickup is no longer in use. <em>permanent</em> means that the maximum health of the Pawn is increased such that the health provided by the pickup will fit in and the maximum health stays that way.
+
+        An examle of a XML implementation of a HealthPickup would be:
+        @code
+        <HealthPickup
+            health = 33
+            healthType = "limited"
+            activationType = "immediate"
+            durationType = "once"
+        />
+        @endcode
+
     @author
         Damian 'Mozork' Frick
+
+    @ingroup PickupItems
     */
     class _PickupExport HealthPickup : public Pickup, public Tickable
@@ -83 +101 @@
 
             /**
-            @brief Get the health that is transfered to the Pawn upon usage of this pickup.
+            @brief Get the health that is transferred to the Pawn upon usage of this pickup.
             @return Returns the health.
             */

code/trunk/src/modules/pickup/items/InvisiblePickup.cc

@@ -57 +57 @@
     {
         RegisterObject(InvisiblePickup);
-        //! Defines who is allowed to pick up the pickup.
         this->initialize();
     }
@@ -86 +85 @@
     {
         this->duration_ = 0.0f;
+        // Defines who is allowed to pick up the pickup.
         this->addTarget(ClassIdentifier<Pawn>::getIdentifier());
     }
@@ -99 +99 @@
 
         this->initializeIdentifier();
+        this->setDurationType(Pickup::durationTypeOnce_s); // The duration type is always once.
     }
 
@@ -109 +110 @@
         SUPER(InvisiblePickup, changedUsed);
 
-        //! If the pickup is not picked up nothing must be done.
+        // If the pickup is not picked up nothing must be done.
         if(!this->isPickedUp())
             return;
@@ -115 +116 @@
         if (this->isUsed())
         {
-            if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
+            if(this->isContinuous()
             {
-                this->durationTimer_.unpauseTimer();
-            }
-            else
-            {
-                this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&InvisiblePickup::pickupTimerCallback, this)));
+                if(!this->durationTimer_.isActive() && this->durationTimer_.getRemainingTime() > 0.0f)
+                {
+                    this->durationTimer_.unpauseTimer();
+                }
+                else
+                {
+                    this->durationTimer_.setTimer(this->getDuration(), false, createExecutor(createFunctor(&InvisiblePickup::pickupTimerCallback, this)));
+                }
             }
 

code/trunk/src/modules/pickup/items/InvisiblePickup.h

@@ -50 +50 @@
         A pickup that makes the Pawn invisible.
         There are 2 parameters that can be chosen:
-        - The @b activation @b type It can be chosen to be either 'immediate' or 'onUse'. The activation type essentially (as indicated by the name) defines when the Pawn will be invisible, either immediately after being picked up or only after the player uses it.
-        - The @b duration @b type It can be chosen how long the Pawn will be invisibel.
+        - The <b>activation type</b> It can be chosen to be either <em>immediate</em> or <em>onUse</em>. The activation type essentially (as indicated by the name) defines when the Pawn will be invisible, either immediately after being picked up or only after the player uses it.
+        - The <b>duration type</b> It can be chosen to be either <em>once</em> or <em>continuous</em>. For <em>once</em> the InvisiblePickup just makes the Pawn invisible for as long as it is used, for <em>continuous</em> the Pawn is invisible for the specified duration.
+        - The <b>duration</b> Specifies how long (in seconds) the invisibility lasts.
+
     @author
         Benedict Simlinger
+
+    @ingroup PickupItems
     */
     class _PickupExport InvisiblePickup : public Pickup