Renamed OSystem::set_timer() to setTimerCallback(); more OSystem Doxygen changes

svn-id: r13289

2 files changed, 24 insertions, 8 deletions

diff --git a/common/system.h b/common/system.h
index 3db60fcf9d..3afe519617 100644
--- a/common/system.h
+++ b/common/system.h
@@ -339,10 +339,11 @@ public:
 	 * can be passed to poll_event. 
 	 */
 	struct Event {
+		/** The type of the event. */
 		EventCode event_code;
 		/**
-		  * Keyboard data; only valid for keyboard events (i.e. EVENT_KEYDOWN
-		  * and EVENT_KEYUP). For all other event types, content is undefined.
+		  * Keyboard data; only valid for keyboard events (EVENT_KEYDOWN and
+		  * EVENT_KEYUP). For all other event types, content is undefined.
 		  */
 		struct {
 			/**
@@ -367,6 +368,12 @@ public:
 			 */
 			byte flags;
 		} kbd;
+		/**
+		 * The mouse coordinates, in virtual screen coordinates. Only valid
+		 * for mouse events.
+		 * Virtual screen coordinatest means: the coordinate system of the
+		 * screen area as defined by the most recent call to initSize().
+		 */
 		Common::Point mouse;
 	};
 
@@ -384,10 +391,19 @@ public:
 	virtual void delay_msecs(uint msecs) = 0;
 
 	/**
-	 * Set the timer callback.
+	 * Set the timer callback, a function which is periodically invoked by the
+	 * backend. This can for example be done via a background thread.
+	 * There is at most one active timer; if this method is called while there
+	 * is already an active timer, then the new timer callback should replace
+	 * the previous one. In particular, passing a callback pointer value of 0
+	 * is legal and can be used to clear the current timer callback.
 	 * @see Common::Timer
+	 *
+	 * @param callback	pointer to the callback. May be 0 to reset the timer
+	 * @param interval	the intervall (in milliseconds) between invocations
+	 *                  of the callback
 	 */
-	virtual void set_timer(TimerProc callback, int interval) = 0;
+	virtual void setTimerCallback(TimerProc callback, int interval) = 0;
 
 	//@}
 
diff --git a/common/timer.cpp b/common/timer.cpp
index 06f3b6af90..88ac735f7e 100644
--- a/common/timer.cpp
+++ b/common/timer.cpp
@@ -46,12 +46,12 @@ Timer::Timer(OSystem *system) :
 	_thisTime = _system->get_msecs();
 
 	// Set the timer last, after everything has been initialised
-	_system->set_timer(&timer_handler, 10);
+	_system->setTimerCallback(&timer_handler, 10);
 
 }
 
 Timer::~Timer() {
-	_system->set_timer(0, 0);
+	_system->setTimerCallback(0, 0);
 
 	{
 		Common::StackLock lock(_mutex);
@@ -64,8 +64,8 @@ Timer::~Timer() {
 
 
 	// FIXME: There is still a potential race condition here, depending on how
-	// the system backend implements set_timer: If timers are done using
-	// threads, and if set_timer does *not* gurantee that after it terminates
+	// the system backend implements setTimerCallback: If timers are done using
+	// threads, and if setTimerCallback does *not* gurantee that after it terminates
 	// that timer thread is not run anymore, we are fine. However, if the timer
 	// is still running in parallel to this destructor, then it might be that
 	// it is still waiting for the _mutex. So, again depending on the backend,