Cleanup and documentation.

svn-id: r50589

backends/audiocd/audiocd.h

@@ -29,14 +29,16 @@
 #include "common/noncopyable.h"
 
 /**
-* Abstract Audio CD manager class. Private subclasses implement the actual
+* Abstract Audio CD manager class. Subclasses implement the actual
 * functionality.
 */
 class AudioCDManager : Common::NonCopyable {
 public:
 	virtual ~AudioCDManager() {}
 
-
+	/**
+	* A structure containing the current playback information
+	*/
 	struct Status {
 		bool playing;
 		int track;
@@ -97,6 +99,7 @@ public:
 
 	/**
 	 * Initialise the specified CD drive for audio playback.
+	 * @param drive the drive id
 	 * @return true if the CD drive was inited succesfully
 	 */
 	virtual bool openCD(int drive) = 0;

backends/audiocd/default/default-audiocd.cpp

@@ -25,7 +25,6 @@
 
 #include "backends/audiocd/default/default-audiocd.h"
 #include "sound/audiostream.h"
-#include "common/util.h"
 #include "common/system.h"
 
 DefaultAudioCDManager::DefaultAudioCDManager() {

backends/audiocd/default/default-audiocd.h

@@ -29,6 +29,9 @@
 #include "backends/audiocd/audiocd.h"
 #include "sound/mixer.h"
 
+/**
+* The default audio cd manager. Implements emulation of audio cd playback.
+*/
 class DefaultAudioCDManager : public AudioCDManager {
 public:
 	DefaultAudioCDManager();

backends/audiocd/sdl/sdl-audiocd.cpp

@@ -64,7 +64,8 @@ bool SdlAudioCDManager::openCD(int drive) {
 	return (_cdrom != NULL);
 }
 
-void SdlAudioCDManager::stopCD() {	/* Stop CD Audio in 1/10th of a second */
+void SdlAudioCDManager::stopCD() {
+	// Stop CD Audio in 1/10th of a second
 	_cdStopTime = SDL_GetTicks() + 100;
 	_cdNumLoops = 0;
 }

backends/audiocd/sdl/sdl-audiocd.h

@@ -34,17 +34,20 @@
 #include <SDL.h>
 #endif
 
+/**
+* The SDL audio cd manager. Implements real audio cd playback.
+*/
 class SdlAudioCDManager : public DefaultAudioCDManager {
 public:
 	SdlAudioCDManager();
-	~SdlAudioCDManager();
+	virtual ~SdlAudioCDManager();
 
 protected:
-	bool openCD(int drive);
+	virtual bool openCD(int drive);
-	void updateCD();
+	virtual void updateCD();
-	bool pollCD() const;
+	virtual bool pollCD() const;
-	void playCD(int track, int num_loops, int start_frame, int duration);
+	virtual void playCD(int track, int num_loops, int start_frame, int duration);
-	void stopCD();
+	virtual void stopCD();
 
 	SDL_CD *_cdrom;
 	int _cdTrack, _cdNumLoops, _cdStartFrame, _cdDuration;

backends/modular-backend.cpp

@@ -40,6 +40,8 @@ ModularBackend::ModularBackend()
 }
 
 ModularBackend::~ModularBackend() {
+	// Delete all managers if they have not been already
+	// freed by a subclass
 	if (_eventManager != 0)
 		delete _eventManager;
 	if (_graphicsManager != 0)

backends/modular-backend.h

@@ -34,15 +34,41 @@
 #include "backends/mutex/null/null-mutex.h"
 #include "backends/graphics/null/null-graphics.h"
 
+/**
+ * Base class for modular backends.
+ * 
+ * It wraps most functions to their manager equivalent, but not
+ * all OSystem functions are implemented here.
+ * 
+ * A backend derivated from this class, will need to implement
+ * these functions on its own:
+ *   OSystem::pollEvent()
+ *   OSystem::createConfigReadStream()
+ *   OSystem::createConfigWriteStream()
+ *   OSystem::getMillis()
+ *   OSystem::delayMillis()
+ *   OSystem::getTimeAndDate()
+ * 
+ * And, it should also initialize all the managers variables
+ * declared in this class, or override their related functions.
+ */
 class ModularBackend : public OSystem, public Common::EventSource {
 public:
 	ModularBackend();
 	virtual ~ModularBackend();
 
+	/** @name Features */
+	//@{
+
 	virtual bool hasFeature(Feature f);
 	virtual void setFeatureState(Feature f, bool enable);
 	virtual bool getFeatureState(Feature f);
 
+	//@}
+
+	/** @name Graphics */
+	//@{
+
 	virtual const GraphicsMode *getSupportedGraphicsModes() const;
 	virtual int getDefaultGraphicsMode() const;
 	virtual bool setGraphicsMode(int mode);
@@ -85,26 +111,56 @@ public:
 	virtual void setCursorPalette(const byte *colors, uint start, uint num);
 	virtual void disableCursorPalette(bool disable);
 
+	//@}
+
+	/** @name Events and Time */
+	//@{
+	
 	virtual Common::TimerManager *getTimerManager();
 	virtual Common::EventManager *getEventManager();
 	virtual Common::HardwareKeySet *getHardwareKeySet() { return 0; }
 
+	//@}
+	
+	/** @name Mutex handling */
+	//@{
+
 	virtual MutexRef createMutex();
 	virtual void lockMutex(MutexRef mutex);
 	virtual void unlockMutex(MutexRef mutex);
 	virtual void deleteMutex(MutexRef mutex);
 
+	//@}
+
+	/** @name Sound */
+	//@{
+
 	virtual Audio::Mixer *getMixer();
 
+	//@}
+
+	/** @name Audio CD */
+	//@{
+
 	virtual AudioCDManager *getAudioCDManager();
 
+	//@}
+
+	/** @name Miscellaneous */
+	//@{
+
+	virtual Common::SaveFileManager *getSavefileManager();
+	virtual FilesystemFactory *getFilesystemFactory();
 	virtual void quit() { exit(0); }
 	virtual void setWindowCaption(const char *caption) {}
 	virtual void displayMessageOnOSD(const char *msg);
-	virtual Common::SaveFileManager *getSavefileManager();
+
-	virtual FilesystemFactory *getFilesystemFactory();
+	//@}
 
 protected:
+	/** @name Managers variables */
+	//@{
+
 	FilesystemFactory *_fsFactory;
 	Common::EventManager *_eventManager;
 	Common::SaveFileManager *_savefileManager;
@@ -113,7 +169,8 @@ protected:
 	GraphicsManager *_graphicsManager;
 	Audio::Mixer *_mixer;
 	AudioCDManager *_audiocdManager;
+
+	//@}
 };
 
-
 #endif

backends/platform/null/null.cpp

@@ -52,7 +52,9 @@ public:
 
 	virtual bool pollEvent(Common::Event &event);
 
-	virtual void quit();
+	virtual uint32 getMillis();
+	virtual void delayMillis(uint msecs) {}
+	virtual void getTimeAndDate(TimeDate &t) const {}
 
 	virtual Common::SeekableReadStream *createConfigReadStream();
 	virtual Common::WriteStream *createConfigWriteStream();
@@ -95,7 +97,8 @@ bool OSystem_NULL::pollEvent(Common::Event &event) {
 	return false;
 }
 
-void OSystem_NULL::quit() {
+uint32 OSystem_NULL::getMillis() {
+	return 0;
 }
 
 #if defined(UNIX)

backends/platform/sdl/macosx/macosx-main.cpp

@@ -25,8 +25,6 @@
 
 #ifdef MACOSX
 
-#include "common/scummsys.h"
-
 #include "backends/platform/sdl/macosx/macosx.h"
 #include "backends/plugins/sdl/sdl-provider.h"
 #include "base/main.h"

backends/platform/sdl/macosx/macosx.h

@@ -31,11 +31,11 @@
 class OSystem_MacOSX : public OSystem_POSIX {
 public:
 	OSystem_MacOSX();
-	~OSystem_MacOSX() {}
+	virtual ~OSystem_MacOSX() {}
 
-	void initBackend();
+	virtual void initBackend();
-	void addSysArchivesToSearchSet(Common::SearchSet &s, int priority = 0);
+	virtual void addSysArchivesToSearchSet(Common::SearchSet &s, int priority = 0);
-	void setupIcon();
+	virtual void setupIcon();
 };
 
 #endif

backends/platform/sdl/main.cpp

@@ -23,12 +23,9 @@
  *
  */
 
-#include "common/scummsys.h"
-
 // Several SDL based ports use a custom main, and hence do not want to compile
 // of this file. The following "#if" ensures that.
-#if !defined(__MAEMO__) && !defined(_WIN32_WCE) && !defined(GP2XWIZ)&& !defined(LINUXMOTO) && !defined(__SYMBIAN32__) && !defined(WIN32) && !defined(UNIX)
+#if !defined(UNIX) && !defined(WIN32) && !defined(__MAEMO__) && !defined(__SYMBIAN32__)
-
 
 #include "backends/platform/sdl/sdl.h"
 #include "backends/plugins/sdl/sdl-provider.h"

backends/platform/sdl/posix/posix-main.cpp

@@ -23,9 +23,7 @@
  *
  */
 
-#if defined(UNIX) && !defined(MACOSX) && !defined(SAMSUNGTV) && !defined(LINUXMOTO) && !defined(GP2XWIZ)
+#if defined(UNIX) && !defined(MACOSX) && !defined(SAMSUNGTV) && !defined(LINUXMOTO) && !defined(GP2XWIZ) && !defined(GP2X)
-
-#include "common/scummsys.h"
 
 #include "backends/platform/sdl/posix/posix.h"
 #include "backends/plugins/sdl/sdl-provider.h"

backends/platform/sdl/sdl.h

@@ -23,8 +23,8 @@
  *
  */
 
-#ifndef SDL_COMMON_H
+#ifndef PLATFORM_SDL_H
-#define SDL_COMMON_H
+#define PLATFORM_SDL_H
 
 #if defined(__SYMBIAN32__)
 #include <esdl\SDL.h>
@@ -36,59 +36,72 @@
 #include "backends/graphics/sdl/sdl-graphics.h"
 #include "backends/mixer/sdl/sdl-mixer.h"
 
+/** 
+ * Base OSystem class for all SDL ports.
+ */
 class OSystem_SDL : public ModularBackend {
 public:
 	OSystem_SDL();
 	virtual ~OSystem_SDL();
 
-	/** Pre-initialize backend, it should be called after
+	/** 
-	 *  instantiating the backend. Early needed managers
+	 * Pre-initialize backend. It should be called after
-	 *  are created here.
+	 * instantiating the backend. Early needed managers are
+	 * created here.
 	 */
 	virtual void init();
 
+	/**
+	 * Get the Graphics Manager instance. Used by other managers.
+	 */
+	virtual SdlGraphicsManager *getGraphicsManager();
+
+	/**
+	 * Get the Mixer Manager instance. Not to confuse with getMixer(),
+	 * that returns Audio::Mixer. The Mixer Manager is a SDL wrapper class
+	 * for the Audio::Mixer. Used by other managers.
+	 */
+	virtual SdlMixerManager *getMixerManager();
+
+	// Override functions from ModularBackend
 	virtual void initBackend();
-
 	virtual Common::HardwareKeySet *getHardwareKeySet();
-
 	virtual void quit();
 	virtual void deinit();
-
 	virtual void setWindowCaption(const char *caption);
-
 	virtual void addSysArchivesToSearchSet(Common::SearchSet &s, int priority = 0);
 	virtual Common::SeekableReadStream *createConfigReadStream();
 	virtual Common::WriteStream *createConfigWriteStream();
-
 	virtual bool pollEvent(Common::Event &event);
-
 	virtual uint32 getMillis();
 	virtual void delayMillis(uint msecs);
 	virtual void getTimeAndDate(TimeDate &td) const;
-
 	virtual Audio::Mixer *getMixer();
 
-	// Get the Graphics Manager instance, used by other managers
-	virtual SdlGraphicsManager *getGraphicsManager();
-
-	// Get the Sdl Mixer Manager instance (not the Audio::Mixer)
-	virtual SdlMixerManager *getMixerManager();
-
 protected:
 	bool _inited;
 	bool _initedSDL;
 
-	// Mixer manager that encapsulates the actual Audio::Mixer
+	/**
+	 * Mixer manager that configures and setups SDL for
+	 * the wrapped Audio::Mixer, the true mixer.
+	 */
 	SdlMixerManager *_mixerManager;
 
-	// Initialze SDL library
+	/**
+	 * Initialze the SDL library.
+	 */
 	virtual void initSDL();
 
-	// Setup the window icon
+	/**
+	 * Setup the window icon.
+	 */
 	virtual void setupIcon();
 
-	// Get the file path where the user configuration
+	/**
-	// of ScummVM will be saved
+	 * Get the file path where the user configuration
+	 * of ScummVM will be saved.
+	 */
 	virtual Common::String getDefaultConfigFileName();
 };
 

backends/platform/sdl/win32/win32-main.cpp

@@ -26,14 +26,12 @@
 #ifdef WIN32
 
 // Fix for bug #2895217 "MSVC compilation broken with r47595":
-// We need to keep this on top of the "common/scummsys.h" include,
+// We need to keep this on top of the "common/scummsys.h"(base/main.h) include,
 // otherwise we will get errors about the windows headers redefining
 // "ARRAYSIZE" for example.
+#define WIN32_LEAN_AND_MEAN
 #include <windows.h>
-// winnt.h defines ARRAYSIZE, but we want our own one...
+#undef ARRAYSIZE // winnt.h defines ARRAYSIZE, but we want our own one...
-#undef ARRAYSIZE
-
-#include "common/scummsys.h"
 
 #include "backends/platform/sdl/win32/win32.h"
 #include "backends/plugins/sdl/sdl-provider.h"
@@ -45,7 +43,6 @@ int __stdcall WinMain(HINSTANCE /*hInst*/, HINSTANCE /*hPrevInst*/,  LPSTR /*lpC
 }
 
 int main(int argc, char *argv[]) {
-
 	// Create our OSystem instance
 	g_system = new OSystem_Win32();
 	assert(g_system);

backends/platform/sdl/win32/win32.cpp

@@ -26,8 +26,8 @@
 #ifdef WIN32
 
 #include <windows.h>
-// winnt.h defines ARRAYSIZE, but we want our own one... - this is needed before including util.h
+#define WIN32_LEAN_AND_MEAN
-#undef ARRAYSIZE
+#undef ARRAYSIZE // winnt.h defines ARRAYSIZE, but we want our own one...
 
 #include "backends/platform/sdl/win32/win32.h"
 #include "backends/fs/windows/windows-fs-factory.h"

backends/platform/sdl/win32/win32.h

@@ -30,10 +30,10 @@
 
 class OSystem_Win32 : public OSystem_SDL {
 public:
-	void init();
+	virtual void init();
 
 protected:
-	Common::String getDefaultConfigFileName();
+	virtual Common::String getDefaultConfigFileName();
 };
 
 #endif