[Add] Fully doxygenized sound.c

src/sound.c

@@ -1,8 +1,13 @@
+/**
+ * @file sound.c
+ *
+ * @brief Handle all the sound details.
+ */
+
 #include <sys/stat.h>
 
 #include <SDL.h>
 #include <SDL_mixer.h>
-#include <SDL_thread.h>
 
 #include "lephisto.h"
 #include "log.h"
@@ -11,31 +16,36 @@
 #include "physics.h"
 #include "sound.h"
 
-#define SOUND_CHANNEL_MAX 256 /* Overkill. */
+#define SOUND_CHANNEL_MAX 256 /**< Number of sound channels to allocate. Overkill. */
 
-#define SOUND_PREFIX      "../snd/sounds/"
+#define SOUND_PREFIX      "../snd/sounds/" /**< Prefix of where to find sounds. */
-#define SOUND_SUFFIX      ".wav"
+#define SOUND_SUFFIX      ".wav"           /**< Suffix of sounds. */
 
 /* Global sound properties. */
-int sound_disabled        = 0;  /* Whether sound is disabled. */
+int sound_disabled        = 0;  /**< Whether sound is disabled. */
-static int sound_reserved = 0;  /* Amount of reserved channels. */
+static int sound_reserved = 0;  /**< Amount of reserved channels. */
-static double sound_pos[3];     /* Position of listener. */
+static double sound_pos[3];     /**< Position of listener. */
 
 /* Give the buffers a name. */
 typedef struct alSound_ {
-  char* name;         /* Buffers name. */
+  char* name;         /**< Buffers name. */
-  Mix_Chunk* buffer;
+  Mix_Chunk* buffer;  /**< Buffer data. */
 } alSound;
 
 /* List of sounds available (All preloaded into a buffer). */
-static alSound* sound_list  = NULL;
+static alSound* sound_list  = NULL; /**< List of available sounds. */
-static int sound_nlist      = 0;
+static int sound_nlist      = 0;    /**< Number of available sounds. */
 
 static int  sound_makeList(void);
 static Mix_Chunk* sound_load(char* filename);
 static void sound_free(alSound* snd);
 
-/* Init the sound subsystem. */
+/**
+ * @fn int sound_init(void)
+ *
+ * @brief Initializes the sound subsystem.
+ *    @return 0 on success.
+ */
 int sound_init(void) {
   int frequency;
   Uint16 format;
@@ -73,7 +83,11 @@ int sound_init(void) {
   return 0;
 }
 
-/* Clean up after the sound system. */
+/**
+ * @fn void sound_exit(void)
+ *
+ * @brief Clean up after the sound subsystem.
+ */
 void sound_exit(void) {
   int i;
   
@@ -87,7 +101,13 @@ void sound_exit(void) {
   music_exit();
 }
 
-/* Get the buffer to sound of name. */
+/**
+ * @fn void sound_get(char* name)
+ *
+ * @brief Get the buffer to sound of name.
+ *    @param name Name of the sound to get id of.
+ *    @return ID of the sound matching name.
+ */
 int sound_get(char* name) {
   int i;
 
@@ -102,7 +122,13 @@ int sound_get(char* name) {
   return -1;
 }
 
-/* Play the sound. */
+/**
+ * @fn int sound_play(int sound)
+ *
+ * @brief Play the sound in the first available channel.
+ *    @param sound Sound to play.
+ *    @return 0 on success.
+ */
 int sound_play(int sound) {
   int channel;
 
@@ -119,6 +145,15 @@ int sound_play(int sound) {
   return 0;
 }
 
+/**
+ * @fn int sound_playPos(int sound, double x, double y)
+ *
+ * @brief Play a sound based on position.
+ *    @param sound Sound to play.
+ *    @param x X position of sound.
+ *    @param y Y position of sound.
+ *    @return 0 on success.
+ */
 int sound_playPos(int sound, double x, double y) {
   int channel;
   double angle, dist;
@@ -151,6 +186,16 @@ int sound_playPos(int sound, double x, double y) {
   return 0;
 }
 
+/**
+ * @fn int sound_updateListener(double dir, double x, double y)
+ *
+ * @brief Update the sound listener.
+ *    @param dir Direction listener if facing.
+ *    @param x X position of the listener.
+ *    @param y Y position of the listener.
+ *
+ * @sa sound_playPos
+ */
 int sound_updateListener(double dir, double x, double y) {
   sound_pos[0] = x;
   sound_pos[1] = y;
@@ -158,7 +203,11 @@ int sound_updateListener(double dir, double x, double y) {
   return 0;
 }
 
-/* Make list of available sounds. */
+/**
+ * @fn static int sound_makeList(void)
+ *
+ * @brief Make the list of available sounds.
+ */
 static int sound_makeList(void) {
   char** files;
   uint32_t nfiles, i;
@@ -208,13 +257,27 @@ static int sound_makeList(void) {
   return 0;
 }
 
-/* Set the volume. */
+/**
+ * @fn int sound_volume(const double vol)
+ *
+ * @brief Set the volume.
+ *    @param vol Volume to set to.
+ *    @return 0 on success.
+ */
 int sound_volume(const double vol) {
   if(sound_disabled) return 0;
   return Mix_Volume(-1, MIX_MAX_VOLUME*vol);
 }
 
-/* Loads a sound into the sound_list. */
+/**
+ * @fn stastic Mix_Chunk* sound_load(char* filename)
+ *
+ * @brief Load a sound into the sound_list.
+ *    @paramfilename Name for the file to load.
+ *    @return The SDL_Mixer of the loaded chunk.
+ *
+ * @sa sound_makeList
+ */
 static Mix_Chunk* sound_load(char* filename) {
   void* wavdata;
   unsigned int size;
@@ -239,6 +302,12 @@ static Mix_Chunk* sound_load(char* filename) {
   return buffer;
 }
 
+/**
+ * @fn static void sound_free(alSound* snd)
+ *
+ * @brief Frees the sound.
+ *    @param snd Sound to free.
+ */
 static void sound_free(alSound* snd) {
   /* Free the stuff. */
   if(snd->name) {
@@ -250,7 +319,13 @@ static void sound_free(alSound* snd) {
   snd->buffer = NULL;
 }
 
-/* Reserve num channels. */
+/**
+ * @fn int sound_reverse(int num)
+ * 
+ * @brief Reserve num channels.
+ *    @param num Number of channels to reserve.
+ *    @return 0 on success.
+ */
 int sound_reserve(int num) {
   int ret;
 
@@ -267,7 +342,15 @@ int sound_reserve(int num) {
   return 0;
 }
 
-/* Create a sound group. */
+/**
+ * @fn int sound_createGroup(int tag, int start, int size)
+ *
+ * @brief Create a sound group.
+ *    @param tag Identifier of the group to create.
+ *    @param start Where to start creating the group.
+ *    @param size Size of the group.
+ *    @return 0 on success.
+ */
 int sound_createGroup(int tag, int start, int size) {
   int ret;
 
@@ -283,7 +366,15 @@ int sound_createGroup(int tag, int start, int size) {
   return 0;
 }
 
-/* Play a sound in a group. */
+/**
+ * @fn int sound_playGroup(int group, int sound, int once)
+ *
+ * @brief Play a sound in a group.
+ *    @param group Group to play sound in.
+ *    @param sound Sound to play.
+ *    @param once Whether to play only once.
+ *    @param 0 on success.
+ */
 int sound_playGroup(int group, int sound, int once) {
   int ret, channel;
 
@@ -303,7 +394,12 @@ int sound_playGroup(int group, int sound, int once) {
   return 0;
 }
 
-/* Stop all the sounds in a group. */
+/**
+ * @fn void sound_stopGroup(int group)
+ *
+ * @brief Stop all the sounds in a group.
+ *    @param group Group to stop all it's sounds.
+ */
 void sound_stopGroup(int group) {
   if(sound_disabled) return;