Index: code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc	(revision 10891)
+++ code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.cc	(revision 10898)
@@ -122,6 +122,5 @@
         this->deltaHp = orxonox_cast<Pawn*> (this->getControllableEntity())->getHealth() - this->previousHp;
         this->previousHp = orxonox_cast<Pawn*> (this->getControllableEntity())->getHealth();
-        if (this->actionCounter_ % 2 == 0)
-            this->startAttackingEnemiesThatAreClose();
+        // if (this->actionCounter_ % 2 == 0)
         //No action -> pop one from stack
         if (this->action_ == Action::NONE || this->bTakenOver_)
@@ -133,4 +132,6 @@
             //     this->parsedActionpoints_.push_back(point);
             // }
+            this->startAttackingEnemiesThatAreClose();
+
             if (this->parsedActionpoints_.empty() && this->loopActionpoints_.empty())
             {
@@ -209,4 +210,5 @@
         else if (this->action_ == Action::FLY)
         {
+            this->startAttackingEnemiesThatAreClose();            
             if (this->squaredDistanceToTarget() <= this->squaredaccuracy_)
             {
@@ -217,4 +219,5 @@
         else if (this->action_ == Action::PROTECT)
         {
+            this->startAttackingEnemiesThatAreClose();            
             if (!this->getProtect())
             {
@@ -226,4 +229,5 @@
         else if (this->action_ == Action::ATTACK)
         {   
+            this->startAttackingEnemiesThatAreClose();            
             if (!this->hasTarget())
             {
Index: code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h	(revision 10891)
+++ code/branches/campaignHS15/src/orxonox/controllers/ActionpointController.h	(revision 10898)
@@ -38,4 +38,25 @@
 namespace orxonox
 {
+    /**
+    @brief
+        ActionpointController is a state machine with states:
+            1) NONE
+            2) FLY: fly towards a point
+            3) FIGHT: fight enemies that are in attackRange_ (see FightingController)
+            4) PROTECT: follow this->protect_
+            5) FIGHTALL: fight all enemies on the map
+            6) ATTACK: fight a specific spaceship
+        This controller always executes an action that is in the back of the vector being used.
+        After current this->action_ is completed, next action becomes the top action (one that will
+        be returned by someVector.back()), and current action either will be removed (if not looping),
+        or moved to the top (if looping).
+
+        Every second action(), which is once in two seconds, this searches the area for enemies that are in attack range, if finds anyone,
+        pushes Action::FIGHT to the stack. That makes spaceship fight enemies inside of a sphere, and when all enemies in range are dead,
+        Action::FIGHT is removed from the stack, and spaceship resumes doing whatever action was being executed before.
+
+        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.
+    */
     namespace Action
     {  
@@ -69,6 +90,73 @@
                
             virtual void tick(float dt);
-
-            void addActionpoint(WorldEntity* waypoint);
+            /**
+            @brief
+                XML method, example XML usage:
+                <SpaceShip position="-2000, 1500, -1000" lookat="0,0,0" team=0 name="ss2">
+                  <templates>
+                    <Template link=spaceshipassff />
+                  </templates>
+                  <controller>
+                    <DivisionController team=0 formationMode="finger4">
+                      <actionpoints>
+                        <Actionpoint position="0,0,0" action="FLY" /> 
+                        <Actionpoint position="-1000,750,-500" action="ATTACK" attack="attack" />
+                        <Actionpoint position="-1000,750,-500" action="PROTECt" protectMe=true />
+                        <Actionpoint position="-1000,750,-500" action="PROTECt" protect="protect" /> 
+                        <Actionpoint position="-1000,750,-500" action="FIGHTALL" />
+                       </actionpoints>
+                    </DivisionController>
+                  </controller>
+                </SpaceShip>
+                
+                Full description:
+                Adds an Actionpoint to this->actionpoints_. Actionpoint can take arguments like action="attack" attack="name".
+                For documentation on Actionpoint XML arguments, check out Actionpoint.h class
+                If any WorldEntity that is not Actionpoint or its child being sent to actionpoints through XML,
+                action would be assumed to be Action::FLY and target position to be position of the entity. Also, if not Actionpoint
+                is passed, it is assumed to be in a loop. How it works is: in <actionpoints> first all Actionpoints between 
+                first Actionpoint with loopStart=true and first following Actionpoint with loopEnd=true are included in a single loop.
+                If they are adjacent (in the input array) with WorldEntity, then WorldEntity is also in a loop.
+                All the Worldentities are assumed to be in loop. 
+               
+                Loop example:
+                <SpaceShip position="-1500, 1500, -1000" lookat="0,0,0" team=0 name="ss1">
+                  <templates>
+                    <Template link=spaceshipassff />
+                  </templates>
+                  <controller>
+                    <DivisionController team=0 formationMode="wall">
+                      <actionpoints>
+                        <Actionpoint position="  0,2000,-600" action="FLY" loopStart=true/>
+                        <Actionpoint position="  0,2000,-1000" action="FLY"  />
+                        <Actionpoint position="400,2000,-1000" action="FLY" />
+                        <Actionpoint position="400,2000,-600" action="FLY" loopEnd=true />
+                      </actionpoints>
+                    </DivisionController>
+                  </controller>
+                </SpaceShip>
+               
+                other loop example:
+                <SpaceShip position="-1500, -1500, -1500" lookat="0,0,0" team=0 name="ss1">
+                  <templates>
+                    <Template link=spaceshipassff />
+                  </templates>
+                  <controller>
+                    <DivisionController team=0 formationMode="diamond">
+                      <actionpoints>
+                        <Model mesh="cube.mesh" scale=8 position="  0,2000,-600" />
+                        <Model mesh="cube.mesh" scale=8 position="  0,2000,-1000" />
+                        <Model mesh="cube.mesh" scale=8 position="400,2000,-1000" />
+                        <Model mesh="cube.mesh" scale=8 position="400,2000,-600" />
+                      </actionpoints>
+                    </DivisionController>
+                  </controller>
+                </SpaceShip> 
+
+            @note
+                Don't use several loops, and don't use WorldEntities as input to <actionpoints> as I didn't test it well, but you
+                can try if feeling lucky.  
+            */
+            void addActionpoint(WorldEntity* actionpoint); 
             WorldEntity* getActionpoint(unsigned int index) const;           
             virtual void stayNearProtect();
@@ -92,5 +180,5 @@
             virtual bool hasFollower()
                 { return true; }
-               
+
         protected:
                 void startAttackingEnemiesThatAreClose();
@@ -104,24 +192,38 @@
                 std::vector<WeakPtr<WorldEntity> > actionpoints_;
                 float squaredaccuracy_;
-                std::vector<Point > parsedActionpoints_;
-                std::vector<Point > loopActionpoints_;
+                std::vector<Point > parsedActionpoints_;//<! actionpoints as they are stored here after being parsed from XML
+                std::vector<Point > loopActionpoints_;  //<! actionpoints that are to be looped
                 bool bInLoop_;
-                bool bLoop_;   
-                bool bEndLoop_;  
-                bool bTakenOver_;  
+                bool bLoop_;                            //<! is state machine looping?
+                bool bEndLoop_;                    
+                bool bTakenOver_;                       //<! are actionpoints taken over from the leader when he died? if yes, top actionpoint 
+                                                        //<! is to be executed for the state machine to start working
             //----[/Actionpoint information]----
                 void setProtect (ControllableEntity* protect);
                 ControllableEntity* getProtect (); 
-                WeakPtr<ControllableEntity> protect_;     
-                void fillLoop();
+                WeakPtr<ControllableEntity> protect_;   //<! entity that is to be protected if this->action_ == Action::PROTECT
+                void fillLoop();                        //<! moves actionpoints that are should be in loop from parsedActionpoints_ to loopActionpoints_
                 void fillLoopReversed();
-                void moveBackToTop();
+                void moveBackToTop();                   //<! analog of removing back actionpoint for loopActionpoints_: instead of removing it, 
+                                                        //<! move it to the top, so that it will be executed later on.
                 void setClosestTarget();
                 Pawn* closestTarget();
             //----[Actionpoint methods]----
-                void executeActionpoint();
-                void nextActionpoint();
-                void pushAction(Point& p);
-                void popAction();
+                /**
+                @brief
+                    Sets this->target_, this->targetPosition_, this->protect_ and this->action_ depending
+                    on the current actionpoint in the vector parsedActionpoints_ if not looping or
+                    loopActionpoints_ if looping.
+                @note
+                */
+                void executeActionpoint();  
+                /**
+                @brief
+                    If this->bLoop_, move back action to top (back is the current one, top is the last),
+                    otherwise remove back actionpoint.
+                @note
+                    actionpoints_ is only used for XML, real state stacks are parsedActionpoints_ and loopActionpoints_
+                */            
+                void nextActionpoint();                 
             //----[Actionpoint methods]----          
                 bool bFirstTick_; 
Index: code/branches/campaignHS15/src/orxonox/controllers/FightingController.cc
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/FightingController.cc	(revision 10891)
+++ code/branches/campaignHS15/src/orxonox/controllers/FightingController.cc	(revision 10898)
@@ -224,18 +224,4 @@
         return squaredDistanceToTarget() < this->attackRange_*this->attackRange_ && this->isLookingAtTarget(math::pi / 20.0f);
     }
-    // void FightingController::doFire() 
-    // {
-    //     if ( !this->target_ || !this->getControllableEntity() )
-    //     {
-    //         return;
-    //     }
-      
-    //     Pawn* pawn = orxonox_cast<Pawn*>( this->getControllableEntity() );
-
-    //     if ( pawn )
-    //         pawn->setAimPosition( this->positionOfTarget_ );
-    //     float distance = CommonController::distance (this->getControllableEntity(), this->target_);
-    //     this->getControllableEntity() ->fire(distance < 1500 ? (distance < 1000 && distance > 700 ? 3 : 0) : (1));
-    // }
 
 
Index: code/branches/campaignHS15/src/orxonox/controllers/FightingController.h
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/FightingController.h	(revision 10891)
+++ code/branches/campaignHS15/src/orxonox/controllers/FightingController.h	(revision 10898)
@@ -35,4 +35,9 @@
 namespace orxonox
 {
+    /**
+    @brief
+        FightingController stores all the fighting methods and member variables of AI.
+        Main methods here are maneuver() and dodge().
+    */
     class _OrxonoxExport FightingController : public FlyingController
     {
@@ -49,20 +54,23 @@
             ControllableEntity* getTarget() const
                 { return this->target_; }
-            bool bKeepFormation_;
+            bool bKeepFormation_;   //even if action_ == FIGHT, you might still want to keep formation if far enough form the target
            
         protected:
-            void setTarget(ControllableEntity* target);
+            void setTarget(ControllableEntity* target); //set a target to shoot at
 
-            void setPositionOfTarget(const Vector3& target);
-            void setOrientationOfTarget(const Quaternion& orient);
-            void stopLookingAtTarget();
-            void startLookingAtTarget();
-            void lookAtTarget(float dt);
+            void setPositionOfTarget(const Vector3& target);    //good to know where target is
+            void setOrientationOfTarget(const Quaternion& orient);  //I don't really use that
+            void stopLookingAtTarget();     //<! target dead -> you need to be able to fly
+            void startLookingAtTarget();    //<! if close to target, no need to fly, just rotate yourself
+            void lookAtTarget(float dt);    //<! rotate yourself towards target
 
-            void maneuver();
-            void dodge(const Vector3& thisPosition, Vector3& diffUnit);
-            void dodgeTowards (Vector3& position);
-            bool canFire();
-            void doFire();
+            void maneuver(); //<! sets this->targetPosition_, which is a Vector3 of where this ship flies. Decision is made based on
+                             //<! the distance to enemy, if being attacked, dodge() is called, otherwise ship just flies towards this->target_.
+            void dodge(const Vector3& thisPosition, Vector3& diffUnit); //<! choose a random Vector3 perpendicular to the difference vector between
+                                                                        //<! this and target_ plus or minus some amount in difference vector direction,
+                                                                        //<! depending on whether it is better to close up or survive.
+            void dodgeTowards (Vector3& position);  //fly towards position and awoid being hit
+            bool canFire(); //<! check if target_ is in radius and if this is looking at target_
+            void doFire();  //<! choose weapon, set aim at target_ and fire
             WeakPtr<ControllableEntity> target_;
             void setClosestTarget();
Index: code/branches/campaignHS15/src/orxonox/controllers/FlyingController.h
===================================================================
--- code/branches/campaignHS15/src/orxonox/controllers/FlyingController.h	(revision 10891)
+++ code/branches/campaignHS15/src/orxonox/controllers/FlyingController.h	(revision 10898)
@@ -35,4 +35,8 @@
 namespace orxonox
 {   
+    /**
+    @brief
+        FlyingController stores all the flying methods and member variables of AI.
+    */
     namespace FormationMode
     {
