Partial fix for bug #859

Header file update from Ken for improved doxygen output

--HG--
extra : convert_revision : svn%3Ac70aab31-4412-0410-b14c-859654838e24/trunk%404127

1 files changed, 178 insertions, 160 deletions

diff --git a/include/SDL_events.h b/include/SDL_events.h
index be199dcf..431a06fc 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -21,9 +21,9 @@
 */
 
 /**
- * \file SDL_events.h
- *
- * Include file for SDL event handling
+ *  \file SDL_events.h
+ *  
+ *  Include file for SDL event handling.
  */
 
 #ifndef _SDL_events_h
@@ -50,9 +50,7 @@ extern "C" {
 #define SDL_PRESSED	1
 
 /**
- * \enum SDL_EventType
- *
- * \brief The types of events that can be delivered
+ * \brief The types of events that can be delivered.
  */
 typedef enum
 {
@@ -76,22 +74,22 @@ typedef enum
     SDL_PROXIMITYIN,            /**< Proximity In event */
     SDL_PROXIMITYOUT,           /**< Proximity Out event */
     SDL_EVENT_RESERVED1,        /**< Reserved for future use... */
-    SDL_EVENT_RESERVED2,
-    SDL_EVENT_RESERVED3,
-    /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
+    SDL_EVENT_RESERVED2,        /**< Reserved for future use... */
+    SDL_EVENT_RESERVED3,        /**< 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;
 
+/*@{*/
+#define SDL_EVENTMASK(X)	(1<<(X))
 /**
- * \enum SDL_EventMask
- *
  * \brief Predefined event masks
  */
-#define SDL_EVENTMASK(X)	(1<<(X))
 typedef enum
 {
     SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT),
@@ -121,71 +119,63 @@ typedef enum
     SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT)
 } SDL_EventMask;
 #define SDL_ALLEVENTS		0xFFFFFFFF
+/*@}*/
 
 /**
- * \struct SDL_WindowEvent
- *
- * \brief Window state change event data (event.window.*)
+ *  \brief Window state change event data (event.window.*)
  */
 typedef struct SDL_WindowEvent
 {
-    Uint8 type;             /**< SDL_WINDOWEVENT */
+    Uint8 type;             /**< ::SDL_WINDOWEVENT */
     SDL_WindowID windowID;  /**< The associated window */
-    Uint8 event;            /**< SDL_WindowEventID */
+    Uint8 event;            /**< ::SDL_WindowEventID */
     int data1;              /**< event dependent data */
     int data2;              /**< event dependent data */
 } SDL_WindowEvent;
 
 /**
- * \struct SDL_KeyboardEvent
- *
- * \brief Keyboard button event structure (event.key.*)
+ *  \brief Keyboard button event structure (event.key.*)
  */
 typedef struct SDL_KeyboardEvent
 {
-    Uint8 type;             /**< SDL_KEYDOWN or SDL_KEYUP */
+    Uint8 type;             /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
     SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
     Uint8 which;            /**< The keyboard device index */
-    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
+    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
     SDL_keysym keysym;      /**< The key that was pressed or released */
 } SDL_KeyboardEvent;
 
+#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
 /**
- * \struct SDL_TextEditingEvent
- *
- * \brief Keyboard text editing event structure (event.edit.*)
+ *  \brief Keyboard text editing event structure (event.edit.*)
  */
-#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
 typedef struct SDL_TextEditingEvent
 {
-    Uint8 type;                                 /**< SDL_TEXTEDITING */
+    Uint8 type;                                 /**< ::SDL_TEXTEDITING */
     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
     int start;                                  /**< The start cursor of selected editing text */
     int length;                                 /**< The length of selected editing text */
 } SDL_TextEditingEvent;
 
+
+#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
 /**
- * \struct SDL_TextInputEvent
- *
- * \brief Keyboard text input event structure (event.text.*)
+ *  \brief Keyboard text input event structure (event.text.*)
  */
-#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
 typedef struct SDL_TextInputEvent
 {
-    Uint8 type;                               /**< SDL_TEXTINPUT */
+    Uint8 type;                               /**< ::SDL_TEXTINPUT */
     SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
     Uint8 which;                              /**< The keyboard device index */
     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
 } SDL_TextInputEvent;
 
 /**
- * \struct SDL_MouseMotionEvent
- *
- * \brief Mouse motion event structure (event.motion.*)
+ *  \brief Mouse motion event structure (event.motion.*)
  */
 typedef struct SDL_MouseMotionEvent
 {
-    Uint8 type;             /**< SDL_MOUSEMOTION */
+    Uint8 type;             /**< ::SDL_MOUSEMOTION */
     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
     Uint8 which;            /**< The mouse device index */
     Uint8 state;            /**< The current button state */
@@ -203,29 +193,25 @@ typedef struct SDL_MouseMotionEvent
 } SDL_MouseMotionEvent;
 
 /**
- * \struct SDL_MouseButtonEvent
- *
- * \brief Mouse button event structure (event.button.*)
+ *  \brief Mouse button event structure (event.button.*)
  */
 typedef struct SDL_MouseButtonEvent
 {
-    Uint8 type;             /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
+    Uint8 type;             /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
     Uint8 which;            /**< The mouse device index */
     Uint8 button;           /**< The mouse button index */
-    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
+    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
     int x;                  /**< X coordinate, relative to window */
     int y;                  /**< Y coordinate, relative to window */
 } SDL_MouseButtonEvent;
 
 /**
- * \struct SDL_MouseWheelEvent
- *
- * \brief Mouse wheel event structure (event.wheel.*)
+ *  \brief Mouse wheel event structure (event.wheel.*)
  */
 typedef struct SDL_MouseWheelEvent
 {
-    Uint8 type;             /**< SDL_MOUSEWHEEL */
+    Uint8 type;             /**< ::SDL_MOUSEWHEEL */
     SDL_WindowID windowID;  /**< The window with mouse focus, if any */
     Uint8 which;            /**< The mouse device index */
     int x;                  /**< The amount scrolled horizontally */
@@ -233,26 +219,22 @@ typedef struct SDL_MouseWheelEvent
 } SDL_MouseWheelEvent;
 
 /**
- * \struct SDL_JoyAxisEvent
- *
- * \brief Joystick axis motion event structure (event.jaxis.*)
+ *  \brief Joystick axis motion event structure (event.jaxis.*)
  */
 typedef struct SDL_JoyAxisEvent
 {
-    Uint8 type;         /**< SDL_JOYAXISMOTION */
+    Uint8 type;         /**< ::SDL_JOYAXISMOTION */
     Uint8 which;        /**< The joystick device index */
     Uint8 axis;         /**< The joystick axis index */
     int value;          /**< The axis value (range: -32768 to 32767) */
 } SDL_JoyAxisEvent;
 
 /**
- * \struct SDL_JoyBallEvent
- *
- * \brief Joystick trackball motion event structure (event.jball.*)
+ *  \brief Joystick trackball motion event structure (event.jball.*)
  */
 typedef struct SDL_JoyBallEvent
 {
-    Uint8 type;         /**< SDL_JOYBALLMOTION */
+    Uint8 type;         /**< ::SDL_JOYBALLMOTION */
     Uint8 which;        /**< The joystick device index */
     Uint8 ball;         /**< The joystick trackball index */
     int xrel;           /**< The relative motion in the X direction */
@@ -260,72 +242,64 @@ typedef struct SDL_JoyBallEvent
 } SDL_JoyBallEvent;
 
 /**
- * \struct SDL_JoyHatEvent
- *
- * \brief Joystick hat position change event structure (event.jhat.*)
+ *  \brief Joystick hat position change event structure (event.jhat.*)
  */
 typedef struct SDL_JoyHatEvent
 {
-    Uint8 type;         /**< SDL_JOYHATMOTION */
+    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 value;        /**< The hat position value.
+                         *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
+                         *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
+                         *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
+                         *   
+                         *   Note that zero means the POV is centered.
                          */
 } SDL_JoyHatEvent;
 
 /**
- * \struct SDL_JoyButtonEvent
- *
- * \brief Joystick button event structure (event.jbutton.*)
+ *  \brief Joystick button event structure (event.jbutton.*)
  */
 typedef struct SDL_JoyButtonEvent
 {
-    Uint8 type;         /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
+    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 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
 } SDL_JoyButtonEvent;
 
 /**
- * \struct SDL_QuitEvent
- *
- * \brief The "quit requested" event
+ *  \brief The "quit requested" event
  */
 typedef struct SDL_QuitEvent
 {
-    Uint8 type;         /**< SDL_QUIT */
+    Uint8 type;         /**< ::SDL_QUIT */
 } SDL_QuitEvent;
 
 /**
- * \struct SDL_UserEvent
- *
- * \brief A user-defined event type (event.user.*)
+ *  \brief A user-defined event type (event.user.*)
  */
 typedef struct SDL_UserEvent
 {
-    Uint8 type;             /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
+    Uint8 type;             /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
     SDL_WindowID windowID;  /**< The associated window if any*/
     int code;               /**< User defined event code */
     void *data1;            /**< User defined data pointer */
     void *data2;            /**< User defined data pointer */
 } SDL_UserEvent;
 
-/**
- * \struct SDL_SysWMEvent
- *
- * \brief A video driver dependent system event (event.syswm.*)
- *
- * \note If you want to use this event, you should include SDL_syswm.h
- */
 struct SDL_SysWMmsg;
 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
+
+/**
+ *  \brief A video driver dependent system event (event.syswm.*)
+ *  
+ *  \note If you want to use this event, you should include SDL_syswm.h.
+ */
 typedef struct SDL_SysWMEvent
 {
-    Uint8 type;         /**< SDL_SYSWMEVENT */
+    Uint8 type;         /**< ::SDL_SYSWMEVENT */
     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
 } SDL_SysWMEvent;
 
@@ -339,8 +313,16 @@ typedef struct SDL_ProximityEvent
     int y;
 } SDL_ProximityEvent;
 
-/* Typedefs for backwards compatibility */
 #ifndef SDL_NO_COMPAT
+/**
+ *  \addtogroup Compatibility 
+ */
+/*@{*/
+
+/**
+ *  \name Typedefs for backwards compatibility
+ */
+/*@{*/
 typedef struct SDL_ActiveEvent
 {
     Uint8 type;
@@ -354,12 +336,13 @@ typedef struct SDL_ResizeEvent
     int w;
     int h;
 } SDL_ResizeEvent;
+/*@}*/
+
+/*@}*//*Compatibility*/
 #endif
 
 /**
- * \union SDL_Event
- *
- * \brief General event structure
+ *  \brief General event structure
  */
 typedef union SDL_Event
 {
@@ -380,129 +363,164 @@ typedef union SDL_Event
     SDL_SysWMEvent syswm;           /**< System dependent window event data */
     SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
 
-    /* Temporarily here for backwards compatibility */
+    /** Temporarily here for backwards compatibility */
+    /*@{*/
 #ifndef SDL_NO_COMPAT
     SDL_ActiveEvent active;
     SDL_ResizeEvent resize;
 #endif
+    /*@}*/
 } SDL_Event;
 
 
 /* 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 \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
+ *  the back of the event queue.
+ *  
+ *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
+ *  of the event queue, matching \c mask, will be returned and will not
+ *  be removed from the queue.
+ *  
+ *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
+ *  of the event queue, matching \c mask, will be returned and will be
+ *  removed from the queue.
+ *  
+ *  \return 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);
+/*@}*/
 
-/* Checks to see if certain event types are in the event queue.
+/**
+ *  Checks to see if certain event types are in the event queue.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(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.
+/**
+ *  \brief Polls for currently pending events.
+ *  
+ *  \return 1 if there are any pending events, or 0 if there are none available.
+ *  
+ *  \param event If 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.
+/**
+ *  \brief Waits indefinitely for the next available event.
+ *  
+ *  \return 1, or 0 if there was an error while waiting for events.
+ *   
+ *  \param event If not NULL, the next event is removed from the queue and 
+ *               stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
 
-/* Waits until the specified timeout (in milliseconds) 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.
+/**
+ *  \brief Waits until the specified timeout (in milliseconds) for the next 
+ *         available event.
+ *  
+ *  \return 1, or 0 if there was an error while waiting for events.
+ *  
+ *  \param event If not NULL, the next event is removed from the queue and 
+ *               stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
                                                  int timeout);
 
-/* Add an event to the event queue.
-   This function returns 1 on success, 0 if the event was filtered,
-   or -1 if the event queue was full or there was some other error.
+/**
+ *  \brief Add an event to the event queue.
+ *  
+ *  \return 1 on success, 0 if the event was filtered, 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:
-*/
 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, 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.
-*/
+
+/**
+ *  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
+ *      int SDL_EventFilter(void *userdata, 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,
                                                 void *userdata);
 
-/*
-  Return the current event filter - can be used to "chain" filters.
-  If there is no event filter set, this function returns SDL_FALSE.
-*/
+/**
+ *  Return the current event filter - can be used to "chain" filters.
+ *  If there is no event filter set, this function returns SDL_FALSE.
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
                                                     void **userdata);
 
-/*
-  Run the filter function on the current event queue, removing any
-  events for which the filter returns 0.
-*/
+/**
+ *  Run the filter function on the current event queue, removing any
+ *  events for which the filter returns 0.
+ */
 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
                                               void *userdata);
 
-/*
-  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.
-*/
+/*@{*/
 #define SDL_QUERY	-1
 #define SDL_IGNORE	 0
 #define SDL_DISABLE	 0
 #define SDL_ENABLE	 1
-extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
 
+/**
+ *  This function allows you to set the state of processing certain events.
+ *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
+ *     dropped from the event queue and will not event be filtered.
+ *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
+ *     normally.
+ *   - If \c 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