More documentation

CamelotCore/Include/CmImportOptions.h

@@ -5,6 +5,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Base class for creating import options from. Import options
+	 *			are specific for each importer and control how is data imported.
+	 */
 	class CM_EXPORT ImportOptions : public IReflectable
 	{
 	public:

CamelotCore/Include/CmImporter.h

@@ -12,9 +12,6 @@ namespace BansheeEngine
 	class CM_EXPORT Importer : public Module<Importer>
 	{
 	public:
-		/**
-		 * @brief	Constructor.
-		 */
 		Importer(); 
 		~Importer(); 
 
@@ -22,7 +19,11 @@ namespace BansheeEngine
 		 * @brief	Imports a resource at the specified location, and returns the loaded data.
 		 *
 		 * @param	inputFilePath	Pathname of the input file.
-		 * @param	importOptions	(optional) Options for controlling the import.
+		 * @param	importOptions	(optional) Options for controlling the import. Caller must
+		 *							ensure import options actually match the type of the importer used
+		 *							for the file type.
+		 *
+		 * @see		createImportOptions
 		 */
 		HResource import(const WString& inputFilePath, ConstImportOptionsPtr importOptions = nullptr);
 
@@ -30,7 +31,11 @@ namespace BansheeEngine
 		 * @brief	Imports a resource and replaces the contents of the provided existing resource with new imported data.
 		 *
 		 * @param	inputFilePath	Pathname of the input file.
-		 * @param	importOptions	(optional) Options for controlling the import.
+		 * @param	importOptions	(optional) Options for controlling the import. Caller must
+		 *							ensure import options actually match the type of the importer used
+		 *							for the file type. 
+		 *
+		 * @see		createImportOptions
 		 */
 		void reimport(HResource& existingResource, const WString& inputFilePath, ConstImportOptionsPtr importOptions = nullptr);
 
@@ -54,7 +59,7 @@ namespace BansheeEngine
 		/**
 		 * @brief	Checks if we can import a file with the specified extension.
 		 *
-		 * @param	extension	The extension without leading dot.
+		 * @param	extension	The extension without the leading dot.
 		 */
 		bool supportsFileType(const WString& extension) const;
 
@@ -70,7 +75,7 @@ namespace BansheeEngine
 		 * @brief	Adds a new asset importer for the specified file extension. If an asset importer for that extension
 		 * 			already exists, it is removed and replaced with the current one.
 		 * 			
-		 * @note	This method should only be called by asset importers themselves on startup.
+		 * @note	Internal method. This method should only be called by asset importers themselves on startup.
 		 *
 		 * @param [in]	importer	The importer that is able to handle files with the specified extension. nullptr if you
 		 * 							want to remove an asset importer for the extension.

CamelotCore/Include/CmInput.h

@@ -9,35 +9,82 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Primary module used for dealing with input. Allows you to receieve 
+	 *			and query raw or OS input for mouse/keyboard/gamepad.
+	 *
+	 *			All inputs are received through an input handler, which can be overriden to 
+	 *			provide custom input functionality.
+	 */
 	class CM_EXPORT Input : public Module<Input>
 	{
+		/**
+		 * @brief	Possible button states
+		 */
 		enum class ButtonState
 		{
-			Off,
-			On,
-			ToggledOn,
-			ToggledOff
+			Off, /**< Button is not being pressed. */
+			On, /**< Button is being pressed. */
+			ToggledOn, /**< Button has been pressed this frame. */
+			ToggledOff /**< Button has been released this frame. */
 		};
 
 	public:
 		Input();
 		~Input();
 
+		/**
+		 * @brief	Triggered whenever a button is first pressed.
+		 */
 		boost::signal<void(const ButtonEvent&)> onButtonDown;
+
+		/**
+		 * @brief	Triggered whenever a button is first released.
+		 */
 		boost::signal<void(const ButtonEvent&)> onButtonUp;
+
+		/**
+		 * @brief	Triggered whenever user inputs a text character. 
+		 */
 		boost::signal<void(const TextInputEvent&)> onCharInput;
 
+		/**
+		 * @brief	Triggers when some pointing device (mouse cursor, touch) moves.
+		 */
 		boost::signal<void(const PositionalInputEvent&)> onCursorMoved;
+
+		/**
+		 * @brief	Triggers when some pointing device (mouse cursor, touch) button is pressed.
+		 */
 		boost::signal<void(const PositionalInputEvent&)> onCursorPressed;
+
+		/**
+		 * @brief	Triggers when some pointing device (mouse cursor, touch) button is released.
+		 */
 		boost::signal<void(const PositionalInputEvent&)> onCursorReleased;
+
+		/**
+		 * @brief	Triggers when some pointing device (mouse cursor, touch) button is double clicked.
+		 */
 		boost::signal<void(const PositionalInputEvent&)> onDoubleClick;
 
+		// TODO Low priority: Remove this, I can emulate it using virtual input
+		/**
+		 * @brief	Triggers on special input commands.
+		 */
 		boost::signal<void(InputCommandType)> onInputCommand;
 
+		/**
+		 * @brief	Registers a new input handler. Replaces any previous input handler.
+		 *
+		 * @note	Internal method.
+		 */
 		void registerRawInputHandler(std::shared_ptr<RawInputHandler> inputHandler);
 
 		/**
-		 * @brief	Called every frame. Dispatches any callbacks resulting from input by the user. Should only be called by Application.
+		 * @brief	Called every frame. Dispatches any callbacks resulting from input by the user.
+		 *
+		 * @note	Internal method.
 		 */
 		void update();
 
@@ -55,10 +102,24 @@ namespace BansheeEngine
 		 */
 		float getVerticalAxis() const;
 
+		/**
+		 * @brief	Query if the provided button is currently being held (this frame or previous frames).
+		 */
 		bool isButtonHeld(ButtonCode keyCode) const;
+
+		/**
+		 * @brief	Query if the provided button is currently being released (one true for one frame).
+		 */
 		bool isButtonUp(ButtonCode keyCode) const;
+
+		/**
+		 * @brief	Query if the provided button is currently being pressed (one true for one frame).
+		 */
 		bool isButtonDown(ButtonCode keyCode) const;
 
+		/**
+		 * @brief	Returns mouse cursor position.
+		 */
 		Vector2I getCursorPosition() const { return mMouseAbsPos; }
 	private:
 		std::shared_ptr<RawInputHandler> mRawInputHandler;
@@ -130,5 +191,8 @@ namespace BansheeEngine
 		static const float WEIGHT_MODIFIER;
 	};
 
+	/**
+	 * @copydoc	Input
+	 */
 	CM_EXPORT Input& gInput();
 }

CamelotCore/Include/CmInputFwd.h

@@ -229,6 +229,9 @@ namespace BansheeEngine
 		BC_NumJoy = 0x20,
 	};
 
+	/**
+	 * @brief	Structure containing information about a button input event.
+	 */
 	struct ButtonEvent
 	{
 	public:
@@ -236,14 +239,34 @@ namespace BansheeEngine
 			:mIsUsed(false)
 		{ }
 
-		ButtonCode buttonCode;
-		UINT64 timestamp;
+		ButtonCode buttonCode; /**< Button code this event is referring to. */
+		UINT64 timestamp; /**< Timestamp in ticks when the event happened. */
 
+		/**
+		 * @brief	Query is the pressed button a keyboard button.
+		 */
 		bool isKeyboard() const { return (buttonCode & 0xC0000000) == 0; }
+
+		/**
+		 * @brief	Query is the pressed button a mouse button.
+		 */
 		bool isMouse() const { return (buttonCode & 0x80000000) != 0; }
+
+		/**
+		 * @brief	Query is the pressed button a gamepad button.
+		 */
 		bool isJoystick() const { return (buttonCode & 0x40000000) != 0; }
 
+		/**
+		 * @brief	Check if the event has been marked as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		bool isUsed() const { return mIsUsed; }
+
+		/**
+		 * @brief	Mark the event as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		void markAsUsed() const { mIsUsed = true; }
 	private:
 		mutable bool mIsUsed;
@@ -258,6 +281,9 @@ namespace BansheeEngine
 		Left, Middle, Right, Count
 	};
 
+	/**
+	 * @brief	Type of positional input event.
+	 */
 	enum class PositionalInputEventType
 	{
 		CursorMoved,
@@ -282,24 +308,37 @@ namespace BansheeEngine
 			buttonStates[2] = false;
 		}
 
-		Vector2I screenPos;
-		bool buttonStates[PositionalInputEventButton::Count];
-		PositionalInputEventButton button;
-		PositionalInputEventType type;
+		Vector2I screenPos; /**< Screen position where the input event occurred. */
+		bool buttonStates[PositionalInputEventButton::Count]; /**< States of the positional input buttons (e.g. mouse buttons). */
+		PositionalInputEventButton button; /**< Button that triggered the positional input event. Might be irrelevant 
+										   depending on event type. (e.g. move events don't correspond to a button. */
+		PositionalInputEventType type; /**< Type of the positional input event. */
 
-		bool shift;
-		bool control;
-		bool alt;
+		bool shift; /**< Is Shift button on the keyboard being held down. */
+		bool control; /**< Is Control button on the keyboard being held down. */
+		bool alt; /**< Is Alt button on the keyboard being held down. */
 
-		float mouseWheelScrollAmount;
+		float mouseWheelScrollAmount; /**< If mouse wheel is being scrolled, what is the amount. */
 
+		/**
+		 * @brief	Check if the event has been marked as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		bool isUsed() const { return mIsUsed; }
+
+		/**
+		 * @brief	Mark the event as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		void markAsUsed() const { mIsUsed = true; }
 
 	private:
 		mutable bool mIsUsed;
 	};
 
+	/**
+	 * @brief	Type of special input command types.
+	 */
 	enum class InputCommandType
 	{
 		CursorMoveLeft, CursorMoveRight, CursorMoveUp, CursorMoveDown, 
@@ -307,6 +346,10 @@ namespace BansheeEngine
 		Escape, Delete, Backspace, Return
 	};
 
+	/**
+	 * @brief	Event that gets sent out when user inputs some text. These events may be preceeded by
+	 *			normal button events if user is typing on a keyboard. 
+	 */
 	struct TextInputEvent
 	{
 	public:
@@ -314,9 +357,18 @@ namespace BansheeEngine
 			:mIsUsed(false)
 		{ }
 
-		UINT32 textChar;
+		UINT32 textChar; /**< Character the user is inputting. */
 
+		/**
+		 * @brief	Check if the event has been marked as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		bool isUsed() const { return mIsUsed; }
+
+		/**
+		 * @brief	Mark the event as used. Internally this means nothing
+		 *			but caller might choose to ignore an used event.
+		 */
 		void markAsUsed() const { mIsUsed = true; }
 
 	private:

CamelotCore/Include/CmSpecificImporter.h

@@ -18,7 +18,16 @@ namespace BansheeEngine
 		SpecificImporter() {}
 		virtual ~SpecificImporter() {}
 
+		/**
+		 * @brief	Check is the provided extension supported by this importer.
+		 *
+		 * @note	Provided extension should be without the leading dot.
+		 */
 		virtual bool isExtensionSupported(const WString& ext) const = 0;
+
+		/**
+		 * @brief	Check if the provided magic number is supported by this importer.
+		 */
 		virtual bool isMagicNumberSupported(const UINT8* magicNumPtr, UINT32 numBytes) const = 0; 
 
 		/**