Documentation

BansheeEditor/Include/BsMainEditorWindow.h

@@ -5,21 +5,45 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Primary editor window, containing the menu bar, status bar
+	 *			and the dock area.
+	 */
 	class BS_ED_EXPORT MainEditorWindow : public EditorWindowBase
 	{
 	public:
 		~MainEditorWindow();
 
-		void update();
+		/**
+		 * @copydoc	EditorWindowBase::update
+		 */
+		void update() override;
 
 		/**
 		 * @copydoc	EditorWindowBase::isMain
 		 */
-		virtual bool isMain() const { return true; }
+		virtual bool isMain() const override { return true; }
 
+		/**
+		 * @brief	Gets the DockManager that is responsible for docking and placement
+		 *			of EditorWidget%s on the main window.
+		 */
 		DockManager& getDockManager() const { return *mDockManager; }
+
+		/**
+		 * @brief	Gets the primary menu bar element.
+		 */
 		GUIMenuBar& getMenuBar() const { return *mMenuBar; }
 
+		/**
+		 * @brief	Creates a new main editor window. If one is already open this method
+		 *			will return the existing one.
+		 *
+		 * @param	renderWindow	Previously created render window to initialize the main
+		 *							editor window in.
+		 *
+		 * @return	Instance of the main editor window.
+		 */
 		static MainEditorWindow* create(const RenderWindowPtr& renderWindow);
 	protected:
 		friend class EditorWindowManager;
@@ -30,8 +54,16 @@ namespace BansheeEngine
 		DockManager* mDockManager;
 		HProfilerOverlay mProfilerOverlay;
 
-		virtual void resized();
+		/**
+		 * @copydoc	EditorWindowBase::resized
+		 */
+		virtual void resized() override;
 
+		/**
+		 * @brief	Updates the placement of child GUI elements and their non-client
+		 *			areas (used for OS move/resize operations). Should be called after
+		 *			window size changes.
+		 */
 		void updateAreas();
 	};
 }

BansheeEditor/Include/BsModalWindow.h

@@ -5,22 +5,39 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Base implementation of a window that when open doesn't allow you
+	 *			to interact with other windows. Modal windows are similar to editor
+	 *			windows but cannot be docked, and are meant to be used for temporary
+	 *			operations like dialog boxes and progress bars.
+	 */
 	class BS_ED_EXPORT ModalWindow : public EditorWindowBase
 	{
 	public:
 		virtual ~ModalWindow();
 
-		virtual void update();
-		virtual void close();
+		/**
+		 * @copydoc	EditorWindowBase::update
+		 */
+		virtual void update() override;
+
+		/**
+		 * @copydoc	EditorWindowBase::close
+		 */
+		virtual void close() override;
+
+		/**
+		 * @brief	Changes the text in the modal window title bar.
+		 */
 		void setTitle(const HString& title);
 
 		/**
-		 * Converts screen pointer coordinates into coordinates relative to the window contents GUI panel.
+		 * Converts screen pointer coordinates into coordinates relative to the window content's GUI panel.
 		 */
 		Vector2I screenToWindowPos(const Vector2I& screenPos) const;
 
 		/**
-		 * Converts pointer coordinates relative to the window contents GUI panel into screen coordinates.
+		 * Converts pointer coordinates relative to the window content's GUI panel into screen coordinates.
 		 */
 		Vector2I windowToScreenPos(const Vector2I& windowPos) const;
 
@@ -28,12 +45,29 @@ namespace BansheeEngine
 		friend class EditorWindowManager;
 
 		ModalWindow(const HString& title, bool hasCloseButton = false);
+
+		/**
+		 * @brief	Returns the area in which the GUI contents are displayed (i.e. not including
+		 *			title bar and other default elements). Area is relative to window.
+		 */
 		Rect2I getContentArea() const;
 
-		virtual void resized();
+		/**
+		 * @copydoc	EditorWindowBase::resized
+		 */
+		virtual void resized() override;
 
 	private:
+		/**
+		 * @brief	Updates the placement of child GUI elements and their non-client
+		 *			areas (used for OS move/resize operations). Should be called after
+		 *			window size changes.
+		 */
 		void updateSize();
+
+		/**
+		 * @brief	Returns the height in pixels taken up by the title bar.
+		 */
 		UINT32 getTitleBarHeight() const;
 
 		GUIPanel* mTitleBarPanel;

BansheeEditor/Include/BsPlatformInfo.h

@@ -5,12 +5,18 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Available platforms we can build for
+	 */
 	enum class PlatformType
 	{
 		Windows,
 		Count // Keep at end
 	};
 
+	/**
+	 * @brief	Contains per-platform information used primarily for build purposes.
+	 */
 	struct BS_ED_EXPORT PlatformInfo : public IReflectable
 	{
 		PlatformInfo();
@@ -25,9 +31,13 @@ namespace BansheeEngine
 	public:
 		friend class PlatformInfoRTTI;
 		static RTTITypeBase* getRTTIStatic();
-		virtual RTTITypeBase* getRTTI() const;
+		virtual RTTITypeBase* getRTTI() const override;
 	};
 
+	/**
+	 * @brief	Contains Windows specific per-platform information used
+	 *			primarily for build purposes.
+	 */
 	struct BS_ED_EXPORT WinPlatformInfo : public PlatformInfo
 	{
 		WinPlatformInfo();
@@ -40,6 +50,6 @@ namespace BansheeEngine
 	public:
 		friend class WinPlatformInfoRTTI;
 		static RTTITypeBase* getRTTIStatic();
-		virtual RTTITypeBase* getRTTI() const;
+		virtual RTTITypeBase* getRTTI() const override;
 	};
 }

BansheeEditor/Include/BsProjectLibrary.h

@@ -5,6 +5,12 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Project library is the primary location for interacting with all the resources
+	 *			in the current project. A complete hierarchy of resources is provided which
+	 *			can be interacted with by importing new ones, deleting them, moving, renaming
+	 *			and similar.
+	 */
 	class BS_ED_EXPORT ProjectLibrary : public Module<ProjectLibrary>
 	{
 	public:
@@ -12,109 +18,350 @@ namespace BansheeEngine
 		struct ResourceEntry;
 		struct DirectoryEntry;
 
+		/**
+		 * @brief	Types of elements in the library, either a file
+		 *			or a folder.
+		 */
 		enum class LibraryEntryType
 		{
 			File,
 			Directory
 		};
 
+		/**
+		 * @brief	A generic library entry that may be a file or a folder
+		 *			depending on its type.
+		 */
 		struct LibraryEntry
 		{
 			LibraryEntry();
 			LibraryEntry(const Path& path, const WString& name, DirectoryEntry* parent, LibraryEntryType type);
 
-			LibraryEntryType type;
-			Path path;
-			WString elementName;
+			LibraryEntryType type; /**< Specific type of this entry. */
+			Path path; /**< Absolute path to the entry. */
+			WString elementName; /**< Name of the entry. */
 
-			DirectoryEntry* parent;
+			DirectoryEntry* parent; /**< Folder this entry is located in. */
 		};
 
+		/**
+		 * @brief	A library entry representing a resource.
+		 */
 		struct ResourceEntry : public LibraryEntry
 		{
 			ResourceEntry();
 			ResourceEntry(const Path& path, const WString& name, DirectoryEntry* parent);
 
-			ProjectResourceMetaPtr meta;
-			std::time_t lastUpdateTime;
+			ProjectResourceMetaPtr meta; /**< Meta file containing various information about the resource. */
+			std::time_t lastUpdateTime; /**< Timestamp of when we last imported the resource. */
 		};
 
+		/**
+		 * @brief	A library entry representing a folder that contains other entries.
+		 */
 		struct DirectoryEntry : public LibraryEntry
 		{
 			DirectoryEntry();
 			DirectoryEntry(const Path& path, const WString& name, DirectoryEntry* parent);
 
-			Vector<LibraryEntry*> mChildren;
+			Vector<LibraryEntry*> mChildren; /**< Child files or folders. */
 		};
 
 	public:
 		ProjectLibrary(const Path& projectFolder);
 		~ProjectLibrary();
 
+		/**
+		 * @brief	To be called once per frame.
+		 *
+		 * @note	Internal methods.
+		 */
 		void update();
+
+		/**
+		 * @brief	Checks if any resources at the specified path have been modified, added or deleted,
+		 *			and updates the internal hierarchy accordingly. 
+		 *
+		 * @param	path	Absolute path of the file or folder to check. If a folder is provided
+		 *					all its children will be checked recursively.
+		 */
 		void checkForModifications(const Path& path);
+
+		/**
+		 * @brief	Checks if any resources at the specified path have been modified, added or deleted,
+		 *			and updates the internal hierarchy accordingly. 
+		 *
+		 * @param	path			Absolute path of the file or folder to check. If a folder is provided
+		 *							all its children will be checked recursively.
+		 * @param	import			Should the dirty resources be automatically reimported.
+		 * @param	dirtyResources	A list of resources that should be reimported.
+		 */
 		void checkForModifications(const Path& path, bool import, Vector<Path>& dirtyResources);
 
+		/**
+		 * @brief	Returns the root library entry that references the entire library hierarchy.
+		 */
 		const LibraryEntry* getRootEntry() const { return mRootEntry; }
+
+		/**
+		 * @brief	Attempts to a find a library entry at the specified path.
+		 *
+		 * @param	path	Path to the entry, either absolute or relative to resources folder.
+		 *
+		 * @return	Found entry, or null if not found.
+		 */
 		LibraryEntry* findEntry(const Path& path) const;
 
+		/**
+		 * @brief	Searches the library for a pattern.
+		 *
+		 * @param	pattern	Pattern to search for. Use wildcard * to match any character(s).
+		 *
+		 * @return	A list of entries matching the pattern.
+		 */
 		Vector<LibraryEntry*> search(const WString& pattern);
+
+		/**
+		 * @brief	Searches the library for a pattern, but only among specific resource types.
+		 *
+		 * @param	pattern	Pattern to search for. Use wildcard * to match any character(s).
+		 * @param	typeIds	RTTI type IDs of the resource types we're interested in searching.
+		 *
+		 * @return	A list of entries matching the pattern.
+		 */
 		Vector<LibraryEntry*> search(const WString& pattern, const Vector<UINT32>& typeIds);
 
+		/**
+		 * @brief	Finds the resource meta file for a resource with the specified UUID.
+		 *
+		 * @param	uuid	UUID of the resource to look for.
+		 *
+		 * @return	Resource meta data if found, null otherwise.
+		 */
 		ProjectResourceMetaPtr findResourceMeta(const String& uuid) const;
+
+		/**
+		 * @brief	Returns resource path based on its UUID.
+		 *
+		 * @param	uuid	UUID of the resource to look for.
+		 *
+		 * @return	Absolute path to the resource.
+		 */
 		Path uuidToPath(const String& uuid) const;
 
+		/**
+		 * @brief	Registers a new resource in the library.
+		 *
+		 * @param	resource	Resource instance to add to the library. A copy of the
+		 *						resource will be saved at the provided path.
+		 * @param	path		Absolute path to where to store the resource.
+		 */
 		void createEntry(const HResource& resource, const Path& path);
+
+		/**
+		 * @brief	Creates a new folder in the library.
+		 *
+		 * @param	path		Absolute path to where to store the folder.
+		 */
 		void createFolderEntry(const Path& path);
+
+		/**
+		 * @brief	Updates a resource that is already in the library.
+		 */
 		void saveEntry(const HResource& resource);
+
+		/**
+		 * @brief	Moves a library entry from one path to another.
+		 *
+		 * @param	oldPath		Source path of the entry, absolute or relative to resources folder.
+		 * @param	newPath		Destination path of the entry, absolute or relative to resources folder.
+		 * @param	overwrite	If an entry already exists at the destination path, should it be overwritten.
+		 */
 		void moveEntry(const Path& oldPath, const Path& newPath, bool overwrite = true);
+
+		/**
+		 * @brief	Copies a library entry from one path to another.
+		 *
+		 * @param	oldPath		Source path of the entry, absolute or relative to resources folder.
+		 * @param	newPath		Destination path of the entry, absolute or relative to resources folder.
+		 * @param	overwrite	If an entry already exists at the destination path, should it be overwritten.
+		 */
 		void copyEntry(const Path& oldPath, const Path& newPath, bool overwrite = true);
+
+		/**
+		 * @brief	Deletes an entry from the library.
+		 *
+		 * @param	path		Path of the entry, absolute or relative to resources folder.
+		 */
 		void deleteEntry(const Path& path);
+
+		/**
+		 * @brief	Triggers a reimport of a resource using the provided import options, if needed.
+		 *
+		 * @param	path			Path to the resource to reimport, absolute or relative to resources folder.
+		 * @param	importOptions	Optional import options to use when importing the resource. Caller must ensure the
+		 *							import options are of the correct type for the resource in question. If null is provided
+		 *							default import options are used.
+		 * @param	forceReimport	Should the resource be reimported even if we detect no changes. This should be true
+		 *							if import options changed since last import.
+		 */
 		void reimport(const Path& path, const ImportOptionsPtr& importOptions = nullptr, bool forceReimport = false);
+
+		/**
+		 * @brief	Loads a resource at the specified path, synchronously.
+		 *
+		 * @param	path	Path of the resource, absolute or relative to resources folder.
+		 *
+		 * @return	Loaded resource, or null handle if one is not found.
+		 */
 		HResource load(const Path& path);
 
+		/**
+		 * @brief	Returns the path to the project's resource folder where all
+		 *			the assets are stored.
+		 */
 		const Path& getResourcesFolder() const { return mResourcesFolder; }
 
-		Event<void(const Path&)> onEntryRemoved;
-		Event<void(const Path&)> onEntryAdded;
+		Event<void(const Path&)> onEntryRemoved; /**< Triggered whenever an entry is removed from the library. Path provided is absolute. */
+		Event<void(const Path&)> onEntryAdded; /**< Triggered whenever an entry is added to the library. Path provided is absolute. */
 	private:
-		static const Path RESOURCES_DIR;
-		static const Path INTERNAL_RESOURCES_DIR;
-		static const WString LIBRARY_ENTRIES_FILENAME;
-		static const WString RESOURCE_MANIFEST_FILENAME;
-
-		ResourceManifestPtr mResourceManifest;
-		DirectoryEntry* mRootEntry;
-		Path mProjectFolder;
-		Path mResourcesFolder;
-
-		UnorderedMap<Path, Vector<Path>> mDependencies;
-		UnorderedSet<Path> mReimportQueue;
-
+		/**
+		 * @brief	Saves all the project library data so it may be restored later,
+		 *			at the default save location in the project folder.
+		 */
 		void save();
+
+		/**
+		 * @brief	Loads previously saved project library data from the default save 
+		 *			location in the project folder. Nothing is loaded if it doesn't
+		 *			exist.
+		 */
 		void load();
 
+		/**
+		 * @brief	Common code for adding a new resource entry to the library.
+		 *
+		 * @param	parent			Parent of the new entry.
+		 * @param	filePath		Absolute path to the resource.
+		 * @param	importOptions	Optional import options to use when importing the resource. Caller must ensure the
+		 *							import options are of the correct type for the resource in question. If null is provided
+		 *							default import options are used.
+		 * @param	forceReimport	Should the resource be reimported even if we detect no changes. This should be true
+		 *							if import options changed since last import.
+		 *
+		 * @return	Newly added resource entry.
+		 */
 		ResourceEntry* addResourceInternal(DirectoryEntry* parent, const Path& filePath, const ImportOptionsPtr& importOptions = nullptr, bool forceReimport = false);
+
+		/**
+		 * @brief	Common code for adding a new folder entry to the library.
+		 *
+		 * @param	parent	Parent of the new entry.
+		 * @param	dirPath	Absolute path to the directory.
+		 *
+		 * @return	Newly added directory entry.
+		 */
 		DirectoryEntry* addDirectoryInternal(DirectoryEntry* parent, const Path& dirPath);
 
+		/**
+		 * @brief	Common code for deleting a resource from the library. This code only removes
+		 *			the library entry, not the actual resource file.
+		 *
+		 * @param	resource	Entry to delete.
+		 */
 		void deleteResourceInternal(ResourceEntry* resource);
+
+		/**
+		 * @brief	Common code for deleting a directory from the library. This code only removes
+		 *			the library entry, not the actual directory.
+		 *
+		 * @param	resource	Entry to delete.
+		 */
 		void deleteDirectoryInternal(DirectoryEntry* directory);
 
+		/**
+		 * @brief	Triggers a reimport of a resource using the provided import options, if needed. Doesn't import dependencies.
+		 *
+		 * @param	path			Absolute Path to the resource to reimport.
+		 * @param	importOptions	Optional import options to use when importing the resource. Caller must ensure the
+		 *							import options are of the correct type for the resource in question. If null is provided
+		 *							default import options are used.
+		 * @param	forceReimport	Should the resource be reimported even if we detect no changes. This should be true
+		 *							if import options changed since last import.
+		 */
 		void reimportResourceInternal(ResourceEntry* resource, const ImportOptionsPtr& importOptions = nullptr, bool forceReimport = false);
 
+		/**
+		 * @brief	Creates a full hierarchy of directory entries up to the provided directory, if any are needed.
+		 *
+		 * @param	fullPath			Absolute path to a directory we are creating the hierarchy to.
+		 * @param	newHierarchyRoot	First directory entry that already existed in our hierarchy.
+		 * @param	newHierarchyLeaf	Leaf entry corresponding to the exact entry at \p path.
+		 */
 		void createInternalParentHierarchy(const Path& fullPath, DirectoryEntry** newHierarchyRoot, DirectoryEntry** newHierarchyLeaf);
 
+		/**
+		 * @brief	Checks has the resource been modified since the last import.
+		 */
 		bool isUpToDate(ResourceEntry* resource) const;
+
+		/**
+		 * @brief	Returns a path to a .meta file based on the resource path.
+		 *
+		 * @param	path	Absolute path to the resource.
+		 *
+		 * @return	Path to the .meta file.
+		 */
 		Path getMetaPath(const Path& path) const;
+		
+		/**
+		 * @brief	Checks does the path represent a .meta file.
+		 */
 		bool isMeta(const Path& fullPath) const;
 
+		/**
+		 * @brief	Triggered whenever a library entry is removed.
+		 */
 		void doOnEntryRemoved(const LibraryEntry* entry);
+
+		/**
+		 * @brief	Triggered whenever a library entry is added.
+		 */
 		void doOnEntryAdded(const LibraryEntry* entry);
 
+		/**
+		 * @brief	Returns a set of resource paths that are dependent on the provided
+		 *			resource entry. (e.g. a shader file might be dependent on shader include file).
+		 */
 		Vector<Path> getImportDependencies(const ResourceEntry* entry);
+
+		/**
+		 * @brief	Registers any import dependencies for the specified resource.
+		 */
 		void addDependencies(const ResourceEntry* entry);
+
+		/**
+		 * @brief	Removes any import dependencies for the specified resource.
+		 */
 		void removeDependencies(const ResourceEntry* entry);
 
+		/**
+		 * @brief	Finds dependants resource for the specified resource entry and queues
+		 *			them for reimport next frame.
+		 */
 		void queueDependantForReimport(const ResourceEntry* entry);
+
+		static const Path RESOURCES_DIR;
+		static const Path INTERNAL_RESOURCES_DIR;
+		static const WString LIBRARY_ENTRIES_FILENAME;
+		static const WString RESOURCE_MANIFEST_FILENAME;
+
+		ResourceManifestPtr mResourceManifest;
+		DirectoryEntry* mRootEntry;
+		Path mProjectFolder;
+		Path mResourcesFolder;
+
+		UnorderedMap<Path, Vector<Path>> mDependencies;
+		UnorderedSet<Path> mReimportQueue;
 	};
 }

BansheeEditor/Include/BsProjectLibraryEntries.h

@@ -6,6 +6,11 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains a list of entries used by the ProjectLibrary. Used primarily
+	 *			for serialization purposes, i.e. persisting ProjectLibrary state
+	 *			between application runs.
+	 */
 	class ProjectLibraryEntries : public IReflectable
 	{
 		struct ConstructPrivately { };
@@ -14,8 +19,16 @@ namespace BansheeEngine
 		explicit ProjectLibraryEntries(const ConstructPrivately& dummy);
 		ProjectLibraryEntries(const ProjectLibrary::DirectoryEntry& rootEntry);
 
+		/**
+		 * @brief	Creates new project library entries based on a ProjectLibrary root directory entry.
+		 *
+		 * @param	rootEntry	Root directory entry in ProjectLibrary.
+		 */
 		static std::shared_ptr<ProjectLibraryEntries> create(const ProjectLibrary::DirectoryEntry& rootEntry);
 		
+		/**
+		 * @brief	Returns the root directory entry that references the entire entry hierarchy.
+		 */
 		const ProjectLibrary::DirectoryEntry& getRootEntry() const { return mRootEntry; }
 
 	private:
@@ -24,11 +37,16 @@ namespace BansheeEngine
 		/************************************************************************/
 		/* 								SERIALIZATION                      		*/
 		/************************************************************************/
+
+		/**
+		 * @brief	Creates new empty project library entries object. Used for serialization
+		 *			purposes.
+		 */
 		static std::shared_ptr<ProjectLibraryEntries> createEmpty();
 
 	public:
 		friend class ProjectLibraryEntriesRTTI;
 		static RTTITypeBase* getRTTIStatic();
-		virtual RTTITypeBase* getRTTI() const;
+		virtual RTTITypeBase* getRTTI() const override;
 	};
 }