From 389f81884459b9de5e5eeb1631d452cc2cc67adf Mon Sep 17 00:00:00 2001 From: Allanis Date: Fri, 2 May 2014 22:06:52 +0100 Subject: [PATCH] [Change] Some more doxygen changes. --- dat/missions/tutorial.lua | 4 +- docs/doxygen/Doxyfile | 4 +- docs/doxygen/luadoc.sh | 5 +- src/llua_faction.c | 57 ++++++------------ src/llua_pilot.c | 121 ++++++++++++-------------------------- src/space.c | 20 ------- 6 files changed, 64 insertions(+), 147 deletions(-) diff --git a/dat/missions/tutorial.lua b/dat/missions/tutorial.lua index 6a597e1..fc8621a 100644 --- a/dat/missions/tutorial.lua +++ b/dat/missions/tutorial.lua @@ -183,7 +183,7 @@ function brakeOver () pilots = pilot.add( "Sml Trader Convoy", "dummy" ) for k,v in ipairs(pilots) do v:setFaction("Dummy") - v:setName("Dummy") + v:rename("Dummy") end misn.timerStart( "targetOver", 20000 ) -- 20 seconds to target else @@ -212,7 +212,7 @@ function addLlamaDummy () pilots = pilot.add( "Trader Llama", "dummy" ) for k,v in ipairs(pilots) do v:setFaction("Dummy") - v:setName("Dummy") + v:rename("Dummy") hook.pilot( v, "disable", "llamaDisabled" ) hook.pilot( v, "death", "llamaDead" ) hook.pilot( v, "board", "llamaBoard" ) diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 3d4f789..2c9204e 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -203,7 +203,9 @@ TAB_SIZE = 8 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = +ALIASES = "luamod=Lua module:" +ALIASES += "luafunc=Lua function:" +ALIASES += "luaparam=Lua function parameter:" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding diff --git a/docs/doxygen/luadoc.sh b/docs/doxygen/luadoc.sh index 4d46543..6d50015 100755 --- a/docs/doxygen/luadoc.sh +++ b/docs/doxygen/luadoc.sh @@ -1,6 +1,6 @@ # Run this from docs directory. # Create docs/lua directory. -if [ ! -d lua ]; then mkdir lua; fi +test -d lua || mkdir lua # Convert doxygen comments to luadoc comments. for F in ../../src/llua_*.c do @@ -16,8 +16,9 @@ sed -n ' s|^ *\* *@luamod *\(.*\)|module "\1"|p #rename some tags: s|^ *\* *@brief|-- @description|p + s|^ *\* *:luaparam|-- @param|p #keep tags luadoc understands: - s|^ *\* *@param|-- @param|p +# s|^ *\* *@param|-- @param|p # Use luaparam, param reserved for C arguments. s|^ *\* *@see|-- @see|p s|^ *\* *@return|-- @return|p s|^ *\* *@usage|-- @usage|p diff --git a/src/llua_faction.c b/src/llua_faction.c index 5bfb611..21b0c56 100644 --- a/src/llua_faction.c +++ b/src/llua_faction.c @@ -207,15 +207,12 @@ int lua_isfaction(lua_State* L, int ind) { } /** - * @fn static int factionL_eq(lua_State* L) - * - * @brief bool __eq(faction comp) - * - * __eq (equality) metamethod for factions. + * @brief __eq (equality) metamethod for factions. * * You can use the '=' operator within Lua to compare factions with this. - * @param comp faction to compare against. + * @luaparam comp faction to compare against. * @return true if both factions are the same. + * @luafunc __eq(comp) */ static int factionL_eq(lua_State* L) { LuaFaction* a, *b; @@ -226,12 +223,9 @@ static int factionL_eq(lua_State* L) { } /** - * @fn static int factionL_name(lua_State* L) - * - * @brief string name(nil) - * - * Get the faction's name. + * @brief Get the faction's name. * @return The name of the faction. + * @luafunc name() */ static int factionL_name(lua_State* L) { LuaFaction* f; @@ -241,12 +235,9 @@ static int factionL_name(lua_State* L) { } /** - * @fn static int factionL_longname(lua_State* L) - * - * @brief string longname(nil) - * - * Get the factions long name. + * @brief Get the factions long name. * @return The long name of the faction. + * @luafunc longname() */ static int factionL_longname(lua_State* L) { LuaFaction* f; @@ -257,9 +248,9 @@ static int factionL_longname(lua_State* L) { /** * @brief Check to see if f is an enemy. - * @param f Faction to check if is an enemy. + * @luaparam f Faction to check if is an enemy. * @return true if they are enemies, false if they aren't. - * @luafunc areEnemies(f) + * @luafunc areEnemies( f ) */ static int factionL_areenemies(lua_State* L) { LuaFaction* f, *ff; @@ -273,9 +264,9 @@ static int factionL_areenemies(lua_State* L) { /** * @brief Check to see if f is an enemy. - * @param f Faction to check if is an enemy. + * @luaparam f Faction to check if is an enemy. * @return true if they are enemies, false if they aren't. - * @luafunc areAllies(f) + * @luafunc areAllies( f ) */ static int factionL_areallies(lua_State* L) { LuaFaction* f, *ff; @@ -288,12 +279,9 @@ static int factionL_areallies(lua_State* L) { } /** - * @fn static int factionL_modplayer(lua_State* L) - * - * @brief modPlayer(number mod) - * - * Modifies the players standing with the faction. - * @param mod The modifier to modify faction by. + * @brief Modifies the players standing with the faction. + * @luaparam mod The modifier to modify faction by. + * @luafunc modPlayer( mod ) */ static int factionL_modplayer(lua_State* L) { LuaFaction* f; @@ -308,14 +296,10 @@ static int factionL_modplayer(lua_State* L) { } /** - * @fn static int factionL_modplayerraw(lua_State* L) - * - * @brief modPlayerRaw(number mod) - * - * Modifies the players standing with the faction. - * + * @brief Modifies the players standing with the faction. * * Does not affect other faction standings. - * @param mod The modifier to modify faction by. + * @luaparam mod The modifier to modify faction by. + * @luafunc modPlayerRaw( mod ) */ static int factionL_modplayerraw(lua_State* L) { LuaFaction* f; @@ -330,12 +314,9 @@ static int factionL_modplayerraw(lua_State* L) { } /** - * @fn static int factionL_playerstanding(lua_State* L) - * - * @brief number, string playerStanding(nil) - * - * Get the players standing with the faction. + * @brief Get the players standing with the faction. * @return The value of the standing and the human readable string. + * @luafunc playerStanding() */ static int factionL_playerstanding(lua_State* L) { LuaFaction* f; diff --git a/src/llua_pilot.c b/src/llua_pilot.c index 22fcb54..0b56337 100644 --- a/src/llua_pilot.c +++ b/src/llua_pilot.c @@ -42,7 +42,6 @@ static int pilotL_velocity(lua_State* L); static int pilotL_warp(lua_State* L); static int pilotL_broadcast(lua_State* L); static int pilotL_setFaction(lua_State* L); -static int pilotL_setName(lua_State* L); static const luaL_reg pilotL_methods[] = { { "__eq", pilotL_eq }, { "name", pilotL_name }, @@ -53,7 +52,6 @@ static const luaL_reg pilotL_methods[] = { { "warp", pilotL_warp }, { "broadcast", pilotL_broadcast }, { "setFaction", pilotL_setFaction }, - { "setName", pilotL_setName }, { 0, 0 } }; /**< Pilot metatable methods. */ @@ -103,6 +101,7 @@ static int pilotL_createmetatable(lua_State* L) { * * @brief Lua bindings to interact with pilots. * + * @luamod pilot * Functions should be called like: * * @code @@ -180,10 +179,9 @@ int lua_ispilot(lua_State* L, int ind) { /** * @ingroup PILOT * - * @brief pilot player(nil) - * - * Get the players pilot. + * @brief Get the players pilot. * @return Pilot pointing to the player. + * @luafunc player() */ static int pilot_getPlayer(lua_State* L) { LuaPilot lp; @@ -199,16 +197,14 @@ static int pilot_getPlayer(lua_State* L) { } /** - * @fn static int pilot_addFleet(lua_State* L) * @ingroup PILOT * - * @brief table add(string fleetname [, string ai, Vec2 pos ]) - * - * Adds a fleet to the system. - * @param fleetname Name of the fleet to add. - * @param ai If set will override the standard fleet AI. "def" means use default. - * @param pos Position to create pilots around instead of choosing randomly. + * @brief Adds a fleet to the system. + * @luaparam fleetname Name of the fleet to add. + * @luaparam ai If set will override the standard fleet AI. "def" means use default. + * @luaparam pos Position to create pilots around instead of choosing randomly. * @return Table populated with all the identifiers of the pilots created. + * @luafunc add(fleetname, ai, pos) */ static int pilot_addFleet(lua_State* L) { LLUA_MIN_ARGS(1); @@ -313,12 +309,9 @@ static int pilot_addFleet(lua_State* L) { } /** - * @fn static int pilot_clear(lua_State* L) * @ingroup PILOT - * - * @brief clear(nil) - * - * Clears the current system of pilots. Used for epic battles and such. + * @brief Clears the current system of pilots. Used for epic battles and such. + * @luafunc clear() */ static int pilot_clear(lua_State* L) { (void) L; @@ -327,15 +320,13 @@ static int pilot_clear(lua_State* L) { } /** - * @fn static int pilot_toggleSpawn(lua_State* L) * @ingroup PILOT * - * @brief bool togglespawn( [bool enable] ) - * - * Disable or enable pilot spawning in the current system. If player jumps + * @brief Disable or enable pilot spawning in the current system. If player jumps * the spawn is enabled again automatically. - * @param enable true enables spawn, false disables it. + * @luaparam enable true enables spawn, false disables it. * @return The current spawn state. + * @luafunc togglespawn(enable) */ static int pilot_toggleSpawn(lua_State* L) { /* Setting it directly. */ @@ -350,13 +341,10 @@ static int pilot_toggleSpawn(lua_State* L) { } /** - * @fn static int pilotL_eq(lua_State* L) - * - * @brief bool __eq(Pilot p) - * - * Check to see if pilot and p are the same. - * @param p Pilot to compare against. + * @brief Check to see if pilot and p are the same. + * @luaparam p Pilot to compare against. * @return true if they are the same. + * @luafunc __eq(pilot) */ static int pilotL_eq(lua_State* L) { LLUA_MIN_ARGS(2); @@ -374,13 +362,11 @@ static int pilotL_eq(lua_State* L) { } /** - * @fn static int pilotL_name(lua_State* L) * @ingroup META_PILOT * - * @brief string name(nil) - * - * Get the pilots current name. + * @brief Get the pilots current name. * @return The current name of the pilot. + * @luafunc name() */ static int pilotL_name(lua_State* L) { LLUA_MIN_ARGS(1); @@ -400,13 +386,11 @@ static int pilotL_name(lua_State* L) { } /** - * @fn static int pilotL_alive(lua_State* L) * @ingroup META_PILOT * - * @brief bool alive(nil) - * - * Checks to see if pilot is still alive. + * @brief Checks to see if pilot is still alive. * @return true if pilot is still alive. + * @luafunc alive() */ static int pilotL_alive(lua_State* L) { LLUA_MIN_ARGS(1); @@ -423,12 +407,9 @@ static int pilotL_alive(lua_State* L) { } /** - * @fn static int pilotL_rename(lua_State* L) - * - * @brief rename(string name) - * - * Changes the pilots name. + * @brief Changes the pilots name. * @param name Name to change to. + * @luafunc rename(name) */ static int pilotL_rename(lua_State* L) { LLUA_MIN_ARGS(2); @@ -455,12 +436,9 @@ static int pilotL_rename(lua_State* L) { } /** - * @fn static int pilotL_position(lua_State* L) - * - * @brief Vec2 pos( nil ) - * - * Get the pilots position. + * @brief Get the pilots position. * @return The pilots current position. + * @luafunc pos() */ static int pilotL_position(lua_State* L) { LLUA_MIN_ARGS(1); @@ -485,10 +463,9 @@ static int pilotL_position(lua_State* L) { * @fn static int pilotL_velocity(lua_State* L) * @ingroup META_PILOT * - * @brief Vec2 vel(nil) - * - * Gets the pilots velocity. + * @brief Gets the pilots velocity. * @return The pilots current velocity. + * @luafunc vel() */ static int pilotL_velocity(lua_State* L) { LLUA_MIN_ARGS(1); @@ -510,11 +487,11 @@ static int pilotL_velocity(lua_State* L) { } /** - * @fn static int pilotL_warp(lua_State* L) * @ingroup META_PILOT * - * @brief Vec2 position. - * @return The pilots current position. + * @brief Set the pilots position. + * @luaparam pos Position to set. + * @luafunc warp( pos ) */ static int pilotL_warp(lua_State* L) { LLUA_MIN_ARGS(2); @@ -539,13 +516,11 @@ static int pilotL_warp(lua_State* L) { } /** - * @fn static int pilotL_broadcast(lua_State* L) * @ingroup META_PILOT * - * @brief broadcast(string msg) - * - * Make the pilot broadcast a message. - * @param msg Message to broadcast. + * @brief Make the pilot broadcast a message. + * @luaparam msg Message to broadcast. + * @luafunc broadcast(msg) */ static int pilotL_broadcast(lua_State* L) { LLUA_MIN_ARGS(2); @@ -570,7 +545,11 @@ static int pilotL_broadcast(lua_State* L) { } /** - * @fn + * @ingroup META_PILOT + * + * @brief Set the pilots faction. + * @luaparam faction Faction to set by name or faction. + * @luafunc setFaction( faction ) */ static int pilotL_setFaction(lua_State* L) { LLUA_MIN_ARGS(2); @@ -602,29 +581,3 @@ static int pilotL_setFaction(lua_State* L) { return 0; } -/** - * - */ -static int pilotL_setName(lua_State* L) { - LLUA_MIN_ARGS(2); - LuaPilot* lp; - Pilot* p; - char* name; - - /* Get the parameters. */ - lp = lua_topilot(L, 1); - if(lua_isstring(L, 2)) - name = (char*)lua_tostring(L, 2); - else LLUA_INVALID_PARAMETER(); - - p = pilot_get(lp->pilot); - if(p == NULL) return 0; - - /* Set the name. */ - if(p->name != NULL) - free(p->name); - p->name = strdup(name); - - return 0; -} - diff --git a/src/space.c b/src/space.c index 9364aa4..635ac2d 100644 --- a/src/space.c +++ b/src/space.c @@ -447,8 +447,6 @@ void space_update(const double dt) { } /** - * @fn static void space_addFleet(Fleet* fleet) - * * @brief Create a fleet. * @param fleet Fleet to add to the system. * @param init Is being run during the space initialization. @@ -605,8 +603,6 @@ void space_init(const char* sysname) { } /** - * @fn static int planets_load(void) - * * @brief Load all the planets in the game. * @return 0 on success. */ @@ -657,8 +653,6 @@ static int planets_load(void) { } /** - * @fn static int planet_parse(Planet* planet, const xmlNodePtr parent) - * * @brief Parses a planet from an xml node. * @param planet Planet to fill up. * @param parent Node that contains planet data. @@ -795,8 +789,6 @@ static int planet_parse(Planet* planet, const xmlNodePtr parent) { } /** - * @fn int system_addPlanet(StarSystem* sys, char* planetname) - * * @brief Add a planet to a star system. * @param sys Star System to add planet to. * @param planetname Name of the planet to add. @@ -840,8 +832,6 @@ int system_addPlanet(StarSystem* sys, char* planetname) { } /** - * @fn int system_rmPlanet(StarSystem* sys, char* planetname) - * * @brief Remove a planet from a star system. * @param sys Star System to remove planet from. * @param planetname Name of the planet to remove. @@ -897,8 +887,6 @@ int system_rmPlanet(StarSystem* sys, char* planetname) { } /** - * @fn int system_addFleet(StarSystem* sys, SystemFleet* fleet) - * * @brief Add a fleet to a star system. * @param sys Star system to add fleet to. * @param fleet Fleet to add. @@ -915,8 +903,6 @@ int system_addFleet(StarSystem* sys, SystemFleet* fleet) { } /** - * @fn int system_rmFleet(StarSystem* sys, SystemFleet* fleet) - * * @brief Remove a fleet from a star system. * @param sys Star System to remove fleet from. * @param fleet Fleet to remove. @@ -1050,8 +1036,6 @@ static StarSystem* system_parse(StarSystem* sys, const xmlNodePtr parent) { } /** - * @fn static void system_setFaction(StarSystem* sys) - * * @brief Set the system faction based on the planet it has. * @param sys System to set the faction of. */ @@ -1106,8 +1090,6 @@ static void system_parseJumps(const xmlNodePtr parent) { } /** - * @fn int space_load(void) - * * @brief Load the ENTIRE universe into RAM. -- WOAH! * @return 0 on success. */ @@ -1125,8 +1107,6 @@ int space_load(void) { } /** - * @fn int systems_load(void) - * * @brief Load the entire systems, needs to be called after planets_load. * * Uses a two system pass to first load the star systems_stack and then set