Index: code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc
===================================================================
--- code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc	(revision 2535)
+++ code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc	(revision 2540)
@@ -52,6 +52,10 @@
     const Vector3 WorldEntity::UP    = Vector3::UNIT_Y;
 
+    /**
+    @brief
+        Creates a new WorldEntity that may immediately be used.
+        All the default values are being set here.
+    */
     WorldEntity::WorldEntity(BaseObject* creator) : BaseObject(creator), Synchronisable(creator), collisionShape_(0)
-
     {
         RegisterObject(WorldEntity);
@@ -92,4 +96,8 @@
     }
 
+    /**
+    @brief
+        Destroys the WorldEntity AND ALL its children with it.
+    */
     WorldEntity::~WorldEntity()
     {
@@ -172,4 +180,8 @@
     }
 
+    /**
+    @brief
+        Network function that object this instance to its correct parent.
+    */
     void WorldEntity::parentChanged()
     {
@@ -182,4 +194,11 @@
     }
 
+    /**
+    @brief
+        Attaches this object to a parent SceneNode.
+    @Remarks
+        Only use this method if you know exactly what you're doing!
+        Normally, attaching works internally by attaching WE's.
+    */
     void WorldEntity::attachToNode(Ogre::SceneNode* node)
     {
@@ -190,4 +209,11 @@
     }
 
+    /**
+    @brief
+        Detaches this object from a parent SceneNode.
+    @Remarks
+        Only use this method if you know exactly what you're doing!
+        Normally, attaching works internally by attaching WE's.
+    */
     void WorldEntity::detachFromNode(Ogre::SceneNode* node)
     {
@@ -196,4 +222,8 @@
     }
 
+    /**
+    @brief
+        Network callback for the collision type. Only change the type if it was valid.
+    */
     void WorldEntity::collisionTypeChanged()
     {
@@ -214,4 +244,5 @@
     }
 
+    //! Network callback for this->bPhysicsActive_
     void WorldEntity::physicsActivityChanged()
     {
@@ -222,4 +253,5 @@
     }
 
+    //! Function is called to set the right flags in Bullet (if there is physics at all)
     void WorldEntity::collisionCallbackActivityChanged()
     {
@@ -235,4 +267,14 @@
     }
 
+    /**
+    @brief
+        Attaches a child WorldEntity to this object. This calls notifyBeingAttached()
+        of the child WE.
+    @Note
+        The collision shape of the child object gets attached nevertheless. That also means
+        that you can change the collision shape of the child and it correctly cascadeds the changes to this instance.
+        Be aware of this implication: When implementing attaching of kinematic objects to others, you have to change
+        this behaviour because you then might not want to merge the collision shapes.
+    */
     void WorldEntity::attach(WorldEntity* object)
     {
@@ -255,4 +297,14 @@
     }
 
+    /**
+    @brief
+        Function gets called when this object is being attached to a new parent.
+
+        This operation is only allowed if the collision types "like" each other.
+        - You cannot a attach a non physical object to a physical one.
+        - Dynamic object can NOT be attached at all.
+        - It is also not possible to attach a kinematic to a dynamic one.
+        - Attaching of kinematic objects otherwise is not yet supported.
+    */
     bool WorldEntity::notifyBeingAttached(WorldEntity* newParent)
     {
@@ -300,4 +352,8 @@
     }
 
+    /**
+    @brief
+        Detaches a child WorldEntity from this instance.
+    */
     void WorldEntity::detach(WorldEntity* object)
     {
@@ -324,4 +380,8 @@
     }
 
+    /**
+    @brief
+        Function gets called when the object has been detached from its parent.
+    */
     void WorldEntity::notifyDetached()
     {
@@ -341,4 +401,5 @@
     }
 
+    //! Returns an attached object (merely for XMLPort).
     WorldEntity* WorldEntity::getAttachedObject(unsigned int index)
     {
@@ -353,4 +414,5 @@
     }
 
+    //! Attaches an Ogre::SceneNode to this WorldEntity.
     void WorldEntity::attachNode(Ogre::SceneNode* node)
     {
@@ -361,4 +423,5 @@
     }
 
+    //! Detaches an Ogre::SceneNode from this WorldEntity.
     void WorldEntity::detachNode(Ogre::SceneNode* node)
     {
@@ -367,4 +430,5 @@
     }
 
+    //! Attaches an Ogre::MovableObject to this WorldEntity.
     void WorldEntity::attachOgreObject(Ogre::MovableObject* object)
     {
@@ -372,4 +436,5 @@
     }
 
+    //! Detaches an Ogre::MovableObject from this WorldEntity.
     void WorldEntity::detachOgreObject(Ogre::MovableObject* object)
     {
@@ -377,4 +442,5 @@
     }
 
+    //! Detaches an Ogre::MovableObject (by string) from this WorldEntity.
     Ogre::MovableObject* WorldEntity::detachOgreObject(const Ogre::String& name)
     {
@@ -382,4 +448,5 @@
     }
 
+    //! Attaches a collision Shape to this object (delegated to the internal CompoundCollisionShape)
     void WorldEntity::attachCollisionShape(CollisionShape* shape)
     {
@@ -388,4 +455,5 @@
     }
 
+    //! Detaches a collision Shape from this object (delegated to the internal CompoundCollisionShape)
     void WorldEntity::detachCollisionShape(CollisionShape* shape)
     {
@@ -394,5 +462,6 @@
     }
 
-    CollisionShape* WorldEntity::getAttachedCollisionShape(unsigned int index) const
+    //! Returns an attached collision Shape of this object (delegated to the internal CompoundCollisionShape)
+    CollisionShape* WorldEntity::getAttachedCollisionShape(unsigned int index)
     {
         return this->collisionShape_.getAttachedShape(index);
@@ -417,4 +486,5 @@
 #endif
 
+    //! Returns the position relative to the root space
     const Vector3& WorldEntity::getWorldPosition() const
     {
@@ -422,4 +492,5 @@
     }
 
+    //! Returns the orientation relative to the root space
     const Quaternion& WorldEntity::getWorldOrientation() const
     {
@@ -427,4 +498,5 @@
     }
 
+    //! Returns the scaling applied relative to the root space in 3 coordinates
     const Vector3& WorldEntity::getWorldScale3D() const
     {
@@ -432,4 +504,10 @@
     }
 
+    /**
+    @brief
+        Returns the scaling applied relative to the root space in 3 coordinates
+    @return
+        Returns the scaling if it is uniform, 1.0f otherwise.
+    */
     float WorldEntity::getWorldScale() const
     {
@@ -438,4 +516,10 @@
     }
 
+    /**
+    @brief
+        Sets the three dimensional scaling of this object.
+    @Note
+        Scaling physical objects has not yet been implemented and is therefore forbidden.
+    */
     void WorldEntity::setScale3D(const Vector3& scale)
     {
@@ -454,4 +538,10 @@
     }
 
+    /**
+    @brief
+        Translates this WorldEntity by a vector.
+    @param relativeTo
+        @see TransformSpace::Enum
+    */
     void WorldEntity::translate(const Vector3& distance, TransformSpace::Enum relativeTo)
     {
@@ -476,5 +566,10 @@
     }
 
-    void WorldEntity::rotate(const Quaternion& rotation, TransformSpace::Space relativeTo)
+    /**
+    @brief
+        Rotates this WorldEntity by a quaternion.
+    @param relativeTo
+        @see TransformSpace::Enum
+    */
     void WorldEntity::rotate(const Quaternion& rotation, TransformSpace::Enum relativeTo)
     {
@@ -496,5 +591,12 @@
     }
 
-    void WorldEntity::lookAt(const Vector3& target, TransformSpace::Space relativeTo, const Vector3& localDirectionVector)
+    /**
+    @brief
+        Makes this WorldEntity look a specific target location.
+    @param relativeTo
+        @see TransformSpace::Enum
+    @param localDirectionVector
+        The vector which normally describes the natural direction of the object, usually -Z.
+    */
     void WorldEntity::lookAt(const Vector3& target, TransformSpace::Enum relativeTo, const Vector3& localDirectionVector)
     {
@@ -515,5 +617,12 @@
     }
 
-    void WorldEntity::setDirection(const Vector3& direction, TransformSpace::Space relativeTo, const Vector3& localDirectionVector)
+    /**
+    @brief
+        Makes this WorldEntity look in specific direction.
+    @param relativeTo
+        @see TransformSpace::Enum
+    @param localDirectionVector
+        The vector which normally describes the natural direction of the object, usually -Z.
+    */
     void WorldEntity::setDirection(const Vector3& direction, TransformSpace::Enum relativeTo, const Vector3& localDirectionVector)
     {
@@ -535,4 +644,5 @@
     }
 
+    //! Activates physics if the CollisionType is not None.
     void WorldEntity::activatePhysics()
     {
@@ -544,4 +654,5 @@
     }
 
+    //! Deactivates physics but the CollisionType does not change.
     void WorldEntity::deactivatePhysics()
     {
@@ -553,4 +664,5 @@
     }
 
+    //! Tells whether the object has already been added to the Bullet physics World.
     bool WorldEntity::addedToPhysicalWorld() const
     {
@@ -558,4 +670,10 @@
     }
 
+    /**
+    @brief
+        Sets the CollisionType. This alters the object significantly! @see CollisionType.
+    @Note
+        Operation does not work on attached WorldEntities.
+    */
     void WorldEntity::setCollisionType(CollisionType type)
     {
@@ -647,4 +765,5 @@
     }
 
+    //! Sets the CollisionType by string (used for the XMLPort)
     void WorldEntity::setCollisionTypeStr(const std::string& typeStr)
     {
@@ -664,4 +783,5 @@
     }
 
+    //! Gets the CollisionType by string (used for the XMLPort)
     std::string WorldEntity::getCollisionTypeStr() const
     {
@@ -695,4 +815,11 @@
     }
 
+    /**
+    @brief
+        Recalculates the accumulated child mass and calls recalculateMassProps()
+        and notifies the parent of the change.
+    @Note
+        Called by a child WE
+    */
     void WorldEntity::notifyChildMassChanged()
     {
@@ -708,4 +835,12 @@
     }
 
+    /**
+    @brief
+        Undertakes the necessary steps to change the collision shape in Bullet, even at runtime.
+    @Note
+        - called by this->collisionShape_
+        - May have a REALLY big overhead when called continuously at runtime, because then we need
+          to remove the physical body from Bullet and add it again.
+    */
     void WorldEntity::notifyCollisionShapeChanged()
     {
@@ -725,4 +860,5 @@
     }
 
+    //! Updates all mass dependent parameters (mass, inertia tensor and child mass)
     void WorldEntity::recalculateMassProps()
     {
@@ -740,5 +876,5 @@
             {
                 // Use default values to avoid very large or very small values
-                CCOUT(4) << "Warning: Setting the internal physical mass to 1.0 because mass_ is 0.0." << std::endl;
+                CCOUT(4) << "Warning: Setting the internal physical mass to 1.0 because mass_ is 0.0" << std::endl;
                 btVector3 inertia(0, 0, 0);
                 this->collisionShape_.calculateLocalInertia(1.0f, inertia);
@@ -752,4 +888,5 @@
     }
 
+    //! Copies our own parameters for restitution, angular factor, dampings and friction to the bullet rigid body.
     void WorldEntity::internalSetPhysicsProps()
     {
