Revision as of 05:08, 6 July 2007

Document Convention

would be nice if these guidlines were followed when editing or adding entries. I like consistency. I wouldn't mind suggestions how to improve them though. Escpecially the way tables are handled may not be butlletproof cause lua tables can be abused in so many ways.

use one page per table if a section of a page may have inaccuracies it should be marked in a way. I use (?)
every table is subdivided into the sections "Functions", "Tables", "Variables"

Functions

every function contains the subsections "Definition", "Description", "Arguments", "Returns", "Example"

Example:
Definition:
ExampleFunction(int arg) -> string ret

Description:
Function that takes a number and returns a string

Arguments:
arg an argument

Returns
ret and outputstring

Example
ExampleFunction(1) -> "1 Example"

Definition

defines the function.

to the left of the arrow specify the function, all variables and their expected types. if an argument can have more than one type the type may be left out.

to the right specify all return values and their types. if there are multiple return values with the same type, subsequent types may be left out.
Example: ExampleFunction(int in) -> string blab blub int blob
this function returns two arguments two of type string and one of type int

valid types are:
float, int (since all numbers in lua are float the distinction is a bit arbitary but int should be used where it makes sense), string, table, userdata. these are reserved words that should not be used as identifiers

tables have the format {type element} where element is a literal key. type is the type of the value. (this won't work too well with non human readable keys though but is probably less messy than other systems) numerals in key names should be avoided.

arrays are defined using {type element1 ..} element1 is a non literal identifier representing all array elements, type is the type of the value

{identifier} may be used to specify a table with undefined contents or layouts not covered by above rules, its content should be descrbed in the arguments or returns sections

Description

short description of the function. maybe related functions or documents. quirks ...

Arguments

short description of each argument specified in definition

Returns

short description of each return value specified in definition

Example

illustrative example code

Tables

tbd

Variables

tbd