Update documentation standard.

docs/DOC_GEN.md

@@ -1,35 +1,37 @@
-#Documentation generation
+# Documentation generation
 
-##Setting up
+## Setting up
 - install [python](https://www.python.org/)(2)
- - when installing, tick to install the path variable
+  - when installing, tick to install the path variable
- - may need restart after for installation to properly take effect
+  - may need restart after for installation to properly take effect
 - install a package manager like [pip](https://pip.pypa.io/en/latest/)
- - if installed pip and doesnt work, restart or try easy_install command
+  - if installed pip and doesnt work, restart or try easy_install command
 - install the dependencies with manager
- - [Jinja2](https://pypi.python.org/pypi/Jinja2)
+  - [Jinja2](https://pypi.python.org/pypi/Jinja2)
- - [typedecorator](https://pypi.python.org/pypi/typedecorator)
+  - [typedecorator](https://pypi.python.org/pypi/typedecorator)
- - [markdown](https://pypi.python.org/pypi/Markdown)
+  - [markdown](https://pypi.python.org/pypi/Markdown)
 
-##Generating
+## Generating
 - Run in cmd `python -m ElunaDoc` when at `\LuaEngine\docs\`
 
-##Documenting
+## Documenting
-You can document functions in the Eluna source code. For examples, simply open a method header file.
+You can document functions in the Eluna source code. For examples, simply open a method header file with docs.
+
+### Template
+Here are basic templates for a function. When defining a parameter or a return value, the type and value name are mandatory, unless the parameter type is ... (for variable arguments; don't include a name in this case).
 
-###Template
-Here are basic templates for a function. When defining a parameter or a return value, the type and value name are mandatory.
 ```c++
 /**
- * Description.
+ * Short description (about 80 characters long).
  *
  * @param Type paramName
  * @return Type returnName
  */
 ```
+
 ```c++
 /**
- * Description.
+ * Short description (about 80 characters long).
  *
  * @param Type paramName = defaultValue : parameter description
  * @return Type returnName : return value description
@@ -37,9 +39,10 @@ Here are basic templates for a function. When defining a parameter or a return v
 ```
 
 This is a template for a function that takes in different parameters. When defining a parameter or a return value, the type and value name are mandatory.
+
 ```c++
 /**
- * Description.
+ * Short description (about 80 characters long).
  *
  * @proto returnValue = (object)
  * @proto returnValue = (x, y, z)
@@ -51,46 +54,59 @@ This is a template for a function that takes in different parameters. When defin
  */
 ```
 
-###Standard
+### Standard
 A documentation comment block will always start with `/**` and end with `*/`.
 All lines start with `*` character followed by one space before any content.
 
-The main description will start with uppercase letter and end with a dot. All paragraphs should end with a dot as well.
+The first paragrph is used as a short description of the function/class, so it should be kept to about 80 characters. The other paragraphs can be as long as desired.
-The parameter and return value descriptions should start with a lowercase letter and at the end there should be no dot.
+
+All paragraphs in the description (including the first) should start with a capital letter and end with a period.
+**Paragraphs must be separated by an empty line**, e.g.:
+
+```c++
+/**
+ * This is a short description (about 80 characters).
+ *
+ * Here's another paragraph with more info. NOTE THE EMPTY LINE BETWEEN THE PARAGRAPHS.
+ * This does need to be short, and this line is still part of the same paragraph because
+ * there is no empty line.
+ */
+ ```
+
+The parameter and return value descriptions should start with a lowercase letter and not end with a period. If more than one sentence is needed, start the *first* without a capital letter and end the *last* without a period.
 
 Any class, enum or function can be referenced (made a link to) with square brackets.
 `[Player]` will reference a player. `[WeatherType]` will reference an enum. `[Player:GetName]` will reference a function.
 
-Use correct indentation with documentation comments
+Use correct indentation with documentation comments.
+
 ```c++
 /**
  * Correct indentation.
- * @param Type paramName = defaultValue : parameter description
- * @return Type returnName : return value description
  */
 ```
+
 ```c++
 /**
 * Invalid indentation.
-* @param Type paramName = defaultValue : parameter description
-* @return Type returnName : return value description
 */
 ```
 
-###Markdown
+### Markdown
 You can use [markdown](http://pythonhosted.org//Markdown/) in your descriptions.
 For syntax see http://daringfireball.net/projects/markdown/syntax and http://pythonhosted.org//Markdown/#differences
+
 ```
 /**
  * Description.
  *
- * * list item
+ * - list item
- * * list item
+ * - list item
- * * list item
+ * - list item
  *
- * <pre>
+ *     // Codeblock
- * codeblock
+ *     // Code goes here.
- * </pre>
+ *     // Note the 4-space indent.
  *
  * `code line`
  *
@@ -98,24 +114,27 @@ For syntax see http://daringfireball.net/projects/markdown/syntax and http://pyt
  * **bold**
  */
 ```
-Produces<br/>
+
+**Produces:**
+
 Description.
 
-* list item
+- list item
-* list item
+- list item
-* list item
+- list item
 
-<pre>
+    // Codeblock
-codeblock
+    // Code goes here.
-</pre>
+    // Note the 4-space indent.
 
 `code line`
 
 *italic*
 **bold**
 
-###Types
+### Types
-Here are some examples of possible types and most commonly used ones
+Here are some examples of possible types and most commonly used ones:
+
 ```
 string
 uint32
@@ -126,6 +145,7 @@ int16
 int8
 double
 float
+...
 [EnumName]
 [Player]
 [Creature]
@@ -134,4 +154,4 @@ float
 [Unit]
 [WorldObject]
 [Object]
-```
+```