From d8fd4383b4911b924d9fc9a5b0df520c1f176488 Mon Sep 17 00:00:00 2001
From: Allanis <allanis@saracraft.net>
Date: Wed, 14 May 2014 16:24:51 +0100
Subject: [PATCH] [Add] More work on documentation.
---
src/ai.c | 10 +++
src/comm.c | 2 +-
src/dialogue.c | 5 +-
src/faction.c | 3 +-
src/input.c | 43 +++++++----
src/land.c | 189 ++++++++++++++++++++++++++++++++++++++-------
src/ldata.c | 4 +-
src/lephisto.c | 14 +---
src/llua_faction.c | 17 +---
src/llua_misn.c | 19 +++--
src/mission.c | 1 +
src/nebulae.c | 14 ++--
src/options.c | 2 +-
src/outfit.c | 25 +++++-
src/pack.c | 20 +++--
src/pause.c | 9 ++-
src/perlin.c | 7 +-
src/pilot.c | 135 ++++++++++++++------------------
18 files changed, 336 insertions(+), 183 deletions(-)
diff --git a/src/ai.c b/src/ai.c
index 327acea..c9be95d 100644
--- a/src/ai.c
+++ b/src/ai.c
@@ -1342,6 +1342,11 @@ static int ai_settarget(lua_State* L) {
LLUA_INVALID_PARAMETER();
}
+/**
+ * @brief Check to see if an outfit is a melee weapon.
+ * @param p Pilot to check for.
+ * @param o Outfit to check.
+ */
static int outfit_isMelee(Pilot* p, PilotOutfit* o) {
(void)p;
if(outfit_isBolt(o->outfit) || outfit_isBeam(o->outfit))
@@ -1349,6 +1354,11 @@ static int outfit_isMelee(Pilot* p, PilotOutfit* o) {
return 0;
}
+/**
+ * @brief Check to see if an outfit is a ranged weapon.
+ * @param p Pilot to check for.
+ * @param o Outfit to check.
+ */
static int outfit_isRanged(Pilot* p, PilotOutfit* o) {
if(outfit_isFighterBay(o->outfit) || outfit_isLauncher(o->outfit)) {
/* Must have ammo. */
diff --git a/src/comm.c b/src/comm.c
index 9c1910f..c84bb6a 100644
--- a/src/comm.c
+++ b/src/comm.c
@@ -24,7 +24,7 @@ static void comm_bribe(unsigned int wid, char* unused);
static unsigned int comm_getBribeAmount(void);
static char* comm_getBribeString(char* str);
/* Extern. */
-extern void ai_setPilot(Pilot* p);
+extern void ai_setPilot(Pilot* p); /**< From ai.c. */
/**
* @brief Open the communication dialogue with a pilot.
diff --git a/src/dialogue.c b/src/dialogue.c
index 98b9339..84900aa 100644
--- a/src/dialogue.c
+++ b/src/dialogue.c
@@ -90,8 +90,9 @@ static void dialogue_alertClose(unsigned int wid, char* str) {
/**
* @brief Get the size needed for the dialogue.
* @param msg Message of the dialogue.
- * @param[out] w Get the width needed.
- * @param[out] h Get the height needed.
+ * @param[out] width Get the width needed.
+ * @param[out] height Get the height needed.
+ * @return The font that matches the size.
*/
static glFont* dialogue_getSize(char* msg, int* width, int* height) {
glFont* font;
diff --git a/src/faction.c b/src/faction.c
index b0661c8..6fc79b6 100644
--- a/src/faction.c
+++ b/src/faction.c
@@ -431,9 +431,8 @@ static int faction_isFaction(int f) {
}
/**
- * @fn static Faction* faction_parse(xmlNodePtr parent)
- *
* @brief Parses a single faction, but doesn't set the allies/enemies bit.
+ * @param tmp Faction to load data into.
* @param parent Parent node to extract faction from.
* @return Faction created from parent node.
*/
diff --git a/src/input.c b/src/input.c
index 2def5fd..a8bbdda 100644
--- a/src/input.c
+++ b/src/input.c
@@ -53,7 +53,9 @@ const char* keybindNames[] = {
"hail",
/* Misc. */
"mapzoomin", "mapzoomout", "screenshot", "pause", "speed", "menu", "info",
- "end" /* Must terminate at the end. */
+ /* Must terminate in "end". */
+ "end"
+ /**< Names of possible keybindings. */
};
/* Keybinding descriptions. Should match in position of the names. */
@@ -99,7 +101,8 @@ const char* keybindDescription[] = {
"Pauses the game.",
"Opens the small ingame menu.",
"Opens the information menu."
-};
+}; /**< Descriptions of the keybindings. Should be in the same position as the
+ matching keybinding name. */
/* Accel hacks. */
static unsigned int input_accelLast = 0; /**< Used to see if double tap. */
@@ -293,14 +296,6 @@ const char* input_getKeybindDescription(char* keybind) {
return NULL;
}
-/**
- * @fn static void input_key(int keynum, double value, int kabs)
- *
- * @brief Run the input command.
- * @param keynum The index of the keybind.
- * @param value The value of the keypress (defined above).
- * @param abs Whether or not it's an absolute value (for the joystick).
- */
#define KEY(s) (strcmp(input_keybinds[keynum]->name, s)==0) /**< Shortcut for ease. */
#define INGAME() (!toolkit && !paused) /**< Make sure player is in game. */
#define NOHYP() \
@@ -309,6 +304,13 @@ const char* input_getKeybindDescription(char* keybind) {
!pilot_isFlag(player, PILOT_HYPERSPACE)) /**< Make sure player isn't jumping. */
#define NODEAD() (player) /**< Player isn't dead. */
#define NOLAND() (!landed) /**< Player isn't landed. */
+
+/**
+ * @brief Run the input command.
+ * @param keynum The index of the keybind.
+ * @param value The value of the keypress (defined above).
+ * @param kabs Whether or not it's an absolute value (for the joystick).
+ */
static void input_key(int keynum, double value, int kabs) {
unsigned int t;
@@ -528,7 +530,11 @@ static void input_keyevent(int event, SDLKey key, SDLMod mod);
/* Joystick. */
-/* Axis. */
+/**
+ * @brief Filters a joystick axis event.
+ * @param axis Axis generated by the event.
+ * @param value Value of the axis.
+ */
static void input_joyaxis(const unsigned int axis, const int value) {
int i;
for(i = 0; strcmp(keybindNames[i], "end"); i++)
@@ -537,7 +543,11 @@ static void input_joyaxis(const unsigned int axis, const int value) {
input_key(i, -(input_keybinds[i]->reverse) * (double)value / 32767., 1);
}
-/* Joystick event. */
+/**
+ * @brief Filters a joystick button event.
+ * @param event Event type (down/up).
+ * @param button Button generating the event.
+ */
static void input_joyevent(int event, const unsigned int button) {
int i;
for(i = 0; strcmp(keybindNames[i], "end");i++)
@@ -548,7 +558,12 @@ static void input_joyevent(int event, const unsigned int button) {
/* Keyboard. */
-/* Key event. */
+/**
+ * @brief Filters a keyboard event.
+ * @param event Event type(down/up).
+ * @param key Key generating the event.
+ * @param mod Modifiers active when event was generated.
+ */
static void input_keyevent(int event, SDLKey key, SDLMod mod) {
int i;
@@ -563,8 +578,6 @@ static void input_keyevent(int event, SDLKey key, SDLMod mod) {
/**
- * @fn void input_handle(SDL_Event* event)
- *
* @brief Handle global input.
*
* Basically seperates the event types.
diff --git a/src/land.c b/src/land.c
index a2d2d52..c945452 100644
--- a/src/land.c
+++ b/src/land.c
@@ -50,27 +50,28 @@
#define MISSION_HEIGHT 600
/* We use visited flags to not duplicate missions generated. */
-#define VISITED_LAND (1<<0)
-#define VISITED_COMMODITY (1<<1)
-#define VISITED_BAR (1<<2)
-#define VISITED_OUTFITS (1<<3)
-#define VISITED_SHIPYARD (1<<4)
-#define visited(f) (land_visited |= (f))
-#define has_visited(f) (land_visited & (f))
+#define VISITED_LAND (1<<0) /**< Player already landed. */
+#define VISITED_COMMODITY (1<<1) /**< Player already visited commodities. */
+#define VISITED_BAR (1<<2) /**< Player already visited bar. */
+#define VISITED_OUTFITS (1<<3) /**< Player already visited outfits. */
+#define VISITED_SHIPYARD (1<<4) /**< Player already visited shipyard. */
+#define visited(f) (land_visited |= (f)) /**< Mark place is visited. */
+#define has_visited(f) (land_visited & (f)) /**< Check if player has visited. */
static unsigned int land_visited = 0;
/* Land variables. */
-int landed = 0;
+int landed = 0; /**< Is player landed. */
static unsigned int land_wid = 0; /**< Land window ID. */
-Planet* land_planet = NULL;
-static glTexture* gfx_exterior = NULL;
+
+Planet* land_planet = NULL; /**< Planet player landed at. */
+static glTexture* gfx_exterior = NULL; /**< Exterior graphic of the landed planet. */
/* Mission computer stack. */
-static Mission* mission_computer = NULL;
-static int mission_ncomputer = 0;
+static Mission* mission_computer = NULL; /**< Missions at the computer. */
+static int mission_ncomputer = 0; /**< Number of missions at the computer. */
/* Player stuff. */
-extern int hyperspace_target;
+extern int hyperspace_target; /**< From player.c. */
/* Commodity excahnge. */
static void commodity_exchange_open(void);
@@ -116,7 +117,9 @@ static void spaceport_refuel(unsigned int wid, char* str);
static unsigned int economy_getPrice(const Commodity* com,
const StarSystem* sys, const Planet* p);
-/* The local market. */
+/**
+ * @brief Open the local market window.
+ */
static void commodity_exchange_open(void) {
int i;
char** goods;
@@ -170,6 +173,11 @@ static void commodity_exchange_open(void) {
}
}
+/**
+ * @brief Update the commodity window.
+ * @param wid Window to update.
+ * @param str Unused.
+ */
static void commodity_update(unsigned int wid, char* str) {
(void)str;
char buf[128];
@@ -192,6 +200,11 @@ static void commodity_update(unsigned int wid, char* str) {
window_modifyText(wid, "txtDesc", com->description);
}
+/**
+ * @brief Buys the selected commodity.
+ * @param wid Window buying from.
+ * @param str Unused.
+ */
static void commodity_buy(unsigned int wid, char* str) {
(void)str;
char* comname;
@@ -218,6 +231,11 @@ static void commodity_buy(unsigned int wid, char* str) {
commodity_update(wid, NULL);
}
+/**
+ * @brief Attempts to sell a commodity.
+ * @param wid Window selling commodity from.
+ * @param str Unused.
+ */
static void commodity_sell(unsigned int wid, char* str) {
(void)str;
char* comname;
@@ -235,6 +253,9 @@ static void commodity_sell(unsigned int wid, char* str) {
commodity_update(wid, NULL);
}
+/**
+ * @brief Open the outfit exchange center window.
+ */
static void outfits_open(void) {
int i;
Outfit** outfits;
@@ -329,6 +350,11 @@ static void outfits_open(void) {
}
}
+/**
+ * @brief Updates the outfits in the outfit window.
+ * @param wid Window to update the outfits in.
+ * @param str Unused.
+ */
static void outfits_update(unsigned int wid, char* str) {
(void)str;
char* outfitname;
@@ -400,6 +426,12 @@ static void outfits_update(unsigned int wid, char* str) {
window_modifyText(wid, "txtDDesc", buf);
}
+/**
+ * @brief Check to see if the player can buy the outfit.
+ * @param outfit Outfit to buy.
+ * @param q Quantity to buy.
+ * @param errmsg Should alert the player?
+ */
static int outfit_canBuy(Outfit* outfit, int q, int errmsg) {
char buf[16];
@@ -459,6 +491,11 @@ static int outfit_canBuy(Outfit* outfit, int q, int errmsg) {
return 1;
}
+/**
+ * @brief Attempts to buy the outfit that is selected.
+ * @param wid Window buying outfit from.
+ * @param str Unused.
+ */
static void outfits_buy(unsigned int wid, char* str) {
(void)str;
char* outfitname;
@@ -478,6 +515,12 @@ static void outfits_buy(unsigned int wid, char* str) {
outfits_update(wid, NULL);
}
+/**
+ * @brief Check to see if the player can sell the selected outfit.
+ * @param outfit Outfit to try to sell.
+ * @param q Quantity to try to sell.
+ * @param errmsg Should alert player?
+ */
static int outfit_canSell(Outfit* outfit, int q, int errmsg) {
/* No outfits to sell. */
if(player_outfitOwned(outfit->name) <= 0) {
@@ -500,6 +543,11 @@ static int outfit_canSell(Outfit* outfit, int q, int errmsg) {
return 1;
}
+/**
+ * @brief Attempts to sell the selected outfit the player has.
+ * @param wid Window selling outfits from.
+ * @param str Unused.
+ */
static void outfits_sell(unsigned int wid, char* str) {
(void)str;
char* outfitname;
@@ -519,7 +567,10 @@ static void outfits_sell(unsigned int wid, char* str) {
outfits_update(wid, NULL);
}
-/* Return the current modifier status. */
+/**
+ * @brief Get the current modifier status.
+ * @return The amount modifier when buying or selling outfits.
+ */
static int outfits_getMod(void) {
SDLMod mods;
int q;
@@ -532,13 +583,20 @@ static int outfits_getMod(void) {
return q;
}
+/**
+ * @brief Render the outfit buying modifier.
+ * @param bx Base X position to render at.
+ * @param by Base Y position to render at.
+ * @param w Width to render at.
+ * @param h Height to render at.
+ */
static void outfits_renderMod(double bx, double by, double w, double h) {
(void) h;
int q;
char buf[8];
q = outfits_getMod();
- if(q == 1) return;
+ if(q == 1) return; /* Ignore modifier. */
snprintf(buf, 8, "%dx", q);
gl_printMid(&gl_smallFont, w,
@@ -547,6 +605,9 @@ static void outfits_renderMod(double bx, double by, double w, double h) {
&cBlack, buf);
}
+/**
+ * Brief Open the shipyard window.
+ */
static void shipyard_open(void) {
int i;
Ship** ships;
@@ -636,6 +697,11 @@ static void shipyard_open(void) {
}
}
+/**
+ * @brief Update the shops in the shipyard window.
+ * @param wid Window to update the ships in.
+ * @param str Unused.
+ */
static void shipyard_update(unsigned int wid, char* str) {
(void)str;
char* shipname;
@@ -693,6 +759,11 @@ static void shipyard_update(unsigned int wid, char* str) {
else window_enableButton(wid, "btnBuyShip");
}
+/**
+ * @brief Open the ships information window.
+ * @param wid Window to find out selected ship.
+ * @param str Unused.
+ */
static void shipyard_info(unsigned int wid, char* str) {
(void)str;
char* shipname;
@@ -701,6 +772,11 @@ static void shipyard_info(unsigned int wid, char* str) {
ship_view(0, shipname);
}
+/**
+ * @brief Player attempts to buy a ship.
+ * @param wid Window player is buying ship from.
+ * @param str Unused.
+ */
static void shipyard_buy(unsigned int wid, char* str) {
(void)str;
char* shipname, buf[16];
@@ -744,6 +820,11 @@ static void shipyard_buy(unsigned int wid, char* str) {
shipyard_update(wid, NULL);
}
+/**
+ * @brief Opens the players ship window.
+ * @param parent Unused.
+ * @param str Unused.
+ */
static void shipyard_yours_open(unsigned int parent, char* str) {
(void)str;
(void)parent;
@@ -817,6 +898,11 @@ static void shipyard_yours_open(unsigned int parent, char* str) {
shipyard_yoursUpdate(wid, NULL);
}
+/**
+ * @brief Update the players ship window.
+ * @param wid Window to update.
+ * @param str Unused.
+ */
static void shipyard_yoursUpdate(unsigned int wid, char* str) {
(void)str;
char buf[256], buf2[16], buf3[16], *buf4;
@@ -885,6 +971,11 @@ static void shipyard_yoursUpdate(unsigned int wid, char* str) {
window_enableButton(wid, "btnSellShip");
}
+/**
+ * @brief Player attempts to change the ship.
+ * @param wid Window player is attempting to change ships in.
+ * @param str Unused.
+ */
static void shipyard_yoursChange(unsigned int wid, char* str) {
(void)str;
char* shipname, *loc;
@@ -917,6 +1008,11 @@ static void shipyard_yoursChange(unsigned int wid, char* str) {
shipyard_yours_open(0, NULL);
}
+/**
+ * @brief Player tries to sell a ship.
+ * @param wid Window player is selling ships in.
+ * @param str Unused.
+ */
static void shipyard_yoursSell(unsigned int wid, char* str) {
(void)str;
char* shipname, buf[16];
@@ -950,6 +1046,11 @@ static void shipyard_yoursSell(unsigned int wid, char* str) {
shipyard_yours_open(0, NULL);
}
+/**
+ * @brief Player attempts to transport her ship to the planet she's at.
+ * @param wid Window player is trying to transport her ship from.
+ * @param str Unused.
+ */
static void shipyard_yoursTransport(unsigned int wid, char* str) {
(void)str;
unsigned int price;
@@ -984,22 +1085,29 @@ static void shipyard_yoursTransport(unsigned int wid, char* str) {
shipyard_yoursUpdate(wid, NULL);
}
+/**
+ * @brief Get the ships transport price.
+ * @param shipname Name of the ship to get the transport price.
+ * @return The price to transport the ship to the current planet.
+ */
static unsigned int shipyard_yoursTransportPrice(char* shipname) {
char* loc;
Pilot* ship;
- int price;
+ unsigned int price;
ship = player_getShip(shipname);
loc = player_getLoc(shipname);
if(strcmp(loc, land_planet->name)==0) /* Already here. */
return 0;
- price = (int)(sqrt(ship->solid->mass)*5000.);
+ price = (unsigned int)(sqrt(ship->solid->mass)*5000.);
return price;
}
-/* Spaceport bar. */
+/**
+ * @brief Open the spaceport bar window.
+ */
static void spaceport_bar_open(void) {
unsigned int wid;
@@ -1023,7 +1131,9 @@ static void spaceport_bar_open(void) {
}
}
-/* Planet news reports. */
+/**
+ * @brief Open the planetary news reports window.
+ */
static void news_open(unsigned int parent, char* str) {
(void)parent;
(void)str;
@@ -1042,7 +1152,9 @@ static void news_open(unsigned int parent, char* str) {
"News reporters report that they are on strike right now! D:");
}
-/* Mission computer, cos' missions rule! */
+/**
+ * @brief Open the mission computer window.
+ */
static void misn_open(void) {
unsigned int wid;
@@ -1073,17 +1185,27 @@ static void misn_open(void) {
misn_genList(wid, 1);
}
+/**
+ * @brief Close the mission computer window.
+ * @param wid Window to close.
+ * @param name Unused.
+ */
static void misn_close(unsigned int wid, char* name) {
/* Remove computer markers just in case. */
space_clearComputerMarkers();
window_close(wid, name);
}
+/**
+ * @brief Accepts the selected mission.
+ * @param wid Window of the mission computer.
+ * @param str Unused.
+ */
static void misn_accept(unsigned int wid, char* str) {
+ (void)str;
char* misn_name;
Mission* misn;
int pos;
- (void)str;
misn_name = toolkit_getList(wid, "lstMission");
@@ -1103,6 +1225,11 @@ static void misn_accept(unsigned int wid, char* str) {
}
}
+/**
+ * @brief Generates the mission list.
+ * @param wid Window to generate the mission list for.
+ * @param first Is it the first time generated?
+ */
static void misn_genList(unsigned int wid, int first) {
int i, j;
char** misn_names;
@@ -1134,12 +1261,16 @@ static void misn_genList(unsigned int wid, int first) {
misn_update(wid, NULL);
}
+/**
+ * @brief Update the mission list.
+ * @param wid Window of the mission computer.
+ * @param str Unused.
+ */
static void misn_update(unsigned int wid, char* str) {
+ (void)str;
char* active_misn;
Mission* misn;
- (void)str;
-
active_misn = toolkit_getList(wid, "lstMission");
if(strcmp(active_misn, "No Missions")==0) {
window_modifyText(wid, "txtReward", "None");
@@ -1156,12 +1287,18 @@ static void misn_update(unsigned int wid, char* str) {
window_enableButton(wid, "btnAcceptMission");
}
-/* Return how much it will cost to refuel the player. */
+/**
+ * @brief Get the cost to refuel.
+ * @return Refuel price.
+ */
static unsigned int refuel_price(void) {
return (unsigned int)((player->fuel_max - player->fuel)*3);
}
-/* Refuel the player. */
+/**
+ * @brief Refuel the player.
+ * @param str Unused.
+ */
static void spaceport_refuel(unsigned int wid, char* str) {
(void)str;
diff --git a/src/ldata.c b/src/ldata.c
index e9683a7..0f06e53 100644
--- a/src/ldata.c
+++ b/src/ldata.c
@@ -15,9 +15,9 @@
#include "lfile.h"
#include "ldata.h"
-#define LDATA_FILENAME "ldata"
+#define LDATA_FILENAME "ldata" /**< Generic ldata file name. */
#ifndef LDATA_DEF
-#define LDATA_DEF LDATA_FILENAME
+#define LDATA_DEF LDATA_FILENAME /**< Default ldata to use. */
#endif
#define XML_START_ID "Start" /**< XML document tag of module start file. */
diff --git a/src/lephisto.c b/src/lephisto.c
index 61d27b0..8f914a8 100644
--- a/src/lephisto.c
+++ b/src/lephisto.c
@@ -423,8 +423,6 @@ void unload_all(void) {
}
/**
- * @fn void main_loop(void)
- *
* @brief Split main loop from main() for secondary loop hack in toolkit.c.
*/
void main_loop(void) {
@@ -445,11 +443,9 @@ void main_loop(void) {
SDL_GL_SwapBuffers();
}
-static double fps_dt = 1.;
-static double cur_dt = 0.;
+static double fps_dt = 1.; /**< Display fps accumulator. */
+static double cur_dt = 0.; /**< Current deltatick. */
/**
- * @fn static void fps_control(void)
- *
* @brief Controls the FPS.
*/
static void fps_control(void) {
@@ -563,11 +559,9 @@ static void render_all(void) {
}
-static double fps = 0.;
-static double fps_cur = 0.;
+static double fps = 0.; /**< FPS to finally display. */
+static double fps_cur = 0.; /**< FPS accumulator to trigger change. */
/**
- * @fn static void display_fps(const double dt)
- *
* @brief Displays FPS on the screen.
*
* @param[in] dt Current delta tick.
diff --git a/src/llua_faction.c b/src/llua_faction.c
index 21b0c56..ad0b1b9 100644
--- a/src/llua_faction.c
+++ b/src/llua_faction.c
@@ -46,20 +46,19 @@ static const luaL_reg faction_methods_cond[] = {
{ "areAllies", factionL_areallies },
{ "playerStanding", factionL_playerstanding },
{ 0, 0 }
-};
+}; /**< Factions read only metatable methods. */
/* Global faction functions. */
static int factionL_get(lua_State* L);
static const luaL_reg factionL_methods[] = {
{ "get", faction_get },
{ 0, 0 }
-};
+}; /**< Faction module functions. */
/**
- * @fn int lua_loadFaction(lua_State* L, int readonly)
- *
* @brief Load the faction library.
* @param L State to load faction library into.
+ * @param readonly Load as read only?
* @return 0 on success.
*/
int lua_loadFaction(lua_State* L, int readonly) {
@@ -73,8 +72,6 @@ int lua_loadFaction(lua_State* L, int readonly) {
}
/**
- * @fn static int factionL_createmetatable(lua_State* L, int readonly)
- *
* @brief Register the faction metatable.
* @param L Lua state to register metatable into.
* @param readonly Whether table should be readonly.
@@ -109,8 +106,6 @@ static int factionL_createmetatable(lua_State* L, int readonly) {
*/
/**
- * @fn static int factionL_get(lua_State* L)
- *
* @brief faction get(string name)
*
* Get the faction based on its name.
@@ -150,8 +145,6 @@ static int factionL_get(lua_State* L) {
*/
/**
- * @fn LuaFaction* lua_tofaction(lua_State* L, int ind)
- *
* @brief Get faction at index.
* @param L Lua state to get faction from.
* @param ind Index position to find the faction.
@@ -167,8 +160,6 @@ LuaFaction* lua_tofaction(lua_State* L, int ind) {
}
/**
- * @fn LuaFaction* lua_pushfaction(lua_State* L, LuaFaction faction)
- *
* @brief Pushes a faction on the stack.
* @param L lua state to push faction into.
* @param faction Faction to push.
@@ -184,8 +175,6 @@ LuaFaction* lua_pushfaction(lua_State* L, LuaFaction faction) {
}
/**
- * @fn int lua_isfaction(lua_State* L, int ind)
- *
* @brief Check to see if ind is a faction.
* @param L Lua state to check.
* @param ind Index position to check.
diff --git a/src/llua_misn.c b/src/llua_misn.c
index 6eeecba..d001974 100644
--- a/src/llua_misn.c
+++ b/src/llua_misn.c
@@ -159,7 +159,7 @@ static const luaL_reg hook_methods[] = {
{ "enter", hook_enter },
{ "pilot", hook_pilot },
{ 0, 0 }
-};
+}; /**< Hook Lua methods. */
/* Diffs. */
static int diff_applyL(lua_State* L);
@@ -170,12 +170,12 @@ static const luaL_reg diff_methods[] = {
{ "remove", diff_removeL },
{ "isApplied", diff_isappliedL },
{ 0, 0 }
-};
+}; /**< Unidiff Lua methods. */
static const luaL_reg diff_cond_methods[] = {
{ "isApplied", diff_isappliedL },
{ 0, 0 }
-};
+}; /**< Unidiff Lua read only methods. */
/* Register all the libaries. */
int misn_loadLibs(lua_State* L) {
@@ -210,6 +210,11 @@ int lua_loadMisn(lua_State* L) {
return 0;
}
+/**
+ * @brief Load the mission variable lua library.
+ * @param readonly Whether to open in read-only form.
+ * @retrun 0 on success.
+ */
int lua_loadVar(lua_State* L, int readonly) {
if(readonly == 0)
luaL_register(L, "var", var_methods);
@@ -226,17 +231,21 @@ int lua_loadPlayer(lua_State* L, int readonly) {
return 0;
}
+/**
+ * @brief Loads the hook lua library.
+ * @param L Lua state.
+ * @return 0 on success.
+ */
int lua_loadHook(lua_State* L) {
luaL_register(L, "hook", hook_methods);
return 0;
}
/**
- * @fn int lua_loadDiff(lua_State* L, int readonly)
- *
* @brief Loads the diff Lua library.
* @param L Lua State.
* @param readonly Load read only functions.
+ * @return 0 on success.
*/
int lua_loadDiff(lua_State* L, int readonly) {
if(readonly == 0)
diff --git a/src/mission.c b/src/mission.c
index 954fa68..32ac0b7 100644
--- a/src/mission.c
+++ b/src/mission.c
@@ -541,6 +541,7 @@ static MissionData* mission_parse(const xmlNodePtr parent) {
} while(xml_nextNode(node));
#define MELEMENT(o,s) \
if(o) WARN("Mission '%s' missing/invalid '"s"' element", tmp->name)
+/**< Hack to check for missing elements. */
MELEMENT(tmp->lua==NULL, "lua");
MELEMENT(tmp->avail.loc==-1, "location");
#undef MELEMENT
diff --git a/src/nebulae.c b/src/nebulae.c
index 22d6d0a..3caa333 100644
--- a/src/nebulae.c
+++ b/src/nebulae.c
@@ -26,9 +26,9 @@
#define NEBULAE_PUFF_BUFFER 300 /**< Nebulae buffer. */
/* Extern. */
-extern double gui_xoff, gui_yoff;
-extern Vec2 shake_pos;
-extern void loadscreen_render(double done, const char* msg);
+extern double gui_xoff, gui_yoff; /**< From player.c */
+extern Vec2 shake_pos; /**< From spfx.c. */
+extern void loadscreen_render(double done, const char* msg); /**< From lephisto.c. */
/* The nebulae textures. */
static GLuint nebu_textures[NEBULAE_Z]; /**< BG Nebulae textures. */
@@ -295,15 +295,13 @@ void nebu_render(const double dt) {
}
/**
- * @fn void nebu_renderOverlay(const double dt)
- *
* @brief Renders the nebulae overlay (hides what player can't see).
* @param dt Current delta tick.
*/
void nebu_renderOverlay(const double dt) {
-#define ANG45 0.70710678118654757
-#define COS225 0.92387953251128674
-#define SIN225 0.38268343236508978
+#define ANG45 0.70710678118654757 /**< sqrt(2) */
+#define COS225 0.92387953251128674 /**< cos(225) */
+#define SIN225 0.38268343236508978 /**< sin(225) */
/* Render the puffs. */
nebu_renderPuffs(dt, 0);
diff --git a/src/options.c b/src/options.c
index 1ac4b07..699a3d4 100644
--- a/src/options.c
+++ b/src/options.c
@@ -25,7 +25,7 @@
#define BUTTON_HEIGHT 30 /**< Button height, standard across menus. */
/* Extern. */
-extern const char* keybindNames[]; /* input.c */
+extern const char* keybindNames[]; /* From input.c */
static const char* modToText(SDLMod mod);
static void menuKeybinds_update(unsigned int wid, char* name);
diff --git a/src/outfit.c b/src/outfit.c
index d581ad7..190ecab 100644
--- a/src/outfit.c
+++ b/src/outfit.c
@@ -528,9 +528,13 @@ static DamageType outfit_strToDamageType(char* buf) {
return DAMAGE_TYPE_NULL;
}
-/* Return the outfit type from string. */
#define O_CMP(s, t) \
- if(strcmp(buf, (s))==0) return t;
+ if(strcmp(buf, (s))==0) return t; /**< Define to help with outfit_strToOutfitType. */
+/**
+ * @brief Get the outfit type from human readable string.
+ * @param buf String to extract outfit type from.
+ * @return Outfit type stored in buf.
+ */
static OutfitType outfit_strToOutfitType(char* buf) {
O_CMP("bolt", OUTFIT_TYPE_BOLT);
O_CMP("beam", OUTFIT_TYPE_BEAM);
@@ -561,6 +565,19 @@ static OutfitType outfit_strToOutfitType(char* buf) {
}
#undef O_CMP
+/**
+ * @brief Parses a damage node.
+ *
+ * Example damage node would be:
+ * @code
+ * <damage type="kinetic">10</damage>
+ * @endcode
+ *
+ * @param[out] dtype Store the damage type here.
+ * @param[out] dmg Store the damage here.
+ * @param[in] node Node to parse damage from.
+ * @return 0 on success.
+ */
static int outfit_parseDamage(DamageType* dtype, double* dmg, xmlNodePtr node) {
char* buf;
@@ -632,6 +649,7 @@ static void outfit_parseSBolt(Outfit* tmp, const xmlNodePtr parent) {
#define MELEMENT(o,s) \
if (o) WARN("Outfit '%s' missing/invalid '"s"' element", tmp->name)
+/**< Define to help check for data errors. */
MELEMENT(tmp->u.blt.gfx_space==NULL, "gfx");
MELEMENT(tmp->u.blt.spfx_shield==-1, "spfx_shield");
MELEMENT(tmp->u.blt.spfx_armour==-1, "spfx_armour");
@@ -645,8 +663,6 @@ static void outfit_parseSBolt(Outfit* tmp, const xmlNodePtr parent) {
}
/**
- * @fn static void outfit_parseSBeam(Outfit* tmp, const xmlNodePtr parent)
- *
* @brief Parse the beam weapon specifics of an outfit.
* @param tmp Outfit to finish loading.
* @param parent Outfit's parent node.
@@ -739,6 +755,7 @@ static void outfit_parseSLauncher(Outfit* tmp, const xmlNodePtr parent) {
} while((node = node->next));
#define MELEMENT(o,s) if(o) WARN("Outfit '%s' missing '"s"' element", tmp->name)
+/**< Define to help check for data errors. */
MELEMENT(tmp->u.lau.ammo_name == NULL, "ammo");
MELEMENT(tmp->u.lau.delay==0, "delay");
#undef MELEMENT
diff --git a/src/pack.c b/src/pack.c
index 7c28b36..e1c4569 100644
--- a/src/pack.c
+++ b/src/pack.c
@@ -302,15 +302,6 @@ int pack_check(const char* filename) {
return ret;
}
-/**
- * @fn int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles)
- *
- * @brief Packages files into a packfile.
- * @param outfile Name of the file to output to.
- * @param infiles Array of filenames to package.
- * @param nfiles Number of filenames in infiles.
- * @return 0 on success.
- */
#ifdef _POSIX_SOURCE
#define WRITE(b,n) if(write(outfd, b, n)==-1) { \
ERR("Error writing to file: %s", strerror(errno)); \
@@ -320,6 +311,14 @@ int pack_check(const char* filename) {
ERR("Error writing to file: %s", strerror(errno)); \
free(buf); return -1; }
#endif
+
+/**
+ * @brief Packages files into a packfile.
+ * @param outfile Name of the file to output to.
+ * @param infiles Array of filenames to package.
+ * @param nfiles Number of filenames in infiles.
+ * @return 0 on success.
+ */
int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles) {
void* buf;
#ifdef _POSIX_SOURCE
@@ -432,10 +431,9 @@ int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles)
/**
* @brief Open a file in the packfile for reading.
- * @param file Packfile to store data into.
* @param packfile Path to real packfile.
* @param filename Name of the file within th. packfile.
- * @return 0 on success.
+ * @return The newly created packfile or NULL on error.
*/
Packfile_t* pack_open(const char* packfile, const char* filename) {
int j;
diff --git a/src/pause.c b/src/pause.c
index da39ace..ff78eeb 100644
--- a/src/pause.c
+++ b/src/pause.c
@@ -12,11 +12,11 @@
#include "pilot.h"
#include "pause.h"
-int paused = 0; /* Are we paused. */
+int paused = 0; /**< Are we paused. */
double dt_mod = 1.; /**< dt modifier. */
/* From main.c */
-extern unsigned int time;
+extern unsigned int time; /**< From lephisto.c. */
/* Pause the game. */
void pause_game(void) {
@@ -31,7 +31,10 @@ void unpause_game(void) {
paused = 0;
}
-/* Set the timers back. */
+/**
+ * @brief Set the timers back.
+ * @param delay Delay to set timers back.
+ */
void pause_delay(unsigned int delay) {
(void)delay;
}
diff --git a/src/perlin.c b/src/perlin.c
index 747ef38..5bd74c0 100644
--- a/src/perlin.c
+++ b/src/perlin.c
@@ -101,10 +101,9 @@ static float lattice2(perlin_data_t* pdata, int ix, float fx, int iy, float fy)
return value;
}
-#define SWAP(a, b, t) t = a; a = b; b = t
-
-#define FLOOR(a) ((int) a - (a < 0 && a != (int)a))
-#define CUBIC(a) (a * a * (3 - 2 * a))
+#define SWAP(a, b, t) t = a; a = b; b = t /**< Swaps two values. */
+#define FLOOR(a) ((int) a - (a < 0 && a != (int)a)) /**< Limits to 0. */
+#define CUBIC(a) (a * a * (3 - 2 * a)) /**< Does cubic filtering. */
/**
* @brief Normalizes a 3d vector.
diff --git a/src/pilot.c b/src/pilot.c
index 22d3e18..d5c2a3a 100644
--- a/src/pilot.c
+++ b/src/pilot.c
@@ -74,8 +74,6 @@ static int fleet_parse(Fleet* tmp, const xmlNodePtr parent);
static void pilot_dead(Pilot* p);
/**
- * @fn static int pilot_getStackPos(const unsigned int id)
- *
* @brief Get the pilots position in the stack.
* @param id ID of the pilot to get.
* @return Position of pilot in stack or -1 if not found.
@@ -97,8 +95,6 @@ static int pilot_getStackPos(const unsigned int id) {
}
/**
- * @fn unsinged int pilot_getNextID(const unsigned int id)
- *
* @brief Get the next pilot on id.
* @param id ID of current pilot.
* @return ID of next pilot of PLAYER_ID if no next pilot.
@@ -112,8 +108,6 @@ unsigned int pilot_getNextID(const unsigned int id) {
}
/**
- * @fn unsigned int pilot_getPrevID(const unsigned int id)
- *
* @brief Get the previous pilot based on ID.
* @param id ID of the current pilot.
* @return ID of previous pilot or PLAYER_ID if no previous pilot.
@@ -155,8 +149,6 @@ unsigned int pilot_getNearestEnemy(const Pilot* p) {
}
/**
- * @fn unsinged int pilot_getNearesetPilot(const Pilot* p)
- *
* @brief Get the nearest pilot to a pilot.
* @param p Pilot to get her nearest pilot.
* @return The nearest pilot.
@@ -266,9 +258,11 @@ void pilot_shoot(Pilot* p, const int secondary) {
}
/**
- * @fn void pilot_shootStop(Pilot* p, const int secondary)
+ * @brief Has pilot stopped shooting her weapon.
*
- * @brief
+ * Only really deals with beam weapons.
+ * @param p Pilot that was shooting.
+ * @param secondary If weapon is secondary.
*/
void pilot_shootStop(Pilot* p, const int secondary) {
int i;
@@ -299,8 +293,6 @@ void pilot_shootStop(Pilot* p, const int secondary) {
}
/**
- * @fn static void pilot_shootWeapon(Pilot* p, PilotOutfit* w)
- *
* @brief Actually handles the shooting, how often the player can shoot and such.
* @param p Pilot that is shooting.
* @param w Pilot's outfit to shoot.
@@ -381,9 +373,9 @@ static void pilot_shootWeapon(Pilot* p, PilotOutfit* w) {
}
/**
- * @fn void pilot_switchSecondary(Pilot* p, int i)
- *
- * @brief
+ * @brief Set the pilots secondary weapon.
+ * @param p Pilot to set secondary weapon.
+ * @param i Index of the weapon to set.
*/
void pilot_switchSecondary(Pilot* p, int i) {
PilotOutfit* cur;
@@ -405,9 +397,6 @@ void pilot_switchSecondary(Pilot* p, int i) {
}
/**
- * @fn void pilot_hit(Pilot* p, const Solid* w, const unsigned int shooter,
- * const DamageType dtype, const double damage)
- *
* @brief Damages the pilot.
* @param p Pilot that is taking damage.
* @param w Solid that is hitting pilot.
@@ -481,8 +470,6 @@ void pilot_hit(Pilot* p, const Solid* w, const unsigned int shooter,
}
/**
- * @fn void pilot_dead(Pilot* p)
- *
* @brief Pilot is dead, now will slowly explode.
* @param p Pilot that just died.
*/
@@ -508,8 +495,6 @@ void pilot_dead(Pilot* p) {
}
/**
- * @fn static void pilot_runHook(Pilot* p, int hook_type)
- *
* @brief Tries to run a pilot hook if she has it.
* @param p Pilot to run the hook.
* @param hook_type Type of hook to run.
@@ -523,8 +508,6 @@ void pilot_runHook(Pilot* p, int hook_type) {
}
/**
- * @fn void pilot_setSecondary(Pilot* p, const char* secondary)
- *
* @brief Set the pilots secondary weapon based on its name.
* @param p Pilot to set secondary weapon.
* @param secondary Name of the secondary weapon to set.
@@ -552,9 +535,7 @@ void pilot_setSecondary(Pilot* p, const char* secondary) {
}
/**
- * @fn void pilot_setAmmo(Pilot* p)
- *
- * @param Set the pilots ammo based on their secondary weapon.
+ * @brief Set the pilots ammo based on their secondary weapon.
* @param p Pilot to set ammo.
*/
void pilot_setAmmo(Pilot* p) {
@@ -580,7 +561,7 @@ void pilot_setAmmo(Pilot* p) {
}
/**
- * @fn int pilot_getAmmo(Pilot* p, Outfit* o)
+ * @brief Get the amount of ammo pilot has for a certain outfit.
* @param p Pilot to get amount of ammo for.
* @param o Outfit to get ammo for.
* @return Amount of ammo for o on p.
@@ -604,8 +585,6 @@ int pilot_getAmmo(Pilot* p, Outfit* o) {
}
/**
- * @fn void pilot_setAfterburner(Pilot* p)
- *
* @brief Set the pilots afterburner if she has one.
* @param p Pilot to set afterburner.
*/
@@ -621,8 +600,6 @@ void pilot_setAfterburner(Pilot* p) {
}
/**
- * @fn int pilot_dock(Pilot* p, Pilot* target)
- *
* @brief Dock the pilot on its target pilot.
* @param p Pilot that wants to dock.
* @param target Pilot to dock on.
@@ -663,6 +640,13 @@ int pilot_dock(Pilot* p, Pilot* target) {
}
/**
+ * @brief Make the pilot explosion.
+ * @param x X position of the pilot.
+ * @param y Y position of the pilot.
+ * @param radius Radius of the explosion.
+ * @param dtype Damage type of the explosion.
+ * @param damage Amount of damage by the explosion.
+ * @param parent ID of the pilot exploding.
*/
void pilot_explode(double x, double y, double radius,
DamageType dtype, double damage, unsigned int parent) {
@@ -697,8 +681,6 @@ void pilot_explode(double x, double y, double radius,
}
/**
- * @fn void pilot_render(Pilot* p)
- *
* @brief Render the pilot.
* @param p Pilot to render.
*/
@@ -709,8 +691,6 @@ void pilot_render(Pilot* p) {
}
/**
- * @fn static void pilot_update(Pilot* pilot, const double dt)
- *
* @brief Updates the pilot.
* @param pilot Pilot to update.
* @param dt Current delta tick.
@@ -903,8 +883,6 @@ static void pilot_hyperspace(Pilot* p) {
}
/**
- * @fn void pilot_hyperspaceAbort(Pilot* p)
- *
* @brief Stops the pilot from hyperspaceing.
*
* Can only stop in preperation mode.
@@ -919,6 +897,13 @@ void pilot_hyperspaceAbort(Pilot* p) {
}
}
+/**
+ * @brief Add an outfit to the pilot.
+ * @param pilot Pilot to add the outfit to.
+ * @param outfit Outfit to add to the pilot.
+ * @param quantity Amount of the outfit to add.
+ * @return Amount of the outfit added.
+ */
int pilot_addOutfit(Pilot* pilot, Outfit* outfit, int quantity) {
int i, q, free_space;
char* osec;
@@ -997,7 +982,13 @@ int pilot_addOutfit(Pilot* pilot, Outfit* outfit, int quantity) {
return q;
}
-/* Remove an outfit from the pilot. */
+/**
+ * @brief Remove an outfit from the pilot.
+ * @param pilot Pilot to remove the outfit from.
+ * @param outfit Outfit to remove from the pilot.
+ * @param quantity Amount of the outfits to remove from the pilot.
+ * @return Number of the outfits removed from the pilot.
+ */
int pilot_rmOutfit(Pilot* pilot, Outfit* outfit, int quantity) {
int i, q, c;
char* osec;
@@ -1036,7 +1027,10 @@ int pilot_rmOutfit(Pilot* pilot, Outfit* outfit, int quantity) {
return 0;
}
-/* Return all the outfits in a nice text form. */
+/**
+ * @brief Get all the outfits in nice text form.
+ * @param pilot Pilot to get the outfits from.
+ */
char* pilot_getOutfits(Pilot* pilot) {
int i;
char* buf;
@@ -1148,13 +1142,20 @@ void pilot_calcStats(Pilot* pilot) {
pilot->fuel = fc * pilot->fuel_max;
}
-/* Pilot free cargo space. */
+/**
+ * @brief Get the pilots free cargo space.
+ * @param p Pilot to get the free space of.
+ * @return Free cargo space on pilot.
+ */
int pilot_cargoFree(Pilot* p) {
return p->cargo_free;
}
/**
- *
+ * @brief Move cargo from one pilot to another.
+ * @param dest Destination pilot.
+ * @param src Source pilot.
+ * @return 0 on success.
*/
int pilot_moveCargo(Pilot* dest, Pilot* src) {
int i;
@@ -1218,7 +1219,11 @@ int pilot_addCargo(Pilot* pilot, Commodity* cargo, int quantity) {
return q;
}
-/* Return the amount of cargo onboard the ship. */
+/**
+ * @brief Get how much cargo ship has on board.
+ * @param pilot Pilot to get used cargo space of.
+ * @param The used cargo space by pilot.
+ */
int pilot_cargoUsed(Pilot* pilot) {
int i, q;
@@ -1229,7 +1234,10 @@ int pilot_cargoUsed(Pilot* pilot) {
return q;
}
-/* Calculate how much cargo ship has left etc. */
+/**
+ * @brief Calculates how much cargo ship has left and such.
+ * @param pilot Pilot to calculate free cargo space of.
+ */
static void pilot_calcCargo(Pilot* pilot) {
int q;
@@ -1316,8 +1324,13 @@ int pilot_rmMissionCargo(Pilot* pilot, unsigned int cargo_id, int jettison) {
return 0;
}
-/* Try to get rid of quantity cargo from pilot, */
-/* return quantity actually removed. */
+/**
+ * @brief Try to get rid of quantity cargo from pilot.
+ * @param pilot Pilot to get rid of cargo.
+ * @param cargo Cargo to get rid of.
+ * @param quantity Amount of cargo to get rid of.
+ * @return Amount of cargo gotten rid of.
+ */
int pilot_rmCargo(Pilot* pilot, Commodity* cargo, int quantity) {
int i, q;
@@ -1347,8 +1360,6 @@ int pilot_rmCargo(Pilot* pilot, Commodity* cargo, int quantity) {
}
/**
- * @fn void pilot_addHook(Pilot* pilot, int type, int hook)
- *
* @brief Add a hook to the pilot.
* @param pilot Pilot to add the hook to.
* @param type Type of the hook to add.
@@ -1368,11 +1379,8 @@ void pilot_addHook(Pilot* pilot, int type, int hook) {
}
/**
- * @fn void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction,
- * char* ai, const double dir, const Vec2* pos,
- * const Vec2* vel, const int flags)
- *
* @brief Initialize pilot.
+ * @param pilot Pilot to initialise.
* @param ship Ship pilot will be flying.
* @param name Pilots name, if NULL ships name will be used.
* @param faction Faction of the pilot.
@@ -1468,10 +1476,6 @@ void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction,
}
/**
- * @fn unsigned int pilot_create(Ship* ship, char* name, int faction,
- * char* ai, const double dir, const Vec2* pos,
- * const Vec2* vel, const int flags)
- *
* @brief Create a new pilot.
*
* See pilot_init for parameters.
@@ -1506,9 +1510,6 @@ unsigned int pilot_create(Ship* ship, char* name, int faction,
}
/**
- * @fn Pilot* pilot_CreateEmpty(Ship* ship, char* name,
- * int faction, char* ai, const int flags)
- *
* @brief Create a pilot without adding it to the stack.
* @param ship Ship for the pilot to use.
* @param name Name of the pilot ship (NULL uses ship name).
@@ -1527,8 +1528,6 @@ Pilot* pilot_createEmpty(Ship* ship, char* name,
}
/**
- * @fn Pilot* pilot_copy(Pilot* src)
- *
* @brief Copies src pilot to dest.
* @param src Pilot to copy.
* @return Copy of src.
@@ -1565,8 +1564,6 @@ Pilot* pilot_copy(Pilot* src) {
}
/**
- * @fn void pilot_free(Pilot* p)
- *
* @brief Free and cleans up a pilot.
* @param p Pilot to free.
*/
@@ -1591,8 +1588,6 @@ void pilot_free(Pilot* p) {
}
/**
- * @fn void pilot_destroy(Pilot* p)
- *
* @brief Destroy pilot from stack.
* @param p Pilot to destroy.
*/
@@ -1613,8 +1608,6 @@ void pilot_destroy(Pilot* p) {
}
/**
- * @fn voud pilots_free(void)
- *
* @brief Free the pilot stack.
*/
void pilots_free(void) {
@@ -1628,8 +1621,6 @@ void pilots_free(void) {
}
/**
- * @fn void pilots_clean(void)
- *
* @brief Clean up the pilot stack - Leave the player.
*/
void pilots_clean(void) {
@@ -1648,8 +1639,6 @@ void pilots_clean(void) {
}
/**
- * @fn void player_cleanAll(void)
- *
* @brief Even cleans up the player.
*/
void pilots_cleanAll(void) {
@@ -1662,8 +1651,6 @@ void pilots_cleanAll(void) {
}
/**
- * @fn void pilots_update(double dt)
- *
* @brief Updates all the pilots.
* @param dt Delta tick for the update.
*/
@@ -1697,8 +1684,6 @@ void pilots_update(double dt) {
}
/**
- * @fn void pilots_render(void)
- *
* @brief Render all the pilots.
*/
void pilots_render(void) {