mod-ale/docs/DOC_GEN.md

#Documentation generation

##Setting up

• install python(2)
• when installing, tick to install the path variable
• may need restart after for installation to properly take effect
• install a package manager like pip
• if installed pip and doesnt work, restart or try easy_install command
• install the dependencies with manager
• Jinja2
• typedecorator
• markdown

##Generating

• 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.

###Template Here are basic templates for a function. When defining a parameter or a return value, the type and value name are mandatory.

/**
 * Description.
 *
 * @param Type paramName
 * @return Type returnName
 */

/**
 * Description.
 *
 * @param Type paramName = defaultValue : parameter description
 * @return Type returnName : return value description
 */

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.

/**
 * Description.
 *
 * @proto returnValue = (object)
 * @proto returnValue = (x, y, z)
 * @param [WorldObject] object = defaultValue : parameter description
 * @param float x = defaultValue : parameter description
 * @param float y = defaultValue : parameter description
 * @param float z = defaultValue : parameter description
 * @return Type returnName : return value description
 */

###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 parameter and return value descriptions should start with a lowercase letter and at the end there should be no dot.

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

/**
 * Correct indentation.
 * @param Type paramName = defaultValue : parameter description
 * @return Type returnName : return value description
 */

/**
* Invalid indentation.
* @param Type paramName = defaultValue : parameter description
* @return Type returnName : return value description
*/

###Markdown You can use 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
 *
 * <pre>
 * codeblock
 * </pre>
 *
 * `code line`
 *
 * *italic*
 * **bold**
 */

Produces
Description.

• list item
• list item
• list item

codeblock

code line

italic bold

###Types Here are some examples of possible types and most commonly used ones

string
uint32
uint16
uint8
int32
int16
int8
double
float
[EnumName]
[Player]
[Creature]
[GameObject]
[Item]
[Unit]
[WorldObject]
[Object]