--- a/include/SDL_events.h	Mon Sep 21 09:27:08 2009 +0000
+++ b/include/SDL_events.h	Mon Sep 21 09:38:10 2009 +0000
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL event handling */
+/**
+ *  @file SDL_events.h
+ *  Include file for SDL event handling
+ */
 
 #ifndef _SDL_events_h
 #define _SDL_events_h
@@ -39,45 +42,48 @@
 extern "C" {
 #endif
 
-/* General keyboard/mouse state definitions */
+/** @name General keyboard/mouse state definitions */
+/*@{*/
 #define SDL_RELEASED	0
 #define SDL_PRESSED	1
+/*@}*/
 
-/* Event enumerations */
+/** Event enumerations */
 typedef enum {
-       SDL_NOEVENT = 0,			/* Unused (do not remove) */
-       SDL_ACTIVEEVENT,			/* Application loses/gains visibility */
-       SDL_KEYDOWN,			/* Keys pressed */
-       SDL_KEYUP,			/* Keys released */
-       SDL_MOUSEMOTION,			/* Mouse moved */
-       SDL_MOUSEBUTTONDOWN,		/* Mouse button pressed */
-       SDL_MOUSEBUTTONUP,		/* Mouse button released */
-       SDL_JOYAXISMOTION,		/* Joystick axis motion */
-       SDL_JOYBALLMOTION,		/* Joystick trackball motion */
-       SDL_JOYHATMOTION,		/* Joystick hat position change */
-       SDL_JOYBUTTONDOWN,		/* Joystick button pressed */
-       SDL_JOYBUTTONUP,			/* Joystick button released */
-       SDL_QUIT,			/* User-requested quit */
-       SDL_SYSWMEVENT,			/* System specific event */
-       SDL_EVENT_RESERVEDA,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVEDB,		/* Reserved for future use.. */
-       SDL_VIDEORESIZE,			/* User resized video mode */
-       SDL_VIDEOEXPOSE,			/* Screen needs to be redrawn */
-       SDL_EVENT_RESERVED2,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVED3,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVED4,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVED5,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVED6,		/* Reserved for future use.. */
-       SDL_EVENT_RESERVED7,		/* Reserved for future use.. */
-       /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
+       SDL_NOEVENT = 0,			/**< Unused (do not remove) */
+       SDL_ACTIVEEVENT,			/**< Application loses/gains visibility */
+       SDL_KEYDOWN,			/**< Keys pressed */
+       SDL_KEYUP,			/**< Keys released */
+       SDL_MOUSEMOTION,			/**< Mouse moved */
+       SDL_MOUSEBUTTONDOWN,		/**< Mouse button pressed */
+       SDL_MOUSEBUTTONUP,		/**< Mouse button released */
+       SDL_JOYAXISMOTION,		/**< Joystick axis motion */
+       SDL_JOYBALLMOTION,		/**< Joystick trackball motion */
+       SDL_JOYHATMOTION,		/**< Joystick hat position change */
+       SDL_JOYBUTTONDOWN,		/**< Joystick button pressed */
+       SDL_JOYBUTTONUP,			/**< Joystick button released */
+       SDL_QUIT,			/**< User-requested quit */
+       SDL_SYSWMEVENT,			/**< System specific event */
+       SDL_EVENT_RESERVEDA,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVEDB,		/**< Reserved for future use.. */
+       SDL_VIDEORESIZE,			/**< User resized video mode */
+       SDL_VIDEOEXPOSE,			/**< Screen needs to be redrawn */
+       SDL_EVENT_RESERVED2,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVED3,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVED4,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVED5,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVED6,		/**< Reserved for future use.. */
+       SDL_EVENT_RESERVED7,		/**< Reserved for future use.. */
+       /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
        SDL_USEREVENT = 24,
-       /* This last event is only for bounding internal arrays
-	  It is the number of bits in the event mask datatype -- Uint32
+       /** This last event is only for bounding internal arrays
+	*  It is the number of bits in the event mask datatype -- Uint32
         */
        SDL_NUMEVENTS = 32
 } SDL_EventType;
 
-/* Predefined event masks */
+/** @name Predefined event masks */
+/*@{*/
 #define SDL_EVENTMASK(X)	(1<<(X))
 typedef enum {
 	SDL_ACTIVEEVENTMASK	= SDL_EVENTMASK(SDL_ACTIVEEVENT),
@@ -107,108 +113,109 @@
 	SDL_SYSWMEVENTMASK	= SDL_EVENTMASK(SDL_SYSWMEVENT)
 } SDL_EventMask ;
 #define SDL_ALLEVENTS		0xFFFFFFFF
+/*@}*/
 
-/* Application visibility event structure */
+/** Application visibility event structure */
 typedef struct SDL_ActiveEvent {
-	Uint8 type;	/* SDL_ACTIVEEVENT */
-	Uint8 gain;	/* Whether given states were gained or lost (1/0) */
-	Uint8 state;	/* A mask of the focus states */
+	Uint8 type;	/**< SDL_ACTIVEEVENT */
+	Uint8 gain;	/**< Whether given states were gained or lost (1/0) */
+	Uint8 state;	/**< A mask of the focus states */
 } SDL_ActiveEvent;
 
-/* Keyboard event structure */
+/** Keyboard event structure */
 typedef struct SDL_KeyboardEvent {
-	Uint8 type;	/* SDL_KEYDOWN or SDL_KEYUP */
-	Uint8 which;	/* The keyboard device index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
+	Uint8 type;	/**< SDL_KEYDOWN or SDL_KEYUP */
+	Uint8 which;	/**< The keyboard device index */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
 	SDL_keysym keysym;
 } SDL_KeyboardEvent;
 
-/* Mouse motion event structure */
+/** Mouse motion event structure */
 typedef struct SDL_MouseMotionEvent {
-	Uint8 type;	/* SDL_MOUSEMOTION */
-	Uint8 which;	/* The mouse device index */
-	Uint8 state;	/* The current button state */
-	Uint16 x, y;	/* The X/Y coordinates of the mouse */
-	Sint16 xrel;	/* The relative motion in the X direction */
-	Sint16 yrel;	/* The relative motion in the Y direction */
+	Uint8 type;	/**< SDL_MOUSEMOTION */
+	Uint8 which;	/**< The mouse device index */
+	Uint8 state;	/**< The current button state */
+	Uint16 x, y;	/**< The X/Y coordinates of the mouse */
+	Sint16 xrel;	/**< The relative motion in the X direction */
+	Sint16 yrel;	/**< The relative motion in the Y direction */
 } SDL_MouseMotionEvent;
 
-/* Mouse button event structure */
+/** Mouse button event structure */
 typedef struct SDL_MouseButtonEvent {
-	Uint8 type;	/* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
-	Uint8 which;	/* The mouse device index */
-	Uint8 button;	/* The mouse button index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
-	Uint16 x, y;	/* The X/Y coordinates of the mouse at press time */
+	Uint8 type;	/**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
+	Uint8 which;	/**< The mouse device index */
+	Uint8 button;	/**< The mouse button index */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
+	Uint16 x, y;	/**< The X/Y coordinates of the mouse at press time */
 } SDL_MouseButtonEvent;
 
-/* Joystick axis motion event structure */
+/** Joystick axis motion event structure */
 typedef struct SDL_JoyAxisEvent {
-	Uint8 type;	/* SDL_JOYAXISMOTION */
-	Uint8 which;	/* The joystick device index */
-	Uint8 axis;	/* The joystick axis index */
-	Sint16 value;	/* The axis value (range: -32768 to 32767) */
+	Uint8 type;	/**< SDL_JOYAXISMOTION */
+	Uint8 which;	/**< The joystick device index */
+	Uint8 axis;	/**< The joystick axis index */
+	Sint16 value;	/**< The axis value (range: -32768 to 32767) */
 } SDL_JoyAxisEvent;
 
-/* Joystick trackball motion event structure */
+/** Joystick trackball motion event structure */
 typedef struct SDL_JoyBallEvent {
-	Uint8 type;	/* SDL_JOYBALLMOTION */
-	Uint8 which;	/* The joystick device index */
-	Uint8 ball;	/* The joystick trackball index */
-	Sint16 xrel;	/* The relative motion in the X direction */
-	Sint16 yrel;	/* The relative motion in the Y direction */
+	Uint8 type;	/**< SDL_JOYBALLMOTION */
+	Uint8 which;	/**< The joystick device index */
+	Uint8 ball;	/**< The joystick trackball index */
+	Sint16 xrel;	/**< The relative motion in the X direction */
+	Sint16 yrel;	/**< The relative motion in the Y direction */
 } SDL_JoyBallEvent;
 
-/* Joystick hat position change event structure */
+/** Joystick hat position change event structure */
 typedef struct SDL_JoyHatEvent {
-	Uint8 type;	/* SDL_JOYHATMOTION */
-	Uint8 which;	/* The joystick device index */
-	Uint8 hat;	/* The joystick hat index */
-	Uint8 value;	/* The hat position value:
-			    SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
-			    SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
-			    SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
-			   Note that zero means the POV is centered.
-			*/
+	Uint8 type;	/**< SDL_JOYHATMOTION */
+	Uint8 which;	/**< The joystick device index */
+	Uint8 hat;	/**< The joystick hat index */
+	Uint8 value;	/**< The hat position value:
+			 *   SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
+			 *   SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
+			 *   SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
+			 *  Note that zero means the POV is centered.
+			 */
 } SDL_JoyHatEvent;
 
-/* Joystick button event structure */
+/** Joystick button event structure */
 typedef struct SDL_JoyButtonEvent {
-	Uint8 type;	/* SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
-	Uint8 which;	/* The joystick device index */
-	Uint8 button;	/* The joystick button index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
+	Uint8 type;	/**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
+	Uint8 which;	/**< The joystick device index */
+	Uint8 button;	/**< The joystick button index */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
 } SDL_JoyButtonEvent;
 
-/* The "window resized" event
-   When you get this event, you are responsible for setting a new video
-   mode with the new width and height.
+/** The "window resized" event
+ *  When you get this event, you are responsible for setting a new video
+ *  mode with the new width and height.
  */
 typedef struct SDL_ResizeEvent {
-	Uint8 type;	/* SDL_VIDEORESIZE */
-	int w;		/* New width */
-	int h;		/* New height */
+	Uint8 type;	/**< SDL_VIDEORESIZE */
+	int w;		/**< New width */
+	int h;		/**< New height */
 } SDL_ResizeEvent;
 
-/* The "screen redraw" event */
+/** The "screen redraw" event */
 typedef struct SDL_ExposeEvent {
-	Uint8 type;	/* SDL_VIDEOEXPOSE */
+	Uint8 type;	/**< SDL_VIDEOEXPOSE */
 } SDL_ExposeEvent;
 
-/* The "quit requested" event */
+/** The "quit requested" event */
 typedef struct SDL_QuitEvent {
-	Uint8 type;	/* SDL_QUIT */
+	Uint8 type;	/**< SDL_QUIT */
 } SDL_QuitEvent;
 
-/* A user-defined event type */
+/** A user-defined event type */
 typedef struct SDL_UserEvent {
-	Uint8 type;	/* SDL_USEREVENT through SDL_NUMEVENTS-1 */
-	int code;	/* User defined event code */
-	void *data1;	/* User defined data pointer */
-	void *data2;	/* User defined data pointer */
+	Uint8 type;	/**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
+	int code;	/**< User defined event code */
+	void *data1;	/**< User defined data pointer */
+	void *data2;	/**< User defined data pointer */
 } SDL_UserEvent;
 
-/* If you want to use this event, you should include SDL_syswm.h */
+/** If you want to use this event, you should include SDL_syswm.h */
 struct SDL_SysWMmsg;
 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
 typedef struct SDL_SysWMEvent {
@@ -216,7 +223,7 @@
 	SDL_SysWMmsg *msg;
 } SDL_SysWMEvent;
 
-/* General event structure */
+/** General event structure */
 typedef union SDL_Event {
 	Uint8 type;
 	SDL_ActiveEvent active;
@@ -237,97 +244,109 @@
 
 /* Function prototypes */
 
-/* Pumps the event loop, gathering events from the input devices.
-   This function updates the event queue and internal input device state.
-   This should only be run in the thread that sets the video mode.
-*/
+/** Pumps the event loop, gathering events from the input devices.
+ *  This function updates the event queue and internal input device state.
+ *  This should only be run in the thread that sets the video mode.
+ */
 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
 
-/* Checks the event queue for messages and optionally returns them.
-   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
-   the back of the event queue.
-   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
-   of the event queue, matching 'mask', will be returned and will not
-   be removed from the queue.
-   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
-   of the event queue, matching 'mask', will be returned and will be
-   removed from the queue.
-   This function returns the number of events actually stored, or -1
-   if there was an error.  This function is thread-safe.
-*/
 typedef enum {
 	SDL_ADDEVENT,
 	SDL_PEEKEVENT,
 	SDL_GETEVENT
 } SDL_eventaction;
-/* */
+
+/**
+ *  Checks the event queue for messages and optionally returns them.
+ *
+ *  If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
+ *  the back of the event queue.
+ *  If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
+ *  of the event queue, matching 'mask', will be returned and will not
+ *  be removed from the queue.
+ *  If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
+ *  of the event queue, matching 'mask', will be returned and will be
+ *  removed from the queue.
+ *
+ *  @return
+ *  This function returns the number of events actually stored, or -1
+ *  if there was an error.
+ *
+ *  This function is thread-safe.
+ */
 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
 				SDL_eventaction action, Uint32 mask);
 
-/* Polls for currently pending events, and returns 1 if there are any pending
-   events, or 0 if there are none available.  If 'event' is not NULL, the next
-   event is removed from the queue and stored in that area.
+/** Polls for currently pending events, and returns 1 if there are any pending
+ *  events, or 0 if there are none available.  If 'event' is not NULL, the next
+ *  event is removed from the queue and stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
 
-/* Waits indefinitely for the next available event, returning 1, or 0 if there
-   was an error while waiting for events.  If 'event' is not NULL, the next
-   event is removed from the queue and stored in that area.
+/** Waits indefinitely for the next available event, returning 1, or 0 if there
+ *  was an error while waiting for events.  If 'event' is not NULL, the next
+ *  event is removed from the queue and stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
 
-/* Add an event to the event queue.
-   This function returns 0 on success, or -1 if the event queue was full
-   or there was some other error.
+/** Add an event to the event queue.
+ *  This function returns 0 on success, or -1 if the event queue was full
+ *  or there was some other error.
  */
 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
 
-/*
-  This function sets up a filter to process all events before they
-  change internal state and are posted to the internal event queue.
-
-  The filter is protypted as:
-*/
+/** @name Event Filtering */
+/*@{*/
 typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
-/*
-  If the filter returns 1, then the event will be added to the internal queue.
-  If it returns 0, then the event will be dropped from the queue, but the 
-  internal state will still be updated.  This allows selective filtering of
-  dynamically arriving events.
-
-  WARNING:  Be very careful of what you do in the event filter function, as 
-            it may run in a different thread!
-
-  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
-  event filter is only called when the window manager desires to close the
-  application window.  If the event filter returns 1, then the window will
-  be closed, otherwise the window will remain open if possible.
-  If the quit event is generated by an interrupt signal, it will bypass the
-  internal queue and be delivered to the application at the next event poll.
-*/
+/**
+ *  This function sets up a filter to process all events before they
+ *  change internal state and are posted to the internal event queue.
+ *
+ *  The filter is protypted as:
+ *      @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode
+ *
+ * If the filter returns 1, then the event will be added to the internal queue.
+ * If it returns 0, then the event will be dropped from the queue, but the 
+ * internal state will still be updated.  This allows selective filtering of
+ * dynamically arriving events.
+ *
+ * @warning  Be very careful of what you do in the event filter function, as 
+ *           it may run in a different thread!
+ *
+ * There is one caveat when dealing with the SDL_QUITEVENT event type.  The
+ * event filter is only called when the window manager desires to close the
+ * application window.  If the event filter returns 1, then the window will
+ * be closed, otherwise the window will remain open if possible.
+ * If the quit event is generated by an interrupt signal, it will bypass the
+ * internal queue and be delivered to the application at the next event poll.
+ */
 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
 
-/*
-  Return the current event filter - can be used to "chain" filters.
-  If there is no event filter set, this function returns NULL.
-*/
+/**
+ *  Return the current event filter - can be used to "chain" filters.
+ *  If there is no event filter set, this function returns NULL.
+ */
 extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
+/*@}*/
 
-/*
-  This function allows you to set the state of processing certain events.
-  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
-  from the event queue and will not event be filtered.
-  If 'state' is set to SDL_ENABLE, that event will be processed normally.
-  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
-  current processing state of the specified event.
-*/
+/** @name Event State */
+/*@{*/
 #define SDL_QUERY	-1
 #define SDL_IGNORE	 0
 #define SDL_DISABLE	 0
 #define SDL_ENABLE	 1
+/*@}*/
+
+/**
+* This function allows you to set the state of processing certain events.
+* If 'state' is set to SDL_IGNORE, that event will be automatically dropped
+* from the event queue and will not event be filtered.
+* If 'state' is set to SDL_ENABLE, that event will be processed normally.
+* If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
+* current processing state of the specified event.
+*/
 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
 
-
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }