Changeset 7494 for code/trunk/src/modules

Timestamp:

Sep 28, 2010, 5:31:59 PM (14 years ago)

Author:

dafrick

Message:

Some documenting and cleaning up/re-organization in pickups module.

Location:

code/trunk/src/modules/pickup

Files:

• CollectiblePickup.cc (modified) (1 diff)
• CollectiblePickup.h (modified) (3 diffs)
• DroppedPickup.cc (modified) (1 diff)
• Pickup.cc (modified) (6 diffs)
• Pickup.h (modified) (6 diffs)
• PickupCollection.cc (modified) (3 diffs)
• PickupCollection.h (modified) (3 diffs)
• PickupCollectionIdentifier.cc (modified) (2 diffs)
• PickupCollectionIdentifier.h (modified) (3 diffs)
• PickupManager.cc (modified) (6 diffs)
• PickupSpawner.h (modified) (1 diff)

code/trunk/src/modules/pickup/CollectiblePickup.cc

@@ -35 +35 @@
 
 #include "core/CoreIncludes.h"
+
 #include "PickupCollection.h"
 

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

@@ -46 +46 @@
         The CollectiblePickup class encompasses all @ref orxonox::Pickupable "Pickupables" that can be added to a @ref orxonox::PickupCollection "PickupCollection" and thus be part of such.
 
-        All you need to do to make your @ref orxonox:.Pickupable "Pickupable" a CollectiblePickup is to, in some way, inherit from it. (The @ref orxonox::Pickup Pickup class, for example, is already a CollectiblePickup).
+        All you need to do to make your @ref orxonox::Pickupable "Pickupable" a CollectiblePickup is to, in some way, inherit from it. (The @ref orxonox::Pickup "Pickup" class, for example, is already a CollectiblePickup).
 
     @author
@@ -63 +63 @@
             /**
             @brief Check whether the given CollectiblePickup is par of a PickupCollection.
-            @return Returns true if the ColelctiblePickup is part of a PickupCollection.
+            @return Returns true if the CollectiblePickup is part of a PickupCollection.
             */
             bool isInCollection(void)
                 { return this->isInCollection_; }
-            
+
             bool addToCollection(PickupCollection* collection); //!< Adds this CollectiblePickup to the input PickupCollection.
             bool removeFromCollection(void); //!< Removes this CollectiblePickup from its PickupCollection.
@@ -75 +75 @@
         protected:
             virtual void preDestroy(void); //!< Is called by OrxonoxClass::destroy() before the object is actually destroyed.
-            virtual void destroyPickup(void); //!< //!< Destroys a Pickupable.
+            virtual void destroyPickup(void); //!< Destroys a Pickupable.
 
         private:

code/trunk/src/modules/pickup/DroppedPickup.cc

@@ -35 +35 @@
 
 #include "core/CoreIncludes.h"
+
 #include "interfaces/Pickupable.h"
 #include "interfaces/PickupCarrier.h"
-#include "graphics/Model.h"
 
 namespace orxonox

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

@@ -36 +36 @@
 #include "core/CoreIncludes.h"
 #include "util/StringUtils.h"
+
 #include "pickup/PickupIdentifier.h"
+
 #include "DroppedPickup.h"
-
-#include "tools/Timer.h"
 
 namespace orxonox
@@ -51 +51 @@
     CreateUnloadableFactory(Pickup);
 
+    /**
+    @brief
+        Constructor. Registers and initializes the object.
+    @param creator
+        The objects creator.
+    */
     Pickup::Pickup(BaseObject* creator) : BaseObject(creator)
     {
@@ -58 +64 @@
     }
 
+    /**
+    @brief
+        Destructor.
+    */
     Pickup::~Pickup()
     {
@@ -158 +168 @@
         else
         {
-            COUT(1) << "Invalid activationType in pickup." << std::endl;
+            COUT(1) << "Invalid activationType '" << type << "' in pickup." << std::endl;
         }
     }
@@ -180 +190 @@
         else
         {
-            COUT(1) << "Invalid durationType in pickup." << std::endl;
+            COUT(1) << "Invalid durationType '" << type << "' in pickup." << std::endl;
         }
     }
@@ -193 +203 @@
         SUPER(Pickup, changedPickedUp);
 
-        //! Sets the Pickup to used if the Pickup has activation type 'immediate' and gets picked up.
+        // Sets the Pickup to used if the Pickup has activation type 'immediate' and gets picked up.
         if(this->isPickedUp() && this->isImmediate())
-        {
             this->setUsed(true);
-        }
-    }
-
-    /**
-    @brief
-        Creates a duplicate of the Pickup.
-    @return
-        Returns the clone of this pickup as a pointer to a Pickupable.
+    }
+
+    /**
+    @brief
+        Creates a duplicate of the OrxonoxClass.
+    @param item
+        A reference to the pointer of the item that we're duplicating.
     */
     void Pickup::clone(OrxonoxClass*& item)

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

@@ -48 +48 @@
 {
 
-    //! Enum for the activation type.
+    //! Enum for the @ref orxonox::Pickup "Pickup" activation type.
     namespace pickupActivationType
     {
         enum Value
         {
-            immediate,
-            onUse,
+            immediate, //!< Means that the @ref orxonox::Pickup "Pickup" will be used immediately after pickup.
+            onUse, //!< Means that the @ref orxonox::Pickup "Pickup" will be used at a later point trough some external influence.
         };
     }
 
-    //! Enum for the duration tyoe.
+    //! Enum for the @ref orxonox::Pickup "Pickup" duration type.
     namespace pickupDurationType
     {
         enum Value
         {
-            once,
-            continuous,
+            once, //!< Means that the @ref orxonox::Pickup "Pickup" will be used only once at a singular time instant.
+            continuous, //!< Means that the @ref orxonox::Pickup "Pickup" will be used over a continuous timespan.
         };
     }
@@ -70 +70 @@
     /**
     @brief
-        Pickup class. Offers base functionality for a wide range of pickups.
-        Pickups ingeriting from this class cann choose an activation type and a duration type.
+        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.
+        - The <b>activation type</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.
+        - The <b>duration type</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.
+
+        If it were not an abstract class it could for example be used as follows in XML.
+        @code
+        <Pickup activationType="onUse" durationType="continuous" />
+        @endcode
+        In reality you can (naturally) use the parameters <b>activation type</b> and <b>duration type</b> in any pickup inheriting from Pickup, unless the pickup already specifies one (or both) of the parameters.
+
     @author
         Damian 'Mozork' Frick
@@ -85 +95 @@
 
             /**
-            @brief Get the activation type of the pickup.
-            @return Returns the activation type of the pickup.
+            @brief Get the activation type of the Pickup.
+            @return Returns the activation type of the Pickup.
             */
             inline pickupActivationType::Value getActivationTypeDirect(void)
                 { return this->activationType_; }
             /**
-            @brief Get the duration type of the pickup.
-            @return Returns the duration type of the pickup.
+            @brief Get the duration type of the Pickup.
+            @return Returns the duration type of the Pickup.
             */
             inline pickupDurationType::Value getDurationTypeDirect(void)
                 { return this->durationType_; }
 
-            const std::string& getActivationType(void); //!< Get the activation type of the pickup.
-            const std::string& getDurationType(void); //!< Get the duration type of the pickup.
+            const std::string& getActivationType(void); //!< Get the activation type of the Pickup.
+            const std::string& getDurationType(void); //!< Get the duration type of the Pickup.
 
             /**
@@ -127 +137 @@
             virtual void changedPickedUp(void); //!< Should be called when the pickup has transited from picked up to dropped or the other way around.
 
-            virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the Pickup.
+            virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the OrxonoxClass.
 
         protected:
@@ -135 +145 @@
 
             /**
-            @brief Set the activation type of the pickup.
-            @param type The activation type of the pickup.
+            @brief Set the activation type of the Pickup.
+            @param type The activation type of the Pickup.
             */
             inline void setActivationTypeDirect(pickupActivationType::Value type)
                 { this->activationType_ = type; }
             /**
-            @brief Set the duration type of the pickup.
-            @param type The duration type of the pickup.
+            @brief Set the duration type of the Pickup.
+            @param type The duration type of the Pickup.
             */
             inline void setDurationTypeDirect(pickupDurationType::Value type)
                 { this->durationType_ = type; }
 
-            void setActivationType(const std::string& type); //!< Set the activation type of the pickup.
-            void setDurationType(const std::string& type); //!< Set the duration type of the pickup
+            void setActivationType(const std::string& type); //!< Set the activation type of the Pickup.
+            void setDurationType(const std::string& type); //!< Set the duration type of the Pickup.
 
         private:
@@ -154 +164 @@
 
             pickupActivationType::Value activationType_; //!< The activation type of the Pickup.
-            pickupDurationType::Value durationType_; //!< The duration type of the pickup.
+            pickupDurationType::Value durationType_; //!< The duration type of the Pickup.
 
             //! Strings for the activation and duration types.

code/trunk/src/modules/pickup/PickupCollection.cc

@@ -34 +34 @@
 #include "core/CoreIncludes.h"
 #include "core/XMLPort.h"
+
 #include "interfaces/PickupCarrier.h"
+
 #include "CollectiblePickup.h"
 #include "DroppedPickup.h"
@@ -49 +51 @@
     @brief
         Default Constructor.
+    @param creator
+        The creator of the object.
     */
     PickupCollection::PickupCollection(BaseObject* creator) : BaseObject(creator)
@@ -201 +205 @@
     /**
     @brief
-        Creates a duplicate of the input OrxonoxClass.
+        Creates a duplicate of the input Pickupable.
         This method needs to be implemented by any Class inheriting from Pickupable.
     @param item

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

@@ -48 +48 @@
     /**
     @brief
-        The PickupCollection combines different Pickupables to a coherent, single pickup and makes them seem (from the outside looking in) just as if they were just one Pickupable.
+        The PickupCollection combines different @ref orxonox::Pickupable "Pickupables" (more precisely @ref orxonox::CollectiblePickup "CollectiblePickups") to a coherent, single pickup and makes them seem (from the outside looking in) just as if they were just one @ref orxonox::Pickupable "Pickupable".
+
+        To differentiate between different types of @ref orxonox::PickupCollection "PickupCollections" (just as we differentiate between different types of @ref orxonox::Pickupable "Pickupables") we define a new identifyer called the @ref orxonox::PickupCollectionIdentifier "PickupCollectionIdentifier" which has pretty much the same properties as the @ref orxonox::PickupIdentifier "PickupIdentifier" but extende to @ref orxonox::PickupCollection "PickupCollections".
+
+        A PickupCollection can be created in XML as follows:
+        @code
+        <PickupCollection>
+            <pickupables>
+                <CollectiblePickup ... />
+                ...
+                <CollectiblePickup ... />
+            </pickupables>
+        </PickupCollection>
+        @endcode
+
     @author
         Damian 'Mozork' Frick
@@ -65 +79 @@
             virtual void changedPickedUp(void); //!< Is called when the pickup has transited from picked up to dropped or the other way around.
 
-            virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
+            virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input pickup.
 
             virtual bool isTarget(PickupCarrier* carrier) const; //!< Get whether a given class, represented by the input Identifier, is a target of this PickupCollection.
@@ -88 +102 @@
             void changedUsedAction(void); //!< Helper method.
             void changedPickedUpAction(void); //!< Helper method.
-            
+
             std::vector<CollectiblePickup*> pickups_; //!< The list of the pointers of all the Pickupables this PickupCollection consists of. They are weak pointers to facilitate testing, whether the pointers are still valid.
 

code/trunk/src/modules/pickup/PickupCollectionIdentifier.cc

@@ -67 +67 @@
     int PickupCollectionIdentifier::compare(const PickupIdentifier* identifier) const
     {
+        assert(identifier);
+
         // Slight un-niceity to cast the PickupIdentifier to a PickupCollectionIdentifier.
         PickupIdentifier* temp = const_cast<PickupIdentifier*>(identifier);
-        const PickupCollectionIdentifier* collectionIdentifier = dynamic_cast<PickupCollectionIdentifier*>(temp);
+        const PickupCollectionIdentifier* collectionIdentifier = orxonox_cast<PickupCollectionIdentifier*>(temp);
 
         // If the input PickupIdentifier 'identifier' is no PickupCollectionIdentifier then just the two PickupIdentifiers are compared.
@@ -92 +94 @@
         }
 
-        //! Means they are equal.
+        // Means they are equal.
         return 0;
     }

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

@@ -38 +38 @@
 #include "PickupPrereqs.h"
 
+#include <set>
+
 #include "pickup/PickupIdentifier.h"
-
-#include <set>
 
 namespace orxonox
@@ -47 +47 @@
     /**
     @brief
-        The PickupCollectionIdentifier is the specialization of the PickupIdentifier for the PickupCollection class.
-        It identifies PickupCollections based on the different Pickupables they consist of.
-        Pickupables can be added to the PickupCollectionIdentifier via the addPickup method.
+        The PickupCollectionIdentifier is the specialization of the PickupIdentifier for the @ref orxonox::PickupCollection "PickupCollection" class.
+        It identifies @ref orxonox::PickupCollection "PickupCollections" based on the different @ref orxonox::CollectiblePickup "CollectiblePickups" they consist of.
+
+        @ref orxonox::Pickupable "Pickupables" (resp. @ref orxonox::CollectiblePickup "CollectiblePickups") can be added to the PickupCollectionIdentifier via the addPickup method.
     @author
         Damian 'Mozork' Frick
@@ -62 +63 @@
             virtual int compare(const PickupIdentifier* identifier) const; //!< Compares a PickupCollectionIdentifier with a PickupIdentifier.
 
-            void addPickup(const PickupIdentifier* identifier); //!< Add a Pickupable to the PickupCollectionIdentifier.
+            void addPickup(const PickupIdentifier* identifier); //!< Add a @ref orxonox::Pickupable "Pickupable" to the PickupCollectionIdentifier.
 
         private:
-            std::set<const PickupIdentifier*, PickupIdentifierCompare> identifiers_; //!< The set of PickupIdentifiers of the Pickupables the PickupCollection with this PickupCollectionIdentifier consists of, ordered by the rule set by PickupIdentifierCompare.
+            std::set<const PickupIdentifier*, PickupIdentifierCompare> identifiers_; //!< The set of PickupIdentifiers of the @ref orxonox::Pickupable "Pickupables", the @ref orxonox::PickupCollection "PickupCollection" with this PickupCollectionIdentifier consists of, ordered by the rule set by @ref orxonox::PickupIdentifierCompare "PickupIdentifierCompare".
 
     };

code/trunk/src/modules/pickup/PickupManager.cc

@@ -21 +21 @@
  *
  *   Author:
- *      ...
+ *      Damian 'Mozork' Frick
  *   Co-authors:
  *      ...
@@ -100 +100 @@
     bool PickupManager::registerRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation)
     {
-        if(identifier == NULL || representation == NULL || this->representations_.find(identifier) != this->representations_.end()) //!< If the Pickupable already has a Representation registered.
+        assert(identifier);
+        assert(representation);
+
+        if(this->representations_.find(identifier) != this->representations_.end()) // If the Pickupable already has a Representation registered.
             return false;
 
         this->representations_[identifier] = representation;
 
-        COUT(4) << "PickupRepresentation " << representation << " registered with the PickupManager." << std::endl;
+        COUT(4) << "PickupRepresentation &" << representation << " registered with the PickupManager." << std::endl;
         return true;
     }
@@ -121 +124 @@
     bool PickupManager::unregisterRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation)
     {
-        if(identifier == NULL || representation == NULL)
-            return false;
+        assert(identifier);
+        assert(representation);
 
         std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare>::iterator it = this->representations_.find(identifier);
@@ -130 +133 @@
         this->representations_.erase(it);
 
-        COUT(4) << "PickupRepresentation " << representation << " unregistered with the PickupManager." << std::endl;
+        COUT(4) << "PickupRepresentation &" << representation << " unregistered with the PickupManager." << std::endl;
         return true;
     }
@@ -167 +170 @@
         if(pickup != NULL)
             return this->getRepresentation(pickup->getPickupIdentifier());
-        
+
         return NULL;
     }
@@ -268 +271 @@
         if(pickup == NULL)
             return;
-        
+
         std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup); // Get the WeakPointer of the Pickupable.
         // If either the input Pickupable is not in the PickupManagers list or it no longer exists, the method returns.

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

@@ -51 +51 @@
             The PickupSpawner class is responsible for spawning pickups of a specific type.
             Forthermore it can be specified how long the time interval between spawning two items is and how many pickups are spawned at maximum, amongst other things.
+
         @author
             Daniel 'Huty' Haggenmueller
+        @author
             Damian 'Mozork' Frick
     */