Index: code/branches/core4/src/core/input/InputState.cc
===================================================================
--- code/branches/core4/src/core/input/InputState.cc	(revision 3291)
+++ code/branches/core4/src/core/input/InputState.cc	(revision 3292)
@@ -32,4 +32,5 @@
 namespace orxonox
 {
+    //! Sets priority of it's a high priority and resizes the handler list
     InputState::InputState(const std::string& name, bool bAlwaysGetsInput, bool bTransparent, InputStatePriority priority)
         : name_(name)
@@ -47,5 +48,5 @@
             priority_ = 0;
 
-        handlers_.resize(InputDeviceEnumerator::FirstJoyStick + JoyStickQuantityListener::getJoyStickList().size(), NULL);
+        handlers_.resize(InputDeviceEnumerator::FirstJoyStick + this->getJoyStickList().size(), NULL);
     }
 
@@ -58,4 +59,5 @@
     }
 
+    //! Called by JoyStickQuantityListener upon joy stick adding/removal
     void InputState::JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList)
     {
@@ -69,14 +71,4 @@
     }
 
-    /**
-    @brief
-        Adds a joy stick handler.
-    @param handler
-        Pointer to the handler object.
-    @param joyStickID
-        ID of the joy stick
-    @return
-        True if added, false otherwise.
-    */
     bool InputState::setJoyStickHandler(InputHandler* handler, unsigned int joyStick)
     {
@@ -90,13 +82,5 @@
     }
 
-    /**
-    @brief
-        Adds a joy stick handler.
-    @param handler
-        Pointer to the handler object.
-    @return
-        True if added, false if handler already existed.
-    */
-    bool InputState::setJoyStickHandler(InputHandler* handler)
+    void InputState::setJoyStickHandler(InputHandler* handler)
     {
         joyStickHandlerAll_ = handler;
@@ -104,20 +88,11 @@
             handlers_[i] = handler;
         bExpired_ = true;
-        return true;
     }
 
-    /**
-    @brief
-        Adds a handler of any kind. dynamic_cast determines to which list it is added.
-    @param handler
-        Pointer to the handler object.
-    @return
-        True if added, false if handler already existed.
-    */
-    bool InputState::setHandler(InputHandler* handler)
+    void InputState::setHandler(InputHandler* handler)
     {
         setKeyHandler(handler);
         setMouseHandler(handler);
-        return setJoyStickHandler(handler);
+        setJoyStickHandler(handler);
     }
 
Index: code/branches/core4/src/core/input/InputState.h
===================================================================
--- code/branches/core4/src/core/input/InputState.h	(revision 3291)
+++ code/branches/core4/src/core/input/InputState.h	(revision 3292)
@@ -42,4 +42,5 @@
 namespace orxonox
 {
+    //! Enumeration wrapper for input state priorities
     struct InputStatePriority : OrxEnum<InputStatePriority>
     {
@@ -55,43 +56,99 @@
     };
 
+    /**
+    @brief
+        InputStates allow you to customise the input event targets at runtime.
+
+        The general idea is a stack: Every activated InputState will be pushed on
+        that stack and only the top one gets the input events. This is done for
+        every device (keyboard, mouse, all joy sticks) separately to allow
+        for intance keyboard input capturing for the console while you can still
+        steer a ship with the mouse.
+        There are two exceptions to this behaviour though:
+        - If an InputState is created with the 'Transparent' parameter on, the
+          state will not prevent input from getting to the state below it on the stack.
+          This can be useful for instance if you need to deploy input to multiple
+          handlers: Simply create two InputStates and make the high priority one transparent.
+        - If an InputState is created with the 'AlwaysGetsInput' parameter on, then
+          the state will always receive input as long as it is activated.
+        - Note: If you mark an InputState with both parameters on, then it will
+          not influence ony other InputState at all.
+
+        Priorities
+        **********
+        Every InputState has a priority when on the stack, but mostly this
+        priority is dynamic (InputStatePriority::Dynamic) which means that a state
+        pushed onto the stack will simply have a higher priority than the top one.
+        This behaviour really only applies to normal states that don't have
+        a high priority (InputStatePriority::HighPriority). These 'special' ones
+        are used for features like the KeyDetector or the console. Use with care!
+    */
     class _CoreExport InputState : public JoyStickQuantityListener
     {
         friend class InputManager;
 
-        static const InputDeviceEnumerator::Value keyboardIndex_s      = InputDeviceEnumerator::Keyboard;
-        static const InputDeviceEnumerator::Value mouseIndex_s         = InputDeviceEnumerator::Mouse;
+        //! Marks the index in the handler vector for the keyboard handler
+        static const InputDeviceEnumerator::Value keyboardIndex_s = InputDeviceEnumerator::Keyboard;
+        //! Marks the index in the handler vector for the mouse handler
+        static const InputDeviceEnumerator::Value mouseIndex_s = InputDeviceEnumerator::Mouse;
+        //! Marks the index in the handler vector for the first joy stick handler
         static const InputDeviceEnumerator::Value firstJoyStickIndex_s = InputDeviceEnumerator::FirstJoyStick;
 
     public:
+        //! Sets the keyboard event handler (overwrites if there already was one!)
         void setKeyHandler     (InputHandler* handler)
             { handlers_[keyboardIndex_s] = handler; bExpired_ = true; }
+        //! Sets the mouse event handler (overwrites if there already was one!)
         void setMouseHandler   (InputHandler* handler)
             { handlers_[mouseIndex_s]    = handler; bExpired_ = true; }
+        /**
+        @brief
+            Sets the joy stick event handler for one specific joy stick (overwrites if there already was one!)
+        @return
+            Returns false if the specified device was not found
+        */
         bool setJoyStickHandler(InputHandler* handler, unsigned int joyStick);
-        bool setJoyStickHandler(InputHandler* handler);
-        bool setHandler        (InputHandler* handler);
-
+        //! Sets the joy stick event handler for all joy sticks (overwrites if there already was one!)
+        void setJoyStickHandler(InputHandler* handler);
+        //! Sets an InputHandler to be used for all devices
+        void setHandler        (InputHandler* handler);
+
+        //! Returns the name of the state (which is unique!)
         const std::string& getName() const { return name_; }
+        //! Returns the priority of the state (which is unique if != 0)
         int getPriority()            const { return priority_; }
 
+        //! Tells whether there a handler installed for a specific device
         bool isInputDeviceEnabled(unsigned int device);
 
+        //! Returns true if the handler situation has changed
         bool hasExpired()      { return this->bExpired_; }
+        //! Call this if you have applied the changes resulting from changed handlers
         void resetExpiration() { bExpired_ = false; }
 
+        //! Updates one specific device handler with #device#Updated
         void update(float dt, unsigned int device);
+        //! Updates all handlers with allDevicesUpdated
         void update(float dt);
 
+        //! Generic function that distributes all 9 button events
         template <typename EventType, class Traits>
         void buttonEvent(unsigned int device, const typename Traits::ButtonTypeParam button);
 
+        //! Event handler
         void mouseMoved(IntVector2 abs, IntVector2 rel, IntVector2 clippingSize);
+        //! Event handler
         void mouseScrolled(int abs, int rel);
+        //! Event handler
         void joyStickAxisMoved(unsigned int device, unsigned int axis, float value);
 
         // Functors
+        //! Called when the state is being activated (even if it doesn't get any events afterwards!)
         void entered();
+        //! Called upon deactivation of the state
         void left();
+        //! Sets a functor to be called upon activation of the state
         void setEnterFunctor(Functor* functor) { this->enterFunctor_ = functor; }
+        //! Sets a functor to be called upon deactivation of the state
         void setLeaveFunctor(Functor* functor) { this->leaveFunctor_ = functor; }
 
@@ -102,15 +159,17 @@
         void JoyStickQuantityChanged(const std::vector<JoyStick*>& joyStickList);
 
+        //! Sets the priority (only to be used by the InputManager!)
         void setPriority(int priority) { priority_ = priority; }
 
-        const std::string           name_;
-        const bool                  bAlwaysGetsInput_;
-        const bool                  bTransparent_;
-        int                         priority_;
-        bool                        bExpired_;
-        std::vector<InputHandler*>  handlers_;
+        const std::string           name_;                  //!< Name of the state
+        const bool                  bAlwaysGetsInput_;      //!< See class declaration for explanation
+        const bool                  bTransparent_;          //!< See class declaration for explanation
+        int                         priority_;              //!< Current priority (might change)
+        bool                        bExpired_;              //!< See hasExpired()
+        std::vector<InputHandler*>  handlers_;              //!< Vector with all handlers where the index is the device ID
+        //! Handler to be used for all joy sticks (needs to be saved in case another joy stick gets attached)
         InputHandler*               joyStickHandlerAll_;
-        Functor*                    enterFunctor_;
-        Functor*                    leaveFunctor_;
+        Functor*                    enterFunctor_;          //!< Functor to be executed on enter
+        Functor*                    leaveFunctor_;          //!< Functor to be executed on leave
     };
 
