Cleanup and documentation.

svn-id: r50609

18 files changed, 171 insertions, 44 deletions

diff --git a/backends/audiocd/default/default-audiocd.h b/backends/audiocd/default/default-audiocd.h
index 474264ef07..ec209d9eb5 100644
--- a/backends/audiocd/default/default-audiocd.h
+++ b/backends/audiocd/default/default-audiocd.h
@@ -30,8 +30,8 @@
 #include "sound/mixer.h"
 
 /**
-* The default audio cd manager. Implements emulation of audio cd playback.
-*/
+ * The default audio cd manager. Implements emulation of audio cd playback.
+ */
 class DefaultAudioCDManager : public AudioCDManager {
 public:
 	DefaultAudioCDManager();
diff --git a/backends/audiocd/sdl/sdl-audiocd.h b/backends/audiocd/sdl/sdl-audiocd.h
index cb88d31a56..42ac980c51 100644
--- a/backends/audiocd/sdl/sdl-audiocd.h
+++ b/backends/audiocd/sdl/sdl-audiocd.h
@@ -35,8 +35,8 @@
 #endif
 
 /**
-* The SDL audio cd manager. Implements real audio cd playback.
-*/
+ * The SDL audio cd manager. Implements real audio cd playback.
+ */
 class SdlAudioCDManager : public DefaultAudioCDManager {
 public:
 	SdlAudioCDManager();
diff --git a/backends/events/gp2xsdl/gp2xsdl-events.h b/backends/events/gp2xsdl/gp2xsdl-events.h
index c50d4e865d..559aa53388 100644
--- a/backends/events/gp2xsdl/gp2xsdl-events.h
+++ b/backends/events/gp2xsdl/gp2xsdl-events.h
@@ -28,14 +28,22 @@
 
 #include "backends/events/sdl/sdl-events.h"
 
+/**
+ * SDL events manager for GP2X and GP2XWIZ
+ */
 class GP2XSdlEventManager : public SdlEventManager {
 public:
 	GP2XSdlEventManager(Common::EventSource *boss);
 
 protected:
 	bool _stickBtn[32];
+
+	/** Button state for L button modifier */
 	bool _buttonStateL;
 
+	/**
+	 * Handles the stick movement
+	 */
 	void moveStick();
 
 	virtual bool handleKeyDown(SDL_Event &ev, Common::Event &event);
diff --git a/backends/events/linuxmotosdl/linuxmotosdl-events.cpp b/backends/events/linuxmotosdl/linuxmotosdl-events.cpp
index 62667422bf..1313007158 100644
--- a/backends/events/linuxmotosdl/linuxmotosdl-events.cpp
+++ b/backends/events/linuxmotosdl/linuxmotosdl-events.cpp
@@ -38,10 +38,6 @@ LinuxmotoSdlEventManager::LinuxmotoSdlEventManager(Common::EventSource *boss)
 
 }
 
-LinuxmotoSdlEventManager::~LinuxmotoSdlEventManager() {
-
-}
-
 void LinuxmotoSdlEventManager::preprocessEvents(SDL_Event *event) {
 	if (event->type == SDL_ACTIVEEVENT) {
 		if (event->active.state == SDL_APPINPUTFOCUS && !event->active.gain) {
diff --git a/backends/events/linuxmotosdl/linuxmotosdl-events.h b/backends/events/linuxmotosdl/linuxmotosdl-events.h
index d7ad715adb..414db080ed 100644
--- a/backends/events/linuxmotosdl/linuxmotosdl-events.h
+++ b/backends/events/linuxmotosdl/linuxmotosdl-events.h
@@ -28,10 +28,12 @@
 
 #include "backends/events/sdl/sdl-events.h"
 
+/**
+ * SDL events manager for LINUXMOTO
+ */
 class LinuxmotoSdlEventManager : public SdlEventManager {
 public:
 	LinuxmotoSdlEventManager(Common::EventSource *boss);
-	virtual ~LinuxmotoSdlEventManager();
 
 protected:
 	virtual void preprocessEvents(SDL_Event *event);
diff --git a/backends/events/samsungtvsdl/samsungtvsdl-events.h b/backends/events/samsungtvsdl/samsungtvsdl-events.h
index 1189af4500..10e1eb84bb 100644
--- a/backends/events/samsungtvsdl/samsungtvsdl-events.h
+++ b/backends/events/samsungtvsdl/samsungtvsdl-events.h
@@ -28,10 +28,12 @@
 
 #include "backends/events/sdl/sdl-events.h"
 
+/**
+ * SDL events manager for Samsung TV
+ */
 class SamsungTVSdlEventManager : public SdlEventManager {
 public:
 	SamsungTVSdlEventManager(Common::EventSource *boss);
-	~SamsungTVSdlEventManager() {}
 
 protected:
 	virtual bool remapKey(SDL_Event &ev, Common::Event &event);
diff --git a/backends/events/sdl/sdl-events.h b/backends/events/sdl/sdl-events.h
index 3b3098dc29..4bc2277fcd 100644
--- a/backends/events/sdl/sdl-events.h
+++ b/backends/events/sdl/sdl-events.h
@@ -34,45 +34,73 @@
 #include <SDL.h>
 #endif
 
+/**
+ * The SDL event manager class.
+ */
 class SdlEventManager : public DefaultEventManager {
 public:
 	SdlEventManager(Common::EventSource *boss);
 	virtual ~SdlEventManager();
 
+	/**
+	 * Gets and proccess SDL events
+	 */
 	virtual bool pollSdlEvent(Common::Event &event);
 
+	/**
+	 * Resets keyboard emulation after a video screen change
+	 */
 	virtual void resetKeyboadEmulation(int16 x_max, int16 y_max);
 
+	/**
+	 * Toggles mouse input grab
+	 */
 	virtual void toggleMouseGrab();
 
 protected:
-	// Keyboard mouse emulation.  Disabled by fingolfin 2004-12-18.
-	// I am keeping the rest of the code in for now, since the joystick
-	// code (or rather, "hack") uses it, too.
+	/** @name Keyboard mouse emulation
+	 * Disabled by fingolfin 2004-12-18.
+	 * I am keeping the rest of the code in for now, since the joystick
+	 * code (or rather, "hack") uses it, too.
+	 */
+	//@{
+
 	struct KbdMouse {
 		int16 x, y, x_vel, y_vel, x_max, y_max, x_down_count, y_down_count;
 		uint32 last_time, delay_time, x_down_time, y_down_time;
 	};
 	KbdMouse _km;
 
-	// Scroll lock state - since SDL doesn't track it
+	//@}
+
+	/** Scroll lock state - since SDL doesn't track it */
 	bool _scrollLock;
 	
-	// Joystick
+	/** Joystick */
 	SDL_Joystick *_joystick;
 
+	/** Last screen id for checking if it was modified */
 	int _lastScreenID;
 
-	// Pre process an event before it is dispatched.
+	/**
+	 * Pre process an event before it is dispatched.
+	 */
 	virtual void preprocessEvents(SDL_Event *event) {}
 
-	// Dispatchs SDL events for each handler.
+	/**
+	 * Dispatchs SDL events for each handler.
+	 */
 	virtual bool dispatchSDLEvent(SDL_Event &ev, Common::Event &event);
 
-	// Handlers for specific SDL events, called by pollEvent.
-	// This way, if a managers inherits fromt this SDL events manager, it can
-	// change the behavior of only a single event, without having to override all
-	// of pollEvent.
+
+	/** @name Event Handlers
+	 * Handlers for specific SDL events, called by SdlEventManager::dispatchSDLEvent().
+	 * This way, if a managers inherits fromt this SDL events manager, it can
+	 * change the behavior of only a single event, without having to override all
+	 * of SdlEventManager::dispatchSDLEvent().
+	 */
+	//@{
+
 	virtual bool handleKeyDown(SDL_Event &ev, Common::Event &event);
 	virtual bool handleKeyUp(SDL_Event &ev, Common::Event &event);
 	virtual bool handleMouseMotion(SDL_Event &ev, Common::Event &event);
@@ -81,13 +109,29 @@ protected:
 	virtual bool handleJoyButtonDown(SDL_Event &ev, Common::Event &event);
 	virtual bool handleJoyButtonUp(SDL_Event &ev, Common::Event &event);
 	virtual bool handleJoyAxisMotion(SDL_Event &ev, Common::Event &event);
+	virtual void handleKbdMouse();
+
+	//@}
 
+	/**
+	 * Assigns the mouse coords to the mouse event
+	 */
 	virtual void fillMouseEvent(Common::Event &event, int x, int y);
 
-	virtual void handleKbdMouse();
+	/**
+	 * Remaps key events. This allows platforms to configure
+	 * their custom keys.
+	 */
 	virtual bool remapKey(SDL_Event &ev, Common::Event &event);
 
+	/**
+	 * Maps the ASCII value of key
+	 */
 	virtual int mapKey(SDLKey key, SDLMod mod, Uint16 unicode);
+
+	/**
+	 * Configures the key modifiers flags status
+	 */
 	virtual void SDLModToOSystemKeyFlags(SDLMod mod, Common::Event &event);
 };
 
diff --git a/backends/events/symbiansdl/symbiansdl-events.cpp b/backends/events/symbiansdl/symbiansdl-events.cpp
index 3c8648fe8c..af57e81ccc 100644
--- a/backends/events/symbiansdl/symbiansdl-events.cpp
+++ b/backends/events/symbiansdl/symbiansdl-events.cpp
@@ -47,10 +47,6 @@ SymbianSdlEventManager::SymbianSdlEventManager(Common::EventSource *boss)
 	}
 }
 
-SymbianSdlEventManager::~SymbianSdlEventManager() {
-
-}
-
 bool SymbianSdlEventManager::remapKey(SDL_Event &ev, Common::Event &event) {
 	if (GUI::Actions::Instance()->mappingActive() || ev.key.keysym.sym <= SDLK_UNKNOWN)
 		return false;
diff --git a/backends/events/symbiansdl/symbiansdl-events.h b/backends/events/symbiansdl/symbiansdl-events.h
index cf94ce09e1..fa1c066cae 100644
--- a/backends/events/symbiansdl/symbiansdl-events.h
+++ b/backends/events/symbiansdl/symbiansdl-events.h
@@ -30,12 +30,12 @@
 
 #define TOTAL_ZONES 3
 
+/**
+ * SDL events manager for Symbian
+ */
 class SymbianSdlEventManager : public SdlEventManager {
 public:
 	SymbianSdlEventManager(Common::EventSource *boss);
-	~SymbianSdlEventManager();
-
-	bool remapKey(SDL_Event &ev, Common::Event &event);
 
 protected:
 	// Used to handle joystick navi zones
@@ -51,6 +51,8 @@ protected:
 	};
 
 	static zoneDesc _zones[TOTAL_ZONES];
+
+	virtual bool remapKey(SDL_Event &ev, Common::Event &event);
 };
 
 #endif
diff --git a/backends/mixer/doublebuffersdl/doublebuffersdl-mixer.h b/backends/mixer/doublebuffersdl/doublebuffersdl-mixer.h
index b71a3ed381..6304c287df 100644
--- a/backends/mixer/doublebuffersdl/doublebuffersdl-mixer.h
+++ b/backends/mixer/doublebuffersdl/doublebuffersdl-mixer.h
@@ -28,10 +28,13 @@
 
 #include "backends/mixer/sdl/sdl-mixer.h"
 
+/**
+ * SDL mixer manager with double buffering support.
+ */
 class DoubleBufferSDLMixerManager : public SdlMixerManager {
 public:
 	DoubleBufferSDLMixerManager();
-	~DoubleBufferSDLMixerManager();
+	virtual ~DoubleBufferSDLMixerManager();
 
 protected:
 	SDL_mutex *_soundMutex;
@@ -44,8 +47,19 @@ protected:
 	uint _soundBufSize;
 	byte *_soundBuffers[2];
 
+	/**
+	 * Handles and swap the sound buffers
+	 */
 	void mixerProducerThread();
+
+	/**
+	 * Finish the mixer manager
+	 */
 	void deinitThreadedMixer();
+
+	/**
+	 * Callback entry point for the sound thread
+	 */
 	static int SDLCALL mixerProducerThreadEntry(void *arg);
 
 	virtual void startAudio();
diff --git a/backends/mixer/sdl/sdl-mixer.h b/backends/mixer/sdl/sdl-mixer.h
index f58260fef2..1b3a3543dc 100644
--- a/backends/mixer/sdl/sdl-mixer.h
+++ b/backends/mixer/sdl/sdl-mixer.h
@@ -34,28 +34,71 @@
 
 #include "sound/mixer_intern.h"
 
+/**
+ * SDL mixer manager. It wraps the actual implementation
+ * of the Audio:Mixer used by the engine, and setups
+ * the SDL audio subsystem and the callback for the
+ * audio mixer implementation.
+ */
 class SdlMixerManager {
 public:
 	SdlMixerManager();
 	virtual ~SdlMixerManager();
 
+	/**
+	 * Initialize and setups the mixer
+	 */
 	virtual void init();
 
+	/**
+	 * Get the audio mixer implementation
+	 */
 	Audio::Mixer *getMixer() { return (Audio::Mixer *)_mixer; }
 
 	// Used by LinuxMoto Port
+
+	/**
+	 * Pauses the audio system
+	 */
 	virtual void suspendAudio();
+
+	/**
+	 * Resumes the audio system
+	 */
 	virtual int resumeAudio();
 
 protected:
+	/** The mixer implementation */
 	Audio::MixerImpl *_mixer;
+
+	/**
+	 * The obtained audio specification after opening the
+	 * audio system.
+	 */
 	SDL_AudioSpec _obtainedRate;
+
+	/** State of the audio system */
 	bool _audioSuspended;
 
+	/**
+	 * Returns the desired audio specification 
+	 */
 	virtual SDL_AudioSpec getAudioSpec();
+
+	/**
+	 * Starts SDL audio
+	 */
 	virtual void startAudio();
 
+	/**
+	 * Handles the audio callback
+	 */
 	virtual void callbackHandler(byte *samples, int len);
+
+	/**
+	 * The mixer callback entry point. Static functions can't be overrided
+	 * by subclasses, so it invokes the non-static function callbackHandler()
+	 */
 	static void sdlCallback(void *this_, byte *samples, int len);
 };
 
diff --git a/backends/mixer/symbiansdl/symbiansdl-mixer.h b/backends/mixer/symbiansdl/symbiansdl-mixer.h
index e809bd4cd0..6a0d281b1a 100644
--- a/backends/mixer/symbiansdl/symbiansdl-mixer.h
+++ b/backends/mixer/symbiansdl/symbiansdl-mixer.h
@@ -28,18 +28,21 @@
 
 #include "backends/mixer/sdl/sdl-mixer.h"
 
+/**
+ * SDL mixer manager for Symbian
+ */
 class SymbianSdlMixerManager : public SdlMixerManager {
 public:
 	SymbianSdlMixerManager();
-	~SymbianSdlMixerManager();
+	virtual ~SymbianSdlMixerManager();
 
-	void init();
+	virtual void init();
 
 protected:
 	int _channels;
 	byte *_stereo_mix_buffer;
 
-	void callbackHandler(byte *samples, int len);
+	virtual void callbackHandler(byte *samples, int len);
 };
 
 #endif
diff --git a/backends/mutex/mutex.h b/backends/mutex/mutex.h
index d8647bae13..ddf27d5932 100644
--- a/backends/mutex/mutex.h
+++ b/backends/mutex/mutex.h
@@ -29,6 +29,10 @@
 #include "common/system.h"
 #include "common/noncopyable.h"
 
+/**
+ * Abstract class for mutex manager. Subclasses
+ * implement the real functionality.
+ */
 class MutexManager : Common::NonCopyable {
 public:
 	virtual ~MutexManager() {}
@@ -39,5 +43,4 @@ public:
 	virtual void deleteMutex(OSystem::MutexRef mutex) = 0;
 };
 
-
 #endif
diff --git a/backends/mutex/null/null-mutex.h b/backends/mutex/null/null-mutex.h
index ddfe23bdee..54b8f5ce96 100644
--- a/backends/mutex/null/null-mutex.h
+++ b/backends/mutex/null/null-mutex.h
@@ -28,12 +28,15 @@
 
 #include "backends/mutex/mutex.h"
 
+/**
+ * Null mutex manager
+ */
 class NullMutexManager : MutexManager {
 public:
-	OSystem::MutexRef createMutex() { return OSystem::MutexRef(); }
-	void lockMutex(OSystem::MutexRef mutex) {}
-	void unlockMutex(OSystem::MutexRef mutex) {}
-	void deleteMutex(OSystem::MutexRef mutex) {}
+	virtual OSystem::MutexRef createMutex() { return OSystem::MutexRef(); }
+	virtual void lockMutex(OSystem::MutexRef mutex) {}
+	virtual void unlockMutex(OSystem::MutexRef mutex) {}
+	virtual void deleteMutex(OSystem::MutexRef mutex) {}
 };
 
 #endif
diff --git a/backends/mutex/sdl/sdl-mutex.h b/backends/mutex/sdl/sdl-mutex.h
index a929ea495f..88a19d398a 100644
--- a/backends/mutex/sdl/sdl-mutex.h
+++ b/backends/mutex/sdl/sdl-mutex.h
@@ -28,12 +28,15 @@
 
 #include "backends/mutex/mutex.h"
 
+/**
+ * SDL mutex manager
+ */
 class SdlMutexManager : public MutexManager {
 public:
-	OSystem::MutexRef createMutex();
-	void lockMutex(OSystem::MutexRef mutex);
-	void unlockMutex(OSystem::MutexRef mutex);
-	void deleteMutex(OSystem::MutexRef mutex);
+	virtual OSystem::MutexRef createMutex();
+	virtual void lockMutex(OSystem::MutexRef mutex);
+	virtual void unlockMutex(OSystem::MutexRef mutex);
+	virtual void deleteMutex(OSystem::MutexRef mutex);
 };
 
 
diff --git a/backends/timer/default/default-timer.h b/backends/timer/default/default-timer.h
index e7ac3d122f..778c69b32d 100644
--- a/backends/timer/default/default-timer.h
+++ b/backends/timer/default/default-timer.h
@@ -40,7 +40,8 @@ private:
 
 public:
 	DefaultTimerManager();
-	~DefaultTimerManager();
+	virtual ~DefaultTimerManager();
+
 	bool installTimerProc(TimerProc proc, int32 interval, void *refCon);
 	void removeTimerProc(TimerProc proc);
 
diff --git a/backends/timer/sdl/sdl-timer.cpp b/backends/timer/sdl/sdl-timer.cpp
index 0fbe12589e..94932d61ba 100644
--- a/backends/timer/sdl/sdl-timer.cpp
+++ b/backends/timer/sdl/sdl-timer.cpp
@@ -34,14 +34,17 @@ static Uint32 timer_handler(Uint32 interval, void *param) {
 }
 
 SdlTimerManager::SdlTimerManager() {
+	// Initializes the SDL timer subsystem
 	if (SDL_InitSubSystem(SDL_INIT_TIMER) == -1) {
 		error("Could not initialize SDL: %s", SDL_GetError());
 	}
 
+	// Creates the timer callback
 	_timerID = SDL_AddTimer(10, &timer_handler, this);
 }
 
 SdlTimerManager::~SdlTimerManager() {
+	// Removes the timer callback
 	SDL_RemoveTimer(_timerID);
 }
 
diff --git a/backends/timer/sdl/sdl-timer.h b/backends/timer/sdl/sdl-timer.h
index 19629151ca..5995aed4b0 100644
--- a/backends/timer/sdl/sdl-timer.h
+++ b/backends/timer/sdl/sdl-timer.h
@@ -34,10 +34,14 @@
 #include <SDL.h>
 #endif
 
+/**
+ * SDL timer manager. Setups the timer callback for
+ * DefaultTimerManager.
+ */
 class SdlTimerManager : public DefaultTimerManager {
 public:
 	SdlTimerManager();
-	~SdlTimerManager();
+	virtual ~SdlTimerManager();
 
 protected:
 	SDL_TimerID _timerID;