More work on documentation

Documentation/Manuals/Native/manuals.md

@@ -105,11 +105,13 @@ A set of manuals covering advanced functionality intented for those wanting to e
 - **Resources**
  - [Creating new resource types](@ref customResources)
  - [Creating custom importers](@ref customImporters)
+- **Scripting**
+ - [Exposing code to script API (automated)](@ref scriptingAuto)
+ - [TODO - Exposing code to script API (manual)](@ref scripting)
  
 ## General guides
 Name                                      | Description
 ------------------------------------------|-------------
-[Scripting](@ref scripting)               | Shows you how to interact with the scripting system, and how to expose C++ objects to the scripting API.
 [BSLFX](@ref bsl)    	  		  		  | Provides a reference for the Banshee Shading Language syntax.
 [Custom GUI elements](@ref customGUI)     | Shows you how to create custom GUI elements, manually render text or modify GUI system in a general way.
 [Meshes](@ref meshes)                     | Shows you how to create, use and manipulate meshes.

Documentation/Manuals/Native/scripting.md

@@ -2,50 +2,89 @@ Scripting									{#scripting}
 ===============
 [TOC]
 
-Often when you extend the native portion of the engine in some way you might want to expose that functionality to the managed (i.e. scripting) code. This guide will show you how to create C++ objects that communicate with C# code and vice versa. 
+In the previous chapter we talked about how to expose a C++ type to the scripting API by using the script binding generator tool. This tool ensures you can generate script bindings easily, but in some cases it is not robust enough and you must interact with the scripting API manually. This manual will explain how to interact with the scripting API and expose C++ code to it manually (without the script binding generator tool). 
 
-Before we delve into the specifics of Banshee's scripting you should understand how the scripting system works in general. All C# script code is ran from the C++ part of the engine using the Mono runtime. Mono runtime allows you to communicate with C# code (and for the C# code to communicate with C++), query class/method/field information and pass data between the two languages.
+You can use manual generation to achieve everything as with the script binding generator tool (in fact this tool uses the same API as described in this manual), plus a lot more. It is preferred you use automatic generation whenever possible, but when working with lower level systems that closely interact with the scripting system (like serialization, script compilation, etc.) you need more direct access.
 
-# Scripting system #	{#scripting_a}
+# Mono {#scripting_a}
+All C# script code is executed using the Mono runtime. Mono runtime allows you to communicate with C# code and vice-versa by invoking methods and querying class/method/field information. In this section we'll focus on how to interact with Mono (and therefore the C# runtime).
 
-Because using Mono directly is complex (mostly due to its lack of documentation), Banshee provides a set of easy to use wrappers for almost all of Mono related functionality. 
-
-BansheeMono is a plugin that wraps the functionality of the Mono runtime. The main entry point of the scripting system is the @ref bs::MonoManager "MonoManager" class which allows you to start the runtime and load managed (script) assemblies. The most important method here is @ref bs::MonoManager::loadAssembly "MonoManager::loadAssembly". It loads all the script code from the managed assembly at the provided path, and provides meta-data for the entire assembly through the returned @ref bs::MonoAssembly "MonoAssembly" object. 
+BansheeMono is a plugin that wraps the functionality of the Mono runtime. The main entry point of the scripting system is the @ref bs::MonoManager "MonoManager" class which allows you to start the runtime and load managed (script) assemblies. The most important method here is @ref bs::MonoManager::loadAssembly "MonoManager::loadAssembly()". It loads all the script code from the managed assembly (.dll) at the provided path, and provides meta-data for the entire assembly through the returned @ref bs::MonoAssembly "MonoAssembly" object. 
 
 ## MonoAssembly 	{#scripting_a_a}
-@ref bs::MonoAssembly "MonoAssembly" gives you access to all the script classes in an assembly. You can retrieve all clases using @ref bs::MonoAssembly::getAllClasses "MonoAssembly::getAllClasses", or retrieve a specific one by calling @ref bs::MonoAssembly::getClass(const String&, const String&) const "MonoAssembly::getClass(namespace, typename)". Both of these methods return a @ref bs::MonoClass "MonoClass" object.
+**MonoAssembly** gives you access to all the script classes in an assembly. You can retrieve all clases using @ref bs::MonoAssembly::getAllClasses "MonoAssembly::getAllClasses()", or retrieve a specific one by calling @ref bs::MonoAssembly::getClass(const String&, const String&) const "MonoAssembly::getClass(const String& namespace, const String& typename)". Both of these methods return a @ref bs::MonoClass "MonoClass" object.
 
 ## MonoClass 	{#scripting_a_b}
-@ref bs::MonoClass "MonoClass" gives you access to all methods, fields, properties and attributes of a specific class. It also allows you to register "internal" methods. These methods allow the managed code to call C++ code, and we'll go into them later.
+**MonoClass** gives you access to all methods, fields, properties and attributes of a specific class. It also allows you to register "internal" methods. These methods allow the managed code to call C++ code, and we'll go into them later.
+
+Classes also allow you to create object instances of their type. Use @ref bs::MonoClass::createInstance "MonoClass::createInstance()" to create a new object instance. This method returns a **MonoObject** instance, which is a C++ representation of the C# object, but more on them later. When creating an instance you may choose whether to construct it or not, and to provide constructor signature if you need a specific one.
+
+To retrieve a method from a class call @ref bs::MonoClass::getMethod() "MonoClass::getMethod()", accepting a name (without parameter types) and a number of parameters. If your method is overloaded you can use @ref bs::MonoClass::getMethodExact "MonoClass:getMethodExact()" which accepts a method name, and a comma separated list of parameter types. You may also use @ref bs::MonoClass::getAllMethods "MonoClass::getAllMethods()" to retrieve all methods in a class. All three of these methods return a @ref bs::MonoMethod "MonoMethod" object.
+
+
+
+
+TODO - Example getting a method
 
-Classes also allow you to create object instances of their type. Use @ref bs::MonoClass::createInstance "MonoClass::createInstance" to create a new object instance. All managed objects are referenced using a `MonoObject` type (more on that later), which is returned from the @ref bs::MonoClass::createInstance "MonoClass:createInstance" call. When creating an instance you may choose whether to construct it or not, and to provide constructor signature if you need a specific one.
 
-To retrieve a method from a class call @ref bs::MonoClass::getMethod() "MonoClass::getMethod()", accepting a name (without parameter types) and a number of parameters. If your method is overloaded you can use @ref bs::MonoClass::getMethodExact "MonoClass:getMethodExact()" which accepts a method name, and a comma separated list of parameter types. You may also use @ref bs::MonoClass::getAllMethods "MonoClass::getAllMethods" to retrieve all methods in a class.
 
-All the above methods return a @ref bs::MonoMethod "MonoMethod" object.
 
 ## MonoMethod {#scripting_a_c}
-This class provides information about about a managed method, as well as giving you multiple ways of invoking it (it allows you to call C# methods from C++).
+**MonoMethod** class provides information about about a managed method, as well as giving you multiple ways of invoking it (i.e. calling C# methods from C++).
 
 To invoke a method you may use multiple approaches:
- - @ref bs::MonoMethod::invoke "MonoMethod::invoke" - Calls the exact method on a specific managed object, with the provided parameters. We'll see how are managed objects referenced in native code later, as well as how passing data between C++ and managed code works.
- - @ref bs::MonoMethod::invokeVirtual "MonoMethod::invokeVirtual" - Calls the method polymorphically. Determines the actual type of the provided managed object instance and calls an overriden method if available.
- - @ref bs::MonoMethod::getThunk "MonoMethod::getThunk" - Returns a C++ function pointer accepting a managed object, zero or more parameters and an exception object. You can then call the function pointer like you would a C++ function. This is equivalent to @ref bs::MonoMethod::invoke "MonoMethod::invoke" but is significantly faster. A helper method @ref bs::MonoUtil::invokeThunk<T, Args> "MonoUtil::invokeThunk" is provided - it is suggested you use it instead of calling thunks manually (it handles exceptions internally).
+ - @ref bs::MonoMethod::invoke "MonoMethod::invoke()" - Accepts a **MonoObject** to invoke the method on (null if a static method), as well as an optional list of parameters. Invokes the exact method to exact type it was provided on.
+ - @ref bs::MonoMethod::invokeVirtual "MonoMethod::invokeVirtual()" - Accepts a **MonoObject** to invoke the method on (null if a static method), as well as an optional list of parameters. Unlike **MonoMethod::invoke()** it calls the method polymorphically, meaning it determines the actual type of the provided managed object instance and calls an overriden method if available.
+ - @ref bs::MonoMethod::getThunk "MonoMethod::getThunk()" - Returns a C++ function pointer accepting a **MonoObject**, zero or more parameters and an exception object. You can then call the function pointer like you would a C++ function. This is equivalent to **MonoMethod::invoke()** but is significantly faster. A helper method @ref bs::MonoUtil::invokeThunk<T, Args> "MonoUtil::invokeThunk()" is provided - it is suggested you use it instead of calling thunks manually  because it handles exceptions internally.
 
-When calling static methods you should provide a null value for the managed object instance.
 
+ 
+ 
+ 
+ TODO - Example invoking a method
+ TODO - Thunk example
+ 
+ 
+We'll talk more about how to pass parameters to methods later. 
+ 
 ## MonoField {#scripting_a_d}
-Similar to methods, field information can be retrieved from a @ref bs::MonoClass "MonoClass" object by calling @ref bs::MonoClass::getField "MonoClass::getField" or @ref bs::MonoClass::getAllFields "MonoClass::getAllFields". The returned value is a @ref bs::MonoField "MonoField" which provides information about the field and allows you to retrieve and set values in the field using @ref bs::MonoField::getValue "MonoField::getValue" / @ref bs::MonoField::setValue "MonoField::setValue". This works similar to how methods are invoked and is explained in more detail later.
+Similar to methods, field information can be retrieved from a **MonoClass** object by calling @ref bs::MonoClass::getField "MonoClass::getField()" or @ref bs::MonoClass::getAllFields "MonoClass::getAllFields()". The returned value is a @ref bs::MonoField "MonoField" which provides information about the field and allows you to retrieve and set values in the field using @ref bs::MonoField::getValue "MonoField::getValue()" / @ref bs::MonoField::setValue "MonoField::setValue()". 
+
+
+
+TODO - Example getting/setting a field
+
+
+
 
 ## MonoProperty {#scripting_a_e}
-Properties are very similar to fields, retrieved from a @ref bs::MonoClass "MonoClass" object by calling @ref bs::MonoClass::getProperty "MonoClass::getProperty". The returned value is a @ref bs::MonoProperty "MonoProperty" which provides information about the property and allows you to retrieve and set values on it. The main difference is that properties in C# can be indexed (like arrays) and therefore a two set of set/get methods are provided, one accepting an index and other one not. It's up to the user to know which one to call. The methods are @ref bs::MonoProperty::get "MonoProperty::get" / @ref bs::MonoProperty::set "MonoProperty::set" and @ref bs::MonoProperty::getIndexed "MonoProperty::getIndexed" / @ref bs::MonoProperty::setIndexed "MonoProperty::setIndexed".
+Properties are very similar to fields, retrieved from a **MonoClass** object by calling @ref bs::MonoClass::getProperty "MonoClass::getProperty()". The returned value is a @ref bs::MonoProperty "MonoProperty" which provides information about the property and allows you to retrieve and set values on it. The main difference is that properties in C# can be indexed (like arrays) and therefore a two set of set/get methods are provided, one accepting an index and other one not. It's up to the user to know which one to call. The methods are @ref bs::MonoProperty::get "MonoProperty::get()" / @ref bs::MonoProperty::set "MonoProperty::set()" and @ref bs::MonoProperty::getIndexed "MonoProperty::getIndexed()" / @ref bs::MonoProperty::setIndexed "MonoProperty::setIndexed()".
+
+
+
+TODO - Example getting/setting a property
+
 
 ## Attributes {#scripting_a_f}
 Attributes provide data about a class, method or field provided at runtime, which usually allows such objects to be specialized in some regard. Attributes don't have their own wrapper, because they are esentially normal managed objects and you can work with them as such.
 
-To retrieve a list of attributes from a class use @ref bs::MonoClass::getAllAttributes() "MonoClass::getAllAttributes", which returns a list of @ref bs::MonoClass "MonoClass" objects that identify the attribute types. To get the actual object instance of the attribute you may call @ref bs::MonoClass::getAttribute "MonoClass::getAttribute" with the wanted attribute's @ref bs::MonoClass "MonoClass". After that you can call methods, work with field values and other, same as you would with a normal managed object (described below).
+To retrieve a list of attributes from a class use @ref bs::MonoClass::getAllAttributes() "MonoClass::getAllAttributes()", which returns a list of **MonoClass** objects that identify the attribute types. To get the actual object instance of the attribute you may call @ref bs::MonoClass::getAttribute "MonoClass::getAttribute()" with the wanted attribute's **MonoClass**. After that you can call methods, work with field values and similar, same as you would with a normal managed object.
+
+Attributes can also be retrieved from a **MonoMethod** by using @ref bs::MonoMethod::getAttribute "MonoMethod::getAttribute()", or from **MonoField** by using @ref bs::MonoField::getAttribute "MonoField::getAttribute()".
+
+
+
+
+
+
+
+
+TODO - Stopped here
+
+
+
+
 
-Attributes can also be retrieved from a @ref bs::MonoMethod "MonoMethod" using @ref bs::MonoMethod::getAttribute "MonoMethod::getAttribute", or from @ref bs::MonoField "MonoField" using @ref bs::MonoField::getAttribute "MonoField::getAttribute".
 
 ## Managed objects {#scripting_a_g}
 So far we have talked about invoking methods and retrieving field values, but we haven't yet explained how to access managed object instances in C++ code. All managed objects in Mono are represented by a `MonoObject`.

Documentation/Manuals/Native/scriptingAuto.md

@@ -0,0 +1,400 @@
+Exposing code to script API (automated)			{#scriptingAuto}
+===============
+[TOC]
+
+When you've added a new feature, system or just extended existing ones you might want to expose that functionality to the scripting API. Banshee makes this process easier through its automated script binding generator tool. All you need to do is to decorate the C++ types and methods you wish to export and run the tool. The tool is ran automatically whenever you build through CMake.
+
+In order to decorate C++ you use the **BS_SCRIPT_EXPORT** macro, which supports a variety of parameters used for customizing how will the type/method be exported.
+
+# Exporting classes {#scriptingAuto_a}
+In order to export a class to script code you need to decorate the class and one or multiple methods with **BS_SCRIPT_EXPORT** macro. 
+
+~~~~~~~~~~~~~{.cpp}
+// Decorate the class and the methods with BS_SCRIPT_EXPORT modifier
+class BS_SCRIPT_EXPORT() MyClass
+{
+public:
+	BS_SCRIPT_EXPORT()
+	MyClass(); // Constructor
+
+	BS_SCRIPT_EXPORT()
+	UINT32 getSomeData();
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script interface (C#):
+~~~~~~~~~~~~~{.cs}
+public partial class MyClass : ScriptObject
+{
+	public MyClass() { ... }
+
+	public int getSomeData() { ... }
+}
+~~~~~~~~~~~~~
+
+There are a few important rules when using **BS_SCRIPT_EXPORT**:
+ - It CAN be used on non-templated classes or structs, as well as **Resource**%s and **Component**%s
+ - It CANNOT be used on templated classes or structs
+ - It CAN be used on public constructors and non-templated methods
+ - It CANNOT be used on destructors, operators, templated methods or private/protected methods of any kind
+
+If you do not respect these rules the code generation will either fail, or the generated code will be invalid and will fail to compile.
+ 
+There are also limitations on the types of parameters and return values the exported methods are allowed to have:
+ - **Resource**%s and **Component**%s must be passed as handles (e.g. **HMesh**, **HRenderable**)
+ - Other classes must be passed as shared pointers (e.g. **SPtr<MyClass>**)
+ - Plain types such as **int**, **float** or types we'll describe below can be passed directly (e.g. **int**)
+ - If a parameter is used as input it is beneficial to decorate it as a constant reference or a pointer (e.g. *const HMesh&*)
+ - If a parameter is used as output it is beneficial to decorate it as a non-constant reference or a pointer (e.g. *HMesh&*)
+ - If a parameter is an array, it must be of type **Vector** (e.g. *Vector<HMesh>* or *Vector<SPtr<MyClass>>*)
+ 
+~~~~~~~~~~~~~{.cpp}
+class BS_SCRIPT_EXPORT() MyOtherClass
+{
+   ...
+};
+
+// Examples of some valid exported methods
+class BS_SCRIPT_EXPORT() MyClass
+{
+public:
+	BS_SCRIPT_EXPORT()
+	MyClass(); // Constructor
+
+	BS_SCRIPT_EXPORT()
+	UINT32 getPlainType();
+	
+	BS_SCRIPT_EXPORT()
+	void getPlainTypeAsParam(UINT32& output);	
+	
+	BS_SCRIPT_EXPORT()
+	void setPlainType(UINT32 value);	
+	
+	BS_SCRIPT_EXPORT()
+	std::string getString(); // or std::wstring
+	
+	BS_SCRIPT_EXPORT()
+	void setString(const std::string& value); // or std::wstring	
+	
+	BS_SCRIPT_EXPORT()
+	HMesh getResource();
+	
+	BS_SCRIPT_EXPORT()
+	void setResource(const HMesh& mesh);
+	
+	BS_SCRIPT_EXPORT()
+	HRenderable getComponent();
+	
+	BS_SCRIPT_EXPORT()
+	void setComponent(const HRenderable& renderable);
+	
+	BS_SCRIPT_EXPORT()
+	SPtr<MyOtherClass> getNormalObject();
+	
+	BS_SCRIPT_EXPORT()
+	void setNormalObject(const SPtr<MyOtherClass>& value);
+	
+	BS_SCRIPT_EXPORT()
+	Vector<HMesh> getArray(); // HMesh could have also been a normal class or a component
+	
+	BS_SCRIPT_EXPORT()
+	void setArray(const Vector<HMesh>& value); // HMesh could have also been a normal class or a component
+};
+~~~~~~~~~~~~~ 
+
+## Renaming {#scriptingAuto_a_a}
+**BS_SCRIPT_EXPORT** accepts a variety of comma separated parameters in the format "param1:value1,param2:value2". Parameter named "n" allows you to specify a different name for a type or a method, so when exported it uses the specified name rather than the same name as in C++.
+
+~~~~~~~~~~~~~{.cpp}
+class BS_SCRIPT_EXPORT(n:MyRenamedClass) MyClass
+{
+public:
+	BS_SCRIPT_EXPORT(n:GetSomeData)
+	UINT32 getSomeData();
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script interface (C#):
+~~~~~~~~~~~~~{.cs}
+public partial class MyRenamedClass : ScriptObject
+{
+	public int GetSomeData() { ... }
+}
+~~~~~~~~~~~~~
+
+## Visibility {#scriptingAuto_a_b}
+You can make a type or a method *public*, *internal* or *private* by specifying the "v" parameter. Accepted values are "public", "internal" and "private. By default all types and methods are public.
+
+~~~~~~~~~~~~~{.cpp}
+class BS_SCRIPT_EXPORT() MyClass
+{
+public:
+	// Exported as a private method
+	BS_SCRIPT_EXPORT(n:GetSomeData,v:private)
+	UINT32 getSomeData();
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script interface (C#):
+~~~~~~~~~~~~~{.cs}
+public partial class MyRenamedClass : ScriptObject
+{
+	private int GetSomeData() { ... }
+}
+~~~~~~~~~~~~~
+
+## Exporting as properties  {#scriptingAuto_a_c}
+Parameter named "pr" allows you to specify that a method should be exported as a property. The supported values for the parameter are "getter" or "setter". When exposing a method as a property the name ("n") parameter is required and ii should be the name of the property.
+
+~~~~~~~~~~~~~{.cpp}
+// Decorate the class and the methods with BS_SCRIPT_EXPORT modifier
+class BS_SCRIPT_EXPORT() MyClass
+{
+public:
+	BS_SCRIPT_EXPORT(pr:getter,n:SomeData)
+	UINT32 getSomeData();
+	
+	BS_SCRIPT_EXPORT(pr:setter,n:SomeData)
+	void setSomeData(UINT32 value);
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script interface (C#):
+~~~~~~~~~~~~~{.cs}
+public partial class MyClass : ScriptObject
+{
+	public int SomeData
+	{
+		get { ... }
+		set { ... }
+	}
+}
+~~~~~~~~~~~~~
+
+You are allowed to provide only getter, only setter, or both. Providing multiple getters or setters for the propery with the same name results in undefined behaviour.
+
+Getter/setter methods must follow a specific template otherwise they will be ignored during generation:
+ - Getter method must return a non-void value, and have no parameters
+ - Setter method must not have a return value and a single parameter
+ - Getter return value and setter parameter types must match
+
+## Extending script interface further {#scriptingAuto_a_d}
+Sometimes automatic code generation just isn't good enough. For that reason all exported C# classes are marked with the *partial* keyword, meaning you can extend their interface with manually written code in a separate file, as required. 
+ 
+# Exporting structures {#scriptingAuto_b}
+A data type can be exported as a C# *struct* by using the "pl" parameter, accepting values "true" or "false" (default being false). When exported all of the fields of the data type will be exported as a C# *struct*. Any constructors will also be exported, but no other methods. This is meant to be used on simple types that will be used for passing data around. Such types are passed by value and will be copied when crossing the C++/C# boundary.
+
+~~~~~~~~~~~~~{.cpp}
+struct BS_SCRIPT_EXPORT(pl:true) Volume
+{
+	Volume()
+		: left(0), top(0), right(1), bottom(1), front(0), back(1)
+	{ }
+
+	Volume(UINT32 left, UINT32 top, UINT32 right, UINT32 bottom):
+		left(left), top(top), right(right), bottom(bottom), front(0), back(1)
+	{ }
+
+	Volume(UINT32 left, UINT32 top, UINT32 front, UINT32 right, UINT32 bottom, UINT32 back):
+		left(left), top(top), right(right), bottom(bottom), front(front), back(back)
+	{ }
+		
+	UINT32 left, top, right, bottom, front, back;
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script code (C#):
+~~~~~~~~~~~~~{.cs}
+public partial struct Volume
+{
+	// C# doesn't support parameterless struct constructors, and therefore a static Default() method is generated instead
+	public static Volume Default()
+	{
+		Volume value = new Volume();
+		value.left = 0;
+		value.top = 0;
+		value.right = 1;
+		value.bottom = 1;
+		value.front = 0;
+		value.back = 1;
+
+		return value;
+	}
+
+	public Volume(int left, int top, int right, int bottom)
+	{
+		this.left = left;
+		this.top = top;
+		this.right = right;
+		this.bottom = bottom;
+		this.front = 0;
+		this.back = 1;
+	}
+
+	public Volume(int left, int top, int front, int right, int bottom, int back)
+	{
+		this.left = left;
+		this.top = top;
+		this.right = right;
+		this.bottom = bottom;
+		this.front = front;
+		this.back = back;
+	}
+
+	public int left;
+	public int top;
+	public int right;
+	public int bottom;
+	public int front;
+	public int back;
+}
+~~~~~~~~~~~~~
+
+Note when generating constructors the system is only able to parse class member initializers and constructor initializers defined in the header file and will ignore any in the .cpp file.
+
+Structs support rename & visibility parameters same as normal class export.
+
+# Exporting enums {#scriptingAuto_c}
+Enums can be exported with no additional parameters, just by specifying **BS_SCRIPT_EXPORT**.
+
+~~~~~~~~~~~~~{.cpp}
+enum BS_SCRIPT_EXPORT() class MyEnum
+{
+	Value1 = 1,
+	Value2 = 10,
+	Value3 = 100
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script code (C#):
+~~~~~~~~~~~~~{.cs}
+public enum MyEnum
+{
+	Value1 = 1,
+	Value2 = 10,
+	Value3 = 100
+}
+~~~~~~~~~~~~~
+
+Enums support rename & visibility parameters same as normal class and struct export.
+
+## Excluding enum entries {#scriptingAuto_c_a}
+By default when exporting enums all of their entries will be exported. You can ignore a certain enum entry by using the "ex" parameter. Supported values are "true" or "false".
+
+~~~~~~~~~~~~~{.cpp}
+// Exclude the third enum entry from script code
+enum BS_SCRIPT_EXPORT() class MyEnum
+{
+	Value1 										= 1,
+	Value2 										= 10,
+	Value3 		BS_SCRIPT_EXPORT(ex:true)		= 100
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script code (C#):
+~~~~~~~~~~~~~{.cs}
+public enum MyEnum
+{
+	Value1 = 1,
+	Value2 = 10,
+}
+~~~~~~~~~~~~~
+
+## Renaming enum entries {#scriptingAuto_c_b}
+Individual enum entries can also be renamed using the "n" parameter.
+
+~~~~~~~~~~~~~{.cpp}
+enum BS_SCRIPT_EXPORT() MyEnum
+{
+	ME_VAL1 	BS_SCRIPT_EXPORT(n:Value1) 		= 1,
+	ME_VAL2 	BS_SCRIPT_EXPORT(n:Value2) 		= 10,
+	ME_VAL3 	BS_SCRIPT_EXPORT(n:Value3) 		= 100
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script code (C#):
+~~~~~~~~~~~~~{.cs}
+public enum MyEnum
+{
+	Value1 = 1,
+	Value2 = 10,
+	Value3 = 100
+}
+~~~~~~~~~~~~~
+
+# Exporting comments {#scriptingAuto_d}
+All Javadoc-type comments on exported types and methods will automatically be parsed, converted to XML documentation format and exported to script code.
+
+# External methods {#scriptingAuto_e}
+Sometimes the C++ interface just isn't suitable for export to script code as-is. Sometimes you want to make the script code more streamlined and higher level, without modifying the existing C++ interface. Other times the method parameters or return values don't fit the requirements we stated above.
+
+External methods allow you to extend functionality of some class, **Resource** or a **Component** by defining static methods which are then exported as if they were part of the original class. Note these types of methods are not relevant for struct or enum export.
+
+Use the "e" parameter to mark a method as external. Value of the parameter should be the name of the class it is extending.
+Use the "ec" parameter to mark a constructor as external. Value of the parameter should be the name of the class it is extending.
+
+~~~~~~~~~~~~~{.cpp}
+struct MY_CLASS_DESC
+{
+	int val1;
+	float val2;
+}
+
+// Some class we're exporting normally
+class BS_SCRIPT_EXPORT() MyClass
+{
+public:
+	MyClass(const MY_CLASS_DESC& desc);
+
+	UINT32* getArrayData(UINT32& count) const;
+};
+
+// Extension class for MyClass
+class BS_SCRIPT_EXPORT(e:MyClass) MyClassEx
+{
+public:
+	// External constructor because we don't want to expose MY_CLASS_DESC to script code
+	BS_SCRIPT_EXPORT(ec:MyClass)
+	static SPtr<MyClass> create(int val1, float val2)
+	{
+		MY_CLASS_DESC desc;
+		desc.val1 = val1;
+		desc.val2 = val2;
+		
+		return bs_shared_ptr_new<MyClass>(desc);
+	}
+
+	// External method because MyClass returns an array in raw form, but we need it in a Vector
+	BS_SCRIPT_EXPORT(e:MyClass)
+	static UINT32 getArrayData(const SPtr<MyClass>& thisPtr)
+	{
+		UINT32 numEntries;
+		UINT32* entries = thisPtr->getArrayData(numEntries);
+		
+		Vector<UINT32> output;
+		for(UINT32 i = 0; i < numEntries; i++)
+			output.push_back(entries[i]);
+			
+		return output;
+	}
+};
+~~~~~~~~~~~~~
+
+The example above results in the following script interface (C#):
+~~~~~~~~~~~~~{.cs}
+public partial class MyClass : ScriptObject
+{
+	public MyClass(int val1, float val2) { ... }
+
+	public int[] getArrayData() { ... }
+}
+~~~~~~~~~~~~~
+
+External methods must follow these rules:
+ - They must be part of a class that is also exported and marked with the "e" parameter
+ - They must be static
+ - External constructors must return a value of the type they're external to
+ - External methods must accept the type they're external to as the first parameter 
+ 
+# Running the code generator {#scriptingAuto_f}
+Once you have decorated the C++ classes with necessary export parameters you can run the code generator simply by regenerating the CMake build. The generator will run automatically over all Banshee code and generate relevant script code.

Source/BansheeUtility/Include/BsPrerequisitesUtil.h

@@ -246,10 +246,10 @@
  */
 
 #if BS_COMPILER == BS_COMPILER_CLANG
-	/** @copydoc scriptBindingMacro */
+	/** @ref scriptBindingMacro */
 	#define BS_SCRIPT_EXPORT(...) __attribute__((annotate("se," #__VA_ARGS__)))
 #else
-	/** @copydoc scriptBindingMacro */
+	/** @ref scriptBindingMacro */
 	#define BS_SCRIPT_EXPORT(...) 
 #endif