More documentation

CamelotCore/Include/CmPlatform.h

@@ -4,6 +4,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains values representing default
+	 *			mouse cursor types.
+	 */
 	enum class PlatformCursorType
 	{
 		Arrow,
@@ -18,6 +22,12 @@ namespace BansheeEngine
 		SizeWE
 	};
 
+	/**
+	 * @brief	Contains values reprenting window non client areas.
+	 *
+	 * @note	These are used for things like resize/move and tell the OS
+	 *			where each of those areas are on our window.
+	 */
 	enum class NonClientAreaBorderType
 	{
 		TopLeft,
@@ -30,11 +40,18 @@ namespace BansheeEngine
 		BottomRight	
 	};
 
+	/**
+	 * @brief	Types of mouse buttons provided by the OS.
+	 */
 	enum class OSMouseButton
 	{
 		Left, Middle, Right, Count
 	};
 
+	/**
+	 * @brief	Describes pointer (mouse, touch) states as reported
+	 *			by the OS.
+	 */
 	struct CM_EXPORT OSPointerButtonStates
 	{
 		OSPointerButtonStates()
@@ -51,30 +68,91 @@ namespace BansheeEngine
 		bool shift, ctrl;
 	};
 
+	/**
+	 * @brief	Type of drop event type. This is used
+	 *			when dragging items over drop targets.
+	 */
 	enum class OSDropType
 	{
 		FileList,
 		None
 	};
 
+	/**
+	 * @brief	Drop targets allow you to register a certain portion of a window as a drop target that
+	 *			accepts certain drop types. Accepted drop types are provided by the OS and include things
+	 *			like file and item dragging.
+	 *
+	 *			You will receive events with the specified drop area as long as it is active.
+	 */
 	class CM_EXPORT OSDropTarget
 	{
 	public:
+		/**
+		 * @brief	Triggered when a pointer is being dragged over the drop area.
+		 *			Provides window coordinates of the pointer position.
+		 */
 		boost::signal<void(INT32 x, INT32 y)> onDragOver;
+
+		/**
+		 * @brief	Triggered when the user completes a drop while pointer is over
+		 *			the drop area.
+		 *			Provides window coordinates of the pointer position.
+		 */
 		boost::signal<void(INT32 x, INT32 y)> onDrop;
+
+		/**
+		 * @brief	Triggered when a pointer enters the drop area.
+		 *			Provides window coordinates of the pointer position.
+		 */
 		boost::signal<void(INT32 x, INT32 y)> onEnter;
+
+		/**
+		 * @brief	Triggered when a pointer leaves the drop area.
+		 */
 		boost::signal<void()> onLeave;
 
+		/**
+		 * @brief	Sets the drop target area, in local window coordinates.
+		 */
 		void setArea(INT32 x, INT32 y, UINT32 width, UINT32 height);
+
+		/**
+		 * @brief	Gets the type of drop that this drop target is looking for. Only
+		 *			valid after a drop has been triggered.
+		 */
 		OSDropType getDropType() const { return mDropType; }
 
+		/**
+		 * @brief	Returns a list of files received by the drop target. Only valid
+		 *			after a drop of FileList type has been triggered.
+		 */
 		const Vector<WString>::type& getFileList() const { return *mFileList; }
 
+		/**
+		 * @brief	Internal method. Clears all internal values.
+		 */
 		void _clear();
+
+		/**
+		 * @brief	Internal method. Sets the file list and marks the drop event as FileList.
+		 */
 		void _setFileList(const Vector<WString>::type& fileList);
+
+		/**
+		 * @brief	Marks the drop area as inactive or active.
+		 */
 		void _setActive(bool active) { mActive = active; }
 
+		/**
+		 * @brief	Checks is the specified position within the current drop area.
+		 *			Position should be in window local coordinates.
+		 */
 		bool _isInside(const Vector2I& pos) const;
+
+		/**
+		 * @brief	Returns true if the drop target is active.
+		 */
 		bool _isActive() const { return mActive; }
 	private:
 		friend class Platform;
@@ -82,6 +160,9 @@ namespace BansheeEngine
 		OSDropTarget(const RenderWindow* ownerWindow, INT32 x, INT32 y, UINT32 width, UINT32 height);
 		~OSDropTarget();
 
+		/**
+		 * @brief	Returns a render window this drop target is attached to.
+		 */
 		const RenderWindow* getOwnerWindow() const { return mOwnerWindow; }
 	private:
 		INT32 mX, mY;
@@ -98,7 +179,7 @@ namespace BansheeEngine
 	};
 }
 
-//Bring in the specific platform's header file
+// Bring in the specific platform's header file
 #if CM_PLATFORM == CM_PLATFORM_WIN32
 # include "Win32/CmPlatformImpl.h"
 #elif (CM_PLATFORM == CM_PLATFORM_LINUX)

CamelotCore/Include/CmShader.h

@@ -6,6 +6,11 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief Describes a single data (int, Vector2, etc.) shader parameter.
+	 *
+	 * @see	Shader::addParameter.
+	 */
 	struct CM_EXPORT SHADER_DATA_PARAM_DESC
 	{
 		String name;
@@ -16,6 +21,11 @@ namespace BansheeEngine
 		UINT32 elementSize;
 	};
 
+	/**
+	 * @brief Describes a single object (texture, sampler state, etc.) shader parameter.
+	 *
+	 * @see	Shader::addParameter.
+	 */
 	struct CM_EXPORT SHADER_OBJECT_PARAM_DESC
 	{
 		String name;
@@ -24,6 +34,9 @@ namespace BansheeEngine
 		bool hidden;
 	};
 
+	/**
+	 * @brief Describes a shader parameter block.
+	 */
 	struct CM_EXPORT SHADER_PARAM_BLOCK_DESC
 	{
 		String name;
@@ -43,25 +56,40 @@ namespace BansheeEngine
 	class CM_EXPORT Shader : public Resource
 	{
 	public:
+		/**
+		 * @brief	Adds a new technique that supports the provided render system
+		 *			and renderer to the shader. It's up to the caller to populate the
+		 *			returned object with valid data.
+		 */
 		TechniquePtr addTechnique(const String& renderSystem, const String& renderer);
 		
+		/**
+		 * @brief	Removes a technique at the specified index.
+		 */
 		void removeTechnique(UINT32 idx);
+
+		/**
+		 * @brief	Removes the specified technique.
+		 */
 		void removeTechnique(TechniquePtr technique);
 
+		/**
+		 * @brief	Returns the total number of techniques in this shader.
+		 */
 		UINT32 getNumTechniques() const { return (UINT32)mTechniques.size(); }
 
 		/**
 		 * @brief	Gets the best supported technique based on current render and other systems.
-		 * 			Throws an exception if not a single technique is supported.
+		 * 			Returns null if not a single technique is supported.
 		 */
 		TechniquePtr getBestTechnique() const;
 
 		/**
-		 * @brief	Registers a new parameter you can use for easily setting GpuProgram constants via Material.
-		 * 			Only data types may be set using this method. Use the other overload of the method if you want
-		 * 			to add object parameters.
+		 * @brief	Registers a new data (int, Vector2, etc.) parameter you that you may then use 
+		 *			via Material by providing the parameter name. All parameters internally map to 
+		 *			variables defined in GPU programs.
 		 *
-		 * @param	name		   	The name of the parameter.
+		 * @param	name		   	The name of the parameter. Name must be unique between all data and object parameters.
 		 * @param	gpuVariableName	Name of the GPU variable in the GpuProgram that the parameter corresponds with.
 		 * @param	type		   	The type of the parameter, must be the same as the type in GpuProgram.
 		 * @param	arraySize	   	(optional) If the parameter is an array, the number of elements in the array. Size of 1 means its not an array.
@@ -71,25 +99,80 @@ namespace BansheeEngine
 		 * 							as hidden to some system. (e.g. hiding internal engine-managed parameters from the user in the Editor)
 		 */
 		void addParameter(const String& name, const String& gpuVariableName, GpuParamDataType type, UINT32 arraySize = 1, UINT32 elementSize = 0, bool hidden = false);
+
+		/**
+		 * @brief	Registers a new object (texture, sampler state, etc.) parameter you that you may then use 
+		 *			via Material by providing the parameter name. All parameters internally map to variables defined in GPU programs.
+		 *
+		 * @param	name		   	The name of the parameter. Name must be unique between all data and object parameters.
+		 * @param	gpuVariableName	Name of the GPU variable in the GpuProgram that the parameter corresponds with.
+		 * @param	type		   	The type of the parameter, must be the same as the type in GpuProgram.
+		 * @param	hidden		   	(optional) Property that is not directly used by the material system, but can be useful if you need to mark certain parameters
+		 * 							as hidden to some system. (e.g. hiding internal engine-managed parameters from the user in the Editor)
+		 */
 		void addParameter(const String& name, const String& gpuVariableName, GpuParamObjectType type, bool hidden = false);
+
+		/**
+		 * @brief	Unregister a parameter with the specified name.
+		 */
 		void removeParameter(const String& name);
+
+		/**
+		 * @brief	Changes parameters of a parameter block with the specified name.
+		 */
 		void setParamBlockAttribs(const String& name, bool shared, GpuParamBlockUsage usage);
 
+		/**
+		 * @brief	Returns type of the parameter with the specified name. Throws exception if
+		 *			the parameter doesn't exist.
+		 */
 		GpuParamType getParamType(const String& name) const;
+
+		/**
+		 * @brief	Returns description for a data parameter with the specified name. Throws exception if
+		 *			the parameter doesn't exist.
+		 */
 		const SHADER_DATA_PARAM_DESC& getDataParamDesc(const String& name) const;
+
+		/**
+		 * @brief	Returns description for an object parameter with the specified name. Throws exception if
+		 *			the parameter doesn't exist.
+		 */
 		const SHADER_OBJECT_PARAM_DESC& getObjectParamDesc(const String& name) const;
 
+		/** 
+		 * @brief	Checks if the parameter with the specified name exists, and is a data parameter.
+		 */
 		bool hasDataParam(const String& name) const;
+
+		/** 
+		 * @brief	Checks if the parameter with the specified name exists, and is an object parameter.
+		 */
 		bool hasObjectParam(const String& name) const;
 
+		/** 
+		 * @brief	Returns a map of all data parameters in the shader.
+		 */
 		const Map<String, SHADER_DATA_PARAM_DESC>::type& getDataParams() const { return mDataParams; }
+
+		/** 
+		 * @brief	Returns a map of all object parameters in the shader.
+		 */
 		const Map<String, SHADER_OBJECT_PARAM_DESC>::type& getObjectParams() const { return mObjectParams; }
+
+		/** 
+		 * @brief	Returns a map of all parameter blocks.
+		 */
 		const Map<String, SHADER_PARAM_BLOCK_DESC>::type& getParamBlocks() const { return mParamBlocks; }
 
 		static bool isSampler(GpuParamObjectType type);
 		static bool isTexture(GpuParamObjectType type);
 		static bool isBuffer(GpuParamObjectType type);
 
+		/** 
+		 * @brief	Returns an empty shader object with the specified name. Caller must register
+		 *			techniques with the shader before using it in a Material.
+		 */
 		static ShaderPtr create(const String& name);
 	private:
 		String mName;

CamelotCore/Include/CmTechnique.h

@@ -5,17 +5,47 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Technique represents a specific implementation of a shader. Contains
+	 *			a number of passes that will be executed when rendering objects using this technique.
+	 *
+	 * @note	Normally you want to have a separate technique for every render system and renderer your 
+	 *			application supports. For example, if you are supporting DirectX11 and OpenGL you will
+	 *			want to have two techniques, one using HLSL based GPU programs, other using GLSL. Those
+	 *			techniques should try to mirror each others end results.
+	 */
 	class CM_EXPORT Technique : public IReflectable
 	{
 	public:
 		Technique(const String& renderSystem, const String& renderer);
 
+		/**
+		 * @brief	Registers a new pass with the technique. It's up to the caller
+		 *			to register GPU programs in the returned pass.
+		 *
+		 * @note	Passes added first will be executed first when rendering.
+		 */
 		PassPtr addPass();
+
+		/**
+		 * @brief	Removes a pass with the specified index.
+		 */
 		void removePass(UINT32 idx);
+
+		/**
+		 * @brief	Returns a pass with the specified index.
+		 */
 		PassPtr getPass(UINT32 idx) const;
 
+		/**
+		 * @brief	Returns total number of passes.
+		 */
 		UINT32 getNumPasses() const { return (UINT32)mPasses.size(); }
 
+		/**
+		 * @brief	Checks if this technique is supported based on current
+		 *			render and other systems.
+		 */
 		bool isSupported() const;
 
 	private:

CamelotCore/Include/CmWin32FolderMonitor.h

@@ -4,18 +4,26 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	These values types of notifications we would like to receive
+	 *			when we start a FolderMonitor on a certain folder.
+	 */
 	enum class FolderChange
 	{
-		FileName = 0x0001,
-		DirName = 0x0002,
-		Attributes = 0x0004,
-		Size = 0x0008,
-		LastWrite = 0x0010,
-		LastAccess = 0x0020,
-		Creation = 0x0040,
-		Security = 0x0080
+		FileName = 0x0001, /**< Called when filename changes. */
+		DirName = 0x0002, /**< Called when directory name changes. */
+		Attributes = 0x0004, /**< Called when attributes changes. */
+		Size = 0x0008, /**< Called when file size changes. */
+		LastWrite = 0x0010, /**< Called when file is written to. */
+		LastAccess = 0x0020, /**< Called when file is accessed. */
+		Creation = 0x0040, /**< Called when file is created. */
+		Security = 0x0080 /**< Called when file security descriptor changes. */
 	};
 
+	/**
+	 * @brief	Allows you to monitor a file system folder for changes. Depending on the flags
+	 *			set this monitor can notify you when file is changed/moved/renamed, etc.
+	 */
 	class CM_EXPORT FolderMonitor
 	{
 		struct Pimpl;
@@ -25,8 +33,25 @@ namespace BansheeEngine
 		FolderMonitor();
 		~FolderMonitor();
 
+		/**
+		 * @brief	Starts monitoring a folder at the specified path.
+		 *
+		 * @param	folderPath		Absolute path to the folder you want to monitor.
+		 * @param	subdirectories	If true, provided folder and all of its subdirectories will be monitored
+		 *							for changes. Otherwise only the provided folder will be monitored.
+		 * @param	changeFilter	A set of flags you may OR together. Different notification events will
+		 *							trigger depending on which flags you set.
+		 */
 		void startMonitor(const WString& folderPath, bool subdirectories, FolderChange changeFilter);
+
+		/**
+		 * @brief	Stops monitoring the folder at the specified path.
+		 */
 		void stopMonitor(const WString& folderPath);
+
+		/**
+		 * @brief	Stops monitoring all folders that are currently being monitored.
+		 */
 		void stopMonitorAll();
 
 		/**
@@ -36,15 +61,41 @@ namespace BansheeEngine
 		 */
 		void update();
 
+		/**
+		 * @brief	Triggers when a file is modified. Provides
+		 *			full path to the file.
+		 */
 		boost::signal<void(const WString&)> onModified;
+
+		/**
+		 * @brief	Triggers when a file/folder is adeed. Provides
+		 *			full path to the file/folder.
+		 */
 		boost::signal<void(const WString&)> onAdded;
+
+		/**
+		 * @brief	Triggers when a file/folder is removed. Provides
+		 *			full path to the file/folder.
+		 */
 		boost::signal<void(const WString&)> onRemoved;
+
+		/**
+		 * @brief	Triggers when a file/folder is renamed. Provides
+		 *			full path to the old and new name.
+		 */
 		boost::signal<void(const WString&, const WString&)> onRenamed;
 
 	private:
 		Pimpl* mPimpl;
 
+		/**
+		 * @brief	Worker method that monitors the IO ports for any modification notifications.
+		 */
 		void workerThreadMain();
+
+		/**
+		 * @brief	Called by the worker thread whenever a modification notification is received.
+		 */
 		void handleNotifications(FileNotifyInfo& notifyInfo, FolderWatchInfo& watchInfo);
 	};
 }

CamelotCore/Source/CmShader.cpp

@@ -56,9 +56,9 @@ namespace BansheeEngine
 			}
 		}
 
-		CM_EXCEPT(InternalErrorException, "No techniques are supported!");
+		return nullptr;
 
-		// TODO - Low priority. Instead of throwing an exception use an extremely simple technique that will be supported almost everywhere as a fallback.
+		// TODO - Low priority. Instead of returning null use an extremely simple technique that will be supported almost everywhere as a fallback.
 	}
 
 	void Shader::addParameter(const String& name, const String& gpuVariableName, GpuParamDataType type, UINT32 arraySize, UINT32 elementSize, bool hidden)