From 8cf010bef456cd2f8318ad83eccb67a59a0a2790 Mon Sep 17 00:00:00 2001 From: Walter Julius Hennecke Date: Mon, 29 Apr 2013 23:45:53 +0200 Subject: [PATCH] Lua documentation update and config.ld for LDoc --- code/game/config.ld | 12 ++ code/game/lua_cinematic.c | 5 + code/game/lua_cvar.c | 28 +++++ code/game/lua_entity.c | 6 + code/game/lua_game.c | 86 ++++++++++---- code/game/lua_mover.c | 5 + code/game/lua_qmath.c | 237 +++++++++++++++++++++++++++++--------- code/game/lua_sound.c | 5 + code/game/lua_trace.c | 6 + code/game/lua_vector.c | 5 + code/game/lua_weapons.c | 5 + 11 files changed, 323 insertions(+), 77 deletions(-) create mode 100644 code/game/config.ld diff --git a/code/game/config.ld b/code/game/config.ld new file mode 100644 index 0000000..213300c --- /dev/null +++ b/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' } diff --git a/code/game/lua_cinematic.c b/code/game/lua_cinematic.c index 2de0c3f..657a057 100644 --- a/code/game/lua_cinematic.c +++ b/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) { diff --git a/code/game/lua_cvar.c b/code/game/lua_cvar.c index ae97224..a316b32 100644 --- a/code/game/lua_cvar.c +++ b/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)); diff --git a/code/game/lua_entity.c b/code/game/lua_entity.c index 1f22e5f..72dab67 100644 --- a/code/game/lua_entity.c +++ b/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 diff --git a/code/game/lua_game.c b/code/game/lua_game.c index 4610504..ae951d5 100644 --- a/code/game/lua_game.c +++ b/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; diff --git a/code/game/lua_mover.c b/code/game/lua_mover.c index 54e2249..684f908 100644 --- a/code/game/lua_mover.c +++ b/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) { diff --git a/code/game/lua_qmath.c b/code/game/lua_qmath.c index e46d4b3..e2d2396 100644 --- a/code/game/lua_qmath.c +++ b/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))); diff --git a/code/game/lua_sound.c b/code/game/lua_sound.c index fea0b07..edb2bfd 100644 --- a/code/game/lua_sound.c +++ b/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 diff --git a/code/game/lua_trace.c b/code/game/lua_trace.c index 6c5e760..5ab5080 100644 --- a/code/game/lua_trace.c +++ b/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) { diff --git a/code/game/lua_vector.c b/code/game/lua_vector.c index e7404ed..e61076a 100644 --- a/code/game/lua_vector.c +++ b/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) { diff --git a/code/game/lua_weapons.c b/code/game/lua_weapons.c index febf96c..23d2654 100644 --- a/code/game/lua_weapons.c +++ b/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) {