From 1f9768ccd69fa0b94ca240aefd63e0342291df6e Mon Sep 17 00:00:00 2001
From: Allanis <allanis@saracraft.net>
Date: Mon, 12 May 2014 14:08:42 +0100
Subject: [PATCH] [Add] Hey, someone has to document this stuff..

---
 src/ai.c         |  89 ++++++++------
 src/llua_space.c | 298 ++++++++++++++++++++++++++++++++++++-----------
 src/map.c        |   3 +-
 src/physics.h    |  15 ++-
 4 files changed, 301 insertions(+), 104 deletions(-)

diff --git a/src/ai.c b/src/ai.c
index 82f28de..327acea 100644
--- a/src/ai.c
+++ b/src/ai.c
@@ -259,8 +259,6 @@ static int pilot_flags      = 0;    /**< Handle stuff like weapon firing. */
 static int ai_status = AI_STATUS_NORMAL;  /**< Current AI run statis. */
 
 /**
- * @fn static void ai_setMemory(void)
- *
  * @brief Set the cur_pilots ai.
  */
 static void ai_setMemory(void) {
@@ -274,9 +272,8 @@ static void ai_setMemory(void) {
 }
 
 /**
- * @fn void ai_setPilot(Pilot* p)
- *
  * @brief Set the pilot for further AI calls.
+ *    @param p Pilot to set.
  */
 void ai_setPilot(Pilot* p) {
   cur_pilot = p;
@@ -284,8 +281,6 @@ void ai_setPilot(Pilot* p) {
 }
 
 /**
- * @fn static void ai_run(lua_State* L, const char* funcname)
- *
  * @brief Attemps to run a function.
  *
  *    @param[in] L Lua state to run function on.
@@ -300,8 +295,6 @@ static void ai_run(lua_State* L, const char* funcname) {
 }
 
 /**
- * @fn int ai_pinit(Pilot* p, char* ai)
- *  
  * @brief Initializes the pilot in the ai.
  *
  * Mainly used to create the pilot's memory table.
@@ -353,8 +346,6 @@ int ai_pinit(Pilot* p, char* ai) {
 }
 
 /**
- * @fn void ai_destroy(Pilot* p)
- *
  * @brief Destroys the ai part of the pilot.
  *    
  *    @param[in] p Pilot to destroy it's AI part.
@@ -376,8 +367,6 @@ void ai_destroy(Pilot* p) {
 }
 
 /**
- * @fn int ai_init(void)
- *
  * @brief Initializes the AI stuff which is basically Lua.
  *
  *    @return 0 on no errors.
@@ -405,8 +394,6 @@ int ai_init(void) {
 }
 
 /**
- * @fn static int ai_loadProfile(char* filename)
- *
  * @brief Initializes an AI_Profile and adds it to the stack.
  * 
  *    @param[in] filename File to create the profile from.
@@ -469,8 +456,7 @@ static int ai_loadProfile(const char* filename) {
   return 0;
 }
 
-/* @fn AI_Profile* ai_getProfile(char* name)
- *
+/*
  * @brief Get the AI_Profile by name.
  *
  *    @param[in] name Name of the profile to get.
@@ -489,8 +475,6 @@ AI_Profile* ai_getProfile(char* name) {
 }
 
 /**
- * @fn void ai_exit(void)
- *
  * @brief Clean up the gloabl AI.
  */
 void ai_exit(void) {
@@ -503,8 +487,6 @@ void ai_exit(void) {
 }
 
 /**
- * @fn void ai_think(Pilot* pilot)
- *
  * @brief Heart of the AI, brains of the pilot.
  *
  *    @param pilot Pilot that needs to think.
@@ -548,8 +530,6 @@ void ai_think(Pilot* pilot) {
 }
 
 /**
- * @fn void ai_attacked(Pilot* attacked, const unsigned int attacker)
- *
  * @brief Trigger the attacked() function in the Pilots AI.
  *
  *    @param attacked Pilot that is attacked.
@@ -567,8 +547,6 @@ void ai_attacked(Pilot* attacked, const unsigned int attacker) {
 }
 
 /**
- * @fn static void ai_create(Pilot* pilot, char* param)
- *
  * @brief Run the create() function in the pilot.
  *
  * Should create all the gear and such the pilot has.
@@ -613,7 +591,10 @@ static void ai_create(Pilot* pilot, char* param) {
 /* INTERNAL C FUNCTIONS. */
 /* ===================== */
 
-/* Free the task. */
+/**
+ * @brief Free an AI task.
+ *    @param t Task to free.
+ */
 static void ai_freetask(Task* t) {
   if(t->next != NULL) {
     ai_freetask(t->next); /* Woot, recursive freeing! */
@@ -646,6 +627,7 @@ static void ai_freetask(Task* t) {
  *
  * @luafunc pushtask(pos, func, data)
  *    @param L Lua state.
+ *    @return Number of Lua parameters.
  */
 static int ai_pushtask(lua_State* L) {
   LLUA_MIN_ARGS(2);
@@ -684,11 +666,10 @@ static int ai_pushtask(lua_State* L) {
 }
 
 /**
- * @fn static int ai_poptask(lua_State* L)
- *
- * @brief poptask(nil)
- *
- * Pops the current running task.
+ * @brief Pops the current running task.
+ * @luafunc poptask()
+ *    @param L Lua state.
+ *    @return Number of Lua parameters.
  */
 static int ai_poptask(lua_State* L) {
   (void)L; /* Just a hack to avoid -W -Wall warnings. */
@@ -706,19 +687,41 @@ static int ai_poptask(lua_State* L) {
   return 0;
 }
 
-/* Grab the current tasks name. */
+/**
+ * @brief Get the current task's name.
+ *    @return The current task name or "none" if there are no tasks.
+ *
+ * @luafunc taskname()
+ *    @param L Lua state.
+ *    @return Number of Lua parameters.
+ */
 static int ai_taskname(lua_State* L) {
   if(cur_pilot->task) lua_pushstring(L, cur_pilot->task->name);
   else lua_pushstring(L, "none");
   return 1;
 }
 
+/**
+ * @brief Get the player.
+ *    @return The players ship identifier.
+ * 
+ * @luafunc getPlayer()
+ *    @param L Lua state.
+ *    @return Number of Lua parameters.
+ */
 static int ai_getplayer(lua_State* L) {
   lua_pushnumber(L, PLAYER_ID);
   return 1;
 }
 
-/* Grab the target. */
+/**
+ * @brief Get the pilots target.
+ *    @return The pilots target ship identifier or nil if no target.
+ *
+ * @luafunc target()
+ *    @param L Lua state.
+ *    @return Number of Lua parameters.
+ */
 static int ai_gettarget(lua_State* L) {
   switch(cur_pilot->task->dtype) {
     case TYPE_INT:
@@ -729,8 +732,28 @@ static int ai_gettarget(lua_State* L) {
   }
 }
 
+/**
+ * @brief Get a random targets id.
+ *    @return Gets a random pilot in the system.
+ *
+ * @luafunc rndpilot()
+ *    @param L Lua state.
+ *    @return Number of Lua parameters.
+ */
 static int ai_getrndpilot(lua_State* L) {
-  lua_pushnumber(L, pilot_stack[RNG(0, pilot_nstack-1)]->id);
+  int p;
+  p = RNG(0, pilot_nstack-1);
+  /* Make sure it can't be the same pilot. */
+  if(pilot_stack[p]->id == cur_pilot->id) {
+    p++;
+    if(p >= pilot_nstack)
+      p = 0;
+  }
+  /* Last check. */
+  if(pilot_stack[p]->id == cur_pilot->id)
+    return 0;
+  /* Actually found a pilot. */
+  lua_pushnumber(L, pilot_stack[p]->id);
   return 1;
 }
 
diff --git a/src/llua_space.c b/src/llua_space.c
index 553733c..e9c823b 100644
--- a/src/llua_space.c
+++ b/src/llua_space.c
@@ -78,7 +78,11 @@ static const luaL_reg vector_methods[] = {
   { 0, 0 }
 }; /**< Vector metatable methods. */
 
-/* Load the space library. */
+/**
+ * @brief Load the space library.
+ *    @param L State to load space library into.
+ *    @return 0 on success.
+ */
 int lua_loadSpace(lua_State* L, int readonly) {
   (void)readonly; /* Only read only atm. */
 
@@ -94,8 +98,6 @@ int lua_loadSpace(lua_State* L, int readonly) {
 }
 
 /**
- * @fn int lua_loadVector(lua_State* L)
- *
  * @brief Loads the vector metatable.
  *    @param L State to load the vector metatable into.
  *    @return 0 on success.
@@ -106,9 +108,11 @@ int lua_loadVector(lua_State* L) {
   return 0;
 }
 
-/* -- SPACE -- */
-
-/* Create a planet metatable from a planet and put it on top of the stack. */
+/**
+ * @brief Registers the planet metatable.
+ *    @param L Lua state to register metatable in.
+ *    @return 0 on success.
+ */
 static int planetL_createmetatable(lua_State* L) {
   /* Create the metatable. */
   luaL_newmetatable(L, PLANET_METATABLE);
@@ -123,7 +127,11 @@ static int planetL_createmetatable(lua_State* L) {
   return 0; /* No error. */
 }
 
-/* Register the system metatable. */
+/**
+ * @brief Register the system metatable.
+ *    @param L Lua state to register metatable in.
+ *    @param 0 on success.
+ */
 static int systemL_createmetatable(lua_State* L) {
   /* Create the metatable. */
   luaL_newmetatable(L, SYSTEM_METATABLE);
@@ -139,8 +147,6 @@ static int systemL_createmetatable(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_createmetatable(lua_State* L)
- *
  * @brief Registers the vector metatable.
  *    @param L Lua state to register metatable in.
  *    @return 0 on success.
@@ -159,9 +165,30 @@ static int vectorL_createmetatable(lua_State* L) {
   return 0; /* No error. */
 }
 
-/* -- PLANET -- */
+/**
+ * @defgroup SPACE Space Lua Bindings.
+ *
+ * @brief Contains Lua bindings for manipulating the space itself.
+ */
+/**
+ * @defgroup META_PLANET Planet metatable
+ *
+ * @brief The planet metatable is a way to represent a planet in Lua.
+ *
+ * It allows all sorts of operators making it much more natural to use.
+ *
+ * To call Members of the metatable always use:
+ * @code
+ * planet:function(param)
+ * @endcode
+ */
 
-/* Get planet at index. */
+/**
+ * @brief Get planet at index.
+ *    @param L Lua state to get planet from.
+ *    @param ind Index position to find the planet.
+ *    @return Planet found at the index in the state.
+ */
 LuaPlanet* lua_toplanet(lua_State* L, int ind) {
   if(lua_isuserdata(L, ind)) {
     return (LuaPlanet*) lua_touserdata(L, ind);
@@ -171,7 +198,12 @@ LuaPlanet* lua_toplanet(lua_State* L, int ind) {
   return NULL;
 }
 
-/* Push a planet on the stack. */
+/**
+ * @brief Pushes a planet on the stack.
+ *    @param L Lua state to push planet into.
+ *    @param planet Planet to push.
+ *    @return Newly pushed planet.
+ */
 LuaPlanet* lua_pushplanet(lua_State* L, LuaPlanet planet) {
   LuaPlanet* p;
   p = (LuaPlanet*) lua_newuserdata(L, sizeof(LuaPlanet));
@@ -181,7 +213,12 @@ LuaPlanet* lua_pushplanet(lua_State* L, LuaPlanet planet) {
   return p;
 }
 
-/* Check see if ind is a planet. */
+/**
+ * @brief Check to see if ind is a planet.
+ *    @param L Lua state to check.
+ *    @param ind Index at position to check.
+ *    @return 1 if ind is a planet.
+ */
 int lua_isplanet(lua_State* L, int ind) {
   int ret;
 
@@ -197,7 +234,22 @@ int lua_isplanet(lua_State* L, int ind) {
   return ret;
 }
 
-/* get a planet. */
+/**
+ * @ingroup SPACE
+ *
+ * @brief planet, system getPlanet([param])
+ *
+ * Get a planet.
+ *
+ * Possible values of param:
+ *    -- nil    : Get the current landed planet or nil if there is none.
+ *    -- number : Get a random planet belonging to faction matching the number.
+ *    -- string : Get the planet by name.
+ *    -- table  : Get random planet belonging to any of the factions in the table.
+ *
+ *    @param param See description.
+ *    @return Returns the planet and the system it belongs to.
+ */
 static int planetL_get(lua_State* L) {
   int       i;
   int*      factions;
@@ -275,7 +327,17 @@ static int planetL_get(lua_State* L) {
   return 2;
 }
 
-/* __eq (equality) metamethod for planets. */
+/**
+ * @ingroup META_PLANET
+ *
+ * @brief bool __eq(planet comp)
+ *
+ * __eq (equality) metamethod for planets.
+ *
+ * You can use the '=' operator within Lua to compare planets with this.
+ *    @param comp planet to compare against.
+ *    @return true if both planets are the same.
+ */
 static int planetL_eq(lua_State* L) {
   LuaPlanet* a, *b;
   a = lua_toplanet(L, 1);
@@ -287,7 +349,14 @@ static int planetL_eq(lua_State* L) {
   return 1;
 }
 
-/* Get the planets name. */
+/**
+ * @ingroup META_PLANET
+ *
+ * @brief string name(nil)
+ *
+ * Get the planets name.
+ *    @return The  name of the planet.
+ */
 static int planetL_name(lua_State* L) {
   LuaPlanet* p;
   p = lua_toplanet(L, 1);
@@ -295,7 +364,14 @@ static int planetL_name(lua_State* L) {
   return 1;
 }
 
-/* Get the planets faction. */
+/**
+ * @ingroup META_PLANET
+ *
+ * @brief number faction(nil)
+ *
+ * Get the planets faction.
+ *    @return The planets faction.
+ */
 static int planetL_faction(lua_State* L) {
   LuaPlanet* p;
   LuaFaction f;
@@ -305,7 +381,14 @@ static int planetL_faction(lua_State* L) {
   return 1;
 }
 
-/* Get the planets class. */
+/**
+ * @ingroup META_PLANET
+ *
+ * @brief string class(nil)
+ *
+ * Get the planets class.
+ *    @return The class of the planet in one char identifier.
+ */
 static int planetL_class(lua_State* L) {
   char buf[2];
   LuaPlanet* p;
@@ -316,7 +399,14 @@ static int planetL_class(lua_State* L) {
   return 1;
 }
 
-/* Get planet services. */
+/**
+ * @ingroup META_PLANET
+ *
+ * @brief Number services(nil)
+ *
+ * Get planet services.
+ *    @return The services the planet has it stored bitwise.
+ */
 static int planetL_services(lua_State* L) {
   LuaPlanet* p;
   p = lua_toplanet(L, 1);
@@ -325,7 +415,6 @@ static int planetL_services(lua_State* L) {
 }
 
 /**
- * @fn static int planetL_position(lua_State* L)
  * @ingroup META_PLANET
  *
  * @brief Vec2 pos(nil)
@@ -342,9 +431,23 @@ static int planetL_position(lua_State* L) {
   return 1;
 }
 
-/* -- SYSTEM -- */
+/**
+ * @defgroup META_SYSTEM System Metatable.
+ *
+ * @brief Represents a system in Lua.
+ *
+ * To call members of the metatable always use:
+ * @code
+ * system:function(param)
+ * @endcode
+ */
 
-/* Get system at index. */
+/**
+ * @brief Get system at index.
+ *    @param L Lus state to get system from.
+ *    @param ind Index position of system.
+ *    @return The LuaSystem at ind.
+ */
 LuaSystem* lua_tosystem(lua_State* L, int ind) {
   if(lua_isuserdata(L, ind)) {
     return (LuaSystem*) lua_touserdata(L,ind);
@@ -353,7 +456,12 @@ LuaSystem* lua_tosystem(lua_State* L, int ind) {
   return NULL;
 }
 
-/* Pushes a system on the stack. */
+/**
+ * @brief Pushes a system on the stack.
+ *    @param L Lua state to push system onto.
+ *    @param sys System to push.
+ *    @return System just pushed.
+ */
 LuaSystem* lua_pushsystem(lua_State* L, LuaSystem sys) {
   LuaSystem* s;
   s = (LuaSystem*) lua_newuserdata(L, sizeof(LuaSystem));
@@ -363,7 +471,12 @@ LuaSystem* lua_pushsystem(lua_State* L, LuaSystem sys) {
   return s;
 }
 
-/* Check to see if ind is a planet. */
+/**
+ * @brief Check to see if ind is a system.
+ *    @param L Lua state to check.
+ *    @param ind Index position to check.
+ *    @return 1 if there is a system at index position.
+ */
 int lua_issystem(lua_State* L, int ind) {
   int ret;
 
@@ -379,7 +492,21 @@ int lua_issystem(lua_State* L, int ind) {
   return ret;
 }
 
-/* Get a system. */
+/**
+ * @ingroup SPACE
+ *
+ * @brief system getSystem([param])
+ *
+ * Get a system.
+ *
+ * Behaves differently depending on what you pass as param:
+ *    -- nil    : Get the current system.
+ *    -- string : Get the system by name.
+ *    -- planet : Get the system by planet.
+ *
+ *    @param param Read description for details.
+ *    @return System metatable matching param.
+ */
 static int systemL_get(lua_State* L) {
   LuaSystem sys;
   LuaPlanet* p;
@@ -404,7 +531,17 @@ static int systemL_get(lua_State* L) {
   return 1;
 }
 
-/* Check system for equality. */
+/**
+ * @ingroup META_SYSTEM
+ *
+ * @brief bool __eq(system comp)
+ *
+ * Check systems for equality.
+ * 
+ * Allows you to use the '=' operator in Lua with systems.
+ *    @param comp System to compare against.
+ *    @return true if both systems are the same.
+ */
 static int systemL_eq(lua_State* L) {
   LuaSystem* a, *b;
   a = lua_tosystem(L, 1);
@@ -417,7 +554,14 @@ static int systemL_eq(lua_State* L) {
   return 1;
 }
 
-/* Return the systems name. */
+/**
+ * @ingroup META_SYSTEM
+ *
+ * @brief string name(nil)
+ *
+ * Return the systems name.
+ *    @return The name of the system.
+ */
 static int systemL_name(lua_State* L) {
   LuaSystem* sys;
   sys = lua_tosystem(L, 1);
@@ -425,7 +569,21 @@ static int systemL_name(lua_State* L) {
   return 1;
 }
 
-/* Get system factions. */
+/**
+ * @ingroup META_SYSTEM
+ *
+ * @brief table faction(nil)
+ *
+ * Get system factions.
+ *
+ * @code
+ * foo = space.faction("foo")
+ * if foo["bar"] then
+ *    print("faction 'bar' found")
+ * end
+ * @endcode
+ *    @return A table containing all the factions in the system.
+ */
 static int systemL_faction(lua_State* L) {
   int i;
   LuaSystem* sys;
@@ -444,7 +602,21 @@ static int systemL_faction(lua_State* L) {
   return 1;
 }
 
-/* Get jump distance for current system, or to another. */
+/**
+ * @ingroup META_SYSTEM
+ *
+ * @brief number jumpDist([param])
+ *
+ * Get jump distance from current system, or to another.
+ *
+ * Does different things depending on the parameter type:
+ *    -- nil    : Get distance from current system.
+ *    -- string : Get distance from system matching name.
+ *    -- system : Get distance from system.
+ *
+ *    @param param See description.
+ *    @return Number of jumps to system.
+ */
 static int systemL_jumpdistance(lua_State* L) {
   LLUA_MIN_ARGS(1);
   LuaSystem* sys;
@@ -536,10 +708,14 @@ int lua_isvector(lua_State* L, int ind) {
 }
 
 /**
- * @fn static int vectorL_new(lua_State* L)
  * @ingroup META_VECTOR
  *
- * @brief 
+ * @brief Vec2 new([number x, number y])
+ *
+ * Creates a new vector.
+ *    @param x if set, the X value for the new vector.
+ *    @param y if set, the Y value for the new vector.
+ *    @return The new vector.
  */
 static int vectorL_new(lua_State* L) {
   LuaVector v;
@@ -559,7 +735,6 @@ static int vectorL_new(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_add(lua_State* L)
  * @ingroup META_VECTOR
  *
  * @brief __add(Vec2 vector)
@@ -591,14 +766,16 @@ static int vectorL_add(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_sub(lua_State* L)
  * @ingroup META_VECTOR
  *
- * @brief __sub(Vec2 vector)
+ * @brief Subtracts a vector and some cartesian coords.
+ *    @luaparam x X coordinate to subtract.
+ *    @luaparam y Y coordinate to subtract.
  *
- * __sub(number x, number y)
- *
- * Subtracts two vectors or a vector and some cartesian coords.
+ * @luafunc __sub(vector)
+ * @brief Subtracts two vectors.
+ *    @luaparam x
+ * @luafunc __sub(x, y)
  */
 static int vectorL_sub(lua_State* L) {
   LLUA_MIN_ARGS(2);
@@ -627,13 +804,11 @@ static int vectorL_sub(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_mul(lua_State* L)
  * @ingroup META_VECTOR
  *
- * @brief __mul(number mod)
- *
- * Multiplies by a number.
- *    @param mod Amount to multiply by.
+ * @brief Multiplies a vector by a number.
+ *    @luaparam mod Amount to multiply by.
+ * @luafunc __mul(mod)
  */
 static int vectorL_mul(lua_State* L) {
   LLUA_MIN_ARGS(2);
@@ -654,13 +829,11 @@ static int vectorL_mul(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_div(lua_State* L)
  * @ingroup META_VECTOR
- *
- * @brief __div(number mod)
- *
- * Divides a vector by a number.
- *    @param mod Amount to divide by.
+ * 
+ * @brief Divides a vector by a number.
+ *    @luaparam mod Amount to divide by.
+ * @luafunc __div(mod)
  */
 static int vectorL_div(lua_State* L) {
   LLUA_MIN_ARGS(2);
@@ -681,13 +854,12 @@ static int vectorL_div(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_get(lua_State* L)
  * @ingroup META_VECTOR
  *
- * @brief number, number get(nil)
- *
- * Get the catesian positions of the vector.
+ * @brief Get the cartesian positions of the vector.
  *    @return X and Y position of the vector.
+ *
+ * @luafunc get()
  */
 static int vectorL_get(lua_State* L) {
   LLUA_MIN_ARGS(1);
@@ -703,13 +875,11 @@ static int vectorL_get(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_set(lua_State* L)
+ * @brief Set the vector by cartesian coordinates.
+ *    @luaparam x X coordinate to set.
+ *    @luaparam y Y coordinate to set.
  *
- * @brief set(number x, number y)
- *
- * Set the vector by cartesian coordinates.
- *    @param x X coordinate to set.
- *    @param y Y coordinate to set.
+ * @luafunc set(x, y)
  */
 static int vectorL_set(lua_State* L) {
   LLUA_MIN_ARGS(3);
@@ -732,14 +902,13 @@ static int vectorL_set(lua_State* L) {
 }
 
 /**
- * @fn static int vectorL_distance(lua_State* L)
  * @ingroup META_VECTOR
  *
- * @brief number dist( [Vec2 vector] )
- *
- * Get the distance from the Vec2.
+ * @brief Get the distance from the Vec2.
  *    @param vector Vector to get distance from, uses origin(0,0) if not set.
  *    @return The distance calculated.
+ *
+ * @luafunc dist(vector)
  */
 static int vectorL_distance(lua_State* L) {
   LLUA_MIN_ARGS(1);
@@ -771,10 +940,9 @@ static int vectorL_distance(lua_State* L) {
 /**
  * @ingroup META_VECTOR.
  *
- * @brief number mod(nil)
- *
- * Gets the modulus of the vector.
+ * @brief Gets the modulus of the vector.
  *    @return The modulus of the vector.
+ * @luafunc mod()
  */
 static int vectorL_mod(lua_State* L) {
   LLUA_MIN_ARGS(1);
diff --git a/src/map.c b/src/map.c
index 1af0f72..bab7b46 100644
--- a/src/map.c
+++ b/src/map.c
@@ -628,7 +628,8 @@ void map_select(StarSystem* sys) {
  * @brief Node structure for A* pathfinding.
  */
 typedef struct SysNode_ {
-  struct SysNode_* next, *gnext;
+  struct SysNode_* next;    /**< Next node. */
+  struct SysNode_* gnext;   /**< Next node in the garbage collector. */
 
   struct SysNode_* parent;
   StarSystem* sys;
diff --git a/src/physics.h b/src/physics.h
index ed23d1d..7921199 100644
--- a/src/physics.h
+++ b/src/physics.h
@@ -18,8 +18,9 @@
  * @brief Represents a 2d vector.
  */
 typedef struct Vec2_ {
-  double x, y; /* Cartesian values. */
-  double mod, angle; /* Polar values. */
+  double x, y;  /**< Cartesian values. */
+  double mod;   /**< Modulus of the vector. */
+  double angle; /**< Angle of the vector. */
 } Vec2;
 
 /* Misc */
@@ -42,9 +43,13 @@ double vect_dot(Vec2* a, Vec2* b);
  * @brief Represents a solid in the game.
  */
 typedef struct Solid_ {
-  double mass, dir, dir_vel; /* Properties. */
-  Vec2 vel, pos, force; /* Position/velocity vectors. */
-  void(*update)(struct Solid_*, const double); /* Update method. */
+  double mass;    /**< Solids mass. */
+  double dir;     /**< Direction solid is facing. */
+  double dir_vel; /**< Velocity at which solid is rotating. */
+  Vec2 vel;       /**< Velocity of the solid. */
+  Vec2 pos;       /**< Position of the solid. */
+  Vec2 force;     /**< Forces acting on the solid. */
+  void(*update)(struct Solid_*, const double); /**< Update method. */
 } Solid;
 
 /* Solid manipulation. */