Documentation

BansheeEditor/Include/BsCodeEditor.h

@@ -8,12 +8,20 @@ namespace BansheeEngine
 	class CodeEditor;
 	class CodeEditorFactory;
 
+	/**
+	 * @brief	Contains data about a reference to a 
+	 *			project in an external editor solution.
+	 */
 	struct BS_ED_EXPORT CodeProjectReference
 	{
 		WString name;
 		Path path;
 	};
 
+	/**
+	 * @brief	Contains data about a single project
+	 *			in an external editor solution.
+	 */
 	struct BS_ED_EXPORT CodeProjectData
 	{
 		WString name;
@@ -24,25 +32,60 @@ namespace BansheeEngine
 		Vector<CodeProjectReference> projectReferences;
 	};
 
+	/**
+	 * @brief	Contains data about an external editor solution,
+	 *			including all projects contained.
+	 */
 	struct BS_ED_EXPORT CodeSolutionData
 	{
 		WString name;
 		Vector<CodeProjectData> projects;
 	};
 
+	/**
+	 * @brief	Handles connectivity of the editor with external code editing tools.
+	 *			The system provides methods for interacting with external tools but
+	 *			the exact tool used depends on the currently active setting.
+	 */
 	class BS_ED_EXPORT CodeEditorManager : public Module<CodeEditorManager>
 	{
 	public:
 		CodeEditorManager();
 		~CodeEditorManager();
 
+		/**
+		 * @brief	Returns a list of all available code editors for this platform.
+		 */
 		const Vector<CodeEditorType>& getAvailableEditors() const { return mEditors; }
+
+		/**
+		 * @brief	Changes the active code editor. All further operations on this object will
+		 *			be executed using this editor. If the specified editor is not valid for this
+		 *			platform, no change will be made.
+		 */
 		void setActive(CodeEditorType editor);
 
+		/**
+		 * @brief	Opens a code file in the active external editor. 
+		 *
+		 * @param	path		Path to the code file to open, can be absolute or relative to project folder.
+		 *						The file should be part of a solution in the active editor.
+		 * @param	lineNumber	Line number to focus on once the file is opened. Might not be supported by all
+		 *						editors.
+		 */
 		void openFile(const Path& path, UINT32 lineNumber) const;
+
+		/**
+		 * @brief	Synchronizes all code files and assemblies in the active project and updates 
+		 *			the project solution for the active editor. Each project can only have one solution
+		 *			per editor.
+		 */
 		void syncSolution() const;
 
 	private:
+		/**
+		 * @brief	Returns the absolute path at which the external editor solution file should be stored.
+		 */
 		Path getSolutionPath() const;
 
 		CodeEditor* mActiveEditor;
@@ -51,17 +94,48 @@ namespace BansheeEngine
 		Vector<CodeEditorFactory*> mFactories;
 	};
 
+	/**
+	 * @brief	Interface that classes interacting with external code editors needs to implement.
+	 *
+	 * @see		CodeEditorManager
+	 */
 	class BS_ED_EXPORT CodeEditor
 	{
 	public:
+		virtual ~CodeEditor() { }
+
+		/**
+		 * @copydoc	CodeEditorManager::openFile
+		 */
 		virtual void openFile(const Path& solutionPath, const Path& path, UINT32 lineNumber) const = 0;
+
+		/**
+		 * @copydoc	CodeEditorManager::syncSolution
+		 */
 		virtual void syncSolution(const CodeSolutionData& data, const Path& outputPath) const = 0;
 	};
 
+	/**
+	 * @brief	Interface for factory that creates a specific implementation(s) of a code editor.
+	 *
+	 * @see		CodeEditor
+	 */
 	class BS_ED_EXPORT CodeEditorFactory
 	{
 	public:
+		virtual ~CodeEditorFactory() { }
+
+		/**
+		 * @brief	Returns a list of code editors supported by this factory.
+		 */
 		virtual const Vector<CodeEditorType>& getAvailableEditors() const = 0;
+
+		/**
+		 * @brief	Creates a specific implementation of a code editor.
+		 *
+		 * @param	editor	Type of editor to create. Make sure to provide a valid value
+		 *					returned by "getAvailableEditors".
+		 */
 		virtual CodeEditor* create(CodeEditorType editor) const = 0;
 	};
 }

BansheeEditor/Include/BsEditorPrerequisites.h

@@ -78,6 +78,10 @@ namespace BansheeEngine
 	static const char* SCRIPT_EDITOR_ASSEMBLY = "MScriptEditor";
 	static const Path INTERNAL_ASSEMBLY_PATH = "Internal//Assemblies//";
 
+	/**
+	 * @brief	Types of drag and drop operations. Different types specify
+	 *			different types of dragged data.
+	 */
 	enum class DragAndDropType
 	{
 		EditorWidget = 10000,
@@ -85,6 +89,11 @@ namespace BansheeEngine
 		Resources = 10002
 	};
 
+	/**
+	 * @brief	Recognized types of external code editors.
+	 *
+	 * @see		CodeEditorManager
+	 */
 	enum class CodeEditorType
 	{
 		VS2008,
@@ -94,6 +103,9 @@ namespace BansheeEngine
 		VS2015
 	};
 
+	/**
+	 * @brief	Type IDs used by the RTTI system for the editor library.
+	 */
 	enum TypeID_BansheeEditor
 	{
 		TID_ProjectResourceMeta = 40000,

BansheeEditor/Include/Win32/BsVSCodeEditor.h

@@ -5,6 +5,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Recognized types of Microsoft Visual Studio versions
+	 *			recognized by VSCodeEditor.
+	 */
 	enum class VisualStudioVersion
 	{
 		VS2008,
@@ -14,12 +18,22 @@ namespace BansheeEngine
 		VS2015
 	};
 
+	/**
+	 * @brief	Code editor implementation that handles interacting with Microsoft Visual Studio.
+	 */
 	class BS_ED_EXPORT VSCodeEditor : public CodeEditor
 	{
 	public:
 		VSCodeEditor(VisualStudioVersion version, const Path& execPath, const WString& CLSID);
 
+		/**
+		 * @copydoc	CodeEditor::openFile
+		 */
 		void openFile(const Path& solutionPath, const Path& filePath, UINT32 lineNumber) const override;
+
+		/**
+		 * @copydoc	CodeEditor::syncSolution
+		 */
 		void syncSolution(const CodeSolutionData& data, const Path& outputPath) const override;
 
 	private:
@@ -28,15 +42,29 @@ namespace BansheeEngine
 		WString mCLSID;
 	};
 
+	/**
+	 * @brief	Code editor factory used for creating specific instances 
+	 *			of the Visual Studio code editor object.
+	 */
 	class BS_ED_EXPORT VSCodeEditorFactory : public CodeEditorFactory
 	{
 	public:
 		VSCodeEditorFactory();
 
+		/**
+		 * @copydoc	CodeEditorFactory::getAvailableEditors
+		 */
 		const Vector<CodeEditorType>& getAvailableEditors() const override { return mAvailableEditors; }
+
+		/**
+		 * @copydoc	CodeEditorFactory::create
+		 */
 		CodeEditor* create(CodeEditorType editor) const override;
 
 	private:
+		/**
+		 * @brief	Contains detailed information about a specific Visual Studio version.
+		 */
 		struct VSVersionInfo
 		{
 			WString name;
@@ -45,6 +73,9 @@ namespace BansheeEngine
 			VisualStudioVersion version;
 		};
 
+		/**
+		 * @brief	Returns a list of Visual Studio versions installed on this machine.
+		 */
 		Map<CodeEditorType, VSVersionInfo> getAvailableVersions() const;
 
 		Map<CodeEditorType, VSVersionInfo> mAvailableVersions;

BansheeEditor/Source/Win32/BsVSCodeEditor.cpp

@@ -11,6 +11,14 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Reads a string value from the specified key in the registry.
+	 * 
+	 * @param	key				Registry key to read from.
+	 * @param	name			Identifier of the value to read from.
+	 * @param	value			Output value read from the key.
+	 * @param	defaultValue	Default value to return if the key or identifier doesn't exist.
+	 */
 	LONG getRegistryStringValue(HKEY hKey, const WString& name, WString& value, const WString& defaultValue)
 	{
 		value = defaultValue;
@@ -24,6 +32,9 @@ namespace BansheeEngine
 		return result;
 	}
 
+	/**
+	 * @brief	Contains data about a Visual Studio project.
+	 */
 	struct VSProjectInfo
 	{
 		WString GUID;
@@ -31,21 +42,35 @@ namespace BansheeEngine
 		Path path;
 	};
 
+	/**
+	 * @brief	Contains various helper classes for interacting with a Visual Studio instance
+	 *			running on this machine.
+	 */
 	class VisualStudio
 	{
 	private:
-		static const String SLN_TEMPLATE;
-		static const String PROJ_ENTRY_TEMPLATE;
-		static const String PROJ_PLATFORM_TEMPLATE;
+		static const String SLN_TEMPLATE; /**< Template text used for a solution file. */
+		static const String PROJ_ENTRY_TEMPLATE; /**< Template text used for a project entry in a solution file. */
+		static const String PROJ_PLATFORM_TEMPLATE; /**< Template text used for platform specific information for a project entry in a solution file. */
 
-		static const String PROJ_TEMPLATE;
-		static const String REFERENCE_ENTRY_TEMPLATE;
-		static const String REFERENCE_PROJECT_ENTRY_TEMPLATE;
-		static const String REFERENCE_PATH_ENTRY_TEMPLATE;
-		static const String CODE_ENTRY_TEMPLATE;
-		static const String NON_CODE_ENTRY_TEMPLATE;
+		static const String PROJ_TEMPLATE; /**< Template XML used for a project file. */
+		static const String REFERENCE_ENTRY_TEMPLATE; /**< Template XML used for a reference to another assembly entry by name. */
+		static const String REFERENCE_PROJECT_ENTRY_TEMPLATE; /**< Template XML used for a reference to another project entry. */
+		static const String REFERENCE_PATH_ENTRY_TEMPLATE; /**< Template XML used for a reference to another assembly entry by name and path. */
+		static const String CODE_ENTRY_TEMPLATE; /**< Template XML used for a single code file entry in a project. */
+		static const String NON_CODE_ENTRY_TEMPLATE; /**< Template XML used for a single non-code file entry in a project. */
 
 	public:
+		/**
+		 * @brief	Scans the running processes to find a running Visual Studio instance with the specified
+		 *			version and open solution.
+		 *
+		 * @param	clsID			Class ID of the specific Visual Studio version we are looking for.
+		 * @param	solutionPath	Path to the solution the instance needs to have open.
+		 *
+		 * @returns	DTE object that may be used to interact with the Visual Studio instance, or null if
+		 *			not found.
+		 */
 		static CComPtr<EnvDTE::_DTE> findRunningInstance(const CLSID& clsID, const Path& solutionPath)
 		{
 			CComPtr<IRunningObjectTable> runningObjectTable = nullptr;
@@ -96,6 +121,12 @@ namespace BansheeEngine
 			return nullptr;
 		}
 
+		/**
+		 * @brief	Opens a new Visual Studio instance of the specified version with the provided solution.
+		 *
+		 * @param	clsID			Class ID of the specific Visual Studio version to start.
+		 * @param	solutionPath	Path to the solution the instance needs to open.
+		 */
 		static CComPtr<EnvDTE::_DTE> openInstance(const CLSID& clsid, const Path& solutionPath)
 		{
 			CComPtr<IUnknown> newInstance = nullptr;
@@ -133,6 +164,13 @@ namespace BansheeEngine
 			return nullptr;
 		}
 
+		/**
+		 * @brief	Opens a file on a specific line in a running Visual Studio instance.
+		 *
+		 * @param	dte			DTE object retrieved from "findRunningInstance" or "openInstance".
+		 * @param	filePath	Path of the file to open. File should be a part of the VS solution.
+		 * @param	line		Line on which to focus Visual Studio after the file is open.
+		 */
 		static bool openFile(CComPtr<EnvDTE::_DTE> dte, const Path& filePath, UINT32 line)
 		{
 			// Open file
@@ -175,6 +213,9 @@ namespace BansheeEngine
 			return true;
 		}
 
+		/**
+		 * @brief	Generates a Visual Studio project GUID from the project name.
+		 */
 		static String getProjectGUID(const WString& projectName)
 		{
 			static const String guidTemplate = "{0}-{1}-{2}-{3}-{4}";
@@ -187,6 +228,16 @@ namespace BansheeEngine
 			return output;
 		}
 
+		/**
+		 * @brief	Builds the Visual Studio solution text (.sln) for the provided version, 
+		 *			using the provided solution data.
+		 *
+		 * @param	version	Visual Studio version for which we're generating the solution file.
+		 * @param	data	Data containing a list of projects and other information required to 
+		 *					build the solution text.
+		 *
+		 * @returns	Generated text of the solution file.
+		 */
 		static String writeSolution(VisualStudioVersion version, const CodeSolutionData& data)
 		{
 			struct VersionData
@@ -220,6 +271,16 @@ namespace BansheeEngine
 			return StringUtil::format(SLN_TEMPLATE, versionData[version].formatVersion, projectEntries, projectPlatforms);
 		}
 
+		/**
+		 * @brief	Builds the Visual Studio project text (.csproj) for the provided version, 
+		 *			using the provided project data.
+		 *
+		 * @param	version		Visual Studio version for which we're generating the project file.
+		 * @param	projectData	Data containing a list of files, references and other information required to 
+		 *						build the project text.
+		 *
+		 * @returns	Generated text of the project file.
+		 */
 		static String writeProject(VisualStudioVersion version, const CodeProjectData& projectData)
 		{
 			struct VersionData