Index: code/branches/campaignHS15/src/orxonox/worldentities/Actionpoint.h
===================================================================
--- code/branches/campaignHS15/src/orxonox/worldentities/Actionpoint.h	(revision 10863)
+++ code/branches/campaignHS15/src/orxonox/worldentities/Actionpoint.h	(revision 10868)
@@ -36,13 +36,60 @@
 #define _Actionpoint_H__
 
-#include "OrxonoxPrereqs.h"
+#include <string>                           //need string for XML input
 
-#include <list>
-#include <string>
-#include "core/XMLNameListener.h"
-#include "worldentities/StaticEntity.h"
+#include "core/XMLPort.h"                   //need XMLPort
+#include "worldentities/StaticEntity.h"     //this is a child of StaticEntity
+
 namespace orxonox
-{
- 
+{ 
+    /**
+    @brief
+        Actionpoints are used by ActionpointController and all derived classes.
+        Such classes will execute actions set in Actionpoints.
+
+        In XML file one can pass an array of Actionpoints to a controller. Each
+        Actionpoint can take action type, string and boolean or 
+        action and two booleans as an argument.
+        If action is set to fly, Actionpoint's position is assumed to be the desired
+        location.
+        Example XML code:
+
+        <SpaceShip position="-2000, 1500, -1000" lookat="0,0,0" team=0 name="thisShipName">
+          <templates>
+            <Template link=spaceshipassff />
+          </templates>
+          <controller>
+            <DivisionController team=0 formationMode="WALL">
+              <actionpoints>
+                <Actionpoint position="0,0,0" action="FLY" /> 
+                <Actionpoint position="-1000,750,-500" action="ATTACK" attack="someShipName" />
+                <Actionpoint position="-1000,750,-500" action="PROTECT" protectMe=true />
+                <Actionpoint position="-1000,750,-500" action="PROTECT" protect="otherShipName" /> 
+                <Actionpoint position="-1000,750,-500" action="FIGHTALL" />
+               </actionpoints>
+            </DivisionController>
+          </controller>
+        </SpaceShip>
+        
+        Example with loops:
+
+        <SpaceShip position="-1500, 1500, -1000" lookat="0,0,0" team=0 name="thisShipName">
+          <templates>
+            <Template link=spaceshipassff />
+          </templates>
+          <controller>
+            <DivisionController team=0 formationMode="finger4">
+              <actionpoints>
+                <Actionpoint position="  0,2000,-600" action="FLY" loopStart=true/>
+                <Actionpoint position="  0,2000,-700" action="FLY"  />
+                <Actionpoint position="100,2000,-700" action="FLY" />
+                <Actionpoint position="100,2000,-600" action="FLY" loopEnd=true />
+              </actionpoints>
+            </DivisionController>
+          </controller>
+        </SpaceShip>
+        
+        For more information read descriptions of the methods.
+    */
     class _OrxonoxExport Actionpoint : public StaticEntity
     {
@@ -51,75 +98,61 @@
             virtual ~Actionpoint() {}
 
-            //----[XML data]----
-                virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
-                //----[Action data]----
-                    void setActionXML( std::string val);
-                    std::string getActionXML();
-                //----[/Action data]----
-                //----[Protect data]----
-                    void setProtectXML( std::string val);
-                    std::string getProtectXML();
-                //----[/Protect data]----
-                //----[Attack data]----
-                    void setAttackXML( std::string val);
-                    std::string getAttackXML();
-                //----[/Attack data]----
-                //----[ProtectMe data]----
-                    inline void setProtectMeXML(bool c)
-                    {
-                        this->bProtectMe_ = c;
-                    }
-                    inline bool getProtectMeXML ()
-                    {
-                        return this->bProtectMe_;
-                    }
+            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
 
-                //----[/ProtectMe data]----
+            /** @brief Decides what AI will do. @param val action to execute */
+            void setActionXML(std::string val)
+                { this->actionName_ = getUppercase (val); }
+            std::string getActionXML() const
+                { return this->actionName_; }
 
-            //----[/XML data]----
-            
-                std::string getName()
-                {
-                    if (protectName_ != "")
-                        return protectName_;
-                    else if (attackName_ != "")
-                        return attackName_;
-                    else if (bProtectMe_)
-                        return "reservedKeyword:human";
-                    else
-                        return "";
-                }
-                void setLoopStart(bool value)
-                {
-                    this->bLoopStart_ = value;
-                }
-                void setLoopEnd (bool value)
-                {
-                    this->bLoopEnd_ = value;
-                }
-            //----["Waypoints" data]----
-                void setTargetPosition(const Vector3& target);
-                Vector3 getTargetPosition ();
-            //----[/"Waypoints" data]----
+            /** @brief Makes AI follow an entity. @param val name of entity to protect */
+            void setProtectXML(std::string val)
+                { this->name_ = val; }
+            std::string getProtectXML() const
+                { return this->name_; }
 
-            bool getLoopStart()
-            {
-                return this->bLoopStart_;
-            }
-            bool getLoopEnd()
-            {
-                return this->bLoopEnd_;
-            }
-        private:
-            
-            std::string actionName_;
-            std::string protectName_;
-            std::string attackName_;
+            /** @brief Makes AI attack an entity. @param val name of entity to attack */
+            void setAttackXML(std::string val)
+                { this->name_ = val; }
+            std::string getAttackXML() const
+                { return this->name_; }
 
+            /** @brief Makes AI follow human player. @param c protect Human? */
+            void setProtectMeXML(bool c)
+                { this->bProtectMe_ = c; }
+            bool getProtectMeXML() const
+                { return this->bProtectMe_; }
 
-            bool bLoopStart_;
-            bool bLoopEnd_;
-            bool bProtectMe_;
-            Vector3 targetPosition_;
+            /** @brief Starts a loop of Actionpoints. @param value start loop? */
+            void setLoopStart(bool value)
+                { this->bLoopStart_ = value; }
+            bool getLoopStart() const
+                { return this->bLoopStart_; }
+            /** @brief Ends a loop of Actionpoints. @param value end loop? */
+            void setLoopEnd (bool value)
+                { this->bLoopEnd_ = value; }
+            bool getLoopEnd() const
+                { return this->bLoopEnd_; }
+
+            std::string getName() const;
+
+        private:    
+            std::string actionName_;    //!< can be set to "FLY", "ATTACK",
+                                        //!< "PROTECT", "FIGHT", "FIGHTALL"
+                                        //!< or "NONE".
+
+            std::string name_;          //!< name of the ship that is to be
+                                        //!< attacked or protected.
+
+            bool bLoopStart_;           //!< if true, this and all following Actionpoints
+                                        //!< until the first Actionpoint with bLoopEnd_
+                                        //!< set to true are executed in a loop.
+
+            bool bLoopEnd_;             //!< if true, this is the last element of
+                                        //!< a loop started by loopStart=true argument
+
+            bool bProtectMe_;           //!< if player is to be protected,
+                                        //!< instead of passing name, one has
+                                        //!< to set protectMe to true.
     };
 }
