Lua documentation update and config.ld for LDoc

code/game/config.ld

@@ -0,0 +1,12 @@
+project = "RPG-X 2.3 Lua Documentation Server Side"
+format = "markdown"
+file = {'lua_cinematic.c',
+        'lua_cvar.c',
+		'lua_entity.c',
+		'lua_game.c',
+		'lua_mover.c',
+		'lua_qmath.c',
+		'lua_sound.c',
+		'lua_trace.c',
+		'lua_vector.c',
+		'lua_weapons.c' }

code/game/lua_cinematic.c

@@ -5,6 +5,11 @@
 
 #ifdef G_LUA
 
+/***
+A library for cinematics. Not finished and therfore not further documented.
+@module cinematic
+*/
+
 // cinematic.Activate(entity ent, entity target)
 // Activates Camera on ent and points it at target.
 static int Cinematic_Activate(lua_State *L) {

code/game/lua_cvar.c

@@ -5,7 +5,17 @@
 
 #ifdef G_LUA
 
+/***
+This module allows getting and setting game cvars.
+@module cvar
+*/
 
+/***
+Get cvar value as integer.
+@function integer
+@param name Cvar name.
+@return Cvar value as integer.
+*/
 static int Cvar_Integer(lua_State *L) {
 	char *cvar;
 	char buf[1024];
@@ -27,6 +37,12 @@ static int Cvar_Integer(lua_State *L) {
 	return 1;
 }
 
+/***
+Get cvar value as floating point number.
+@function value
+@param name Cvar name.
+@return Cvar value as floating point number.
+*/
 static int Cvar_Value(lua_State *L) {
 	char *cvar;
 	char buf[1024];
@@ -48,6 +64,12 @@ static int Cvar_Value(lua_State *L) {
 	return 1;
 }
 
+/***
+Get cvar value as string.
+@function string
+@param name Cvar name.
+@return Cvar value as string.
+*/
 static int Cvar_String(lua_State *L) {
 	char *cvar;
 	char buf[1024];
@@ -69,6 +91,12 @@ static int Cvar_String(lua_State *L) {
 	return 1;
 }
 
+/***
+Get value for rpg_phaserdmg as number.
+@function integer
+@param name Cvar name.
+@return Value for rpg_phaserdmg as number.
+*/
 static int Cvar_rpg_phaserdmg(lua_State *L) {
 	lua_pushnumber(L, (rpg_dmgFlags.integer & 1));
 

code/game/lua_entity.c

@@ -6,6 +6,12 @@
 extern qboolean G_CallSpawn(gentity_t *ent);
 
 #ifdef G_LUA
+
+/***
+Module to access entity functions and manage enities. Documentation under work.
+@module entiy
+*/
+
 // entity.MMBRefit()
 // this is just a function called from lua
 // it should be called before any other model work

code/game/lua_game.c

@@ -3,8 +3,17 @@
 #include "g_lua.h"
 
 #ifdef G_LUA
-// game.Print(string text)
-// Prints text to the server console
+
+/***
+This module provides access to some of the servers functionality.
+@module game
+*/
+
+/***
+Prints text to the servers console.
+@function Print
+@param test Text to print.
+*/
 static int Game_Print(lua_State *L) {
 	int		i;
 	char	buf[MAX_STRING_CHARS];
@@ -42,9 +51,12 @@ static int Game_Print(lua_State *L) {
 	return 0;
 }
 
-// game.CenterPrint(integer clientNum, string text)
-// Prints text to the center of the screen of the client with client number clientNum. 
-// If clientNum is -1 the text gets printed for all clients.
+/***
+Prints text to the center of the screen of the client with client number clientNum. If clientNum is -1 the text gets printed for all clients.
+@function CenterPrint
+@param clientNum Client number.
+@param text Text to print.
+*/
 static int Game_CenterPrint(lua_State *L) {
 	int			i;
 	char		buf[MAX_STRING_CHARS];
@@ -86,9 +98,12 @@ static int Game_CenterPrint(lua_State *L) {
 	return 1;
 }
 
-// game.ClientPrint(integer clientNum, string text)
-// Prints text to the clients console that has the client number clientNum. 
-// If clientNum is -1 the text gets printed to all clients consoles.
+/***
+Prints text to the clients console that has the client number clientNum. If clientNum is -1 the text gets printed to all clients consoles.
+@function ClientPrint
+@param clientNum Client number.
+@param text Text to print.
+*/
 static int Game_ClientPrint(lua_State *L) {
 	int			i;
 	char		buf[MAX_STRING_CHARS];
@@ -136,9 +151,12 @@ static int Game_ClientPrint(lua_State *L) {
 	return 1;
 }
 
-// game.MessagePrint(integer clientNum, string text)
-// Prints text to the lower right corner of the screen of the client with client number clientNum. 
-// If clientNum is -1 the text gets printed for all clients.
+/***
+Prints text to the lower right corner of the screen of the client with client number clientNum. If clientNum is -1 the text gets printed for all clients.
+@functiton MessagePrint
+@param clientNum Client number.
+@param text Text tp print.
+*/
 static int Game_MessagePrint(lua_State *L) {
 	int			i;
 	char		buf[MAX_STRING_CHARS];
@@ -179,10 +197,12 @@ static int Game_MessagePrint(lua_State *L) {
 	return 1;
 }
 
-// game.SetGlobal(string name, value)
-// Sets a global Lua variable which is called name to value. 
-// Creates a new global variable if a variable of name does not exist. 
-// value can be of any type.
+/***
+Sets a global Lua variable which is called name to value. Creates a new global variable if a variable of name does not exist. Value can be of any type.
+@function SetGlobal
+@param name Name of global variable.
+@param value New value for global variable.
+*/
 static int Game_SetGlobal(lua_State *L) {
 	char *name;
 
@@ -204,9 +224,12 @@ static int Game_SetGlobal(lua_State *L) {
 	return 0;
 }
 
-// game.GetGlobal(string name)
-// Returns the value of the global variable name. 
-// Returns nil if the variable does not exist.
+/***
+Returns the value of the global variable name. Returns nil if the variable does not exist.
+@function GetGlobal
+@param name Name of Global variable.
+@return value of Global variable.
+*/
 static int Game_GetGlobal(lua_State *L) {
 	char *name;
 
@@ -330,8 +353,11 @@ static int Game_Alert(lua_State *L) {
 	return 0;
 }
 
-// game.LevelTime()
-// Returns the current level time in milliseconds.
+/***
+Get the current level time in milliseconds. Level time is the time since level start.
+@function LevelTime
+@return Level time in milliseconds.
+*/
 static int Game_Leveltime(lua_State * L)
 {
 	LUA_DEBUG("BEGIN - game.Leveltime");
@@ -343,6 +369,19 @@ static int Game_Leveltime(lua_State * L)
 	return 1;
 }
 
+/***
+Damage and player or entity.
+@function Damage
+@param target Target entity.
+@param inflictor Inflicting entity. Can be nil.
+@param attacker Attacking entity. Can be nil.
+@param direction Direction of knockback. Can be nil.
+@param point Point where the damage is inflicted. Can be nil.
+@param damage Ammount of damage.
+@param dflags Damage flags.
+@param mod Means of death.
+@return Success or fail.
+*/
 static int Game_Damage(lua_State *L) {
 	lent_t *lent;
 	gentity_t *targ = NULL, *inflictor = NULL, *attacker = NULL;
@@ -387,6 +426,13 @@ static int Game_Damage(lua_State *L) {
 	return 1;
 }
 
+/***
+Repair an entity.
+@function Repair
+@param target Target entity.
+@param rate Repair rate.
+@return Success or fail.
+*/
 static int Game_Repair(lua_State *L) {
 	lent_t *lent;
 	float rate;

code/game/lua_mover.c

@@ -3,6 +3,11 @@
 #include "g_lua.h"
 
 #ifdef G_LUA
+/***
+A module for entity movement, especially for mover entities such as doors. Documentation under work.
+@module mover
+*/
+
 // mover.Halt(entity ent)
 // Stops translational movement on ent immediately.
 static int Mover_Halt(lua_State *L) {

code/game/lua_qmath.c

@@ -3,96 +3,152 @@
 #include "g_lua.h"
 
 #ifdef G_LUA
-// qmath.abs(float f)
-// Returns the integer part of f.
+/***
+Provides access to many mathematical functions.
+@module qmath
+*/
+
+/***
+Get the integer part of a number.
+@function abs
+@param number Number
+@return Integer part of number.
+*/
 static int Qmath_Abs(lua_State * L)
 {
 	lua_pushnumber(L, fabs(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.sin(float degree)
-// Returns the sine of degree.
+/***
+Get the sine for a number (degree).
+@function sin
+@param number Number
+@return Sine of number.
+*/
 static int Qmath_Sin(lua_State * L)
 {
 	lua_pushnumber(L, sin(DEG2RAD(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.cos(float degree)
-// Returns the cosine of degree.
+/***
+Get the cosine for a number (degree).
+@function cos
+@param number Number
+@return Consine of number.
+*/
 static int Qmath_Cos(lua_State * L)
 {
 	lua_pushnumber(L, cos(DEG2RAD(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.tan(float degree)
-// Returns the tangent of degree.
+/***
+Get the tangent for a number.
+@function tan
+@param number Number
+@return Tangent of number.
+*/
 static int Qmath_Tan(lua_State * L)
 {
 	lua_pushnumber(L, tan(DEG2RAD(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.asin(float f)
-// Returns the arcsine of f.
+/***
+Get the arcsine for a number.
+@function asin
+@param number Number
+@return arcsine for number.
+*/
 static int Qmath_Asin(lua_State * L)
 {
 	lua_pushnumber(L, RAD2DEG(asin(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.acos(float f)
-// Returns the arccosine of f.
+/***
+Get the arccosine for a number.
+@function acos
+@param number Number
+@return arccosine of number.
+*/
 static int Qmath_Acos(lua_State * L)
 {
 	lua_pushnumber(L, RAD2DEG(acos(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.atan(float f)
-// Returns the arctangent of f.
+/***
+Get the arctangent for a number.
+@function atan
+@param number Number
+@return arctangent of number.
+*/
 static int Qmath_Atan(lua_State * L)
 {
 	lua_pushnumber(L, RAD2DEG(atan(luaL_checknumber(L, 1))));
 	return 1;
 }
 
-// qmath.atan2
+/***
+Get the arctangent for a number. Alternate to atan.
+@function atan2
+@param number Number
+@return arctangent of number.
+*/
 static int Qmath_Atan2(lua_State * L)
 {
 	lua_pushnumber(L, RAD2DEG(atan2(luaL_checknumber(L, 1), luaL_checknumber(L, 2))));
 	return 1;
 }
 
-// qmath.ceil(float f)
-// Returns the ceiled value of f.
+/***
+Get the ceiled value of a number.
+@function ceil
+@param number Number
+@return Ceiled value of number.
+*/
 static int Qmath_Ceil(lua_State * L)
 {
 	lua_pushnumber(L, ceil(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.floor(float f)
-// Returns the floored value of f.
+/***
+Get the floored value of a number.
+@function floor
+@param numerb Number
+@return Floored value of number.
+*/
 static int Qmath_Floor(lua_State * L)
 {
 	lua_pushnumber(L, floor(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.fmod(float f, float n)
-// Returns the remainder of f=n.
+/***
+Get the remainder of numerator/denominator.
+@functiom fmod
+@param n numerator
+@param f denominator
+@return Remainder of numerator/denominator.
+*/
 static int Qmath_Fmod(lua_State * L)
 {
 	lua_pushnumber(L, fmod(luaL_checknumber(L, 1), luaL_checknumber(L, 2)));
 	return 1;
 }
 
-// qmath.modf(float f)
-// Breaks f apart into its integer part and its fractional part.
-// The fractional part is returned while the integer part is assigned to f.
+/***
+BUGGED
+Breaks a given number apart into its integer part and its fractional part. The fractional part is returned while the integer part is assigned to number.
+@function modf
+@param number Number
+@return Array containing integer and fractional part.
+*/
+/* TODO return an array the current way won't work */
 static int Qmath_Modf(lua_State * L)
 {
 	double          ip;
@@ -103,65 +159,100 @@ static int Qmath_Modf(lua_State * L)
 	return 2;
 }
 
-// qmath.sqrt(float f)
-// Returns the square root of f.
+/***
+Get the square root of a number.
+@function sqrt
+@param number Number
+@return Square root of number.
+*/
 static int Qmath_Sqrt(lua_State * L)
 {
 	lua_pushnumber(L, sqrt(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.pow(float f, float n)
-// What's this??
+// What's this?? f^n e.g. 2^4 = 2 * 2 * 2 = 8
+/***
+Returns f raised to the power of n.
+@function pow
+@param f Number
+@param n Number
+@return f raised to the power of n.
+*/
 static int Qmath_Pow(lua_State * L)
 {
 	lua_pushnumber(L, pow(luaL_checknumber(L, 1), luaL_checknumber(L, 2)));
 	return 1;
 }
 
-// qmath.log(float f)
-// Returns logarithm of f.
+/***
+Get the logarithm of a number.
+@function log
+@param number Number
+@return Logarithm of number.
+*/
 static int Qmath_Log(lua_State * L)
 {
 	lua_pushnumber(L, log(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.log10(float f)
-// Returns logarithm to base 10 of f.
+/***
+Get logarithm to the base of 10 of number.
+@function log10
+@param number Number
+@return Logarithm to the base of 10 of number.
+*/
 static int Qmath_Log10(lua_State * L)
 {
 	lua_pushnumber(L, log10(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.exp(float number)
-// What's this??
+/***
+Get the base-e exponential function of a given number.
+@function exp
+@param number Number
+@return Base-e exponential of number.
+*/
 static int Qmath_Exp(lua_State * L)
 {
 	lua_pushnumber(L, exp(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.deg(float radian)
-// Converts radian to degree.
+/***
+Convert radian to degree.
+@function deg
+@param number Number
+@return number converted to degree.
+*/
 static int Qmath_Deg(lua_State * L)
 {
 	lua_pushnumber(L, RAD2DEG(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.rad(float dgree)
-// Converts degree to radian.
+/***
+Convert degree to radian.
+@function rad
+@param number Number
+@return number converted to radian.
+*/
 static int Qmath_Rad(lua_State * L)
 {
 	lua_pushnumber(L, DEG2RAD(luaL_checknumber(L, 1)));
 	return 1;
 }
 
-// qmath.frexp(float f)
-// Breaks f into its binary significant and an integral exponent for 2.
-// x = significant 2exponent
+/***
+BUGGED
+Breaks a number into its binary significant and an integral exponent for 2.
+@function frexp
+@param number
+@return Array containing binary significant and integral exponent for 2.
+*/
+/* TODO return array */
 static int Qmath_Frexp(lua_State * L)
 {
 	int             e;
@@ -171,8 +262,13 @@ static int Qmath_Frexp(lua_State * L)
 	return 2;
 }
 
-// qmath.ldexp(float f, float n)
-// Returns the result from multiplying f by 2 raised to the power of n.
+/***
+Get the result from multiplying f by 2 raised to the power of n.
+@function ldexp
+@param f Number
+@param n Number
+@return The result from multiplying f by 2 raised to the power of n.
+*/
 static int Qmath_Ldexp(lua_State * L)
 {
 	lua_pushnumber(L, ldexp(luaL_checknumber(L, 1), luaL_checkint(L, 2)));
@@ -180,8 +276,12 @@ static int Qmath_Ldexp(lua_State * L)
 }
 
 
-// qmath.min(int array[])
-// Return the lowest value in array[].
+/***
+Get the lowest value in array[].
+@function min
+@param array Array of numbers.
+@return the lowest value in the array.
+*/
 static int Qmath_Min(lua_State * L)
 {
 	int             n = lua_gettop(L);	/* number of arguments */
@@ -199,8 +299,12 @@ static int Qmath_Min(lua_State * L)
 	return 1;
 }
 
-// qmath.max(int array[])
-// Return the highest value in array[].
+/***
+Get the highest value in array[].
+@function min
+@param array Array of numbers.
+@return the highest value in the array.
+*/
 static int Qmath_Max(lua_State * L)
 {
 	int             n = lua_gettop(L);	/* number of arguments */
@@ -218,40 +322,59 @@ static int Qmath_Max(lua_State * L)
 	return 1;
 }
 
-// qmath.rand()
-// Returns a random integer.
+/***
+Get a random integer.
+@function rand
+@return Random integer.
+*/
 static int Qmath_Rand(lua_State * L)
 {
 	lua_pushinteger(L, rand());
 	return 1;
 }
 
-// qmath.random()
-// Returns a random float.
+/***
+Get a random floating point number.
+@function random
+@return Random floating point number.
+*/
 static int Qmath_Random(lua_State * L)
 {
 	lua_pushnumber(L, random());
 	return 1;
 }
 
-// qmath.crandom()
-// Returns random floats (crazy random function).
+/***
+Get a random floating point number (using crazy random function).
+@function crandom
+@return A random floating point number (using crazy random function).
+*/
 static int Qmath_Crandom(lua_State * L)
 {
 	lua_pushnumber(L, crandom());
 	return 1;
 }
 
-// qmath.irandom(int i, int j)
-// Returns a random integer from the range of integers defined by and including i and j.
+/***
+Get a random integer from the range of integers defined by and including i and j.
+@function irandom
+@param i Number, lower limit.
+@param j Number, upper limit.
+@return A random integer from the range of integers defined by and including i and j.
+*/
 static int Qmath_Irandom(lua_State * L)
 {
 	lua_pushnumber(L, irandom(luaL_checkint(L, 1), luaL_checkint(L, 2)));
 	return 1;
 }
 
-// qmath.flrandom(float i, float j)
-// Returns a random float from the range of floats defined by and including i and j.
+/***
+Get a random float from the range of floats defined by and including i and j.
+@function flrandom
+@param i Number, lower limit.
+@param j Number, upper limit.
+@return A random float from the range of floats defined by and including i and j.
+*/
 static int Qmath_FLrandom(lua_State * L)
 {
 	lua_pushnumber(L, flrandom(luaL_checknumber(L, 1), luaL_checknumber(L, 2)));

code/game/lua_sound.c

@@ -4,6 +4,11 @@
 
 #ifdef G_LUA
 
+/***
+A documentation to play sounds. Documentation under work.
+@module sound
+*/
+
 // sound.PlaySound(entity ent, string sound, integer chan)
 // * ent the entity the sound will be played on
 // * sound the sound file which will be played

code/game/lua_trace.c

@@ -3,6 +3,12 @@
 #include "g_lua.h"
 
 #ifdef G_LUA
+
+/***
+A module allowing to do traces. Documentation under work.
+@module trace
+*/
+
 static int Trace_GC(lua_State * L)
 {
 

code/game/lua_vector.c

@@ -8,6 +8,11 @@
 #include "lauxlib.h"
 #include "lualib.h"
 
+/***
+A module implementing vectors. Documentation under work.
+@module vector
+*/
+
 // vector.New()
 // Allocates and returns a new vector (0|0|0).
 static int Vector_New(lua_State *L) {

code/game/lua_weapons.c

@@ -4,6 +4,11 @@
 
 #ifdef G_LUA
 
+/***
+A module for everything converning weapons. Documentation under way.
+@module weapons
+*/
+
 #include "g_weapon.h"
 
 static int weapon_GetForward(lua_State *L) {