Index: /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc	(revision 10955)
@@ -78,31 +78,29 @@
             return;
 
+        //count ticks, ticks_ is unsigned, so overflow is not a problem
         ++this->ticks_;
         if (this->ticks_ == 1)
         {
+            //those vectors are in reversed order after being set by XML.
             std::reverse(parsedActionpoints_.begin(), parsedActionpoints_.end());
             std::reverse(actionpoints_.begin(), actionpoints_.end());
-            if (this->parsedActionpoints_.empty())
-            {
-                this->action_ = Action::FIGHTALL;
-            }
-        }
-
-        if (!this || !this->getControllableEntity())
-            return;
+        }
+
+        if (!this || !this->getControllableEntity())
+            return;
+        //fly
+        if (this->bHasTargetPosition_)
+        {
+            this->moveToTargetPosition(dt);
+        }//or just rotate
+        else if (this->bLookAtTarget_)
+        {
+            this->lookAtTarget(dt);
+        }
         
-        if (this->bHasTargetPosition_)
-        {
-            this->moveToTargetPosition(dt);
-        }
-        else if (this->bLookAtTarget_)
-        {
-            this->lookAtTarget(dt);
-        }
-        
-
-        if (!this || !this->getControllableEntity())
-            return;
-
+
+        if (!this || !this->getControllableEntity())
+            return;
+        //don't fire rocket each tick
         if (timeout_ <= 0)
         {    
@@ -116,5 +114,5 @@
         if (!this || !this->getControllableEntity())
             return;
-
+        //sometimes dodge, sometimes attack
         if (this->ticks_ % 80 <= 10)
         {
@@ -128,13 +126,16 @@
         if (!this || !this->getControllableEntity())
             return;
+        //fire if you can
+        if (this->bShooting_)
+        {
+            this->doFire();
+        }
+        SUPER(ActionpointController, tick, dt);
+    }
      
-        if (this->bShooting_)
-        {
-            this->doFire();
-        }
-        SUPER(ActionpointController, tick, dt);
-    }
-     
-
+    /**
+    @brief
+        action() manages the state machine.
+    */
 
     void ActionpointController::action()
@@ -143,6 +144,9 @@
             return;
 
+        //deltaHp is used to know if this got attacked
         this->deltaHp = orxonox_cast<Pawn*> (this->getControllableEntity())->getHealth() - this->previousHp;
         this->previousHp = orxonox_cast<Pawn*> (this->getControllableEntity())->getHealth();
+
+        //look out for enemies
         if (this->bDefaultPatrol_ || (this->action_ != Action::FLY && this->action_ != Action::NONE))
         {
@@ -155,4 +159,5 @@
         if (this->action_ == Action::NONE || this->bTakenOver_)
         {
+            //if default behaviour is fighting all, push it onto the stack
             if (this->parsedActionpoints_.empty() && this->loopActionpoints_.empty() && this->bDefaultFightAll_)
             {
@@ -296,4 +301,8 @@
 
     }
+    /**
+    @brief
+        if action is protect, this follows protect_ and fights enemies that are close
+    */
     void ActionpointController::setProtect (ControllableEntity* protect)
     {
@@ -306,4 +315,5 @@
         return this->protect_;
     }
+    //XML method
     void ActionpointController::addActionpoint(WorldEntity* actionpoint)
     {
@@ -360,4 +370,5 @@
             this->actionpoints_.push_back(actionpoint);
     }
+    //XML method
     WorldEntity* ActionpointController::getActionpoint(unsigned int index) const
     {
@@ -367,9 +378,10 @@
             return 0;
     }
-
+    //XML method
     Action::Value ActionpointController::getAction ()
     {
         return this->action_;
     }
+    //XML method
     std::string ActionpointController::getActionName()
     {
@@ -393,8 +405,10 @@
         }
     }
+    //XML method
     void ActionpointController::setAction (Action::Value action)
     {
         this->action_ = action;
     }
+    //set action and target/protect
     void ActionpointController::setAction (Action::Value action, ControllableEntity* target)
     {
@@ -413,4 +427,5 @@
         }
     }
+    //set action and target position
     void ActionpointController::setAction (Action::Value action, const Vector3& target)
     {
@@ -423,4 +438,5 @@
         }
     }
+    //set action and target position and orientation
     void ActionpointController::setAction (Action::Value action, const Vector3& target,  const Quaternion& orient )
     {
@@ -590,5 +606,5 @@
     }
 
-    
+    //calculate where in world coordinates this ship has to be, so that it keeps distance to protect_, and fly there
     void ActionpointController::stayNearProtect()
     {
@@ -612,4 +628,5 @@
         this->setTargetOrientation(this->getProtect()->getWorldOrientation());
     }
+    //remove current point from the stack
     void ActionpointController::nextActionpoint()
     {
@@ -638,4 +655,5 @@
         this->bHasTargetPosition_ = false;
     }
+    //if looping, instead of erasing point, move it to the top (back is what gets executed, so it's kinda reversed stack)
     void ActionpointController::moveBackToTop()
     {
@@ -649,4 +667,5 @@
         std::reverse (loopActionpoints_.begin(), loopActionpoints_.end());
     }
+    //POST: moves all consecutive points that are in loop to the loop stack
     void ActionpointController::fillLoop()
     {
@@ -667,5 +686,5 @@
         }
     }
-    
+    //copy other ship's stacks so that if it dies, this can finish that ship's actions
     void ActionpointController::takeActionpoints (const std::vector<Point>& vector, const std::vector<Point>& loop, bool b)
     {
@@ -679,8 +698,10 @@
         this->bTakenOver_ = true;
     }
+    //attack closest target
     void ActionpointController::setClosestTarget()
     {
         this->setTarget (static_cast<ControllableEntity*>( closestTarget() ) ); 
     }
+    //find closest target
     Pawn* ActionpointController::closestTarget()
     {
@@ -711,4 +732,5 @@
         return 0;  
     }
+    //push action FIGHT to the stack and set target to the closest enemy
     void ActionpointController::startAttackingEnemiesThatAreClose()
     {
Index: /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h	(revision 10955)
@@ -61,4 +61,6 @@
         In XML one has to attack Actionpoints in order to achieve any complex behaviour, but in Controller all actionpoints are effectively 
         being stored in an array of type Point::Value.
+    @note
+        ActionpointController will not work, if there is no MasterController in the level!
     */
     namespace Action
@@ -93,5 +95,10 @@
             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);          
                
-            virtual void tick(float dt);
+            /**
+            @brief
+                tick is called every tick by Game (?).
+                In tick ship flies and fires.
+            */
+            virtual void tick(float dt);   
             /**
             @brief
@@ -175,5 +182,5 @@
 
             virtual void stayNearProtect();
-            virtual void action(); //<! action() is called in regular intervals managing the bot's behaviour.
+            virtual void action(); //<! action() is called in regular intervals managing the bot's behaviour. Only gets called by MasterController
             virtual void takeActionpoints (const std::vector<Point>& vector, const std::vector<Point>& loop, bool b);
 
Index: /code/branches/campaignHS15/src/orxonox/controllers/CommonController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/CommonController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/CommonController.h	(revision 10955)
@@ -49,5 +49,4 @@
             CommonController(Context* context);
             virtual ~CommonController();
-            virtual void action(){}; //<! action() is called in regular intervals managing the bot's behaviour.
             static float randomInRange(float a, float b);
             static float distance(const ControllableEntity* entity1, const ControllableEntity* entity2);
Index: /code/branches/campaignHS15/src/orxonox/controllers/DivisionController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/DivisionController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/DivisionController.h	(revision 10955)
@@ -36,4 +36,8 @@
 namespace orxonox
 {
+    /**
+        @note
+        ActionpointController will not work, if there is no MasterController in the level!
+    */
     class _OrxonoxExport DivisionController : public ActionpointController
     {
Index: /code/branches/campaignHS15/src/orxonox/controllers/FightingController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/FightingController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/FightingController.h	(revision 10955)
@@ -39,4 +39,7 @@
         FightingController stores all the fighting methods and member variables of AI.
         Main methods here are maneuver() and dodge().
+    
+    @note
+        ActionpointController will not work, if there is no MasterController in the level!
     */
     class _OrxonoxExport FightingController : public FlyingController
@@ -59,5 +62,5 @@
             bool bShooting_;
             bool canFire(); //<! check if target_ is in radius and if this is looking at target_
-
+            virtual void action(){};//<! action() is called in regular intervals managing the bot's behaviour. Only gets called by MasterController, is implemented in ActionpointController
         protected:
             void setTarget(ControllableEntity* target); //set a target to shoot at
Index: /code/branches/campaignHS15/src/orxonox/controllers/MasterController.cc
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/MasterController.cc	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/MasterController.cc	(revision 10955)
@@ -58,4 +58,5 @@
         if (this->ticks_ == 1)
         {
+            //fill the vector in the first tick
             for (ObjectList<ActionpointController>::iterator it = ObjectList<ActionpointController>::begin(); it; ++it)
             {
@@ -69,11 +70,14 @@
         else
         {
+
             if (this->controllers_.empty())
                 return;
 
+            //iterate over vecotr with the index, keep index in boundaries 
             if (this->indexOfCurrentController_ >= this->controllers_.size())
             {
                 this->indexOfCurrentController_ = 0;
             }
+            //each 9 ticks index is incremented
             if (this->numberOfTicksPassedSinceLastActionCall_ >= 9)
             {
@@ -83,4 +87,5 @@
             if (this->numberOfTicksPassedSinceLastActionCall_ > 0)
             {
+                //call maneuver for current index
                 if (this->numberOfTicksPassedSinceLastActionCall_ == 3)
                 {
@@ -95,4 +100,5 @@
                 else if (this->numberOfTicksPassedSinceLastActionCall_ == 6)
                 {
+                    //call canFire for current index
                     if (!this->controllers_.at(this->indexOfCurrentController_))
                     {
@@ -107,4 +113,5 @@
             else
             {
+                //call action for current index
                 if (!this->controllers_.at(this->indexOfCurrentController_))
                 {
Index: /code/branches/campaignHS15/src/orxonox/controllers/MasterController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/MasterController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/MasterController.h	(revision 10955)
@@ -37,4 +37,17 @@
 namespace orxonox
 {
+    /**
+    @brief
+      calles action(), maneuver() and canFire() methods of all the ActionpointControllers in level.
+      Only one instance of MasterController is to be placed in level.
+      If no MasterController is initialized, none of ActionpointControllers will work.
+      Example:
+      <Pawn position = "100000, 100000, 100000">
+        <controller>
+          <MasterController>
+          </MasterController>
+        </controller>
+      </Pawn>
+    */
     class _OrxonoxExport MasterController : public FightingController, public Tickable
     {
@@ -54,8 +67,8 @@
           
         private:
-            std::vector<WeakPtr<FightingController> > controllers_;
-            size_t indexOfCurrentController_;
+            std::vector<WeakPtr<FightingController> > controllers_;  //<! vector of controllers, which action(), canFire() and maneuver() methods are to be called
+            size_t indexOfCurrentController_;                        //<! index of current controller
             unsigned int numberOfTicksPassedSinceLastActionCall_;
-            unsigned int ticks_;     //<! local tick counter            
+            unsigned int ticks_;                                     //<! local tick counter            
 
     };
Index: /code/branches/campaignHS15/src/orxonox/controllers/SectionController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/SectionController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/SectionController.h	(revision 10955)
@@ -35,4 +35,8 @@
 namespace orxonox
 {
+    /**
+        @note
+        ActionpointController will not work, if there is no MasterController in the level!
+    */
     class _OrxonoxExport SectionController : public ActionpointController
     {
Index: /code/branches/campaignHS15/src/orxonox/controllers/WingmanController.h
===================================================================
--- /code/branches/campaignHS15/src/orxonox/controllers/WingmanController.h	(revision 10954)
+++ /code/branches/campaignHS15/src/orxonox/controllers/WingmanController.h	(revision 10955)
@@ -36,4 +36,8 @@
 namespace orxonox
 {
+    /**
+        @note
+        ActionpointController will not work, if there is no MasterController in the level!
+    */
     class _OrxonoxExport WingmanController : public ActionpointController
     {
