Index: /code/branches/core4/src/core/input/InputManager.cc
===================================================================
--- /code/branches/core4/src/core/input/InputManager.cc	(revision 3280)
+++ /code/branches/core4/src/core/input/InputManager.cc	(revision 3281)
@@ -30,7 +30,6 @@
 @file
 @brief
-    Implementation of the InputManager that captures all the input from OIS
-    and redirects it to handlers.
- */
+    Implementation of the InputManager and a static variable from the InputHandler.
+*/
 
 #include "InputManager.h"
@@ -60,7 +59,4 @@
 namespace orxonox
 {
-    // TODO: Add console commands again as member commands
-    //SetConsoleCommand(InputManager, calibrate, true);
-    //SetConsoleCommand(InputManager, reload, false);
     SetCommandLineSwitch(keyboard_no_grab).information("Whether not to exclusively grab the keyboard");
 
@@ -70,8 +66,5 @@
     InputManager* InputManager::singletonRef_s = 0;
 
-    /**
-    @brief
-        Defines the |= operator for easier use.
-    */
+    //! Defines the |= operator for easier use.
     inline InputManager::State operator|=(InputManager::State& lval, InputManager::State rval)
     {
@@ -79,8 +72,5 @@
     }
 
-    /**
-    @brief
-        Defines the &= operator for easier use.
-    */
+    //! Defines the &= operator for easier use.
     inline InputManager::State operator&=(InputManager::State& lval, int rval)
     {
@@ -92,9 +82,4 @@
     // ##########                                        ##########
     // ############################################################
-    /**
-    @brief
-        Constructor only sets member fields to initial zero values
-        and registers the class in the class hierarchy.
-    */
     InputManager::InputManager(size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight)
         : internalState_(Bad)
@@ -157,8 +142,4 @@
     }
 
-    /**
-    @brief
-        Sets the configurable values.
-    */
     void InputManager::setConfigValues()
     {
@@ -168,5 +149,5 @@
     @brief
         Creates the OIS::InputMananger, the keyboard, the mouse and
-        the joysticks and assigns the key bindings.
+        the joys ticks. If either of the first two fail, this method throws an exception.
     @param windowHnd
         The window handle of the render window
@@ -244,4 +225,5 @@
     }
 
+    //! Creates a new orxonox::Mouse
     void InputManager::loadMouse(unsigned int windowWidth, unsigned int windowHeight)
     {
@@ -262,10 +244,5 @@
     }
 
-    /**
-    @brief
-        Creates all joy sticks and sets the event handler.
-    @return
-        False joy stick stay uninitialised, true otherwise.
-    */
+    //! Creates as many joy sticks as are available.
     void InputManager::loadJoySticks()
     {
@@ -287,10 +264,4 @@
     }
 
-    /**
-    @brief
-        Checks whether there is already a joy stick with the given ID string.
-    @return
-        Returns true if ID is ok (unique), false otherwise.
-    */
     bool InputManager::checkJoyStickID(const std::string& idString) const
     {
@@ -301,10 +272,4 @@
     }
 
-    /**
-    @brief
-        Sets the the name of the command used by the KeyDetector as callback.
-    @param command
-        Command name as string
-    */
     void InputManager::setKeyDetectorCallback(const std::string& command)
     {
@@ -317,9 +282,4 @@
     // ############################################################
 
-    /**
-    @brief
-        Destroys all the created input devices and states.
-    */
-    // TODO: export this to be used with reload()
     InputManager::~InputManager()
     {
@@ -346,4 +306,10 @@
     }
 
+    /**
+    @brief
+        Destoys all input devices (joy sticks, mouse, keyboard and OIS::InputManager)
+    @throw
+        Method does not throw
+    */
     void InputManager::destroyDevices()
     {
@@ -388,9 +354,4 @@
     // ############################################################
 
-    /**
-    @brief
-        Public interface. Only reloads immediately if the call stack doesn't
-        include the update() method.
-    */
     void InputManager::reload()
     {
@@ -408,8 +369,5 @@
     }
 
-    /**
-    @brief
-        Internal reload method. Destroys the OIS devices and loads them again.
-    */
+    //! Internal reload method. Destroys the OIS devices and loads them again.
     void InputManager::reloadInternal()
     {
@@ -438,10 +396,4 @@
     // ############################################################
 
-    /**
-    @brief
-        Updates the states and the InputState situation.
-    @param time
-        Clock holding the current time.
-    */
     void InputManager::update(const Clock& time)
     {
@@ -581,8 +533,4 @@
     }
 
-    /**
-    @brief
-        Clears all buffers that store what keys/buttons are being pressed at the moment.
-    */
     void InputManager::clearBuffers()
     {
@@ -592,8 +540,4 @@
     }
 
-    /**
-    @brief
-        Starts joy stick calibration.
-    */
     void InputManager::calibrate()
     {
@@ -609,4 +553,5 @@
     }
 
+    //! Tells all devices to stop the calibration and evaluate it. Buffers are being cleared as well!
     void InputManager::stopCalibration()
     {
@@ -627,53 +572,11 @@
     // ############################################################
 
-    /**
-    @brief
-        Creates a new InputState by type, name and priority.
-        
-        You will have to use this method because the
-        c'tors and d'tors are private.
-    @remarks
-        The InputManager will take care of the state completely. That also
-        means it gets deleted when the InputManager is destroyed!
-    @param name
-        Name of the InputState when referenced as string
-    @param priority
-        Priority matters when multiple states are active. You can specify any
-        number, but 1 - 99 is preferred (99 means high).
-    */
     InputState* InputManager::createInputState(const std::string& name, bool bAlwaysGetsInput, bool bTransparent, InputStatePriority priority)
     {
-        InputState* state = new InputState;
-        if (configureInputState(state, name, bAlwaysGetsInput, bTransparent, priority))
-            return state;
-        else
-        {
-            delete state;
+        if (name == "")
             return 0;
-        }
-    }
-
-    /**
-    @brief
-        Adds a new key handler.
-    @param handler
-        Pointer to the handler object.
-    @param name
-        Unique name of the handler.
-    @param priority
-        Determines which InputState gets the input. Higher is better.
-        Use 0 to handle it implicitely by the order of activation.
-        Otherwise numbers larger than maxStateStackSize_s have to be used!
-    @return
-        True if added, false if name or priority already existed.
-    */
-    bool InputManager::configureInputState(InputState* state, const std::string& name, bool bAlwaysGetsInput, bool bTransparent, int priority)
-    {
-        if (name == "")
-            return false;
-        if (!state)
-            return false;
         if (statesByName_.find(name) == statesByName_.end())
         {
+            InputState* state = new InputState;
             if (priority >= InputStatePriority::HighPriority || priority == InputStatePriority::Empty)
             {
@@ -685,5 +588,5 @@
                     {
                         COUT(2) << "Warning: Could not add an InputState with the same priority '"
-                            << priority << "' != 0." << std::endl;
+                            << static_cast<int>(priority) << "' != 0." << std::endl;
                         return false;
                     }
@@ -697,21 +600,14 @@
             if (priority >= InputStatePriority::HighPriority || priority == InputStatePriority::Empty)
                 state->setPriority(priority);
-            return true;
+
+            return state;
         }
         else
         {
             COUT(2) << "Warning: Could not add an InputState with the same name '" << name << "'." << std::endl;
-            return false;
-        }
-    }
-
-    /**
-    @brief
-        Returns the pointer to the requested InputState.
-    @param name
-        Unique name of the state.
-    @return
-        Pointer to the instance, 0 if name was not found.
-    */
+            return 0;
+        }
+    }
+
     InputState* InputManager::getState(const std::string& name)
     {
@@ -723,13 +619,4 @@
     }
 
-    /**
-    @brief
-        Activates a specific input state.
-        It might not be really activated if the priority is too low!
-    @param name
-        Unique name of the state.
-    @return
-        False if name was not found, true otherwise.
-    */
     bool InputManager::enterState(const std::string& name)
     {
@@ -754,12 +641,4 @@
     }
 
-    /**
-    @brief
-        Deactivates a specific input state.
-    @param name
-        Unique name of the state.
-    @return
-        False if name was not found, true otherwise.
-    */
     bool InputManager::leaveState(const std::string& name)
     {
@@ -784,15 +663,4 @@
     }
 
-    /**
-    @brief
-        Removes and destroys an input state.
-    @param name
-        Name of the handler.
-    @return
-        True if removal was successful, false if name was not found.
-    @remarks
-        You can't remove the internal states "empty", "calibrator" and "detector".
-        The removal process is being postponed if InputManager::update() is currently running.
-    */
     bool InputManager::destroyState(const std::string& name)
     {
@@ -824,8 +692,5 @@
     }
 
-    /**
-    @brief
-        Destroys an InputState internally
-    */
+    //! Destroys an InputState internally.
     void InputManager::destroyStateInternal(InputState* state)
     {
Index: /code/branches/core4/src/core/input/InputManager.h
===================================================================
--- /code/branches/core4/src/core/input/InputManager.h	(revision 3280)
+++ /code/branches/core4/src/core/input/InputManager.h	(revision 3281)
@@ -27,11 +27,4 @@
  */
 
-/**
-@file
-@brief
-    Implementation of a little Input handler that distributes everything
-    coming from OIS.
-*/
-
 #ifndef _InputManager_H__
 #define _InputManager_H__
@@ -51,9 +44,26 @@
     /**
     @brief
-        Captures and distributes mouse and keyboard input.
+        Manages the input devices (mouse, keyboard, joy sticks) and the input states.
+
+        Every input device has its own wrapper class which does the actualy input event
+        distribution. The InputManager only creates reloads (on request) those devices.
+
+        The other functionality concerns handling InputStates. They act as a layer
+        between InputHandlers (like the KeyBinder or the GUIManager) and InputDevices.
+        InputStates are memory managed by the IputManager. You cannot create or destroy
+        them on your own. Therefore all states get destroyed with the InputManager d'tor.
+    @note
+        - The actual lists containing all the InputStates for a specific device are stored
+          in the InputDevices themselves.
+        - The devices_ vector always has at least two elements: Keyboard (first) and mouse.
+          You best access them intenally with InputDeviceEnumerator::Keyboard/Mouse
+          The first joy stick is accessed with InputDeviceEnumerator::FirstJoyStick.
+        - Keyboard construction is mandatory , mouse and joy sticks are not.
+          If the OIS::InputManager or the Keyboard fail, an exception is thrown.
     */
     class _CoreExport InputManager : public OrxonoxClass
     {
     public:
+        //! Represents internal states of the InputManager.
         enum State
         {
@@ -65,11 +75,34 @@
         };
 
-        InputManager (size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight);
+        /**
+        @brief
+            Loads the devices and initialises the KeyDetector and the Calibrator.
+            
+            If either the OIS input system and/or the keyboard could not be created,
+            the constructor fails with an std::exception.
+        */
+        InputManager(size_t windowHnd, unsigned int windowWidth, unsigned int windowHeight);
+        //! Destroys all devices AND all input states!
         ~InputManager();
         void setConfigValues();
 
+        /**
+        @brief
+            Updates the devices (which distribute the input events) and the input states.
+
+            Any InpuStates changes (destroy, enter, leave) and happens here. If a reload request
+            was submitted while updating, the request wil be postponed until the next update call.
+        */
         void update(const Clock& time);
+        //! Clears all input device buffers. This usually only includes the pressed button list.
         void clearBuffers();
+        //! Starts joy stick calibration.
         void calibrate();
+        /**
+        @brief
+            Reloads all the input devices. Use this method to initialise new joy sticks.
+        @note
+            Only reloads immediately if the call stack doesn't include the update() method.
+        */
         void reload();
 
@@ -77,21 +110,71 @@
         // Input States
         //-------------------------------
+        /**
+        @brief
+            Creates a new InputState that gets managed by the InputManager.
+        @remarks
+            The InputManager will take care of the state completely. That also
+            means it gets deleted when the InputManager is destroyed!
+        @param name
+            Unique name of the InputState when referenced as string
+        @param priority
+            Priority matters when multiple states are active. You can specify any
+            number, but 1 - 99 is preferred (99 means high priority).
+        */
         InputState* createInputState(const std::string& name, bool bAlwaysGetsInput = false, bool bTransparent = false, InputStatePriority priority = InputStatePriority::Dynamic);
+        /**
+        @brief
+            Returns a pointer to a InputState referenced by name.
+        @return
+            Returns NULL if state was not found.
+        */
         InputState* getState(const std::string& name);
-        bool enterState     (const std::string& name);
-        bool leaveState     (const std::string& name);
-        bool destroyState   (const std::string& name);
+        /**
+        @brief
+            Activates a specific input state.
+            It might not be actually activated if the priority is too low!
+        @return
+            False if name was not found, true otherwise.
+        */
+        bool enterState(const std::string& name);
+        /**
+        @brief
+            Deactivates a specific input state.
+        @return
+            False if name was not found, true otherwise.
+        */
+        bool leaveState(const std::string& name);
+        /**
+        @brief
+            Removes and destroys an input state.
+        @return
+            True if removal was successful, false if name was not found.
+        @remarks
+            - You can't remove the internal states "empty", "calibrator" and "detector".
+            - The removal process is being postponed if InputManager::update() is currently running.
+        */
+        bool destroyState(const std::string& name);
 
         //-------------------------------
         // Various getters and setters
         //-------------------------------
+        //! Sets the the name of the command used by the KeyDetector as callback.
         void setKeyDetectorCallback(const std::string& command);
+        /**
+        @brief
+            Checks whether there is already a joy stick with the given ID string.
+        @return
+            Returns true if ID is ok (unique), false otherwise.
+        */
         bool checkJoyStickID(const std::string& idString) const;
+        //! Returns the number of joy stick that have been created since the c'tor or last call to reload().
         unsigned int getJoyStickQuantity() const
             { return devices_.size() - InputDeviceEnumerator::FirstJoyStick; }
+        //! Returns a pointer to the OIS InputManager. Only you if you know what you're doing!
         OIS::InputManager* getOISInputManager()
             { return this->oisInputManager_; }
 
-        static InputManager& getInstance()    { assert(singletonRef_s); return *singletonRef_s; }
+        //! Returns a reference to the singleton instance
+        static InputManager& getInstance() { assert(singletonRef_s); return *singletonRef_s; }
 
     private: // functions
@@ -106,10 +189,8 @@
 
         void stopCalibration();
+        void reloadInternal();
 
         void destroyStateInternal(InputState* state);
         void updateActiveStates();
-        bool configureInputState(InputState* state, const std::string& name, bool bAlwaysGetsInput, bool bTransparent, int priority);
-
-        void reloadInternal();
 
     private: // variables
@@ -117,20 +198,22 @@
         OIS::InputManager*                  oisInputManager_;      //!< OIS input manager
         std::vector<InputDevice*>           devices_;              //!< List of all input devices (keyboard, mouse, joy sticks)
-        size_t                              windowHnd_;            //!< Render window handle
+        // TODO: Get this from the GraphicsManager during reload
+        size_t                              windowHnd_;            //!< Render window handle (used to reload the InputManager)
 
         // some internally handled states and handlers
-        InputState*                         emptyState_;
+        InputState*                         emptyState_;           //!< Lowest priority states (makes handling easier)
         KeyDetector*                        keyDetector_;          //!< KeyDetector instance
+        //! InputBuffer that reacts to the Enter key when calibrating the joy sticks
         InputBuffer*                        calibratorCallbackHandler_;
 
-        std::map<std::string, InputState*>  statesByName_;
-        std::map<int, InputState*>          activeStates_;
-        std::vector<InputState*>            activeStatesTicked_;
-
-        std::set<InputState*>               stateEnterRequests_;   //!< Request to enter a new state
-        std::set<InputState*>               stateLeaveRequests_;   //!< Request to leave a running state
-        std::set<InputState*>               stateDestroyRequests_; //!< Request to destroy a state
-
-        static InputManager*                singletonRef_s;
+        std::map<std::string, InputState*>  statesByName_;         //!< Contains all the created input states by name
+        std::map<int, InputState*>          activeStates_;         //!< Contains all active input states by priority (std::map is sorted!)
+        std::vector<InputState*>            activeStatesTicked_;   //!< Like activeStates_, but only contains the ones that currently receive events
+
+        std::set<InputState*>               stateEnterRequests_;   //!< Requests to enter a new state
+        std::set<InputState*>               stateLeaveRequests_;   //!< Requests to leave a running state
+        std::set<InputState*>               stateDestroyRequests_; //!< Requests to destroy a state
+
+        static InputManager*                singletonRef_s;        //!< Pointer reference to the singleton
     };
 }
