[Add] More work on documentation.

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. */

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.

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] width Get the width needed.
- *    @param[out] h Get the height 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;

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.
  */

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.

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_LAND      (1<<0)    /**< Player already landed. */
-#define VISITED_COMMODITY (1<<1)
+#define VISITED_COMMODITY (1<<1)    /**< Player already visited commodities. */
-#define VISITED_BAR       (1<<2)
+#define VISITED_BAR       (1<<2)    /**< Player already visited bar. */
-#define VISITED_OUTFITS   (1<<3)
+#define VISITED_OUTFITS   (1<<3)    /**< Player already visited outfits. */
-#define VISITED_SHIPYARD  (1<<4)
+#define VISITED_SHIPYARD  (1<<4)    /**< Player already visited shipyard. */
-#define visited(f)        (land_visited |= (f))
+#define visited(f)        (land_visited |= (f)) /**< Mark place is visited. */
-#define has_visited(f)    (land_visited  & (f))
+#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 Mission* mission_computer = NULL; /**< Missions at the computer. */
-static int mission_ncomputer = 0;
+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;
 

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. */

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 fps_dt = 1.;  /**< Display fps accumulator. */
-static double cur_dt = 0.;
+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 = 0.;     /**< FPS to finally display. */
-static double fps_cur = 0.;
+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.

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.

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)

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

src/nebulae.c

@@ -26,9 +26,9 @@
 #define NEBULAE_PUFF_BUFFER   300 /**< Nebulae buffer. */
 
 /* Extern. */
-extern double gui_xoff, gui_yoff;
+extern double gui_xoff, gui_yoff; /**< From player.c */
-extern Vec2 shake_pos;
+extern Vec2 shake_pos;            /**< From spfx.c. */
-extern void loadscreen_render(double done, const char* msg);
+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 ANG45   0.70710678118654757 /**< sqrt(2) */
-#define COS225  0.92387953251128674
+#define COS225  0.92387953251128674 /**< cos(225) */
-#define SIN225  0.38268343236508978
+#define SIN225  0.38268343236508978 /**< sin(225) */
 
   /* Render the puffs. */
   nebu_renderPuffs(dt, 0);

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);

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

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;

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;
 }

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 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 FLOOR(a)        ((int) a - (a < 0 && a != (int)a))
+#define CUBIC(a)      (a * a * (3 - 2 * a))               /**< Does cubic filtering. */
-#define CUBIC(a)        (a * a * (3 - 2 * a))
 
 /**
  * @brief Normalizes a 3d vector.

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 Set the pilots secondary weapon.
- *
+ *    @param p Pilot to set secondary weapon.
- * @brief 
+ *    @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)
+ * @brief Set the pilots ammo based on their secondary weapon.
- *
- * @param 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) {