Update documentation standard.

docs/DOC_GEN.md

@@ -15,21 +15,23 @@
 - Run in cmd `python -m ElunaDoc` when at `\LuaEngine\docs\`
 
 ## 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.
+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).
+
 ```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)
@@ -55,42 +58,55 @@ This is a template for a function that takes in different parameters. When defin
 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 parameter and return value descriptions should start with a lowercase letter and at the end there should be no dot.
+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.
+
+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
 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
- * </pre>
+ *     // Codeblock
+ *     // Code goes here.
+ *     // Note the 4-space indent.
  *
  * `code line`
  *
@@ -98,16 +114,18 @@ 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
-</pre>
+    // Codeblock
+    // Code goes here.
+    // Note the 4-space indent.
 
 `code line`
 
@@ -115,7 +133,8 @@ codeblock
 **bold**
 
 ### 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]