cleanup / doxygenification

svn-id: r10578

17 files changed, 108 insertions, 150 deletions

diff --git a/scumm/imuse_digi.cpp b/scumm/imuse_digi.cpp
index f0a08957f7..c5cc8059b3 100644
--- a/scumm/imuse_digi.cpp
+++ b/scumm/imuse_digi.cpp
@@ -28,13 +28,6 @@
 
 namespace Scumm {
 
-////////////////////////////////////////
-//
-// iMuse Digital Implementation
-//   for SCUMM v7 and higher
-//
-////////////////////////////////////////
-
 struct imuse_music_table {
 	int room;
 	int id;
diff --git a/scumm/imuse_digi.h b/scumm/imuse_digi.h
index 8dd861f4f4..5416da47cb 100644
--- a/scumm/imuse_digi.h
+++ b/scumm/imuse_digi.h
@@ -35,6 +35,9 @@ namespace Scumm {
 
 class ScummEngine;
 
+/**
+ * iMuse Digital Implementation for SCUMM v7 and higher.
+ */
 class IMuseDigital : public MusicEngine {
 private:
 
diff --git a/scumm/midiparser_eup.cpp b/scumm/midiparser_eup.cpp
index 402e1d07f4..a094ade5ce 100644
--- a/scumm/midiparser_eup.cpp
+++ b/scumm/midiparser_eup.cpp
@@ -27,12 +27,9 @@
 
 namespace Scumm {
 
-//////////////////////////////////////////////////
-//
-// The FM Towns Euphony version of MidiParser
-//
-//////////////////////////////////////////////////
-
+/**
+ * The FM Towns Euphony version of MidiParser.
+ */
 class MidiParser_EUP : public MidiParser {
 protected:
 	struct {
diff --git a/scumm/player_mod.cpp b/scumm/player_mod.cpp
index 6aee4087ba..7715e4d002 100644
--- a/scumm/player_mod.cpp
+++ b/scumm/player_mod.cpp
@@ -24,12 +24,6 @@
 
 namespace Scumm {
 
-////////////////////////////////////////
-//
-// Generic Amiga MOD mixer - provides a 60Hz 'update' routine.
-//
-////////////////////////////////////////
-
 Player_MOD::Player_MOD(ScummEngine *scumm) {
 	int i;
 	_mixer = scumm->_mixer;
diff --git a/scumm/player_mod.h b/scumm/player_mod.h
index bdc4bc5cf0..b48bc07cbe 100644
--- a/scumm/player_mod.h
+++ b/scumm/player_mod.h
@@ -30,8 +30,9 @@
 
 namespace Scumm {
 
-#define	MOD_MAXCHANS	16
-
+/**
+ * Generic Amiga MOD mixer - provides a 60Hz 'update' routine.
+ */
 class Player_MOD {
 public:
 	Player_MOD(ScummEngine *scumm);
@@ -50,11 +51,9 @@ public:
 	virtual void clearUpdateProc();
 
 private:
-	SoundMixer *_mixer;
-
-	uint32 _mixamt;
-	uint32 _mixpos;
-	int _samplerate;
+	enum {
+		MOD_MAXCHANS = 16
+	};
 
 	struct soundChan
 	{
@@ -66,6 +65,13 @@ private:
 		RateConverter *converter;
 		AudioInputStream *input;
 	};
+
+	SoundMixer *_mixer;
+
+	uint32 _mixamt;
+	uint32 _mixpos;
+	int _samplerate;
+
 	soundChan _channels[MOD_MAXCHANS];
 
 	uint8 _maxvol;
diff --git a/scumm/player_v1.cpp b/scumm/player_v1.cpp
index 4eec5e2f69..a934b56bf5 100644
--- a/scumm/player_v1.cpp
+++ b/scumm/player_v1.cpp
@@ -27,15 +27,12 @@
 
 namespace Scumm {
 
+#define FB_WNOISE 0x12000       /* feedback for white noise */
+#define FB_PNOISE 0x08000       /* feedback for periodic noise */
+
 #define TIMER_BASE_FREQ 1193000
 #define FIXP_SHIFT  16
 
-////////////////////////////////////////
-//
-// V1 PC-Speaker player
-//
-////////////////////////////////////////
-
 
 Player_V1::Player_V1(ScummEngine *scumm) : Player_V2(scumm) {	
 	// Initialize channel code
diff --git a/scumm/player_v1.h b/scumm/player_v1.h
index ce9b7ddfdb..83a901ea75 100644
--- a/scumm/player_v1.h
+++ b/scumm/player_v1.h
@@ -27,23 +27,9 @@
 
 namespace Scumm {
 
-#define FB_WNOISE 0x12000       /* feedback for white noise */
-#define FB_PNOISE 0x08000       /* feedback for periodic noise */
-
-struct channel_data_v1 {
-	uint freq;
-	uint volume;
-	byte *cmd_ptr;
-	uint notelen;
-	uint hull_counter;
-	uint attack;
-	uint decay;
-	uint level;
-	uint sustain_1;
-	uint sustain_2;
-	int  sustctr;
-};
-
+/**
+ * V1 PC-Speaker player.
+ */
 class Player_V1 : public Player_V2 {
 public:
 	Player_V1(ScummEngine *scumm);
@@ -63,7 +49,6 @@ protected:
 	virtual void generatePCjrSamples(int16 *data, uint len);
 
 	void restartSound();
-	void next_speaker_cmd(ChannelInfo *channel);
 
 	void set_mplex(uint mplex);
 	void parseSpeakerChunk();
@@ -72,6 +57,20 @@ protected:
 	void nextPCjrCmd();
 
 private:
+	struct channel_data_v1 {
+		uint freq;
+		uint volume;
+		byte *cmd_ptr;
+		uint notelen;
+		uint hull_counter;
+		uint attack;
+		uint decay;
+		uint level;
+		uint sustain_1;
+		uint sustain_2;
+		int  sustctr;
+	};
+
 	channel_data_v1 _channels[4];
 
 	byte *_next_chunk;
diff --git a/scumm/player_v2.cpp b/scumm/player_v2.cpp
index a723905f29..a86a6ad43f 100644
--- a/scumm/player_v2.cpp
+++ b/scumm/player_v2.cpp
@@ -340,12 +340,6 @@ static const uint16 pcjr_freq_table[12] = {
 };
 #endif
 
-////////////////////////////////////////
-//
-// V2 PC-Speaker MIDI driver
-//
-////////////////////////////////////////
-
 
 Player_V2::Player_V2(ScummEngine *scumm) {
 	int i;
diff --git a/scumm/player_v2.h b/scumm/player_v2.h
index 55af6970c2..0490845f92 100644
--- a/scumm/player_v2.h
+++ b/scumm/player_v2.h
@@ -67,11 +67,9 @@ struct channel_data {
 #endif
 
 
-union ChannelInfo {
-	channel_data d;
-	uint16 array[sizeof(channel_data)/2];
-};
-
+/**
+ * V2 PC-Speaker MIDI driver.
+ */
 class Player_V2 : public MusicEngine {
 public:
 	Player_V2(ScummEngine *scumm);
@@ -112,6 +110,11 @@ protected:
 	byte *_retaddr;
 
 private:
+	union ChannelInfo {
+		channel_data d;
+		uint16 array[sizeof(channel_data)/2];
+	};
+	
 	int _music_timer;
 	int _music_timer_ctr;
 	int _ticks_per_music_timer;
diff --git a/scumm/player_v2a.cpp b/scumm/player_v2a.cpp
index 6e5e07ab8e..9b7af2e075 100644
--- a/scumm/player_v2a.cpp
+++ b/scumm/player_v2a.cpp
@@ -29,12 +29,6 @@ namespace Scumm {
 
 #define BASE_FREQUENCY 3579545
 
-////////////////////////////////////////
-//
-// V2 Amiga sound/music driver
-//
-////////////////////////////////////////
-
 static uint32	CRCtable[256];
 static void	InitCRC (void)
 {
@@ -49,6 +43,7 @@ static void	InitCRC (void)
 		CRCtable[i] = n;
 	}
 }
+
 static uint32 GetCRC (byte *data, int len)
 {
 	uint32 CRC = 0xFFFFFFFF;
diff --git a/scumm/player_v2a.h b/scumm/player_v2a.h
index f54495cf98..e3fec9b27d 100644
--- a/scumm/player_v2a.h
+++ b/scumm/player_v2a.h
@@ -32,11 +32,12 @@ class SoundMixer;
 
 namespace Scumm {
 
-#define	V2A_MAXSLOTS 8
-
 class ScummEngine;
 class V2A_Sound;
 
+/**
+ * V2 Amiga sound/music driver.
+ */
 class Player_V2A : public MusicEngine {
 public:
 	Player_V2A(ScummEngine *scumm);
@@ -50,17 +51,22 @@ public:
 	virtual int  getSoundStatus(int sound) const;
 
 private:
-	OSystem *_system;
-	ScummEngine *_scumm;
-	Player_MOD *_mod;
+	enum {
+		V2A_MAXSLOTS = 8
+	};
 
 	struct soundSlot
 	{
 		int id;
 		V2A_Sound *sound;
-	} _slot[V2A_MAXSLOTS];
-	int getSoundSlot (int id = 0) const;
+	};
 
+	OSystem *_system;
+	ScummEngine *_scumm;
+	Player_MOD *_mod;
+	soundSlot _slot[V2A_MAXSLOTS];
+
+	int getSoundSlot (int id = 0) const;
 	static void update_proc(void *param);
 	void updateSound();
 };
diff --git a/scumm/player_v3a.cpp b/scumm/player_v3a.cpp
index 4b98653acb..e311de2fbe 100644
--- a/scumm/player_v3a.cpp
+++ b/scumm/player_v3a.cpp
@@ -34,12 +34,6 @@ static const uint16 note_freqs[4][12] = {
 	{0x00D6,0x00CA,0x00BE,0x00B4,0x00A9,0x00A0,0x0097,0x008E,0x0086,0x007F,0x00F0,0x00E2}
 };
 
-////////////////////////////////////////
-//
-// V3 Amiga sound/music driver
-//
-////////////////////////////////////////
-
 Player_V3A::Player_V3A(ScummEngine *scumm) {
 	int i;
 	_scumm = scumm;
diff --git a/scumm/player_v3a.h b/scumm/player_v3a.h
index 25857680fc..e175111482 100644
--- a/scumm/player_v3a.h
+++ b/scumm/player_v3a.h
@@ -32,11 +32,11 @@ class SoundMixer;
 
 namespace Scumm {
 
-#define	V3A_MAXMUS	8
-#define	V3A_MAXSFX	8
-
 class ScummEngine;
 
+/**
+ * V3 Amiga sound/music driver.
+ */
 class Player_V3A : public MusicEngine {
 public:
 	Player_V3A(ScummEngine *scumm);
@@ -50,31 +50,23 @@ public:
 	virtual int  getSoundStatus(int sound) const;
 
 private:
-	OSystem *_system;
-	ScummEngine *_scumm;
-	Player_MOD *_mod;
+	enum {
+		V3A_MAXMUS = 8,
+		V3A_MAXSFX = 8
+	};
 
 	struct musChan
 	{
 		int id;
 		int dur;
-	} _mus[V3A_MAXMUS];
-	int getMusChan (int id = 0) const;
+	};
 
 	struct sfxChan
 	{
 		int id;
 		int dur;
 		// SFX will eventually have pitch bends
-	} _sfx[V3A_MAXSFX];
-	int getSfxChan (int id = 0) const;
-
-	int _curSong;
-	uint8 *_songData;
-	uint16 _songPtr;
-	uint16 _songDelay;
-	int _music_timer;
-	bool _isinit;
+	};
 
 	struct instData
 	{
@@ -84,8 +76,26 @@ private:
 		uint16 _llen[6];
 		uint16 _oct[6];
 		int16 _pitadjust;
-	} **_wavetable;
+	};
 
+	OSystem *_system;
+	ScummEngine *_scumm;
+	Player_MOD *_mod;
+
+	musChan _mus[V3A_MAXMUS];
+	sfxChan _sfx[V3A_MAXSFX];
+
+	int _curSong;
+	uint8 *_songData;
+	uint16 _songPtr;
+	uint16 _songDelay;
+	int _music_timer;
+	bool _isinit;
+
+	instData **_wavetable;
+
+	int getMusChan (int id = 0) const;
+	int getSfxChan (int id = 0) const;
 	static void update_proc(void *param);
 	void playMusic();
 };
diff --git a/simon/midiparser_s1d.cpp b/simon/midiparser_s1d.cpp
index ba844fe4b2..404717a1cf 100644
--- a/simon/midiparser_s1d.cpp
+++ b/simon/midiparser_s1d.cpp
@@ -28,12 +28,13 @@
 
 namespace Simon {
 
-//////////////////////////////////////////////////
-//
-// Simon 1 Demo version of MidiParser
-//
-//////////////////////////////////////////////////
-
+/**
+ * Simon 1 Demo version of MidiParser.
+ *
+ * This parser is the result of eyeballing the one MUS file that's included
+ * with simon1demo. So there might be some things missing. I've tried to notate
+ * question-mark areas where they occur.
+ */
 class MidiParser_S1D : public MidiParser {
 protected:
 	byte *_data;
@@ -51,19 +52,6 @@ public:
 };
 
 
-
-//////////////////////////////////////////////////
-//
-// MidiParser_S1D implementation
-//
-// This parser is the result of eyeballing the
-// one MUS file that's included with simon1demo.
-// So there might be some things missing.
-// I've tried to notate question-mark areas
-// where they occur.
-//
-//////////////////////////////////////////////////
-
 // The VLQs for simon1demo seem to be
 // in Little Endian format.
 uint32 MidiParser_S1D::readVLQ2(byte * &data) {
diff --git a/sound/midiparser.h b/sound/midiparser.h
index d44b477015..30d3243667 100644
--- a/sound/midiparser.h
+++ b/sound/midiparser.h
@@ -24,10 +24,9 @@
 #ifndef INCLUDED_MIDIPARSER
 #define INCLUDED_MIDIPARSER
 
-class MidiParser;
-
 #include "common/scummsys.h"
 
+class MidiParser;
 class MidiDriver;
 
 
diff --git a/sound/midiparser_smf.cpp b/sound/midiparser_smf.cpp
index b4365607a0..7ec5035ad2 100644
--- a/sound/midiparser_smf.cpp
+++ b/sound/midiparser_smf.cpp
@@ -25,12 +25,9 @@
 #include "common/util.h"
 
 
-//////////////////////////////////////////////////
-//
-// The Standard MIDI File version of MidiParser
-//
-//////////////////////////////////////////////////
-
+/**
+ * The Standard MIDI File version of MidiParser.
+ */
 class MidiParser_SMF : public MidiParser {
 protected:
 	byte *_buffer;
@@ -49,15 +46,8 @@ public:
 };
 
 
-
-//////////////////////////////////////////////////
-//
-// MidiParser_SMF implementation
-//
-//////////////////////////////////////////////////
-
-static byte command_lengths[8] = { 3, 3, 3, 3, 2, 2, 3, 0 };
-static byte special_lengths[16] = { 0, 1, 1, 3, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0 };
+static const byte command_lengths[8] = { 3, 3, 3, 3, 2, 2, 3, 0 };
+static const byte special_lengths[16] = { 0, 1, 1, 3, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0 };
 
 MidiParser_SMF::~MidiParser_SMF() {
 	if (_buffer)
diff --git a/sound/midiparser_xmidi.cpp b/sound/midiparser_xmidi.cpp
index 176b1aacc0..8b4a194aa0 100644
--- a/sound/midiparser_xmidi.cpp
+++ b/sound/midiparser_xmidi.cpp
@@ -25,12 +25,12 @@
 #include "common/util.h"
 
 
-//////////////////////////////////////////////////
-//
-// The XMIDI version of MidiParser
-//
-//////////////////////////////////////////////////
-
+/**
+ * The XMIDI version of MidiParser.
+ * 
+ * Much of this code is adapted from the XMIDI implementation from the exult
+ * project.
+ */
 class MidiParser_XMIDI : public MidiParser {
 protected:
 	NoteTimer _notes_cache[32];
@@ -49,16 +49,6 @@ public:
 };
 
 
-
-//////////////////////////////////////////////////
-//
-// MidiParser_XMIDI implementation
-//
-// Much of this code is adapted from the XMIDI
-// implementation from the exult project.
-//
-//////////////////////////////////////////////////
-
 // This is a special XMIDI variable length quantity
 uint32 MidiParser_XMIDI::readVLQ2 (byte * &pos) {
 	uint32 value = 0;