[Add] music.c is documented.

src/music.c

@@ -1,3 +1,8 @@
+/**
+ * @file music.c
+ * @brief Control all the music playing.
+ */
+
 #include <SDL_mixer.h>
 #include <SDL.h>
 
@@ -10,15 +15,15 @@
 #include "pack.h"
 #include "music.h"
 
-#define MUSIC_PREFIX    "../snd/music/"
-#define MUSIC_SUFFIX    ".ogg"
+#define MUSIC_PREFIX    "../snd/music/" /**< Prefix of where to find music. */
+#define MUSIC_SUFFIX    ".ogg"          /**< Suffix of music. */
 
-#define MUSIC_LUA_PATH  "../snd/music.lua"
+#define MUSIC_LUA_PATH  "../snd/music.lua" /**< Lua music control file. */
 
-int music_disabled = 0;
+int music_disabled = 0; /**< Whether or not music is disabled. */
 
 /* Global music lua. */
-static lua_State* music_lua = NULL;
+static lua_State* music_lua = NULL; /**< The Lua music control state. */
 /* Functions. */
 static int musicL_load(lua_State* L);
 static int musicL_play(lua_State* L);
@@ -28,15 +33,15 @@ static const luaL_reg music_methods[] = {
   { "play",   musicL_play },
   { "stop",   musicL_stop },
   {0, 0}
-};
+}; /**< Music specific methods. */
 
 /* What is available? */
-static char** music_selection = NULL;
-static int nmusic_selection = 0;
+static char** music_selection = NULL; /**< Available music selection. */
+static int nmusic_selection = 0;      /**< Size of available music selection. */
 
-static void* music_data       = NULL;
-static SDL_RWops* music_rw    = NULL;
-static Mix_Music* music_music = NULL;
+static void* music_data       = NULL; /**< Current music data. */
+static SDL_RWops* music_rw    = NULL; /**< Current music RWops. */
+static Mix_Music* music_music = NULL; /**< Current music. */
 
 /* Music stuff. */
 static int music_find(void);
@@ -46,7 +51,12 @@ static void music_rechoose(void);
 static int music_luaInit(void);
 static void music_luaQuit(void);
 
-/* Init/Exit. */
+/**
+ * @fn int music init(void)
+ *
+ * @brief Initializes the music subsystem.
+ *    @return 0 on success.
+ */
 int music_init(void) {
   if(music_disabled) return 0;
 
@@ -57,11 +67,20 @@ int music_init(void) {
   return 0;
 }
 
+/**
+ * @fn void music_exit(void)
+ *
+ * @brief Exits the music subsystem.
+ */
 void music_exit(void) {
   music_free();
 }
 
-/* Free the current playing music. */
+/**
+ * @fn static void music_free(void)
+ *
+ * @brief Free the current playing music.
+ */
 static void music_free(void) {
   if(music_music != NULL) {
     Mix_HookMusicFinished(NULL);
@@ -75,7 +94,12 @@ static void music_free(void) {
   }
 }
 
-/* Internal music loading routines. */
+/**
+ * @fn static int music_find(void)
+ *
+ * @brief Internal music loading routines.
+ *    @return 0 on success.
+ */
 static int music_find(void) {
   char** files;
   uint32_t nfiles, i;
@@ -113,14 +137,25 @@ static int music_find(void) {
   return 0;
 }
 
-/* Music control functions. */
+/**
+ * @fn int music_volume(const double vol)
+ *
+ * @brief Set the music volume.
+ *    @param vol Volume to set to (between 0 and 1).
+ *    @return 0 on success.
+ */
 int music_volume(const double vol) {
   if(music_disabled) return 0;
 
   return Mix_VolumeMusic(MIX_MAX_VOLUME*vol);
 }
 
-/* Music control functions. */
+/**
+ * @fn void music_load(const char* name)
+ *
+ * @brief Load the music by name.
+ *    @param name Name of the file to load.
+ */
 void music_load(const char* name) {
   unsigned int size;
   char filename[PATH_MAX];
@@ -140,6 +175,11 @@ void music_load(const char* name) {
   Mix_HookMusicFinished(music_rechoose);
 }
 
+/**
+ * @fn void music_play(void)
+ *
+ * @brief Play the loaded music.
+ */
 void music_play(void) {
   if(music_music == NULL) return;
 
@@ -147,6 +187,11 @@ void music_play(void) {
     WARN("SDL_Mixer: %s", Mix_GetError());
 }
 
+/**
+ * @fn void music_stop(void)
+ *
+ * @brief Stop the loaded music.
+ */
 void music_stop(void) {
   if(music_music == NULL) return;
 
@@ -156,7 +201,12 @@ void music_stop(void) {
 
 /* Music lua stuff. */
 
-/* Initialize. */
+/**
+ * @fn static int music_luaInit(void)
+ *
+ * @brief Initializes the music Lua control system.
+ *    @return 0 on success.
+ */
 static int music_luaInit(void) {
   char* buf;
   uint32_t bufsize;
@@ -188,7 +238,11 @@ static int music_luaInit(void) {
   return 0;
 }
 
-/* Destroy. */
+/**
+ * @fn static void music_luaQuit(void)
+ *
+ * @brief Quit the music Lua control system.
+ */
 static void music_luaQuit(void) {
   if(music_lua == NULL)
     return;
@@ -197,12 +251,27 @@ static void music_luaQuit(void) {
   music_lua = NULL;
 }
 
+/**
+ * @fn int lua_loadMusic(lua_State* L, int read_only)
+ *
+ * @brief Load the music functions into a lua_State.
+ *    @param L Lua State to load the music functions into.
+ *    @param read_only Load the write functions?
+ *    @return  0 on success.
+ */
 int lua_loadMusic(lua_State* L, int read_only) {
   (void)read_only; /* Future proof. */
   luaL_register(L, "music", music_methods);
   return 0;
 }
 
+/**
+ * @fn int music_choose(char* situation)
+ *
+ * @brief Actually run the music stuff, based on situation.
+ *    @param situation choose a new music to play.
+ *    @return 0 on success.
+ */
 int music_choose(char* situation) {
   if(music_disabled) return 0;
 
@@ -216,7 +285,11 @@ int music_choose(char* situation) {
   return 0;
 }
 
-/* Attempt to rechoose the music. */
+/**
+ * @fn static void music_rechoose(void)
+ *
+ * @brief Attempts to rechoose the music.
+ */
 static void music_rechoose(void) {
   music_choose("idle");
 }