(svn r22410) -Document: some more bits ;)

src/music/allegro_m.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** Allegro's music player. */
 class MusicDriver_Allegro: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "allegro"; }
 };
 
+/** Factory for allegro's music player. */
 class FMusicDriver_Allegro: public MusicDriverFactory<FMusicDriver_Allegro> {
 public:
 #if !defined(WITH_SDL) && defined(WITH_ALLEGRO)

src/music/bemidi.cpp

@@ -16,8 +16,10 @@
 /* BeOS System Includes */
 #include <MidiSynthFile.h>
 
+/** The file we're playing. */
 static BMidiSynthFile midiSynthFile;
 
+/** Factory for BeOS' midi player. */
 static FMusicDriver_BeMidi iFMusicDriver_BeMidi;
 
 const char *MusicDriver_BeMidi::Start(const char * const *parm)

src/music/bemidi.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** The midi player for BeOS. */
 class MusicDriver_BeMidi: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "bemidi"; }
 };
 
+/** Factory for the BeOS midi player. */
 class FMusicDriver_BeMidi: public MusicDriverFactory<FMusicDriver_BeMidi> {
 public:
 	static const int priority = 10;

src/music/dmusic.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** Music player making use of DirectX. */
 class MusicDriver_DMusic: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "dmusic"; }
 };
 
+/** Factory for the DirectX music player. */
 class FMusicDriver_DMusic: public MusicDriverFactory<FMusicDriver_DMusic> {
 public:
 	static const int priority = 10;

src/music/extmidi.cpp

@@ -26,9 +26,11 @@
 #include <errno.h>
 
 #ifndef EXTERNAL_PLAYER
+/** The default external midi player. */
 #define EXTERNAL_PLAYER "timidity"
 #endif
 
+/** Factory for the midi player that uses external players. */
 static FMusicDriver_ExtMidi iFMusicDriver_ExtMidi;
 
 const char *MusicDriver_ExtMidi::Start(const char * const * parm)

src/music/libtimidity.cpp

@@ -26,6 +26,7 @@
 #include <pspaudiolib.h>
 #endif /* PSP */
 
+/** The state of playing. */
 enum MidiState {
 	MIDI_STOPPED = 0,
 	MIDI_PLAYING = 1,
@@ -39,7 +40,7 @@ static struct {
 	MidiState status;
 	uint32 song_length;
 	uint32 song_position;
-} _midi;
+} _midi; ///< Metadata about the midi we're playing.
 
 #if defined(PSP)
 static void AudioOutCallback(void *buf, unsigned int _reqn, void *userdata)
@@ -51,6 +52,7 @@ static void AudioOutCallback(void *buf, unsigned int _reqn, void *userdata)
 }
 #endif /* PSP */
 
+/** Factory for the libtimidity driver. */
 static FMusicDriver_LibTimidity iFMusicDriver_LibTimidity;
 
 const char *MusicDriver_LibTimidity::Start(const char * const *param)

src/music/libtimidity.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** Music driver making use of libtimidity. */
 class MusicDriver_LibTimidity: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "libtimidity"; }
 };
 
+/** Factory for the libtimidity driver. */
 class FMusicDriver_LibTimidity: public MusicDriverFactory<FMusicDriver_LibTimidity> {
 public:
 	static const int priority = 5;

src/music/music_driver.hpp

@@ -14,20 +14,41 @@
 
 #include "../driver.h"
 
+/** Driver for all music playback. */
 class MusicDriver: public Driver {
 public:
+	/**
+	 * Play a particular song.
+	 * @param filename The name of file with the song to play.
+	 */
 	virtual void PlaySong(const char *filename) = 0;
 
+	/**
+	 * Stop playing the current song.
+	 */
 	virtual void StopSong() = 0;
 
+	/**
+	 * Are we currently playing a song?
+	 * @return True if a song is being played.
+	 */
 	virtual bool IsSongPlaying() = 0;
 
+	/**
+	 * Set the volume, if possible.
+	 * @param vol The new volume.
+	 */
 	virtual void SetVolume(byte vol) = 0;
 };
 
+/** Base of the factory for the music drivers. */
 class MusicDriverFactoryBase: public DriverFactoryBase {
 };
 
+/**
+ * Factory for the music drivers.
+ * @tparam T The type of the music factory to register.
+ */
 template <class T>
 class MusicDriverFactory: public MusicDriverFactoryBase {
 public:

src/music/null_m.cpp

@@ -12,5 +12,5 @@
 #include "../stdafx.h"
 #include "null_m.h"
 
+/** The factory for the music player that does nothing. */
 static FMusicDriver_Null iFMusicDriver_Null;
-

src/music/null_m.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** The music player that does nothing. */
 class MusicDriver_Null: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param) { return NULL; }
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "null"; }
 };
 
+/** Factory for the null music player. */
 class FMusicDriver_Null: public MusicDriverFactory<FMusicDriver_Null> {
 public:
 	static const int priority = 1;

src/music/os2_m.cpp

@@ -29,6 +29,11 @@
  * eh? Anyone would think they both came from the same place originally! ;)
  */
 
+/**
+ * Send a midi command.
+ * @param cmd The command to send.
+ * @return The result of sending it.
+ */
 static long CDECL MidiSendCommand(const char *cmd, ...)
 {
 	va_list va;
@@ -39,6 +44,7 @@ static long CDECL MidiSendCommand(const char *cmd, ...)
 	return mciSendString(buf, NULL, 0, NULL, 0);
 }
 
+/** OS/2's music player's factory. */
 static FMusicDriver_OS2 iFMusicDriver_OS2;
 
 void MusicDriver_OS2::PlaySong(const char *filename)

src/music/os2_m.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** OS/2's music player. */
 class MusicDriver_OS2: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "os2"; }
 };
 
+/** Factory for OS/2's music player. */
 class FMusicDriver_OS2: public MusicDriverFactory<FMusicDriver_OS2> {
 public:
 	static const int priority = 10;

src/music/win32_m.h

@@ -14,6 +14,7 @@
 
 #include "music_driver.hpp"
 
+/** The Windows music player. */
 class MusicDriver_Win32: public MusicDriver {
 public:
 	/* virtual */ const char *Start(const char * const *param);
@@ -30,6 +31,7 @@ public:
 	/* virtual */ const char *GetName() const { return "win32"; }
 };
 
+/** Factory for Windows' music player. */
 class FMusicDriver_Win32: public MusicDriverFactory<FMusicDriver_Win32> {
 public:
 	static const int priority = 5;