Index: code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc
===================================================================
--- code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.cc	(revision 2537)
+++ 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()
     {
Index: code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.h
===================================================================
--- code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.h	(revision 2537)
+++ code/branches/presentation/src/orxonox/objects/worldentities/WorldEntity.h	(revision 2540)
@@ -47,4 +47,28 @@
 namespace orxonox
 {
+    /**
+    @brief
+        The WorldEntity represents everything that can be put in a Scene at a certain location.
+
+        It is supposed to be the base class of everything you would call an 'object' in a Scene.
+        The class itself is abstract which means you cannot use it directly. You may use StaticEntity
+        as the simplest derivative or (derived from MobileEntity) MovableEntity and ControllableEntity
+        as more advanced ones.
+
+        The basic task of the WorldEntity is provide a location, a direction and a scaling and the possibility
+        to create an entire hierarchy of derivated objects.
+        It is also the basis for the physics interface to the Bullet physics engine.
+        Every WorldEntity can have a specific collision type: @see CollisionType
+        This would then imply that every scene object could have any collision type. To limit this, you can always
+        override this->isCollisionTypeLegal(CollisionType). Return false if the collision type is not supported
+        for a specific object.
+        There is also support for attaching WorldEntities with physics to each other. Currently, the collision shape
+        of both objects simply get merged into one larger shape (for static collision type).
+        The phyiscal body that is internally stored and administrated has the following supported properties:
+        - Restitution, angular factor, linear damping, angular damping, fricition, mass and collision shape.
+        You can get more information at the corresponding set function.
+
+        Collision shapes: These are controlled by the internal CompoundCollisionShape. @see CompoundCollisionShape.
+    */
     class _OrxonoxExport WorldEntity : public BaseObject, public Synchronisable, public btMotionState
     {
@@ -182,4 +206,13 @@
 
         public:
+            /**
+            @brief
+                Denotes the possible types of physical objects in a Scene.
+
+                Dynamic:   The object is influenced by its physical environment, like for instance little ball.
+                Kinematic: The object can only influence other dynamic objects. It's movement is coordinated by your own saying.
+                Static:    Like kinematic but the object is not allowed to move during the simulation.
+                None:      The object has no physics at all.
+            */
             enum CollisionType
             {
@@ -190,8 +223,13 @@
             };
 
+            //! Tells whether the object has any connection to the Bullet physics engine. If hasPhysics() is false, the object may still have a velocity.
             bool hasPhysics()       const { return getCollisionType() != None     ; }
+            //! @see CollisionType
             bool isStatic()         const { return getCollisionType() == Static   ; }
+            //! @see CollisionType
             bool isKinematic()      const { return getCollisionType() == Kinematic; }
+            //! @see CollisionType
             bool isDynamic()        const { return getCollisionType() == Dynamic  ; }
+            //! Tells whether physics has been activated (you can temporarily deactivate it)
             bool isPhysicsActive()  const { return this->bPhysicsActive_; }
             bool addedToPhysicalWorld() const;
@@ -200,4 +238,5 @@
             void deactivatePhysics();
 
+            //! Returns the CollisionType. @see CollisionType.
             inline CollisionType getCollisionType() const
                 { return this->collisionType_; }
@@ -207,37 +246,71 @@
             std::string getCollisionTypeStr() const;
 
+            //! Sets the mass of this object. Note that the total mass may be influenced by attached objects!
             inline void setMass(float mass)
                 { this->mass_ = mass; recalculateMassProps(); }
+            //! Returns the mass of this object without its children.
             inline float getMass() const
                 { return this->mass_; }
 
+            //! Returns the total mass of this object with all its attached children.
             inline float getTotalMass() const
                 { return this->mass_ + this->childrenMass_; }
 
+            /**
+            @brief
+                Returns the diagonal elements of the inertia tensor when calculated in local coordinates.
+            @Note
+                The local inertia tensor cannot be set, but is calculated by Bullet according to the collisionShape.
+                With compound collision shapes, an approximation is used.
+            */
             inline const btVector3& getLocalInertia() const
                 { return this->localInertia_; }
 
+            /**
+            @brief
+                Sets how much reaction is applied in a collision.
+                
+                Consider two equal spheres colliding with equal velocities:
+                Restitution 1 means that both spheres simply reverse their velocity (no loss of energy)
+                Restitution 0 means that both spheres will immediately stop moving
+                (maximum loss of energy without violating of the preservation of momentum)
+            */
             inline void setRestitution(float restitution)
                 { this->restitution_ = restitution; internalSetPhysicsProps(); }
+            //! Returns the restitution parameter. @see setRestitution.
             inline float getRestitution() const
                 { return this->restitution_; }
 
+            /**
+            @brief
+                Sets an artificial parameter that tells how much torque is applied when you apply a non-central force.
+
+                Normally the angular factor is 1, which means it's physically 'correct'. Howerver if you have a player
+                character that should not rotate when hit sideways, you can set the angular factor to 0.
+            */
             inline void setAngularFactor(float angularFactor)
                 { this->angularFactor_ = angularFactor; internalSetPhysicsProps(); }
+            //! Returns the angular factor. @see setAngularFactor.
             inline float getAngularFactor() const
                 { return this->angularFactor_; }
 
+            //! Applies a mass independent damping. Velocities will simply diminish exponentially.
             inline void setLinearDamping(float linearDamping)
                 { this->linearDamping_ = linearDamping; internalSetPhysicsProps(); }
+            //! Returns the linear damping. @see setLinearDamping.
             inline float getLinearDamping() const
                 { return this->linearDamping_; }
 
+            //! Applies a tensor independent rotation damping. Angular velocities will simply diminish exponentially.
             inline void setAngularDamping(float angularDamping)
                 { this->angularDamping_ = angularDamping; internalSetPhysicsProps(); }
+            //! Returns the angular damping. @see setAngularDamping.
             inline float getAngularDamping() const
                 { return this->angularDamping_; }
 
+            //! Applies friction to the object. Friction occurs when two objects collide.
             inline void setFriction(float friction)
                 { this->friction_ = friction; internalSetPhysicsProps(); }
+            //! Returns the amount of friction applied to the object.
             inline float getFriction() const
                 { return this->friction_; }
@@ -250,18 +323,42 @@
             void notifyChildMassChanged();
 
+            /**
+            @brief
+                Virtual function that gets called when this object collides with another.
+            @param otherObject
+                The object this one has collided into.
+            @pram contactPoint
+                Contact point provided by Bullet. Holds more information and can me modified. See return value.
+            @Return
+                Returning false means that no modification to the contactPoint has been made. Return true otherwise!
+            @Note
+                Condition is that enableCollisionCallback() was called.
+            */
             virtual inline bool collidesAgainst(WorldEntity* otherObject, btManifoldPoint& contactPoint)
                 { return false; } /* With false, Bullet assumes no modification to the collision objects. */
 
+            //! Enables the collidesAgainst(.) function. The object doesn't respond to collision otherwise!
             inline void enableCollisionCallback()
                 { this->bCollisionCallbackActive_ = true; this->collisionCallbackActivityChanged(); }
+            //! Disables the collidesAgainst(.) function. @see enableCollisionCallback()
             inline void disableCollisionCallback()
                 { this->bCollisionCallbackActive_ = false; this->collisionCallbackActivityChanged(); }
+            //! Tells whether there could be a collision response via collidesAgainst(.)
             inline bool isCollisionCallbackActive() const
                 { return this->bCollisionCallbackActive_; }
 
         protected:
+            /**
+            @brief
+                Function checks whether the requested collision type is legal to this object.
+
+                You can override this function in a derived class to constrain the collision to e.g. None or Dynamic.
+                A projectile may not prove very useful if there is no physical body. Simply set the CollisionType
+                in its constructor and override this method. But be careful that a derived classe's virtual functions
+                don't yet exist in the constructor if a base class.
+            */
             virtual bool isCollisionTypeLegal(CollisionType type) const = 0;
 
-            btRigidBody* physicalBody_;
+            btRigidBody*  physicalBody_; //!< Bullet rigid body. Everything physical is applied to this instance.
 
         private:
@@ -277,32 +374,39 @@
             void physicsActivityChanged();
             void collisionCallbackActivityChanged();
+            //! Network callback workaround to call a function when the value changes.
             inline void massChanged()
                 { this->setMass(this->mass_); }
+            //! Network callback workaround to call a function when the value changes.
             inline void restitutionChanged()
                 { this->setRestitution(this->restitution_); }
+            //! Network callback workaround to call a function when the value changes.
             inline void angularFactorChanged()
                 { this->setAngularFactor(this->angularFactor_); }
+            //! Network callback workaround to call a function when the value changes.
             inline void linearDampingChanged()
                 { this->setLinearDamping(this->linearDamping_); }
+            //! Network callback workaround to call a function when the value changes.
             inline void angularDampingChanged()
                 { this->setAngularDamping(this->angularDamping_); }
+            //! Network callback workaround to call a function when the value changes.
             inline void frictionChanged()
                 { this->setFriction(this->friction_); }
 
-            CollisionType                collisionType_;
-            CollisionType                collisionTypeSynchronised_;
-            bool                         bPhysicsActive_;
-            bool                         bPhysicsActiveSynchronised_;
+            CollisionType                collisionType_;                 //!< @see setCollisionType
+            CollisionType                collisionTypeSynchronised_;     //!< Network synchronised variable for collisionType_
+            bool                         bPhysicsActive_;                //!< @see isPhysicsActive
+            bool                         bPhysicsActiveSynchronised_;    //!< Network synchronised variable for bPhysicsActive_
+            //! When attaching objects hierarchically this variable tells this object (as child) whether physics was activated before attaching (because the deactivate physics while being attached).
             bool                         bPhysicsActiveBeforeAttaching_;
-            CompoundCollisionShape       collisionShape_;
-            btScalar                     mass_;
-            btVector3                    localInertia_;
-            btScalar                     restitution_;
-            btScalar                     angularFactor_;
-            btScalar                     linearDamping_;
-            btScalar                     angularDamping_;
-            btScalar                     friction_;
-            btScalar                     childrenMass_;
-            bool                         bCollisionCallbackActive_;
+            CompoundCollisionShape       collisionShape_;                //!< Attached collision shapes go here
+            btScalar                     mass_;                          //!< @see setMass
+            btVector3                    localInertia_;                  //!< @see getLocalInertia
+            btScalar                     restitution_;                   //!< @see setRestitution
+            btScalar                     angularFactor_;                 //!< @see setAngularFactor
+            btScalar                     linearDamping_;                 //!< @see setLinearDamping
+            btScalar                     angularDamping_;                //!< @see setAngularDamping
+            btScalar                     friction_;                      //!< @see setFriction
+            btScalar                     childrenMass_;                  //!< Sum of all the children's masses
+            bool                         bCollisionCallbackActive_;      //!< @see enableCollisionCallback
     };
 
Index: code/branches/presentation/src/orxonox/overlays/OverlayGroup.h
===================================================================
--- code/branches/presentation/src/orxonox/overlays/OverlayGroup.h	(revision 2537)
+++ code/branches/presentation/src/orxonox/overlays/OverlayGroup.h	(revision 2540)
@@ -90,5 +90,5 @@
     private:
         std::map<std::string, OrxonoxOverlay*> hudElements_;    //!< Contains all the OrxonoxOverlays of the this group.
-        Vector2 scale_;                                         //!< Current scale (independant of the elements).
+        Vector2 scale_;                                         //!< Current scale (independent of the elements).
         Vector2 scroll_;                                        //!< Current scrolling offset.
         ControllableEntity* owner_;                             //!< The owner of this OverlayGroup
