More work on documentation

Documentation/Manuals/Native/codeStyle.md

@@ -0,0 +1,96 @@
+Coding style							{#codeStyle}
+===============
+[TOC]
+
+When making changes or additions that you plan on contributing to Banshee, you must follow the same coding style as the rest of the codebase. This document tries to list the most important aspects of the style.
+
+**Spacing**
+ - Use tabs instead of spaces for indentation
+ - Always put a space after a semicolon (e.g. `for(int i = 0; i < 5; i++)`).
+ - Always put a space between operators (e.g. `5 + 2`).
+ - Separate meaningful parts of the code with empty lines
+ - Always but a blank line after a block {}
+ - No single line should be longer than column 124 (set up a guideline in your editor)
+ 
+**Brackets**
+ - Both opening and closing brackets should be in their own line
+  - The exceptions are empty methods and small methods defined directly in class declarations
+ - Conditionals or loops that have just one line should omit the brackets
+  
+**Naming**
+ - Methods, fields and local variables must be in camelCase with first letter as lowercase (e.g. `void myMethod(); int myVar;`).
+ - Class/struct/enum names must be in PascalCase with first letter as uppercase (e.g. `class MyClass`).
+ - Non-public class/struct fields should be prefixed with "m", followed by a capital first letter (e.g. `int mClassMemberField;`).
+ - Non-constant global variables and methods should be prefixed with an "g", followed by a capital first letter (e.g. `const Application& %gApplication();`).
+ - Constant global variables should be written in all caps with underscores separating the words (e.g. `int NUM_ELEMENTS = 5;`).
+ - Macros should be written in all caps with underscores separating the words, and prefixed with "BS_" (e.g. \#`define BS_EXCEPT`).
+ - Static non-constant variables should be prefixed with an "s", followed by a capital first letter (e.g. `bool sIsInitialized;`).
+ - Static constant variables should be written in all caps with underscores separating the words (e.g. `int NUM_ELEMENTS = 5;`).
+ - Everything needs to be part of the "bs" namespace
+  - Types used primarily on the core thread should be part of the "bs::ct" namespace
+ - Use "Base" suffix to mark base classes unless a more generalized name is more appropriate
+ - Prefix templated base classes/structs with a "T" unless a more generalized name is more appropriate
+ - Use "C" prefix for component implementations
+ - Use "H" prefix for component and resource handles
+ 
+**Class interface**
+ - Carefully construct class interfaces, keeping only relevant methods public and everything else private/protected/internal
+ - Public fields should be avoided (except for simple structures) and getter/setter methods should be provided instead
+ - If a class needs to communicate with another class within a sub-system, but the functionality isn't something a normal user is meant to use, provide "internal" methods. Those may be (depending on what is more convenient):
+  - Private methods that are exposed to the other class using the `friend` syntax
+  - Public methods that are prefixed with "_" (e.g. `void _internalMethod();`).
+ - Class entries should be listed in this order:
+  - typedefs
+  - nested classes/structures
+  - public methods
+  - internal methods
+  - public fields
+  - internal fields
+  - protected methods
+  - private methods
+  - protected fields
+  - private fields
+ - Each major class should belong to its own .h file, prefixed with "Bs" followed by the class name
+  - If helper types are required, they can belong to the same file, but prefer to list them after the main class when possible
+ 
+**Function/method interface**
+ - If method doesn't modify data, always mark it as const (getters especially) (e.g. `int getValue() const;`)
+ - Always pass non-primitive parameters by reference unless `null` is a valid value in which case use a pointer (e.g. `void myMethod(int a, const SomeStruct& b)`)
+ - Reference/pointer parameters that won't be modified by a function should always be `const` (e.g. `bool processData(const SomeStruct& input, SomeStruct& output)`)
+ 
+**Implementation**
+ - Avoid the use of `auto` for variable types, with the exception of very long type names (like iterators)
+  - If `auto` is used try to name the variable so its type can be easily deduced
+ - Use built-in typedefs for standard library containers (e.g. `Vector`) and shared pointers (`SPtr`).
+ - Don't allocate memory using `new/delete` or `malloc/free`, instead use Banshee's allocators
+ - No code warnings under default compiler warning settings are allowed. Fix all your warnings or if absolutely not possible isolate that bit of code and disable that specific warning (but only in that bit of code).
+ - Never use `using namespace` in a header
+ 
+**Documentation**
+ - Document every class/structure/enum with a short description on what their purpose is
+  - Optionally provide an use-case example
+  - Document every enum member
+  - Document struct fields unless they have getter/setter methods that are already documented
+  - Documentation for private class fields is optional
+ - Document every method, both public and private
+  - The only exceptions being very trivial methods whose use can be deduced from their name
+  - You are allowed to omit documentation for method parameters & return value if it is clear from the general method description what they do
+  - If you document one parameter you must document them all, as well as the return value
+ - Document implementations
+  - Prefer writing self-documenting code as opposed to writing comments
+   - Give variables meaningful names
+   - If an expression is too complex break it down using temporary variables using meaningful names
+   - If it is still unclear, write comments
+  - Carefully document complex mathematical expressions
+   - Add a comment what the expression does or a hyperlink to expression source
+   - If simplified or re-arranged, provide reference expression in comments, as well as explanation on how the current expression was derived (or a link to one)
+ - Documentation must be in JavaDoc format 
+ - Write **meaningful** documentation
+  - Avoid writing documentation that provides information that can be deduced from class/method name and instead try to provide the reader with deeper understanding. For example `/** Gets value */ getValue(); ` is pointless documentation
+  - Avoid giving away implementation details in documentation. Implementation should be allowed to change, and as long as the interface remains the same, the documentation should remain the same
+ - Use \@`addtogroup` to group classes into relevant sections (e.g. a class doing something physics-related should be in the "Physics" group)
+  - Classes/structs/functions/enums that aren't meant to be used by normal users should be placed in a separate group to avoid polluting the user-facing documentation (e.g. user-facing physics functionality should be in the "Physics" group, while non-user-facing should be in "Physics_Internal" group)
+ - Use \@`name Internal` to mark methods inside a class that they are not meant for normal use (i.e. they might be used for internal communication within a sub-system only)
+ - Documentation should produce no Doxygen warnings when it is generated
+ - If it is not obvious for which thread is a class/method meant to be used on, note it in the documentation
+ 

Documentation/Manuals/Native/manuals.md

@@ -110,6 +110,9 @@ A set of manuals covering advanced functionality intented for those wanting to e
  - **Exposing code to script API (manually)**
   - [Interacting with the script runtime](@ref mono)
   - [Script objects](@ref scriptObjects)
+- [Porting to other platforms](@ref porting)
+- [Code style](@ref codeStyle)
+- [Quick reference](@ref quickref)
  
 ## General guides
 Name                                      | Description
@@ -117,7 +120,4 @@ Name                                      | Description
 [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.
-[Materials](@ref materials)				  | Shows you how to create and use materials and shaders.
-[Quick reference](@ref quickref)          | Provides a few bits of commonly required information, that might be hard to remember otherwise.
-[Porting](@ref porting)                   | Information about how to go on about porting Banshee to a different operating system.
-[Code style](@ref style)                  | Information about code style used when writing Banshee.
+[Materials](@ref materials)				  | Shows you how to create and use materials and shaders.

Documentation/Manuals/Native/porting.md

@@ -10,17 +10,18 @@ Banshee currently compiles using MSVC and Clang on Windows. There should be litt
 This means that as far as the compilation goes most of the work should be done for you.
 
 # Platform specific functionality {#porting_b}
-Most of the porting work remains in adding platform specific functionality like file-system, windows and similar. Banshee comes with a fully working implementation of OpenGL, which means the rendering API is already cross-platform (for the most part), and the platform functionality mostly lies in various utility functionality.
+Most of the porting work remains in adding platform specific functionality like file-system, windows and similar. Banshee comes with a fully working implementation of OpenGL & Vulkan, which means the rendering API is already cross-platform (for the most part), and the platform-specific functionality mostly lies in various utility functionality.
 
 Banshee was built with multi-platform in mind from day one, and it tries to minimize the amount of platform specific functionality as much as possible. The functionality that is platform specific is encapsulated so external code never needs to access it directly, making the porting process transparent to higher level systems. All of the platform specific functionality is cleanly marked either in an \#ifdef block or is in a separate source file with a special prefix.
 
-Banshee is built in layers, higher layers referencing lower layers. This should make porting easier as you can start with the lowest layer and work your way up. This way you can compile and test layer by layer instead of needing to fully port the entire engine to properly compile it. Additionally a lot of functionality is in plugins and those generally don't have any platform specific code (except the OpenGL plugin), which should also help with dividing the work into manageable chunks. These aspects of Banshee should significantly help with the porting effort, so keep the layers/plugins in mind.
+Banshee is built in layers, higher layers referencing lower layers. This should make porting easier as you can start with the lowest layer and work your way up. This way you can compile and test layer by layer instead of needing to fully port the entire engine to properly compile it. Additionally a lot of functionality is in plugins and those generally don't have any platform specific code (except the OpenGL & Vulkan plugins), which should also help with dividing the work into manageable chunks. These aspects of Banshee should significantly help with the porting effort, so keep the layers/plugins in mind.
 
-Aside from dividing the work by layers/plugins you should most definitely also divide it by functionality needed: editor requires significantly more platform specific code than a standalone game. You should first strive to port all the features used by the standalone game, then after everything is working should you proceed with working on editor features. You can use the `ExampleProject` as a test-bed for the standalone features. 
+Aside from dividing the work by layers/plugins you should most definitely also divide it by functionality needed: editor requires significantly more platform specific code than the core framework. You should first strive to port all the features used by the core framework, then after everything is working should you proceed with working on editor features.
 
 All the features that need porting are wrapped in a BS_PLATFORM \#ifdef block, or in files prefixed with "Win32". In a very limited set of cases there are also BS_COMPILER defines for functionality specific to a compiler. For every such block and file you will need to write equivalent code for the destination platform. 
 
-Below you will find a fairly complete list of all such blocks/files that need to be modified, to give you a good idea of the scope. Each listed feature has an indication whether this is a engine or editor-only feature.
+Below you will find a fairly complete list of all such blocks/files that need to be modified, to give you a good idea of the scope. Each listed feature has an indication whether this is a framework or editor-only feature.
+
 Additionally, not all features are critical, meaning you can get the engine to run without them (e.g. platform cursors or clipboard), which are also specially marked. For them it is suggested you implement a dummy version first, and only proceed with actual implementation once the critical features are done.
 
 ## Critical features {#porting_b_a}
@@ -30,8 +31,9 @@ Feature                                         | Editor only 	| Library
 ------------------------------------------------|---------------|-------------------------------|-----------------------|--------------------------------------------------------|-----------------
 File system*								   	| No			| BansheeUtility				| No					| BsFileSystem.h/BsWin32FileSystem.cpp 					 | Opening/creating files, iterating over directories
 Dynamic library loading							| No			| BansheeUtility				| No					| BsDynLib.h/BsDynLib.cpp 							     | Loading dynamic libraries (.dll, .so)
-OpenGL initialization*							| No			| BansheeGLRenderAPI			| No					| BsGLUtil.h, BsGLSupport.h/BsWin32GLSupport.cpp, BsWin32Context.h/BsWin32Context.cpp, BsWin32VideoModeInfo.cpp | Initializing the OpenGL context (or other context if non-OpenGL API is used for the port)
-Window creation*								| No			| BansheeUtility, BansheeGLRenderAPI | No				| BsWin32Window.h/BsWin32Window.cpp, BsWin32Platform.h/BsWin32Platform.cpp, BsWin32RenderWindow.h/BsWin32RenderWindow.cpp | Creating and interacting with the window
+OpenGL initialization*							| No			| BansheeGLRenderAPI			| No					| BsGLUtil.h, BsGLSupport.h/BsWin32GLSupport.cpp, BsWin32Context.h/BsWin32Context.cpp, BsWin32VideoModeInfo.cpp | Initializing the OpenGL context 
+Vulkan initialization*							| No			| BansheeVulkanRenderAPI		| No					| BsVulkanRenderAPI.cpp, BsWin32VideoModeInfo.cpp | Initializing the Vulkan context
+Window creation*								| No			| BansheeUtility, BansheeGLRenderAPI, BansheeVulkanRenderAPI | No				| BsWin32Window.h/BsWin32Window.cpp, BsWin32Platform.h/BsWin32Platform.cpp, BsWin32RenderWindow.h/BsWin32RenderWindow.cpp | Creating and interacting with the window
 OS message loop*								| No			| BansheeCore					| No					| BsWin32Platform.h/BsWin32Platform.cpp 				 | Running the main message loop, responding to its events
 Input*											| No			| BansheeCore					| Maybe					| BsPlatform.h/BsWin32Platform.cpp 						 | Receive input from OS (mouse, keyboard)
 UUID generation									| No			| BansheeUtility				| No					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp 		 | Generate UUID/GUID
@@ -62,7 +64,9 @@ MonoDevelop integration*						| Yes			|BansheeEditor					| Yes					| BsCodeEdito
 # Compiling third party dependencies {#porting_c} 
 In order to run Banshee on different platforms you will also need to compile all of Banshee's dependencies. Most of Banshee's dependencies are only used in plugins, which should make it easier to compile and test them individually.
 
-All used dependencies are already multi-platform and you should have little trouble compiling them for major platforms. See "CompilingDependenciesManually.txt" (distributed with the source code) for information which dependencies are needed.
+All used dependencies are already multi-platform and you should have little trouble compiling them for major platforms. See [this link](http://bit.ly/2oLL0uR) for information which dependencies are needed.
 
 # Mobile platforms {#porting_d} 
-If building for mobile platforms you will also need to provide a compatible render API plugin. It is suggested you use the BansheeOpenGL plugin as an example of creating such an API (for example OpenGL ES). API's like Metal or Vulkan for mobiles will require more work but you can still use the existing render API plugins for a good basis of what needs to be implemented.
+If porting to mobile platforms you will also need to provide a compatible render API plugin. Vulkan can be used for some mobiles but isn't supported for all, so you might need to write your own render API plugin. It is suggested you use the BansheeOpenGL plugin as an example of creating it (OpenGL ES is commonly supported on most mobiles, or Metal supported only on Apple platforms).
+
+When porting to mobile you do not need to port any editor specific functionality, and can concern yourself only with porting the core framework. 

Documentation/Manuals/Native/quickref.md

@@ -2,9 +2,9 @@ Quick reference									{#quickref}
 ===============
 [TOC]
 
-Here is some commonly required information that is assumed throughout Banshee.
- - Right handed coordinate system is used
- - Camera is looking towards negative z axis
+Here are some common conventions used throughout Banshee:
+ - It uses right handed coordinate system
+ - Camera is looking towards the negative z axis
  - Screen/window space origin is located in the top left corner
  - Normalized device coordinates origin is located in the bottom left corner
  - Clip space ranges from -1 to 1 for x, y and depth

Documentation/Manuals/Native/style.md

@@ -1,67 +0,0 @@
-Coding style							{#style}
-===============
-[TOC]
-
-This document provides information on the coding style that should be used when contributing to Banshee. Although you should remember the notes in this document, you can get away without remembering all of this by just following the style in existing code. This guide applies only to C++ code.
-
-Guidelines
- - Documentation
-   - Write JavaDoc style documentation.
-   - Document every class/structure/enum.
-   - Document every non-trivial method (i.e. anything that you can't deduce what it does from its name).
-   - You are allowed to omit documenting method parameters if its clear from the general method descriptions what they do.
-   - Documentation of fields in classes and enums is optional if it's clear what they do or their documentation is available elsewhere.
-   - Write RELEVANT documentation. For example `/** Gets value */ getValue(); ` is pointless documentation. Try to give the user a deeper understanding of what the code does from what he can already deduce by reading the name of the method.
-   - Use \@`addtogroup` to group classes into relevant sections.
-    - Use separate groups for code that can be considered internal (i.e. more specialized, not meant for normal use) to clean up the user-facing documentation.
-	- Use \@`name Internal` to group internal methods within a class for a similar purpose.
-   - Documentation should produce no Doxygen warnings when generating.
-   - If it is not obvious for which thread is a class/method meant to be used on, note it in the documentation.
- - Prefixes/Sufixes
-   - Use "_" prefix to identify a method is internal. A method is internal if it is public but it is not meant to be used by the normal user. You can alternatively use a private method and C++ `friend` syntax. Although the former approach is sometimes preferable to avoid exposing too much of the interface.
-   - Use "Core" suffix to note that a class is used on the core thread, but also has a sim-thread counterpart. The sim-thread counterpart should share the name of the class but without the "Core" suffix.
-   - Use "Base" suffix to mark base classes unless a more generalized name is more appropriate.
-   - Prefix templated base classes/structs with a "T" unless a more generalized name is more appropriate.
-   - Use "C" prefix for component implementations.
- - Naming
-  - Methods, fields and local variables should be written in camelCase with first letter as lowercase (e.g. `void myMethod(); int myVar;`).
-  - Class/struct/enum names should be in PascalCase with first letter as uppercase (e.g. `class MyClass`).
-  - Non-public class/struct fields should be prefixed with "m", followed by a capital first letter (e.g. `int mClassMemberField;`).
-  - Non-constant global variables and methods should be prefixed with an "g", followed by a capital first letter (e.g. `void gApplication();`).
-  - Constant global variables should be written in all caps with underscores separating the words (e.g. `int NUM_ELEMENTS = 5;`).
-  - Macros should be written in all caps with underscores separating the words (e.g. \#`define BS_EXCEPT`).
-  - Static non-constant variables should be prefixed with an "s", followed by a capital first letter (e.g. `bool sIsInitialized;`).
-  - Static constant variables should be written in all caps with underscores separating the words (e.g. `int NUM_ELEMENTS = 5;`).
- - Brackets/Spacing
-  - Use indentation for new blocks
-  - Use tabs for one indentation step
-  - Brackets {} should always be on their own line unless they're empty or for small method definitions directly in class declaration
-  - Conditionals or loops that have just one line of content should omit the brackets
-  - Always put a space after a semicolon (e.g. for(int i = 0; i < 5; i++)).
-  - Always put a space between operators (e.g. 5 + 2).
-  - Separate meaningful parts of the code in a method with empty lines
-  - Always but a blank line after a block {}
-  - No single line should be longer than column 124 (set up a guideline in your editor)
- - If method doesn't modify data, always mark it as const (getters especially)
- - Always pass non-primitive parameters by reference unless `null` is a valid value in which case use a pointer
- - Reference/pointer parameters that won't be modified by a function should always be `const`
- - Prefer using `enum class` to `enum`
- - Use built-in typedefs for standard library containers (e.g. `Vector`) and shared pointers (`SPtr`).
- - Don't allocate memory using `new/delete` or `malloc/free`, instead use Banshee's allocators
- - Carefully construct class interfaces, keeping only relevant methods public and everything else private/protected/internal
- - No code warnings under default compiler warning settings are allowed. Fix all your warnings or if absolutely not possible isolate that bit of code and disable that specific warning (but only in that bit of code).
- - Prefer putting helper types (e.g. structs, enums) to the bottom of the include file if possible and keep the first class in the file the primary class
- - Put everything in BansheeEngine namespace unless specializing code for a third party library
- - Never use `using namespace` in a header
- - Public fields should be avoided (except for simple structures) and instead getter/setter methods should be provided
- - In a class list elements in this order:
-    - typedefs
-    - nested classes/structures
-	- public methods
-	- public fields
-	- internal methods
-	- internal fields
-	- protected methods
-	- protected fields
-	- private methods
-    - private fields