More documentation

BansheeMono/Include/BsMonoAssembly.h

@@ -6,9 +6,16 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains information about a single Mono (i.e. managed) assembly
+	 */
 	class BS_MONO_EXPORT MonoAssembly
 	{
 	public:
+		/**
+		 * @brief	Used for uniquely identifying a managed class, normally for use
+		 *			in containers.
+		 */
 		struct ClassId
 		{
 			struct Hash
@@ -32,10 +39,26 @@ namespace BansheeEngine
 	public:
 		virtual ~MonoAssembly();
 
+		/**
+	     * @brief	Attempts to find a managed class with the specified namespace and name
+		 *			in this assembly. Returns null if one cannot be found.
+	     */
 		MonoClass* getClass(const String& namespaceName, const String& name) const;
+
+		/**
+		 * @brief	Converts an internal mono representation of a class into engine class.
+		 */
 		MonoClass* getClass(::MonoClass* rawMonoClass) const;
+
+		/**
+		 * @brief	Returns a list of all classes in the assembly.
+		 */
 		const Vector<MonoClass*>& getAllClasses() const;
 
+		/**
+	     * @brief	Invokes a zero-parameter static method in the format
+		 *			"Class::Method". Used primarily for invoking an assembly entry point.
+	     */
 		void invoke(const String& functionName);
 
 	private:
@@ -43,10 +66,28 @@ namespace BansheeEngine
 
 		MonoAssembly();
 
+		/**
+		 * @brief	Loads an assembly from the specified path.
+		 */
 		void load(const String& path, const String& name);
+
+		/**
+		 * @brief	Loads an assembly from an internal mono image.
+		 */
 		void loadAsDependency(MonoImage* image, const String& name);
+
+		/**
+		 * @brief	Unloads the assembly and all the types associated with it.
+		 *			Caller must ensure not to use any types from this assembly after
+		 *			it has been unloaded.
+		 */
 		void unload();
 
+		/**
+	     * @brief	Returns true if the provided name represents a generic class.
+		 *
+		 * @note	This method only analyzes the name to determine if it is in generic class format.
+	     */
 		bool isGenericClass(const String& name) const;
 
 		String mName;

BansheeMono/Include/BsMonoClass.h

@@ -5,8 +5,15 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains information about a single Mono (i.e. managed) class.
+	 */
 	class BS_MONO_EXPORT MonoClass
 	{
+		/**
+		 * @brief	Used for uniquely identifying a method in a managed class, normally for use
+		 *			in containers.
+		 */
 		struct MethodId
 		{
 			struct Hash
@@ -28,21 +35,59 @@ namespace BansheeEngine
 	public:
 		~MonoClass();
 
+		/**
+		 * @brief	Returns the namespace of this class.
+		 */
 		const String& getNamespace() const { return mNamespace; }
+
+		/**
+		 * @brief	Returns the type name of this class.
+		 */
 		const String& getTypeName() const { return mTypeName; }
+
+		/**
+		 * @brief	Returns the full name (Namespace::TypeName) of this class.
+		 */
 		const String& getFullName() const { return mFullName; }
 
+		/**
+		 * @brief	Returns an object referencing a method with the specified name and number of parameters.
+		 *			If the method is overloaded then you should use "getMethodExact". Throws an exception
+		 *			if method cannot be found.
+		 *			Does not query base class methods.
+		 */
 		MonoMethod& getMethod(const String& name, UINT32 numParams = 0);
 
+		/**
+		 * @brief	Returns an object referencing a field with the specified name.
+		 *			Does not query base class fields.
+		 *			Returns null if field cannot be found.
+		 */
 		MonoField* getField(const String& name) const;
+
+		/**
+		 * @brief	Returns an object referencing a property with the specified name.
+		 *			Does not query base class properties.
+		 *			Throws an exception if the property cannot be found.
+		 */
 		MonoProperty& getProperty(const String& name);
+
+		/**
+		 * @brief	Returns an instance of an attribute of the specified "monoClass" that is part
+		 *			of this class. Returns null if this class type does not have that type of attribute.
+		 */
 		MonoObject* getAttribute(MonoClass* monoClass) const;
+
+		/**
+		 * @brief	Returns the base class of this class. Null if this class has no base.
+		 */
 		MonoClass* getBaseClass() const;
 
 		/**
-		 * @brief	Retrieves a method, expects exact method name with parameters.
+		 * @brief	Returns an object referencing a method, expects exact method name with parameters.
+		 *			Does not query base class methods.
 		 *
-		 * @note	Example: Name = "CreateInstance", Signature = "type,int[]"
+		 * @note	Example: name = "CreateInstance", signature = "Vector2,int[]"
 		 */
 		MonoMethod* getMethodExact(const String& name, const String& signature);
 
@@ -53,22 +98,92 @@ namespace BansheeEngine
 		 */
 		const Vector<MonoField*> getAllFields() const;
 
+		/**
+		 * @brief	Check if this class has an attribute of the type "monoClass".
+		 */
 		bool hasAttribute(MonoClass* monoClass) const;
+
+		/**
+		 * @brief	Check if this class has a field with the specified name. Does not
+		 *			check base classes.
+		 */
 		bool hasField(const String& name) const;
+
+		/**
+		 * @brief	Checks if this class is a sub class of the specified class.
+		 */
 		bool isSubClassOf(const MonoClass* monoClass) const;
+
+		/**
+		 * @brief	Checks is the provided object instance of this class' type.
+		 */
 		bool isInstanceOfType(MonoObject* object) const;
 
+		/**
+		 * @brief	Shortcut for invoking a method on a class. Invokes a method with the provided name
+		 *			and number of parameters.
+		 *
+		 * @param	name		Name of the method to invoke (no parameter list or brackets.
+		 * @param	instance	Object instance on invoke the method on. Null if method is static.
+		 * @param	params		Array containing pointers to method parameters. Array length must be equal to number of parameters. 
+		 *						Can be null if method has no parameters. For value types parameters should be pointers to the values 
+		 *						and for reference types they should be pointers to MonoObject.
+		 * @param	numParams	Number of parameters the method accepts.
+		 *
+		 * @note	You cannot use this to call overloaded methods that have the same number of parameters. Use "getMethodExact" and then
+		 *			invoke the method from the returned method object.
+		 */
 		MonoObject* invokeMethod(const String& name, MonoObject* instance = nullptr, void** params = nullptr, UINT32 numParams = 0);
+
+		/**
+		 * @brief	Hooks up an internal call that will trigger the provided method callback when the managed method with the
+		 *			specified name is called. If name is not valid this will silently fail.
+		 */
 		void addInternalCall(const String& name, const void* method);
 
+		/**
+		 * @brief	Returns the internal mono representation of the class.
+		 */
 		::MonoClass* _getInternalClass() const { return mClass; }
 
+		/**
+		 * @brief	Creates a new instance of this class and optionally constructs it.
+		 *			If you don't construct the instance then you should invoke the ".ctor" method manually
+		 *			afterwards.
+		 */
 		MonoObject* createInstance(bool construct = true) const;
+
+		/**
+		 * @brief	Creates a new instance of this class and then constructs it using the constructor
+		 *			with the specified number of parameters.
+		 *
+		 * @param	params		Array containing pointers to constructor parameters. Array length must be equal to number of parameters. 
+		 * @param	numParams	Number of parameters the constructor accepts.
+		 *
+		 * @note	If the class have multiple constructors with the same number of parameters use the other "createInstance" overload
+		 *			that allows you to provide exact signature.
+		 */
 		MonoObject* createInstance(void** params, UINT32 numParams);
+
+		/**
+		 * @brief	Creates a new instance of this class and then constructs it using the constructor
+		 *			with the specified signature.
+		 *
+		 * @param	ctorSignature	Method signature. Example: "Vector2,int[]"
+		 * @param	params			Array containing pointers to constructor parameters. Array length must be equal to number of parameters. 
+		 */
 		MonoObject* createInstance(const String& ctorSignature, void** params);
 	private:
 		friend class MonoAssembly;
 
+		/**
+		 * @brief	Constructs a new mono class object.
+		 * 
+		 * @param	ns				Namespace the class belongs to.
+		 * @param	type			Type name of the class.
+		 * @param	monoClass		Internal mono class.
+		 * @param	parentAssembly	Assembly to which this class belongs.
+		 */
 		MonoClass(const String& ns, const String& type, ::MonoClass* monoClass, const MonoAssembly* parentAssembly);
 
 		const MonoAssembly* mParentAssembly;

BansheeMono/Include/BsMonoField.h

@@ -6,6 +6,9 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Returns the level of field visibility in the class.
+	 */
 	enum class MonoFieldVisibility
 	{
 		Private,
@@ -15,20 +18,68 @@ namespace BansheeEngine
 		Public
 	};
 
+	/**
+	 * @brief	Encapsulates information about a single Mono (i.e. managed) field
+	 *			belonging to some managed class. This object also allows you to set
+	 *			or retrieve values to/from specific instances containing the field.
+	 */
 	class BS_MONO_EXPORT MonoField
 	{
 	public:
+		/**
+		 * @brief	Returns the name of the field.
+		 */
 		const String& getName() const { return mName; }
+
+		/**
+		 * @brief	Returns the class representing the type of data the field holds.
+		 */
 		MonoClass* getType();
 
+		/**
+		 * @brief	Retrieves value currently set in the field on the specified object instance.
+		 *			If field is static object instance can be null. 
+		 *
+		 * @note	Value will be a pointer to raw data type for value types (e.g. int, float), and a MonoObject*
+		 *			for reference types.
+		 */
 		void getValue(MonoObject* instance, void* outValue);
+
+		/**
+		 * @brief	Retrieves value currently set in the field on the specified object instance.
+		 *			If field is static object instance can be null. If returned value is a value
+		 *			type it will be boxed.
+		 */
 		MonoObject* getValueBoxed(MonoObject* instance);
+
+		/**
+		 * @brief	Sets a value for the field on the specified object instance.
+		 *			If field is static object instance can be null. 
+		 *
+		 * @note	Value should be a pointer to raw data type for value types (e.g. int, float), and a MonoObject*
+		 *			for reference types.
+		 */
 		void setValue(MonoObject* instance, void* value);
 
+		/**
+		 * @brief	Checks if field has an attribute if the specified type.
+		 */
 		bool hasAttribute(MonoClass* monoClass);
+
+		/**
+		 * @brief	Returns an instance of an attribute of the specified type. Returns null
+		 *			if the field doesn't have such an attribute.
+		 */
 		MonoObject* getAttribute(MonoClass* monoClass);
 
+		/**
+		 * @brief	Returns field visibility in the class.
+		 */
 		MonoFieldVisibility getVisibility();
+
+		/**
+		 * @brief	Query if the field is static.
+		 */
 		bool isStatic();
 
 	private:

BansheeMono/Include/BsMonoManager.h

@@ -16,7 +16,19 @@ namespace BansheeEngine
 		MonoManager();
 		~MonoManager();
 
+		/**
+		 * @brief	Loads a new assembly from the provided path.
+		 *
+		 * @param	path	Absolute path to the assembly .dll.
+		 * @param	name	Unique name for the assembly.
+		 */
 		MonoAssembly& loadAssembly(const String& path, const String& name);
+
+		/**
+		 * @brief	Unloads a previously loaded assembly.
+		 *
+		 * @note	You must perform JIT cleanup before unloading assemblies.
+		 */
 		void unloadAssembly(MonoAssembly& assembly);
 
 		/**
@@ -50,14 +62,30 @@ namespace BansheeEngine
 		 */
 		String getTypeName(MonoObject* obj);
 
+		/**
+		 * @brief	Returns the current Mono domains.
+		 */
 		MonoDomain* getDomain() const { return mDomain; }
+
+		/**
+		 * @brief	Attempts to find a previously loaded assembly with the specified name.
+		 *			Returns null if assembly cannot be found.
+		 */
 		MonoAssembly* getAssembly(const String& name) const;
 
+		/**
+		 * @brief	Registers a new script type. This should be done before any assembly loading is done.
+		 *			Upon assembly load these script types will be initialized with necessary information about their
+		 *			managed counterparts.
+		 */
 		static void registerScriptType(ScriptMeta* metaData);
 	private:
 		static const String MONO_LIB_DIR;
 		static const String MONO_ETC_DIR;
 
+		/**
+		 * @brief	Returns a list of all types that will be initializes with their assembly gets loaded.
+		 */
 		static UnorderedMap<String, Vector<ScriptMeta*>>& getTypesToInitialize()
 		{
 			static UnorderedMap<String, Vector<ScriptMeta*>> mTypesToInitialize;

BansheeMono/Include/BsMonoMethod.h

@@ -5,10 +5,42 @@
 
 namespace BansheeEngine
 {
+
+	/**
+	 * @brief	Encapsulates information about a single Mono (i.e. managed) method
+	 *			belonging to some managed class. This object also allows you to invoke
+	 *			the method.
+	 */
 	class BS_MONO_EXPORT MonoMethod
 	{
 	public:
+		
+		/**
+		 * @brief	Invokes the method on the provided object instance. 
+		 *			This does not respect polymorphism and will invoke the exact method
+		 *			of the class this object was retrieved from. Use "invokeVirtual" if you
+		 *			need polymorphism.
+		 *
+		 * @param	instance	Instance of the object to invoke the method on. Can be null for static methods.
+		 * @param	param		Array of parameters to pass to the method. Caller must ensure they match method 
+		 *						parameter count and type. For value types parameters should be pointers to the 
+		 *						values and for reference types they should be pointers to MonoObject.
+		 *
+		 @returns	A boxed return value, or null if method has no return value.
+		 */
 		MonoObject* invoke(MonoObject* instance, void** params);
+
+		/**
+		 * @brief	Invokes the method on the provided object instance. If the instance has an override of this
+		 *			method it will be called.
+		 *
+		 * @param	instance	Instance of the object to invoke the method on.
+		 * @param	param		Array of parameters to pass to the method. Caller must ensure they match method 
+		 *						parameter count and type. For value types parameters should be pointers to the 
+		 *						values and for reference types they should be pointers to MonoObject.
+		 *
+		 * @returns	A boxed return value, or null if method has no return value.
+		 */
 		MonoObject* invokeVirtual(MonoObject* instance, void** params);
 
 		/**
@@ -19,8 +51,16 @@ namespace BansheeEngine
 		 */
 		void* getThunk() const;
 
+		/**
+		 * @brief	Returns the name of the method.
+		 */
 		String getName() const;
 
+
+		/**
+		 * @brief	Returns the type of the return value. Returns null if method
+		 *			has no return value.
+		 */
 		MonoClass* getReturnType();
 
 	private:

BansheeMono/Include/BsMonoProperty.h

@@ -5,15 +5,57 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Encapsulates information about a single Mono (i.e. managed) property
+	 *			belonging to some managed class. This object also allows you to set
+	 *			or retrieve values to/from specific instances containing the property.
+	 */
 	class BS_MONO_EXPORT MonoProperty
 	{
 	public:
+		/**
+		 * @brief	Returns a boxed value contained in the property in the specified instance.
+		 *
+		 * @param	instance	Object instance to access the property on. Can be null for static properties.
+		 *
+		 * @returns	A boxed value of the property.
+		 */
 		MonoObject* get(MonoObject* instance) const;
+
+		/**
+		 * @brief	Sets a value of the property in the specified instance. 
+		 *
+		 * @param	instance	Object instance to access the property on. Can be null for static properties.
+		 * @param	value		Value to set on the property. For value type it should be a pointer to the 
+		 *						value and for reference type it should be a pointer to MonoObject.
+		 */
 		void set(MonoObject* instance, void* value) const;
 
-		MonoObject* getIndexed(MonoObject* instance, void* index) const;
-		void setIndexed(MonoObject* instance, void* index, void* value) const;
+		/**
+		 * @brief	Returns a boxed value contained in the property in the specified instance. Used for properties
+		 *			with indexers.
+		 *
+		 * @param	instance	Object instance to access the property on. Can be null for static properties.
+		 * @param	index		Index of the value to retrieve.
+		 *
+		 * @returns	A boxed value of the property.
+		 */
+		MonoObject* getIndexed(MonoObject* instance, UINT32 index) const;
+
+		/**
+		 * @brief	Sets a value of the property in the specified instance. Used for properties
+		 *			with indexers.
+		 *
+		 * @param	instance	Object instance to access the property on. Can be null for static properties.
+		 * @param	index		Index of the value to set.
+		 * @param	value		Value to set on the property. For value type it should be a pointer to the 
+		 *						value and for reference type it should be a pointer to MonoObject.
+		 */
+		void setIndexed(MonoObject* instance, UINT32 index, void* value) const;
 
+		/**
+		 * @brief	Returns the data type the property holds.
+		 */
 		MonoClass* getReturnType();
 	private:
 		friend class MonoClass;

BansheeMono/Include/BsMonoScriptManager.h

@@ -6,13 +6,23 @@
 
 namespace BansheeEngine 
 {
+	/**
+	 * @brief	Handles Mono and script system initialization and destruction.
+	 */
 	class BS_MONO_EXPORT MonoScriptSystem : public ScriptSystem
 	{
 	public:
 		MonoScriptSystem();
 		~MonoScriptSystem();
 
+		/**
+		 * @copydoc	ScriptSystem::initialize
+		 */
 		virtual void initialize();
+
+		/**
+		 * @copydoc	ScriptSystem::destroy
+		 */
 		virtual void destroy();
 
 	private:

BansheeMono/Include/BsMonoUtil.h

@@ -7,9 +7,16 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Utility class containing methods for various common Mono/Script related
+	 *			operations.
+	 */
 	class BS_MONO_EXPORT MonoUtil
 	{
 	public:
+		/**
+		 * @brief	Converts a Mono (i.e. managed) string to a native wide string.
+		 */
 		static WString monoToWString(MonoString* str)
 		{
 			if(str == nullptr)
@@ -25,6 +32,9 @@ namespace BansheeEngine
 			return ret;
 		}
 
+		/**
+		 * @brief	Converts a Mono (i.e. managed) string to a native narrow string.
+		 */
 		static String monoToString(MonoString* str)
 		{
 			if(str == nullptr)
@@ -40,21 +50,33 @@ namespace BansheeEngine
 			return ret;
 		}
 
+		/**
+		 * @brief	Converts a native wide string to a Mono (i.e. managed) string.
+		 */
 		static MonoString* wstringToMono(MonoDomain* domain, const WString& str)
 		{
 			return mono_string_from_utf16((mono_unichar2*)str.c_str());
 		}
 
+		/**
+		 * @brief	Converts a native narrow string to a Mono (i.e. managed) string.
+		 */
 		static MonoString* stringToMono(MonoDomain* domain, const String& str)
 		{
 			return wstringToMono(domain, toWString(str));
 		}
 
+		/**
+		 * @copydoc	throwIfException
+		 */
 		static void throwIfException(MonoException* exception)
 		{
 			throwIfException(reinterpret_cast<MonoObject*>(exception));
 		}
 
+		/**
+		 * @brief	Throws a native exception if the provided object is a valid managed exception.
+		 */
 		static void throwIfException(MonoObject* exception)
 		{
 			if(exception != nullptr)

BansheeMono/Include/BsScriptMeta.h

@@ -4,16 +4,19 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains information required for initializing and handling a single script class.
+	 */
 	struct BS_MONO_EXPORT ScriptMeta
 	{
 		ScriptMeta();
 		ScriptMeta(const String& assembly, const String& ns, const String& name, std::function<void()> initCallback);
 
-		String ns;
-		String name;
-		String assembly;
-		std::function<void()> initCallback;
-		MonoClass* scriptClass;							
-		MonoField* thisPtrField;	
+		String ns; /**< Namespace the script class is located in. */
+		String name; /**< Type name of the script class. */
+		String assembly; /**< Name of the assembly the script class is located in. */
+		std::function<void()> initCallback; /**< Callback that will be triggered when assembly containing the class is loaded. Used for one time initialization. */
+		MonoClass* scriptClass; /**< Class object describing the script class. Only valid after assembly containing this type was loaded. */			
+		MonoField* thisPtrField; /**< Field object that contains a pointer to the native instance of the script object. Only valid after assembly containing this type was loaded. */
 	};
 }

BansheeMono/Source/BsMonoProperty.cpp

@@ -23,17 +23,17 @@ namespace BansheeEngine
 		mono_runtime_invoke(mSetMethod, instance, args, nullptr);
 	}	
 
-	MonoObject* MonoProperty::getIndexed(MonoObject* instance, void* index) const
+	MonoObject* MonoProperty::getIndexed(MonoObject* instance, UINT32 index) const
 	{
 		void* args[1];
-		args[0] = index;
+		args[0] = &index;
 		return mono_runtime_invoke(mGetMethod, instance, args, nullptr);
 	}
 
-	void MonoProperty::setIndexed(MonoObject* instance, void* index, void* value) const
+	void MonoProperty::setIndexed(MonoObject* instance, UINT32 index, void* value) const
 	{
 		void* args[2];
-		args[0] = index;
+		args[0] = &index;
 		args[1] = value;
 		mono_runtime_invoke(mSetMethod, instance, args, nullptr);
 	}	

SBansheeEngine/Source/BsManagedSerializableList.cpp

@@ -81,7 +81,7 @@ namespace BansheeEngine
 
 	void ManagedSerializableList::setFieldData(UINT32 arrayIdx, const ManagedSerializableFieldDataPtr& val)
 	{
-		mItemProp->setIndexed(mManagedInstance, &arrayIdx, val->getValue(mListTypeInfo->mElementType));
+		mItemProp->setIndexed(mManagedInstance, arrayIdx, val->getValue(mListTypeInfo->mElementType));
 	}
 
 
@@ -94,7 +94,7 @@ namespace BansheeEngine
 
 	ManagedSerializableFieldDataPtr ManagedSerializableList::getFieldData(UINT32 arrayIdx)
 	{
-		MonoObject* obj = mItemProp->getIndexed(mManagedInstance, &arrayIdx);
+		MonoObject* obj = mItemProp->getIndexed(mManagedInstance, arrayIdx);
 
 		return ManagedSerializableFieldData::create(mListTypeInfo->mElementType, obj);
 	}