[Sync] Build system and docs proj sync

doc/CodingStandard.md

@@ -0,0 +1,149 @@
+Coding standards
+================
+It is highly recommended to use a single *coding style* for the whole project
+source code. Exceptions are allowed for external libraries used in the project,
+but it is generally advisable all contributors to use this style.
+
+Tab Size
+--------
+First of all, we use spaces. Tabs are four-character width. That is, no 8-space
+tabs, no 2-space tabs. Four. Unfortunately there's no such thing as 'standard
+tab width', and 4-space indenting looks best from our point of view, besides MSVC'
+editor has this setting by default.
+
+Line length
+-----------
+Then, please use 80-character wide lines. If your line is way longer than that,
+please split it. If it's just a little longer, so be it. The continuation text,
+if you're splitting text inside the brackets, should be indented to the position
+after the opening bracket:
+
+	printf("This is a example of how we split lines longer than %d characters\n"
+		   "into several so that they won't exceed this limit.\n",
+		   max_sourcecode_width);
+
+If you have long strings, you can split them as shown above, just remember that
+C/C++ compilers will glue together several strings that come without any special
+characters between them into one.
+
+Brackets
+--------
+Now we use symmetric bracket placement, closing bracket under the opening bracket:
+
+	if (something)
+	{
+		...;
+	}
+	else
+	{
+		...;
+	}
+
+	switch (x)
+	{
+		case 1:
+			printf("X is one!\n");
+			break;
+		case 2:
+		{
+			printf("X is two!\n");
+			break;
+		}
+	}
+
+	for (int i = 1; i < 3; ++i)
+	{
+		printf("I is %i!\n", i);
+	}
+
+Every bracketed block moves its contents by one tab to right. Labels (but not case
+selectors or 'public:/private:/protected' C++ keywords) are placed at the leftmost
+indention position for the current block, that is, in the same position where
+enclosing brackets are.
+
+Also please don't use brackets around a single statement because it clutters the
+code with unneeded stuff; use brackets only when using non-obvious constructs,
+like:
+
+	if (...)
+	{
+		if (...)
+			...;
+	}
+	else
+		...;
+
+Also, please place one space before opening parenthesis. Before, but not after
+(the `if ( blah )` style is a no-no!).
+
+Class declaration and constructors
+----------------------------------
+Here is an example:
+
+	class Class : public Parent
+	{
+		public:
+			Class() : Parent(0),
+				m_field(1)
+			{
+				func();
+			}
+
+		   void func() {}
+
+		private:
+			int m_field;
+	};
+
+Please follow the following rules for classes:
+
+* space before and after : in class parents list and constructor body
+* next line and indent for class field initialization list
+* indent for public:/private:/protected: section with additional indent
+  for section content
+* empty or short function body can be at same line with declaration in
+  in-class definition case
+
+Code documentation with Doxygen
+-------------------------------
+Now, please use DoxyGen-type comments. This is a bit similar to JavaDoc comments
+and to other automatic code documentation generation tools. One-line documentation
+should be placed in `///` (three slashes) comments if the comment is above the
+function/member, if you want the comment on the same line you should use `///<`
+instead, multi-line comments should be put in a `/** ... */` block (slash-two-stars).
+
+Here's a example that shows most useful keywords that you can use in a comment block:
+
+	/**
+	* This function does something very useful. If used with care, this function
+	* has the potential to make your programs really really useful.
+	*
+	* \arg \c x
+	*   The x argument specifies a integer that is transformed into something useful.
+	* \arg \c y
+	*   This argument, if not NULL, is a pointer to a free memory area where this
+	*   function will put something really really useful.
+	* \return
+	*   A useful value, or NULL if error.
+	*
+	* Here is a example that you can paste into your code so that it saves you a
+	* lot of typing:
+	*
+	* \verb atim  (Remove the space)
+	* for (int x = 0; x < 100; ++x)
+	*     printf("DoSomethingUseful%d = %s\n", i,
+	*             DoSomethingUseful(i, &ScratchPad));
+	* \endve rbatim (Remove the space)
+	*
+	* Paragraphs are split from each other by inserting a empty line. Also some HTML
+	* tags are supported, like <ol> [<li>...] </ol> and <ul> [<li>...] </ul> for
+	* ordered (numbered) and unordered (dotted) lists respectively.
+	*/
+	char *DoSomethingUseful(int x, void *y);
+
+	/// This is a one-line comment
+	void Something();
+
+Use normal comments like `//` and `/* ... */` only if you want to make a comment
+that should not go into the automatically annotated code (like:
+`/* shit ... this does not work */`).