TONY: Doxygen-ify comments in sound files

2 files changed, 372 insertions, 636 deletions

diff --git a/engines/tony/sound.cpp b/engines/tony/sound.cpp
index e650a5d74b..d8b3655d2e 100644
--- a/engines/tony/sound.cpp
+++ b/engines/tony/sound.cpp
@@ -37,70 +37,43 @@
 namespace Tony {
 
 
-/****************************************************************************\
-*       Defines
-\****************************************************************************/
-
 #define RELEASE(x)             {if ((x) != NULL) { (x)->release(); x = NULL; }}
 
-/****************************************************************************\
-*       Methods for FPSound
-\****************************************************************************/
-
-/****************************************************************************\
-*
-* Function:     FPSound::FPSound();
-*
-* Description:  Default constructor. Initializes the attributes.
-*
-\****************************************************************************/
+/**
+ * Default constructor. Initializes the attributes.
+ *
+ */
 
 FPSound::FPSound() {
 	_bSoundSupported = false;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool FPSound::init();
-*
-* Description:  Initializes the object, and prepare everything you need to
-                create streams and sound effects.
-*
-* Return:       True if everything's OK, False otherwise.
-*
-\****************************************************************************/
+/**
+ * Initializes the object, and prepare everything you need to create streams and sound effects.
+ *
+ * @returns     True is everything is OK, False otherwise
+ */
 
 bool FPSound::init() {
 	_bSoundSupported = g_system->getMixer()->isReady();
 	return _bSoundSupported;
 }
 
-
-/****************************************************************************\
-*
-* Function:     FPSound::~FPSound();
-*
-* Description:  Destroy the object and free the memory.
-*
-\****************************************************************************/
+/**
+ * Destroy the object and free the memory
+ *
+ */
 
 FPSound::~FPSound() {
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool CreateStream(FPStream** lplpStream);
-*
-* Description:  Allocates an object of type FPStream, and return its pointer
-*
-* Input:        FPStream** lplpStream   Will contain a pointer to the object
-*                                       you just created.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Allocates an object of type FPStream, and return its pointer
+ *
+ * @param lplpStream   Will contain a pointer to the object you just created.
+ *
+ * @returns     True is everything is OK, False otherwise
+ */
 
 bool FPSound::createStream(FPStream **lplpStream) {
 	(*lplpStream) = new FPStream(_bSoundSupported);
@@ -108,18 +81,13 @@ bool FPSound::createStream(FPStream **lplpStream) {
 	return (*lplpStream != NULL);
 }
 
-/****************************************************************************\
-*
-* Function:     bool CreateSfx(FPSfx** lplpSfx);
-*
-* Description:  Allocates an object of type FpSfx, and return its pointer
-*
-* Input:        FPSfx** lplpSfx         Will contain a pointer to the object
-*                                       you just created.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Allocates an object of type FpSfx, and return its pointer
+ *
+ * @param lplpSfx         Will contain a pointer to the object you just created.
+ *
+ * @returns     True is everything is OK, False otherwise
+ */
 
 bool FPSound::createSfx(FPSfx **lplpSfx) {
 	(*lplpSfx) = new FPSfx(_bSoundSupported);
@@ -127,15 +95,11 @@ bool FPSound::createSfx(FPSfx **lplpSfx) {
 	return (*lplpSfx != NULL);
 }
 
-/****************************************************************************\
-*
-* Function:     void setMasterVolume(int dwVolume);
-*
-* Description:  Set the general volume
-*
-* Input:        int dwVolume          Volume to set (0-63)
-*
-\****************************************************************************/
+/**
+ * Set the general volume
+ *
+ * @param dwVolume          Volume to set (0-63)
+ */
 
 void FPSound::setMasterVolume(int dwVolume) {
 	if (!_bSoundSupported)
@@ -144,16 +108,11 @@ void FPSound::setMasterVolume(int dwVolume) {
 	g_system->getMixer()->setVolumeForSoundType(Audio::Mixer::kPlainSoundType, CLIP<int>(dwVolume, 0, 63) * Audio::Mixer::kMaxChannelVolume / 63);
 }
 
-/****************************************************************************\
-*
-* Function:     void getMasterVolume(int *lpdwVolume);
-*
-* Description:  Get the general volume
-*
-* Input:        int *lpdwVolume        Variable that will contain the 
-*                                      volume (0-63)
-*
-\****************************************************************************/
+/**
+ * Get the general volume
+ *
+ * @param lpdwVolume          Variable that will contain the volume (0-63)
+ */
 
 void FPSound::getMasterVolume(int *lpdwVolume) {
 	if (!_bSoundSupported)
@@ -162,18 +121,13 @@ void FPSound::getMasterVolume(int *lpdwVolume) {
 	*lpdwVolume = g_system->getMixer()->getVolumeForSoundType(Audio::Mixer::kPlainSoundType) * 63 / Audio::Mixer::kMaxChannelVolume;
 }
 
-/****************************************************************************\
-*       Methods for FPSfx
-\****************************************************************************/
-
-/****************************************************************************\
-*
-* Function:     FPSfx(bool bSoundOn);
-*
-* Description:  Default constructor. Do *NOT* declare an object directly, 
-*               but rather create it using FPSound::CreateSfx()
-*
-\****************************************************************************/
+/**
+ * Default constructor.
+ *
+ * @remarks                   Do *NOT* declare an object directly, but rather
+ *                            create it using FPSound::CreateSfx()
+ *
+ */
 
 FPSfx::FPSfx(bool bSoundOn) {
 	_bSoundSupported = bSoundOn;
@@ -188,15 +142,13 @@ FPSfx::FPSfx(bool bSoundOn) {
 	_vm->_activeSfx.push_back(this);
 }
 
-
-/****************************************************************************\
-*
-* Function:     ~FPSfx();
-*
-* Description:  Default Destructor. It is also stops the sound effect that 
-*               may be currently played, and free the memory it uses.
-*
-\****************************************************************************/
+/**
+ * Default Destructor.
+ *
+ * @remarks                   It is also stops the sound effect that may be
+ *                            currently played, and free the memory it uses.
+ *
+ */
 
 FPSfx::~FPSfx() {
 	if (!_bSoundSupported)
@@ -215,35 +167,19 @@ FPSfx::~FPSfx() {
 	//	CloseHandle(hEndOfBuffer);
 }
 
-/****************************************************************************\
-*
-* Function:     release();
-*
-* Description:  Releases the memory used by the object.
-*               Must be called when the object is no longer used and 
-*               **ONLY** if the object was created by FPSound::CreateStream()
-*
-* Note:         Object pointers are no longer valid after this call.
-*
-\****************************************************************************/
+/**
+ * Releases the memory used by the object.
+ *
+ * @remarks                Must be called when the object is no longer used and
+ *                         **ONLY** if the object was created by
+ *                         FPSound::CreateStream().
+ *                         Object pointers are no longer valid after this call.
+ */
 
 void FPSfx::release() {
 	delete this;
 }
 
-/****************************************************************************\
-*
-* Function:     bool loadWave(Common::SeekableReadStream *stream);
-*
-* Description:  Opens a file and loads a sound effect.
-*
-* Input:        byte *lpBuf            Buffer containing the Sfx
-*               uint32 dwCodec         CODEC used to uncompress the samples
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
-
 bool FPSfx::loadWave(Common::SeekableReadStream *stream) {
 	if (!stream)
 		return false;
@@ -258,20 +194,6 @@ bool FPSfx::loadWave(Common::SeekableReadStream *stream) {
 	return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool LoadFile(const char * lpszFileName, uint32 dwCodec=FPCODEC_RAW);
-*
-* Description:  Opens a file and loads a sound effect.
-*
-* Input:        LPSTR lpszFile         Sfx filename
-*               uint32 dwCodec         CODEC used to uncompress the samples
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
-
 bool FPSfx::loadVoiceFromVDB(Common::File &vdbFP) {
 	if (!_bSoundSupported)
 		return true;
@@ -287,6 +209,14 @@ bool FPSfx::loadVoiceFromVDB(Common::File &vdbFP) {
 	return true;
 }
 
+/**
+ * Opens a file and loads a sound effect.
+ *
+ * @param lpszFileName     Sfx filename
+ * @param dwCodec          CODEC used to uncompress the samples
+ *
+ * @returns                True is everything is OK, False otherwise
+ */
 
 bool FPSfx::loadFile(const char *lpszFileName, uint32 dwCodec) {
 	if (!_bSoundSupported)
@@ -323,16 +253,11 @@ bool FPSfx::loadFile(const char *lpszFileName, uint32 dwCodec) {
 	return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool play();
-*
-* Description:  Play the Sfx in memory.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Play the Sfx in memory.
+ *
+ * @returns                True is everything is OK, False otherwise
+ */
 
 bool FPSfx::play() {
 	stop(); // sanity check
@@ -365,16 +290,11 @@ bool FPSfx::play() {
 	return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool stop(void);
-*
-* Description:  Stop an sfx.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Stops a Sfx.
+ *
+ * @returns                True is everything is OK, False otherwise
+ */
 
 bool FPSfx::stop() {
 	if (_bFileLoaded) {
@@ -385,26 +305,25 @@ bool FPSfx::stop() {
 	return true;
 }
 
-
-
-/****************************************************************************\
-*
-* Function:     bool setLoop(bool bLoop);
-*
-* Description:  Enables or disables the Sfx loop.
-*
-* Input:        bool bLoop          True to enable the loop, False to disable
-*
-* Note:         The loop must be activated BEFORE the sfx starts playing. 
-*               Any changes made during the play will have no effect until 
-*               the sfx is stopped then played again.
-*
-\****************************************************************************/
+/**
+ * Enables or disables the Sfx loop.
+ *
+ * @param bLoop         True to enable the loop, False to disable
+ *
+ * @remarks             The loop must be activated BEFORE the sfx starts
+ *                      playing. Any changes made during the play will have
+ *                      no effect until the sfx is stopped then played again.
+ */
 
 void FPSfx::setLoop(bool bLop) {
 	_bLoop = bLop;
 }
 
+/**
+ * Pauses a Sfx.
+ *
+ */
+
 void FPSfx::pause(bool bPause) {
 	if (_bFileLoaded) {
 		if (g_system->getMixer()->isSoundHandleActive(_handle) && (bPause ^ _bPaused))
@@ -414,15 +333,12 @@ void FPSfx::pause(bool bPause) {
 	}
 }
 
-/****************************************************************************\
-*
-* Function:     void setVolume(int dwVolume);
-*
-* Description:  Change the volume of Sfx
-*
-* Input:        int dwVolume            Volume to be set (0-63)
-*
-\****************************************************************************/
+/**
+ * Change the volume of Sfx
+ *
+ * @param dwVolume      Volume to be set (0-63)
+ *
+ */
 
 void FPSfx::setVolume(int dwVolume) {
 	if (dwVolume > 63)
@@ -453,17 +369,12 @@ void FPSfx::setVolume(int dwVolume) {
 		g_system->getMixer()->setChannelVolume(_handle, dwVolume * Audio::Mixer::kMaxChannelVolume / 63);
 }
 
-
-
-/****************************************************************************\
-*
-* Function:     void GetVolume(int *lpdwVolume);
-*
-* Description:  Gets the Sfx volume
-*
-* Input:        int *lpdwVolume        Will contain the current Sfx volume
-*
-\****************************************************************************/
+/**
+ * Gets the Sfx volume
+ *
+ * @param lpdwVolume    Will contain the current Sfx volume
+ *
+ */
 
 void FPSfx::getVolume(int *lpdwVolume) {
 	if (g_system->getMixer()->isSoundHandleActive(_handle))
@@ -475,6 +386,7 @@ void FPSfx::getVolume(int *lpdwVolume) {
 /**
  * Returns true if the underlying sound has ended
  */
+
 bool FPSfx::endOfBuffer() const {
 	return !g_system->getMixer()->isSoundHandleActive(_handle) && (!_rewindableStream || _rewindableStream->endOfData());
 }
@@ -505,18 +417,12 @@ void FPSfx::soundCheckProcess(CORO_PARAM, const void *param) {
 	CORO_END_CODE;
 }
 
-/****************************************************************************\
-*       Methods for FPStream
-\****************************************************************************/
-
-/****************************************************************************\
-*
-* Function:     FPStream(LPDIRECTSOUND lpDS, bool bSoundOn);
-*
-* Description:  Default constructor. Do *NOT* declare an object directly, 
-*               but rather create it using FPSound::CreateStream()
-*
-\****************************************************************************/
+/**
+ * Default constructor. 
+ *
+ * @remarks             Do *NOT* declare an object directly, but rather
+ *                      create it using FPSound::CreateStream()
+ */
 
 FPStream::FPStream(bool bSoundOn) {
 #ifdef REFACTOR_ME
@@ -599,14 +505,11 @@ bool FPStream::createBuffer(int nBufSize) {
 	return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     ~FPStream();
-*
-* Description:  Default destructor. It calls CloseFile() if needed.
-*
-\****************************************************************************/
+/**
+ * Default destructor. 
+ *
+ * @remarks             It calls CloseFile() if needed.
+ */
 
 FPStream::~FPStream() {
 #ifdef REFACTOR_ME
@@ -648,37 +551,27 @@ FPStream::~FPStream() {
 #endif
 }
 
-
-/****************************************************************************\
-*
-* Function:     release();
-*
-* Description:  Releases the memory object. Must be called when the object 
-*               is no longer used and **ONLY** if the object was created by
-*               FPSound::CreateStream().
-*
-* Note:         Object pointers are no longer valid after this call.
-*
-\****************************************************************************/
+/**
+ * Releases the memory object. 
+ *
+ * @remarks             Must be called when the object is no longer used 
+ *                      and **ONLY** if the object was created by
+ *                      FPSound::CreateStream().
+ *                      Object pointers are no longer valid after this call.
+ */
 
 void FPStream::release() {
 	delete this;
-//	return NULL;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool loadFile(const char *lpszFileName, uint32 dwCodec=FPCODEC_RAW);
-*
-* Description:  Opens a file stream.
-*
-* Input:        LPSTR lpszFile          Filename to be opened
-*               uint32 dwCodec          CODEC to be used to uncompress samples
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Opens a file stream
+ *
+ * @param lpszFile      Filename to be opened
+ * @param dwCodec       CODEC to be used to uncompress samples
+ *
+ * @returns             True is everything is OK, False otherwise
+ */
 
 bool FPStream::loadFile(const char *lpszFileName, uint32 dwCodType, int nBufSize) {
 #ifdef REFACTOR_ME
@@ -714,18 +607,15 @@ bPaused = false;
 return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     unloadFile();
-*
-* Description:  Closes a file stream (opened or not). It is necessary to call
-*               this function to free the memory used by the stream.
-*
-* Return:       For safety, the destructor calls unloadFile() if it has not
-*               been mentioned explicitly.
-*
-\****************************************************************************/
+/**
+ * Closes a file stream (opened or not).
+ *
+ * @returns             For safety, the destructor calls unloadFile() if it has not
+ *                      been mentioned explicitly.
+ * 
+ * @remarks             It is necessary to call this function to free the 
+ *                      memory used by the stream.
+ */
 
 bool FPStream::unloadFile() {
 #ifdef REFACTOR_ME
@@ -745,16 +635,6 @@ bool FPStream::unloadFile() {
 	return true;
 }
 
-/****************************************************************************\
-*
-* Function:     bool Play();
-*
-* Description:  Play the stream.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
-
 void FPStream::prefetch(void) {
 #ifdef REFACTOR_ME
 	uint32 dwId;
@@ -845,6 +725,12 @@ void FPStream::playFast(void) {
 #endif
 }
 
+/**
+ * Play the stream.
+ *
+ * @returns             True is everything is OK, False otherwise
+ */
+
 bool FPStream::play() {
 #ifdef REFACTOR_ME
 	uint32 dwId;
@@ -922,16 +808,12 @@ bool FPStream::play() {
 	return true;
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool stop(bool bSync);
-*
-* Description:  Closes the stream.
-*
-* Return:       True is everything is OK, False otherwise
-*
-\****************************************************************************/
+/**
+ * Closes the stream.
+ *
+ * @returns             True is everything is OK, False otherwise
+ * 
+ */
 
 bool FPStream::stop(bool bSync) {
 #ifdef REFACTOR_ME
@@ -1005,13 +887,10 @@ void FPStream::waitForSync(FPStream *toplay) {
 	_bIsPlaying = false;
 }
 
-/****************************************************************************\
-*
-* Function:     void FPStream::PlayThread();
-*
-* Description:  Thread playing the stream
-*
-\****************************************************************************/
+/**
+ * Thread playing the stream
+ *
+ */
 
 void FPStream::playThread(FPStream *This) {
 #ifdef REFACTOR_ME
@@ -1126,26 +1005,27 @@ void FPStream::playThread(FPStream *This) {
 #endif
 }
 
-
-/****************************************************************************\
-*
-* Function:     bool setLoop(bool bLoop);
-*
-* Description:  Unables or disables stream loop.
-*
-* Input:        bool bLoop              True enable loop, False disables it
-*
-* Note:         The loop must be activated BEFORE the stream starts playing. 
-*               Any changes made during the play will have no effect until 
-*               the stream is stopped then played again.
-*
-\****************************************************************************/
+/**
+ * Unables or disables stream loop.
+ *
+ * @param bLoop         True enable loop, False disables it
+ *
+ * @remarks             The loop must be activated BEFORE the stream starts
+ *                      playing. Any changes made during the play will have no
+ *                      effect until the stream is stopped then played again.
+ */
 
 void FPStream::setLoop(bool loop) {
 	_bLoop = loop;
 }
 
 
+/**
+ * Pause sound effect
+ *
+ * @param bPause        True enables pause, False disables it
+ */
+
 void FPStream::pause(bool bPause) {
 #ifdef REFACTOR_ME
 
@@ -1179,16 +1059,12 @@ void FPStream::pause(bool bPause) {
 #endif
 }
 
-
-/****************************************************************************\
-*
-* Function:     void SetVolume(int dwVolume);
-*
-* Description:  Change the volume of the stream
-*
-* Input:        int dwVolume            Volume to be set (0-63)
-*
-\****************************************************************************/
+/**
+ * Change the volume of the stream
+ *
+ * @param dwVolume      Volume to be set (0-63)
+ *
+ */
 
 void FPStream::setVolume(int dwVolume) {
 #ifdef REFACTOR_ME
@@ -1208,16 +1084,12 @@ void FPStream::setVolume(int dwVolume) {
 #endif
 }
 
-/****************************************************************************\
-*
-* Function:     void GetVolume(int *lpdwVolume);
-*
-* Description:  Gets the vgolume of the stream
-*
-* Input:        int *lpdwVolume        Variable that will contain the 
-*                                      current volume
-*
-\****************************************************************************/
+/**
+ * Gets the vgolume of the stream
+ *
+ * @param lpdwVolume    Variable that will contain the current volume
+ *
+ */
 
 void FPStream::getVolume(int *lpdwVolume) {
 #ifdef REFACTOR_ME
diff --git a/engines/tony/sound.h b/engines/tony/sound.h
index 5e50c31554..e1f0e40851 100644
--- a/engines/tony/sound.h
+++ b/engines/tony/sound.h
@@ -50,131 +50,77 @@ enum SoundCodecs {
 };
 
 
-/****************************************************************************\
-*****************************************************************************
-*       class FPSound
-*       -------------
-* Description: Sound driver per Falling Pumpkins
-*****************************************************************************
-\****************************************************************************/
+//****************************************************************************
+//* class FPSound
+//* -------------
+//* Description: Sound driver For Tony Tough
+//****************************************************************************
 
 class FPSound {
-
 private:
-
 	bool _bSoundSupported;
 
-	/****************************************************************************\
-	*       Methods
-	\****************************************************************************/
-
 public:
-
-	/****************************************************************************\
-	*
-	* Function:     FPSound::FPSound();
-	*
-	* Description:  Default constructor. Initializes the attributes
-	*
-	\****************************************************************************/
+	/**
+	 * Default constructor. Initializes the attributes.
+	 *
+	 */
 
 	FPSound();
 
-	/****************************************************************************\
-	*
-	* Function:     FPSound::~FPSound();
-	*
-	* Description:  Deinitialize the object, free memory
-	*
-	\****************************************************************************/
+	/**
+	 * Destroy the object and free the memory
+	 *
+	 */
 
 	~FPSound();
 
-	/****************************************************************************\
-	*
-	* Function:     bool FPSound::Init();
-	*
-	* Description:  Initializes the objects, and prepare everything required to 
-	*               create streams and sound effects.
-	*
-	* Return:       True if everything is OK, False otherwise.
-	*
-	\****************************************************************************/
+	/**
+	 * Initializes the object, and prepare everything you need to create streams and sound effects.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool init();
 
-	/****************************************************************************\
-	*
-	* Function:     bool CreateStream(FPStream** lplpStream);
-	*
-	* Description:  Allocates an object of type FPStream, and return its 
-	*               pointer after it has been initialized.
-	*
-	* Input:        FPStream** lplpStream   Will contain the pointer of the 
-	*                                       object
-	*
-	* Return:       True is everything i OK, False otherwise
-	*
-	* Note:         The use of functions like CreateStream () and CreateSfx () 
-	*               are due to the fact that the class constructors and 
-	*               FPStream FPSfx require that DirectSound is already initialized. 
-	*               In this way, you avoid the bugs that would be created if an 
-	*               object type is declared FPStream FPSfx or global 
-	*               (or anyway before initializing DirectSound).
-	\****************************************************************************/
+	/**
+	 * Allocates an object of type FPStream, and return its pointer
+	 *
+	 * @param lplpStream    Will contain a pointer to the object you just created.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool createStream(FPStream **lplpStream);
 
-	/****************************************************************************\
-	*
-	* Function:     bool CreateSfx(FPSfx** lplpSfx);
-	*
-	* Description:  Allocates an object of type FPSfx and returns a pointer 
-	*               pointing to it
-	*
-	* Input:        FPSfx** lplpSfx         Will contain the pointer of the 
-	*                                       object
-	*
-	* Return:       True is everything i OK, False otherwise
-	*
-	* Note:         See notes about CreateStream()
-	*
-	\****************************************************************************/
+	/**
+	 * Allocates an object of type FpSfx, and return its pointer
+	 *
+	 * @param lplpSfx       Will contain a pointer to the object you just created.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool createSfx(FPSfx **lplpSfx);
 
-	/****************************************************************************\
-	*
-	* Function:     void SetMasterVolume(int dwVolume);
-	*
-	* Description:  Set main volume
-	*
-	* Input:        int dwVolume          Volume to be set (0-63)
-	*
-	\****************************************************************************/
+	/**
+	 * Set the general volume
+	 *
+	 * @param dwVolume      Volume to set (0-63)
+	 */
 
 	void setMasterVolume(int dwVolume);
 
-	/****************************************************************************\
-	*
-	* Function:     void GetMasterVolume(LPINT lpdwVolume);
-	*
-	* Description:  Get main volume
-	*
-	* Input:        LPINT lpdwVolume        This variable will contain the 
-	*                                       current volume (0-63)
-	*
-	\****************************************************************************/
+	/**
+	 * Get the general volume
+	 *
+	 * @param lpdwVolume    Variable that will contain the volume (0-63)
+	 */
 
 	void getMasterVolume(int *lpdwVolume);
 };
 
 class FPSfx {
-
-	/****************************************************************************\
-	*       Attributes
-	\****************************************************************************/
-
 private:
 	bool _bSoundSupported;                 // True if the sound is active
 	bool _bFileLoaded;                     // True is a file is opened
@@ -191,167 +137,121 @@ private:
 public:
 	uint32 _hEndOfBuffer;
 
-private:
-
-
-	/****************************************************************************\
-	*       Methods
-	\****************************************************************************/
-
-public:
 	/**
 	 * Check process for whether sounds have finished playing
 	 */
 	static void soundCheckProcess(CORO_PARAM, const void *param);
 
-	/****************************************************************************\
-	*
-	* Function:     FPSfx(bool bSoundOn);
-	*
-	* Description:  Default constructor. *DO NOT* declare the object directly,
-	*               create it though FPSound::CreateSfx() instead
-	*
-	\****************************************************************************/
+	/**
+	 * Default constructor.
+	 *
+	 * @remarks             Do *NOT* declare an object directly, but rather
+	 *                      create it using FPSound::CreateSfx()
+	 *
+	 */
 
 	FPSfx(bool bSoundOn);
 
-	/****************************************************************************\
-	*
-	* Function:     ~FPSfx();
-	*
-	* Description:  Default destructor. It also stops the sound effect that 
-	*               may be running, and free the memory used.
-	*
-	\****************************************************************************/
+	/**
+	 * Default Destructor.
+	 *
+	 * @remarks             It is also stops the sound effect that may be
+	 *                      currently played, and free the memory it uses.
+	 *
+	 */
 
 	~FPSfx();
 
-	/****************************************************************************\
-	*
-	* Function:     release();
-	*
-	* Description:  Releases the memory object. Must be called when the object 
-	*               is no longer useful and **ONLY** when the object was created 
-	*               with the FPSound :: CreateStream ().
-	*
-	* Note:         Any object pointers are no longer valid after this call.
-	*
-	\****************************************************************************/
+	/**
+	 * Releases the memory used by the object.
+	 *
+	 * @remarks             Must be called when the object is no longer used and
+	 *                      **ONLY** if the object was created by
+	 *                      FPSound::CreateStream().
+	 *                      Object pointers are no longer valid after this call.
+	 */
 
 	void release();
 
-	/****************************************************************************\
-	*
-	* Function:     bool loadFile(char *lpszFileName, uint32 dwCodec=FPCODEC_RAW);
-	*
-	* Description:  Opens a file and load sound effect
-	*
-	* Input:        char *lpszFile          SFX filename
-	*               uint32 dwCodec          CODEC to be used to decompress
-	*                                       the sound samples
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Opens a file and loads a sound effect.
+	 *
+	 * @param lpszFileName  Sfx filename
+	 * @param dwCodec       CODEC used to uncompress the samples
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool loadFile(const char *lpszFileName, uint32 dwCodec = FPCODEC_RAW);
 	bool loadWave(Common::SeekableReadStream *stream);
 	bool loadVoiceFromVDB(Common::File &vdbFP);
 
-	/****************************************************************************\
-	*
-	* Function:     bool play();
-	*
-	* Description:  Play the loaded FX.
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Play the Sfx in memory.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool play();
 
-	/****************************************************************************\
-	*
-	* Function:     bool stop();
-	*
-	* Description:  Stop a FX
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Stops a Sfx.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool stop();
 
-	/****************************************************************************\
-	*
-	* Function:     void pause(bool bPause);
-	*
-	* Description:  Pause a FX
-	*
-	\****************************************************************************/
+	/**
+	 * Pauses a Sfx.
+	 *
+	 */
 
 	void pause(bool bPause);
 
-	/****************************************************************************\
-	*
-	* Function:     bool setLoop(bool bLoop);
-	*
-	* Description:  Enables or disables SFX loop
-	*
-	* Input:        bool bLoop              True to activate the loop, else False
-	*
-	* Note:         The loop must be activated before the SFX starts to play, 
-	*               else the effect will only be noticable next time the SFX is 
-	*               played
-	*
-	\****************************************************************************/
+	/**
+	 * Enables or disables the Sfx loop.
+	 *
+	 * @param bLoop         True to enable the loop, False to disable
+	 *
+	 * @remarks             The loop must be activated BEFORE the sfx starts
+	 *                      playing. Any changes made during the play will have
+	 *                      no effect until the sfx is stopped then played again.
+	 */
 
 	void setLoop(bool bLoop);
 
-	/****************************************************************************\
-	*
-	* Function:     void setVolume(int dwVolume);
-	*
-	* Description:  Set SFX Volume
-	*
-	* Input:        int dwVolume            Volume to set (0-63)
-	*
-	\****************************************************************************/
+	/**
+	 * Change the volume of Sfx
+	 *
+	 * @param dwVolume      Volume to be set (0-63)
+	 *
+	 */
 
 	void setVolume(int dwVolume);
 
-	/****************************************************************************\
-	*
-	* Function:     void getVolume(int * lpdwVolume);
-	*
-	* Description:  Get SFX volume
-	*
-	* Input:        int * lpdwVolume        Will contain the current volume
-	*
-	\****************************************************************************/
+	/**
+	 * Gets the Sfx volume
+	 *
+	 * @param lpdwVolume    Will contain the current Sfx volume
+	 *
+	 */
 
 	void getVolume(int *lpdwVolume);
 
 	/**
-	 * Returns true if the sound has finished playing
+	 * Returns true if the underlying sound has ended
 	 */
 	bool endOfBuffer() const;
 };
 
 class FPStream {
-
-	/****************************************************************************\
-	*       Attributes
-	\****************************************************************************/
-
 private:
+	// HWND hwnd;
+	// LPDIRECTSOUND lpDS;
+	// LPDIRECTSOUNDBUFFER lpDSBuffer;     // DirectSound circular buffer
+	// LPDIRECTSOUNDNOTIFY lpDSNotify;     // Notify hotspots in the buffer
 
-	/*
-	    HWND hwnd;
-	    LPDIRECTSOUND lpDS;
-	    LPDIRECTSOUNDBUFFER lpDSBuffer;    // DirectSound circular buffer
-	    LPDIRECTSOUNDNOTIFY lpDSNotify;    // Notify hotspots in the buffer
-	*/
 	byte  *_lpTempBuffer;                  // Temporary buffer use for decompression
 
 	uint32 _dwBufferSize;                  // Buffer size (bytes)
@@ -373,7 +273,8 @@ private:
 	bool _bPaused;
 	int  _lastVolume;
 	FPStream *_syncToPlay;
-//	DSBPOSITIONNOTIFY dspnHot[3];
+
+	// DSBPOSITIONNOTIFY dspnHot[3];
 
 	bool createBuffer(int nBufSize);
 
@@ -381,155 +282,118 @@ public:
 	bool _bIsPlaying;                      // True if the stream is playing
 
 private:
-
+	/**
+	 * Thread playing the stream
+	 *
+	 */
 	static void playThread(FPStream *This);
 
-	/****************************************************************************\
-	*       Methods
-	\****************************************************************************/
-
 public:
 
-	/****************************************************************************\
-	*
-	* Function:     FPStream(bool bSoundOn);
-	*
-	* Description:  Default contractor. *DO NOT* declare the object directly: use
-	*                                   FPSound::CreateStream() indtead
-	*
-	\****************************************************************************/
+	/**
+	 * Default constructor. 
+	 *
+	 * @remarks             Do *NOT* declare an object directly, but rather
+	 *                      create it using FPSound::CreateStream()
+	 */
 
 	FPStream(bool bSoundOn);
 
-	/****************************************************************************\
-	*
-	* Function:     ~FPStream();
-	*
-	* Description:  Destructor by default. Stops the playing stream (if any) and
-	*                                      frees the memory used by them
-	*
-	\****************************************************************************/
+	/**
+	 * Default destructor. 
+	 *
+	 * @remarks             It calls CloseFile() if needed.
+	 */
 
 	~FPStream();
 
-	/****************************************************************************\
-	*
-	* Function:     release();
-	*
-	* Description:  Releases memory used by object. Must be used when the object 
-	*               is no longer used. *ONLY*¨for objects created by 
-	*               FPSound::CreateStream().
-	*
-	* Note:         Object pointers are no longer valid after this call.
-	*
-	\****************************************************************************/
+	/**
+	 * Releases the memory object. 
+	 *
+	 * @remarks             Must be called when the object is no longer used 
+	 *                      and **ONLY** if the object was created by
+	 *                      FPSound::CreateStream().
+	 *                      Object pointers are no longer valid after this call.
+	 */
 
 	void release();
 
-	/****************************************************************************\
-	*
-	* Function:     bool loadFile(char *lpszFileName, uint32 dwCodec=FPCODEC_RAW);
-	*
-	* Description:  Open a file for a stream.
-	*
-	* Input:        char *lpszFile          Filename to be opened
-	*               uint32 dwCodec          CODEC to be used to decompress
-	*                                       sound samples
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Opens a file stream
+	 *
+	 * @param lpszFile      Filename to be opened
+	 * @param dwCodec       CODEC to be used to uncompress samples
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool loadFile(const char *lpszFileName, uint32 dwCodec = FPCODEC_RAW, int nSync = 2000);
 
-	/****************************************************************************\
-	*
-	* Function:     unloadFile();
-	*
-	* Description:  Close a file stream (if opened). This function must be
-	*               called to free the memory used by the stream
-	*
-	* Return:       Just to be sure, the destructor of this class calls
-	*               UnloadFile() if it has not been mentioned explicitly
-	*
-	\****************************************************************************/
+	/**
+	 * Closes a file stream (opened or not).
+	 *
+	 * @returns             For safety, the destructor calls unloadFile() if it has not
+	 *                      been mentioned explicitly.
+	 * 
+	 * @remarks             It is necessary to call this function to free the 
+	 *                      memory used by the stream.
+	 */
 
 	bool unloadFile();
 
-	/****************************************************************************\
-	*
-	* Function:     bool play();
-	*
-	* Description:  Play the loaded stream.
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Play the stream.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool play();
 	void playFast(void);
 	void prefetch(void);
 
-	/****************************************************************************\
-	*
-	* Function:     bool stop();
-	*
-	* Description:  Stops the play of the stream.
-	*
-	* Return:       True if everything is OK, False otherwise
-	*
-	\****************************************************************************/
+	/**
+	 * Closes the stream.
+	 *
+	 * @returns             True is everything is OK, False otherwise
+	 */
 
 	bool stop(bool bSync = false);
 	void waitForSync(FPStream *toplay);
 
-	/****************************************************************************\
-	*
-	* Function:     void pause(bool bPause);
-	*
-	* Description:  Pause sound effect
-	*
-	\****************************************************************************/
+	/**
+	 * Pause sound effect
+	 *
+	 * @param bPause        True enables pause, False disables it
+	 */
 
 	void pause(bool bPause);
 
-	/****************************************************************************\
-	*
-	* Function:     bool setLoop(bool bLoop);
-	*
-	* Description:  Enable of disable stream loop
-	*
-	* Input:        bool bLoop              True to enable loop, false otherwise
-	*
-	* Note:         The loop must be activated BEFORE you play back the stream. 
-	*               Any changes made during play will not have 'effect until
-	*               the stream is not stopped, and then comes back into play.
-	*
-	\****************************************************************************/
+	/**
+	 * Unables or disables stream loop.
+	 *
+	 * @param bLoop         True enable loop, False disables it
+	 *
+	 * @remarks             The loop must be activated BEFORE the stream starts
+	 *                      playing. Any changes made during the play will have no
+	 *                      effect until the stream is stopped then played again.
+	 */
 
 	void setLoop(bool bLoop);
 
-	/****************************************************************************\
-	*
-	* Function:     void setVolume(int dwVolume);
-	*
-	* Description:  Change stream colume
-	*
-	* Input:        int dwVolume            Volume to be set (0-63)
-	*
-	\****************************************************************************/
+	/**
+	 * Change the volume of the stream
+	 *
+	 * @param dwVolume      Volume to be set (0-63)
+	 */
 
 	void setVolume(int dwVolume);
 
-	/****************************************************************************\
-	*
-	* Function:     void getVolume(LPINT lpdwVolume);
-	*
-	* Description:  Get stream volume
-	*
-	* Input:        LPINT lpdwVolume        Will contain the current stream volume
-	*
-	\****************************************************************************/
+	/**
+	 * Gets the vgolume of the stream
+	 *
+	 * @param lpdwVolume    Variable that will contain the current volume
+	 *
+	 */
 
 	void getVolume(int *lpdwVolume);
 };