[Add] Documented specail effects.

src/spfx.c

@@ -73,7 +73,17 @@ static void spfx_base_free(SPFX_Base* effect);
 static void spfx_destroy(SPFX* layer, int* nlayer, int spfx);
 static void spfx_update_layer(SPFX* layer, int* nlayer, const double dt);
 
-/* Load the SPFX_Base. */
+/**
+ * @fn static int spfx_base_load(char* name, int ttl, int anim, char* gfx, int sx, int sy)
+ *
+ * @brief Load an SPFX_Base into the stack based on some params.
+ *    @param name Name of the spfx.
+ *    @param ttl Time to live of the spfx.
+ *    @param gfx Name of the graphic effect to use.
+ *    @param sx Number of x sprites in the graphic.
+ *    @param sy Number of y sprites in the graphic.
+ *    @return 0 on success.
+ */
 static int spfx_base_load(char* name, int ttl, int anim, char* gfx, int sx, int sy) {
   SPFX_Base* cur;
   char buf[PATH_MAX];
@@ -92,22 +102,40 @@ static int spfx_base_load(char* name, int ttl, int anim, char* gfx, int sx, int
   return 0;
 }
 
+/**
+ * @fn static void spfx_base_free(SPFX_Base* effect)
+ *
+ * @brief Free an SPFX_Base.
+ *    @param effect SPFX_Base to free.
+ */
 static void spfx_base_free(SPFX_Base* effect) {
   if(effect->name != NULL)  free(effect->name);
   if(effect->gfx != NULL)   gl_freeTexture(effect->gfx);
 }
 
+/**
+ * @fn int spfx_get(char* name)
+ *
+ * @brief Get the id of an spfx based on name.
+ *    @param name Name to match.
+ *    @return ID of the special effect or -1 on error.
+ */
 int spfx_get(char* name) {
   int i;
   for(i = 0; i < spfx_neffects; i++)
     if(strcmp(spfx_effects[i].name, name)==0)
       return i;
   WARN("SPFX '%s' not found!", name);
-  return 0;
+  return -1;
 }
 
-/* Load/Unload. 
- * @todo Make it customizable?
+/**
+ * @fn int spfx_load(void)
+ *
+ * @brief Load the spfx stack.
+ *    @return 0 on success.
+ * 
+ * @todo Make spfx not hardcoded.
  */
 int spfx_load(void) {
   /* Standard explosion effects. */
@@ -118,6 +146,11 @@ int spfx_load(void) {
   return 0;
 }
 
+/**
+ * @fn void spfx_free(void)
+ *
+ * @brief Free the spfx stack.
+ */
 void spfx_free(void) {
   int i;
 
@@ -137,6 +170,20 @@ void spfx_free(void) {
   spfx_neffects = 0;
 }
 
+/**
+ * @fn void spfx_add(int effect,
+ *             const double px, const double py,
+ *             const double vx, const double vy,
+ *             const int layer) {
+ *
+ * @brief Create a new special effect.
+ *    @param effect Base effect identifier to use.
+ *    @param px X position of the effect.
+ *    @param py Y position of the effect.
+ *    @param vx X velocity of the effect.
+ *    @param vy Y velocity of the effect.
+ *    @param layer Layer to put the effect on.
+ */
 void spfx_add(int effect,
               const double px, const double py,
               const double vx, const double vy,
@@ -185,6 +232,11 @@ void spfx_add(int effect,
     cur_spfx->timer = ttl;
 }
 
+/**
+ * @fn void spfx_clear(void)
+ *
+ * @brief Clear all the currently running effects.
+ */
 void spfx_clear(void) {
   int i;
 
@@ -202,16 +254,38 @@ void spfx_clear(void) {
   shake_vel.x = shake_vel.y = 0.;
 }
 
+/**
+ * @fn static void spfx_destroy(SPFX* layer, int* nlayer, int spfx)
+ *
+ * @brief Destroys an active spfx.
+ *    @param layer Layer the spfx is on.
+ *    @param nlayer Pointer to the number of elements in the layer.
+ *    @param spfx Position of the spfx in the stack.
+ */
 static void spfx_destroy(SPFX* layer, int* nlayer, int spfx) {
   (*nlayer)--;
   memmove(&layer[spfx], &layer[spfx+1], (*nlayer-spfx)*sizeof(SPFX));
 }
 
+/**
+ * @fn void spfx_update(const double dt)
+ *
+ * @brief Update all the spfx.
+ *    @param dt Current delta tick.
+ */
 void spfx_update(const double dt) {
   spfx_update_layer(spfx_stack_front, &spfx_nstack_front, dt);
   spfx_update_layer(spfx_stack_back,  &spfx_nstack_back, dt);
 }
 
+/**
+ * @fn static void spfx_update_layer(SPFX* layer, int* nlayer, const double dt)
+ *
+ * @brief Update an individual spfx.
+ *    @param layer Layer the spfx is on.
+ *    @param nlayer Pointer to the assosiated nlayer.
+ *    @param dt Current delta tick.
+ */
 static void spfx_update_layer(SPFX* layer, int* nlayer, const double dt) {
   int i;
 
@@ -229,8 +303,15 @@ static void spfx_update_layer(SPFX* layer, int* nlayer, const double dt) {
   }
 }
 
-/* Prepare the rendering for special affects. */
-void spfx_start(double dt) {
+/**
+ * @fn void spfx_start(double dt)
+ *
+ * @brief Prepare the rendering for the special effects.
+ *
+ * Should be called at the beginning of the rendering loop.
+ *    @param dt Current delta tick.
+ */
+void spfx_start(const double dt) {
   GLdouble bx, by, x, y;
   double inc;
 
@@ -269,7 +350,14 @@ void spfx_start(double dt) {
   glOrtho(-bx+x, bx+x,  -by+y, by+y, -1., 1.);
 }
 
-/* Add ruuumble!! */
+/**
+ * @fn void spfx_shake(double mod)
+ *
+ * @brief Increases the current rumble level.
+ *
+ * Rumble will decay over time.
+ *    @param mod Modifier to increase levely by.
+ */
 void spfx_shake(double mod) {
   shake_rad += mod*SHAKE_MOD_FACTOR;
   if(shake_rad > SHAKE_MAX) shake_rad = SHAKE_MAX;
@@ -278,6 +366,13 @@ void spfx_shake(double mod) {
   vect_pset(&shake_vel, SHAKE_VEL_MOD*shake_rad, RNGF() * 2. * M_PI);
 }
 
+/**
+ * @fn void spfx_cinematic(void)
+ *
+ * @brief Set the cinematic mode.
+ *
+ * Should be run at the end of the render loop if needed.
+ */
 void spfx_cinematic(void) {
   glMatrixMode(GL_MODELVIEW);
   glPushMatrix(); /* Translation matrix. */
@@ -298,6 +393,12 @@ void spfx_cinematic(void) {
   glPopMatrix(); /* Translation matrix. */
 }
 
+/**
+ * @fn void spfx_render(const int layer)
+ * 
+ * @brief Render the entire spfx layer.
+ *    @param layer Layer to render.
+ */
 void spfx_render(const int layer) {
   SPFX* spfx_stack;
   int i, spfx_nstack;

src/spfx.h

@@ -21,7 +21,7 @@ void spfx_render(const int layer);
 void spfx_clear(void);
 
 /* Get ready to rumble! */
-void spfx_start(double dt);
+void spfx_start(const double dt);
 void spfx_shake(double mod);
 
 /* Other effects. */

src/weapon.c

@@ -44,6 +44,7 @@ extern int pilot_nstack;
 extern unsigned int player_target;
 
 /* Ai stuff. */
+/**< Triggers the 'attacked' function in the ai. */
 extern void ai_attacked(Pilot* attacked, const unsigned int attacker);
 
 /**
@@ -600,6 +601,7 @@ static void weapon_hit(Weapon* w, Pilot* p, WeaponLayer layer, Vec2* pos) {
  *    @param p Pilot that got hit.
  *    @param layer Layer to which the weapon belongs.
  *    @param pos Position of the hit.
+ *    @param dt Current delta tick.
  */
 static void weapon_hitBeam(Weapon* w, Pilot* p, WeaponLayer layer,
     Vec2 pos[2], const double dt) {