[Add] Have some more documentation.

src/ldata.c

@@ -192,7 +192,7 @@ const char* ldata_name(void) {
 /**
  * @brief Read a file from the ldata.
  *    @param filename Name of the file to read.
- *    @param[out] Stores the size of the file.
+ *    @param[out] filesize Stores the size of the file.
  *    @return The file data or NULL on error.
  */
 void* ldata_read(const char* filename, uint32_t* filesize) {

src/llua.c

@@ -87,8 +87,6 @@ int llua_load(lua_State* L, lua_CFunction f) {
 }
 
 /**
- * @fn int llua_loadBasic(lua_State* L)
- *
  * @brief Load specially modified basic stuff.
  *    @param L Lua state to load the basic stuff into.
  *    @return 0 on success.

src/llua_space.c

@@ -83,6 +83,7 @@ static const luaL_reg vector_methods[] = {
 /**
  * @brief Load the space library.
  *    @param L State to load space library into.
+ *    @param readonly Load read only functions?
  *    @return 0 on success.
  */
 int lua_loadSpace(lua_State* L, int readonly) {
@@ -668,8 +669,6 @@ static int systemL_jumpdistance(lua_State* L) {
  */
 
 /**
- * @fn LuaVector* lua_tovector(lua_State* L, int ind)
- * 
  * @brief Gets vector at index.
  *    @param L Lua state to get vector from.
  *    @param ind Index position of vector.
@@ -685,11 +684,9 @@ LuaVector* lua_tovector(lua_State* L, int ind) {
 }
 
 /**
- * @fn LuaVector* lua_pushvector(lua_State* L, LuaVector vec)
- *
  * @brief Pushes a vector on the stack.
  *    @param L Lua state to push vector onto.
- *    @param sys Vector to push.
+ *    @param vec Vector to push.
  *    @return Vector just pushed.
  */
 LuaVector* lua_pushvector(lua_State* L, LuaVector vec) {
@@ -702,8 +699,6 @@ LuaVector* lua_pushvector(lua_State* L, LuaVector vec) {
 }
 
 /**
- * @fn int lua_isvector(lua_State* L, int ind)
- *
  * @brief Check to see if ind is a vector.
  *    @param L lua state to check.
  *    @param ind Index position to check.

src/nebulae.c

@@ -294,15 +294,15 @@ void nebu_render(const double dt) {
   nebu_renderPuffs(dt, 1);
 }
 
+#define ANG45   0.70710678118654757 /**< sqrt(2) */
+#define COS225  0.92387953251128674 /**< cos(225) */
+#define SIN225  0.38268343236508978 /**< sin(225) */
+
 /**
  * @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 /**< sqrt(2) */
-#define COS225  0.92387953251128674 /**< cos(225) */
-#define SIN225  0.38268343236508978 /**< sin(225) */
-
   /* Render the puffs. */
   nebu_renderPuffs(dt, 0);
 

src/opengl.c

@@ -693,7 +693,7 @@ static void gl_blitTexture(const glTexture* texture,
 
 /**
  * @brief Blits a sprite, position is relative to the player.
- *    @param texture Sprite to blit.
+ *    @param sprite Sprite to blit.
  *    @param bx X position of the texture relative to the player.
  *    @param by Y position of the texture relative to the player.
  *    @param sx X position of the sprite to use.
@@ -724,7 +724,7 @@ void gl_blitSprite(const glTexture* sprite, const double bx, const double by,
 
 /**
  * @brief Blits a sprite, position is in absolute screen coordinates.
- *    @param texture Sprite to blit.
+ *    @param sprite Sprite to blit.
  *    @param bx X position of the texture in screen coordinates.
  *    @param by Y position of the texture in screen coordinates.
  *    @param sx X position of the sprite to use.

src/pack.c

@@ -19,7 +19,7 @@
  *    -- Magic number (16 bytes).
  *    -- Number of files (uint32_t).
  *    -- Files in format name/location.
- *      -- File name (128 bytes max, ending in \0).
+ *      -- File name (128 bytes max, ending in NUL).
  *      -- File location (uint32_t).
  *  -- File data in format Size/Data.
  *    -- File size (uint32_t).

src/pilot.c

@@ -549,9 +549,9 @@ void pilot_runHook(Pilot* p, int hook_type) {
 }
 
 /**
- * @brief Set the pilots secondary weapon based on its name.
+ * @brief Set the pilots secondary weapon.
  *    @param p Pilot to set secondary weapon.
- *    @param secondary Name of the secondary weapon to set.
+ *    @param o Outfit to set as secondary.
  */
 static void pilot_setSecondary(Pilot* p, Outfit* o) {
   int i;
@@ -947,6 +947,7 @@ void pilot_hyperspaceAbort(Pilot* p) {
 
 /**
  * @brief Set the mount points for an outfit.
+ *    @param p Pilot to set mounts on.
  *    @param po Outfit to set mount points for.
  *    @param o Original number of outfits.
  *    @param q outfits added.
@@ -1503,8 +1504,8 @@ void pilot_addHook(Pilot* pilot, int type, int hook) {
  *    @param faction Faction of the pilot.
  *    @param ai Name of the AI profile to use for the pilot.
  *    @param dir Initial direction to face (radians).
- *    @param vel Initial velocity.
  *    @param pos Initial position.
+ *    @param vel Initial velocity.
  *    @param flags Used for tweaking the pilot.
  */
 void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction,

src/player.c

@@ -1536,7 +1536,7 @@ static void gui_createInterference(void) {
 
 /**
  * @brief Parses a gui node.
- *    @param Parent node to parse from.
+ *    @param parent Node to parse from.
  *    @param name Name of the GUI to load.
  */
 static int gui_parse(const xmlNodePtr parent, const char* name) {
@@ -2560,6 +2560,13 @@ int player_save(xmlTextWriterPtr writer) {
   return 0;
 }
 
+/**
+ * @brief Save a ship.
+ *    @param writer XML writer.
+ *    @param ship Ship to save.
+ *    @param loc Location of the ship.
+ *    @return 0 on success.
+ */
 static int player_saveShip(xmlTextWriterPtr writer, Pilot* ship, char* loc) {
   int i, j, k;
   int found;

src/save.c

@@ -24,21 +24,30 @@
 #define BUTTON_HEIGHT 30
 
 /* Externs. */
-extern int  player_save(xmlTextWriterPtr writer);         /* A lot of stuff. */
+/* player.c */
-extern int  player_load(xmlNodePtr parent);
+extern int  player_save(xmlTextWriterPtr writer); /**< Save player related stuff. */
-extern int  missions_saveActive(xmlTextWriterPtr writer); /* Active missions. */
+extern int  player_load(xmlNodePtr parent); /**< Load player related stuff. */
-extern int  missions_loadActive(xmlNodePtr parent);
+/* mission.c */
-extern int  var_save(xmlTextWriterPtr writer);            /* misn var. */
+extern int  missions_saveActive(xmlTextWriterPtr writer); /**< Save active missions. */
-extern int  var_load(xmlNodePtr parent);
+extern int  missions_loadActive(xmlNodePtr parent); /**< Load active missions. */
-extern int  pfaction_save(xmlTextWriterPtr writer);       /* Faction data. */
+/* llua_misn.c */
-extern int  pfaction_load(xmlNodePtr parent);
+extern int  var_save(xmlTextWriterPtr writer); /**< Save mission variables. */
-extern int  hook_save(xmlTextWriterPtr writer);           /* Hooks. */
+extern int  var_load(xmlNodePtr parent); /**< Load mission variables. */
-extern int  hook_load(xmlNodePtr parent);
+/* faction.c */
-extern int  space_sysSave(xmlTextWriterPtr writer);       /* Space stuff. */
+extern int  pfaction_save(xmlTextWriterPtr writer); /**< Save faction data. */
-extern int  space_sysLoad(xmlNodePtr parent);
+extern int  pfaction_load(xmlNodePtr parent); /**< Load faction data. */
-extern int  diff_save(xmlTextWriterPtr writer);
+/* hook.c */
-extern int  diff_load(xmlNodePtr parent);
+extern int  hook_save(xmlTextWriterPtr writer); /**< Save hooks. */
-extern void menu_main_close(void);
+extern int  hook_load(xmlNodePtr parent); /**< Load hooks. */
+/* space.c */
+extern int  space_sysSave(xmlTextWriterPtr writer); /**< Save the space stuff. */
+extern int  space_sysLoad(xmlNodePtr parent); /**< Load the space stuff. */
+/* unidiff.c */
+extern int  diff_save(xmlTextWriterPtr writer); /**< Save the universe diffs. */
+extern int  diff_load(xmlNodePtr parent); /**< Load the universe diffs. */
+/* menu.c */
+extern void menu_main_close(void); /**< Close the main menu. */
+
 /* Static. */
 static int  save_data(xmlTextWriterPtr writer);
 static void load_menu_close(unsigned int wdw, char* str);
@@ -194,6 +203,11 @@ static void load_menu_load(unsigned int wdw, char* str) {
   load_game(path);
 }
 
+/**
+ * @brief Delete an old game.
+ *    @param wdw Window to delete.
+ *    @param str Unused.
+ */
 static void load_menu_delete(unsigned int wdw, char* str) {
   (void)str;
   char* save, path[PATH_MAX];

src/ship.c

@@ -49,7 +49,7 @@ Ship* ship_get(const char* name) {
  *    @param s Ship to get the mount point o.
  *    @param dir Direction ship is facing.
  *    @param id ID of the mount point to get.
- *    @param[out] The position of the mount point.
+ *    @param[out] p The position of the mount point.
  *    @return 0 on success.
  */
 int ship_getMount(Ship* s, double dir, const int id, Vec2* p) {
@@ -200,8 +200,6 @@ char* ship_class(Ship* s) {
 }
 
 /**
- * @fn ShipClass ship_classFromString(char* str)
- *
  * @brief Get the machine ship class identifier from a human readable string.
  *    @param str String to extract ship class identifier from.
  */
@@ -251,8 +249,6 @@ ShipClass ship_classFromString(char* str) {
 }
 
 /**
- * @fn int ship_basePrice(Ship* s)
- *
  * @brief Get the ships base price (no outfits).
  */
 int ship_basePrice(Ship* s) {
@@ -272,6 +268,12 @@ int ship_basePrice(Ship* s) {
   return price;
 }
 
+/**
+ * @brief Extracts the ingame ship from an XML node.
+ *    @param tmp Ship to load data into.
+ *    @param parent Node to get ship from.
+ *    @return 0 on success.
+ */
 static int ship_parse(Ship* tmp, xmlNodePtr parent) {
   xmlNodePtr cur, node;
   ShipOutfit* otmp, *ocur;

src/space.c

@@ -108,7 +108,8 @@ int space_sysLoad(xmlNodePtr parent);
 /* Draw the planet. Used in planet.c */
 /* Matrix mode is already displaced to center of the minimap. */
 #define PIXEL(x,y)  if((shape == RADAR_RECT && ABS(x)<w/2. && ABS(y)<h/2.) || \
-  (shape == RADAR_CIRCLE && (((x)*(x)+(y)*(y)) <= rc))) glVertex2i((x),(y))
+  (shape == RADAR_CIRCLE && (((x)*(x)+(y)*(y)) <= rc))) \
+  glVertex2i((x),(y)) /**< Put a pixel on radar if inbounts. */
 void planets_minimap(const double res, const double w,
     const double h, const RadarShape shape, double alpha) {
   int i;