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

include/SDL.h

@@ -25,50 +25,51 @@
  *  
  *  Main include header for the SDL library
  */
+
 /**
  *  \mainpage Simple DirectMedia Layer (SDL)
-
-http://www.libsdl.org/
-
-* \section intro_sec Introduction
-
-This is the Simple DirectMedia Layer, a general API that provides low
-level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
-and 2D framebuffer across multiple platforms.
-
-The current version supports Linux, Windows, Windows CE, BeOS, MacOS,
-Mac OS X, FreeBSD, NetBSD, OpenBSD, BSD/OS, Solaris, IRIX, and QNX.
-The code contains support for AIX, OSF/Tru64, RISC OS, and SymbianOS,
-but these are not officially supported.
-
-SDL is written in C, but works with C++ natively, and has bindings to
-several other languages, including Ada, C#, Eiffel, Erlang, Euphoria,
-Guile, Haskell, Java, Lisp, Lua, ML, Objective C, Pascal, Perl, PHP,
-Pike, Pliant, Python, Ruby, and Smalltalk.
-
-This library is distributed under GNU LGPL version 2, which can be
-found in the file  "COPYING".  This license allows you to use SDL
-freely in commercial programs as long as you link with the dynamic
-library.
-
-The best way to learn how to use SDL is to check out the header files in
-the "include" subdirectory and the programs in the "test" subdirectory.
-The header files and test programs are well commented and always up to date.
-More documentation is available in HTML format in "docs/index.html", and
-a documentation wiki is available online at:
-	http://www.libsdl.org/cgi/docwiki.cgi
-
-The test programs in the "test" subdirectory are in the public domain.
-
-Frequently asked questions are answered online:
-	http://www.libsdl.org/faq.php
-
-If you need help with the library, or just want to discuss SDL related
-issues, you can join the developers mailing list:
-	http://www.libsdl.org/mailing-list.php
-
-Enjoy!
-	Sam Lantinga				(slouken@libsdl.org)
+ *  
+ *  http://www.libsdl.org/
+ *  
+ *  \section intro_sec Introduction
+ *  
+ *  This is the Simple DirectMedia Layer, a general API that provides low
+ *  level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
+ *  and 2D framebuffer across multiple platforms.
+ *  
+ *  The current version supports Linux, Windows, Windows CE, BeOS, MacOS,
+ *  Mac OS X, FreeBSD, NetBSD, OpenBSD, BSD/OS, Solaris, IRIX, and QNX.
+ *  The code contains support for AIX, OSF/Tru64, RISC OS, and SymbianOS,
+ *  but these are not officially supported.
+ *  
+ *  SDL is written in C, but works with C++ natively, and has bindings to
+ *  several other languages, including Ada, C#, Eiffel, Erlang, Euphoria,
+ *  Guile, Haskell, Java, Lisp, Lua, ML, Objective C, Pascal, Perl, PHP,
+ *  Pike, Pliant, Python, Ruby, and Smalltalk.
+ *  
+ *  This library is distributed under GNU LGPL version 2, which can be
+ *  found in the file  "COPYING".  This license allows you to use SDL
+ *  freely in commercial programs as long as you link with the dynamic
+ *  library.
+ *  
+ *  The best way to learn how to use SDL is to check out the header files in
+ *  the "include" subdirectory and the programs in the "test" subdirectory.
+ *  The header files and test programs are well commented and always up to date.
+ *  More documentation is available in HTML format in "docs/index.html", and
+ *  a documentation wiki is available online at:
+ *  	http://www.libsdl.org/cgi/docwiki.cgi
+ *  
+ *  The test programs in the "test" subdirectory are in the public domain.
+ *  
+ *  Frequently asked questions are answered online:
+ *  	http://www.libsdl.org/faq.php
+ *  
+ *  If you need help with the library, or just want to discuss SDL related
+ *  issues, you can join the developers mailing list:
+ *  	http://www.libsdl.org/mailing-list.php
+ *  
+ *  Enjoy!
+ *  	Sam Lantinga				(slouken@libsdl.org)
  */
 
 #ifndef _SDL_H
@@ -102,23 +103,28 @@ extern "C" {
 
 /* As of version 0.5, SDL is loaded dynamically into the application */
 
-/* These are the flags which may be passed to SDL_Init() -- you should
-   specify the subsystems which you will be using in your application.
-*/
+/**
+ *  \name SDL_INIT_*
+ *  
+ *  These are the flags which may be passed to SDL_Init().  You should
+ *  specify the subsystems which you will be using in your application.
+ */
+/*@{*/
 #define SDL_INIT_TIMER          0x00000001
 #define SDL_INIT_AUDIO          0x00000010
 #define SDL_INIT_VIDEO          0x00000020
 #define SDL_INIT_JOYSTICK       0x00000200
 #define SDL_INIT_HAPTIC         0x00001000
-#define SDL_INIT_NOPARACHUTE    0x00100000      /* Don't catch fatal signals */
-#define SDL_INIT_EVENTTHREAD    0x01000000      /* Not supported on all OS's */
+#define SDL_INIT_NOPARACHUTE    0x00100000      /**< Don't catch fatal signals */
+#define SDL_INIT_EVENTTHREAD    0x01000000      /**< Not supported on all OS's */
 #define SDL_INIT_EVERYTHING     0x0000FFFF
+/*@}*/
 
 /**
  *  This function loads the SDL dynamically linked library and initializes 
- * the subsystems specified by 'flags' (and those satisfying dependencies)
- * Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
- * signal handlers for some commonly ignored fatal signals (like SIGSEGV)
+ *  the subsystems specified by \c flags (and those satisfying dependencies).
+ *  Unless the ::SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
+ *  signal handlers for some commonly ignored fatal signals (like SIGSEGV).
  */
 extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
 
@@ -127,14 +133,17 @@ extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
  */
 extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
 
-/** This function cleans up specific SDL subsystems */
+/**
+ *  This function cleans up specific SDL subsystems
+ */
 extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
 
 /**
-   This function returns mask of the specified subsystems which have
-   been initialized.
-   If 'flags' is 0, it returns a mask of all initialized subsystems.
-*/
+ *  This function returns mask of the specified subsystems which have
+ *  been initialized.
+ *  
+ *  If \c flags is 0, it returns a mask of all initialized subsystems.
+ */
 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
 
 /**

include/SDL_atomic.h

@@ -26,6 +26,16 @@
  *  \file SDL_atomic.h
  *  
  *  Atomic operations.
+ *  
+ *  These operations may, or may not, actually be implemented using
+ *  processor specific atomic operations. When possible they are
+ *  implemented as true processor specific atomic operations. When that
+ *  is not possible the are implemented using locks that *do* use the
+ *  available atomic operations.
+ *  
+ *  At the very minimum spin locks must be implemented. Without spin
+ *  locks it is not possible (AFAICT) to emulate the rest of the atomic
+ *  operations.
  */
 
 #ifndef _SDL_atomic_h_
@@ -43,176 +53,139 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/**
- * These operations may, or may not, actually be implemented using
- * processor specific atomic operations. When possible they are
- * implemented as true processor specific atomic operations. When that
- * is not possible the are implemented using locks that *do* use the
- * available atomic operations.
- *
- * At the very minimum spin locks must be implemented. Without spin
- * locks it is not possible (AFAICT) to emulate the rest of the atomic
- * operations.
- */
-
 /* Function prototypes */
 
 /**
- * SDL AtomicLock.
+ *  \name SDL AtomicLock
  *  
  *  The spin lock functions and type are required and can not be
  *  emulated because they are used in the emulation code.
  */
+/*@{*/
 
 typedef volatile Uint32 SDL_SpinLock;
 
 /**
- * \fn  void SDL_AtomicLock(SDL_SpinLock *lock);
- *
  *  \brief Lock a spin lock by setting it to a none zero value.
  *  
- * \param lock points to the lock.
- *
+ *  \param lock Points to the lock.
  */
 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
 
 /**
- * \fn  void SDL_AtomicUnlock(SDL_SpinLock *lock);
- *
  *  \brief Unlock a spin lock by setting it to 0. Always returns immediately
  *
- * \param lock points to the lock.
- *
+ *  \param lock Points to the lock.
  */
 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
 
-/* 32 bit atomic operations */
+/*@}*//*SDL AtomicLock*/
 
 /**
- * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
- *
- * \brief Check to see if *ptr == 0 and set it to 1.
+ *  \name 32 bit atomic operations
+ */
+/*@{*/
+
+/**
+ *  \brief Check to see if \c *ptr == 0 and set it to 1.
  *  
- * \return SDL_True if the value pointed to by ptr was zero and
+ *  \return SDL_True if the value pointed to by \c ptr was zero and
  *          SDL_False if it was not zero
  *  
- * \param ptr points to the value to be tested and set.
- *
+ *  \param ptr Points to the value to be tested and set.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
 
 /**
- * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
- *
- * \brief set the value pointed to by ptr to be zero.
- *
- * \param ptr address of the value to be set to zero
+ *  \brief Set the value pointed to by \c ptr to be zero.
  *  
+ *  \param ptr Address of the value to be set to zero
  */
 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
 
 /**
- * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
- *
- * \brief fetch the current value of *ptr and then increment that
+ *  \brief Fetch the current value of \c *ptr and then increment that
  *         value in place.
  *  
- * \return the value before it was incremented.
- *
- * \param ptr address of the value to fetch and increment
+ *  \return The value before it was incremented.
  *  
+ *  \param ptr Address of the value to fetch and increment
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
 
 /**
- * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
- *
- * \brief fetch *ptr and then decrement the value in place.
- *
- * \return the value before it was decremented.
+ *  \brief Fetch \c *ptr and then decrement the value in place.
  *  
- * \param ptr address of the value to fetch and drement
+ *  \return The value before it was decremented.
  *  
+ *  \param ptr Address of the value to fetch and drement
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
 
 /**
- * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
+ *  \brief Fetch the current value at \c ptr and then add \c value to \c *ptr.
  *  
- * \brief fetch the current value at ptr and then add value to *ptr.
- *
- * \return *ptr before the addition took place.
- *
- * \param ptr the address of data we are changing.
- * \param value the value to add to *ptr. 
+ *  \return \c *ptr before the addition took place.
  *  
+ *  \param ptr The address of data we are changing.
+ *  \param value The value to add to \c *ptr. 
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
 
 /**
- * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
- *
- * \brief Fetch *ptr and then subtract value from it.
+ *  \brief Fetch \c *ptr and then subtract \c value from it.
  *  
- * \return *ptr before the subtraction took place.
- *
- * \param ptr the address of the data being changed.
- * \param value the value to subtract from *ptr.
+ *  \return \c *ptr before the subtraction took place.
  *  
+ *  \param ptr The address of the data being changed.
+ *  \param value The value to subtract from \c *ptr.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
 
 /**
- * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
- *
- * \brief Add one to the data pointed to by ptr and return that value.
+ *  \brief Add one to the data pointed to by \c ptr and return that value.
  *  
- * \return the incremented value.
- *
- * \param ptr address of the data to increment.
+ *  \return The incremented value.
  *  
+ *  \param ptr The address of the data to increment.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
 
 /**
- * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
- *
- * \brief Subtract one from data pointed to by ptr and return the new value.
+ *  \brief Subtract one from data pointed to by \c ptr and return the new value.
  *  
  *  \return The decremented value.
  *  
  *  \param ptr The address of the data to decrement.
- *
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
 
 /**
- * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
- *
- * \brief Add value to the data pointed to by ptr and return result.
+ *  \brief Add \c value to the data pointed to by \c ptr and return result.
  *  
- * \return The sum of *ptr and value.
+ *  \return The sum of \c *ptr and \c value.
  *  
  *  \param ptr The address of the data to be modified.
  *  \param value The value to be added.
- *
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
 
 /**
- * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
+ *  \brief Subtract \c value from the data pointed to by \c ptr and return the result.
  *  
- * \brief Subtract value from the data pointed to by ptr and return the result.
- *
- * \return the difference between *ptr and value.
+ *  \return The difference between \c *ptr and \c value.
  *  
  *  \param ptr The address of the data to be modified.
  *  \param value The value to be subtracted.
- *
  */
 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
 
-/* 64 bit atomic operations */
+/*@}*//*32 bit atomic operations*/
+
+/**
+ *  \name 64 bit atomic operations
+ */
+/*@{*/
 #ifdef SDL_HAS_64BIT_TYPE
 
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
@@ -227,6 +200,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, U
 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
 #endif /*  SDL_HAS_64BIT_TYPE */
 
+/*@}*//*64 bit atomic operations*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 /* *INDENT-OFF* */

include/SDL_audio.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_audio.h
  *  
- * Access to the raw audio mixing buffer for the SDL library
+ *  Access to the raw audio mixing buffer for the SDL library.
  */
 
 #ifndef _SDL_audio_h
@@ -44,33 +44,13 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-typedef Uint16 SDL_AudioFormat;
-
-/* The calculated values in this structure are calculated by SDL_OpenAudio() */
-typedef struct SDL_AudioSpec
-{
-    int freq;                   /* DSP frequency -- samples per second */
-    SDL_AudioFormat format;     /* Audio data format */
-    Uint8 channels;             /* Number of channels: 1 mono, 2 stereo */
-    Uint8 silence;              /* Audio buffer silence value (calculated) */
-    Uint16 samples;             /* Audio buffer size in samples (power of 2) */
-    Uint16 padding;             /* Necessary for some compile environments */
-    Uint32 size;                /* Audio buffer size in bytes (calculated) */
-    /* This function is called when the audio device needs more data.
-       'stream' is a pointer to the audio data buffer
-       'len' is the length of that buffer in bytes.
-       Once the callback returns, the buffer will no longer be valid.
-       Stereo samples are stored in a LRLRLR ordering.
-     */
-    void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
-    void *userdata;
-} SDL_AudioSpec;
-
-
-/*
- These are what the 16 bits in SDL_AudioFormat currently mean...
- (Unspecified bits are always zero.)
-
+/**
+ *  \brief Audio format flags.
+ *  
+ *  These are what the 16 bits in SDL_AudioFormat currently mean...
+ *  (Unspecified bits are always zero).
+ *  
+ *  \verbatim
     ++-----------------------sample is signed if set
     ||
     ||       ++-----------sample is bigendian if set
@@ -80,9 +60,16 @@ typedef struct SDL_AudioSpec
     ||       ||          || +---sample bit size---+
     ||       ||          || |                     |
     15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
+    \endverbatim
+ *  
+ *  There are macros in SDL 1.3 and later to query these bits.
+ */
+typedef Uint16 SDL_AudioFormat;
 
- There are macros in SDL 1.3 and later to query these bits.
-*/
+/**
+ *  \name Audio flags
+ */
+/*@{*/
 
 #define SDL_AUDIO_MASK_BITSIZE       (0xFF)
 #define SDL_AUDIO_MASK_DATATYPE      (1<<8)
@@ -96,27 +83,48 @@ typedef struct SDL_AudioSpec
 #define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
 #define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
 
-/* Audio format flags (defaults to LSB byte order) */
-#define AUDIO_U8	0x0008  /* Unsigned 8-bit samples */
-#define AUDIO_S8	0x8008  /* Signed 8-bit samples */
-#define AUDIO_U16LSB	0x0010  /* Unsigned 16-bit samples */
-#define AUDIO_S16LSB	0x8010  /* Signed 16-bit samples */
-#define AUDIO_U16MSB	0x1010  /* As above, but big-endian byte order */
-#define AUDIO_S16MSB	0x9010  /* As above, but big-endian byte order */
+/** 
+ *  \name Audio format flags
+ *
+ *  Defaults to LSB byte order.
+ */
+/*@{*/
+#define AUDIO_U8	0x0008  /**< Unsigned 8-bit samples */
+#define AUDIO_S8	0x8008  /**< Signed 8-bit samples */
+#define AUDIO_U16LSB	0x0010  /**< Unsigned 16-bit samples */
+#define AUDIO_S16LSB	0x8010  /**< Signed 16-bit samples */
+#define AUDIO_U16MSB	0x1010  /**< As above, but big-endian byte order */
+#define AUDIO_S16MSB	0x9010  /**< As above, but big-endian byte order */
 #define AUDIO_U16	AUDIO_U16LSB
 #define AUDIO_S16	AUDIO_S16LSB
+/*@}*/
 
-/* int32 support new to SDL 1.3 */
-#define AUDIO_S32LSB	0x8020  /* 32-bit integer samples */
-#define AUDIO_S32MSB	0x9020  /* As above, but big-endian byte order */
+/**
+ *  \name int32 support
+ *  
+ *  New to SDL 1.3.
+ */
+/*@{*/
+#define AUDIO_S32LSB	0x8020  /**< 32-bit integer samples */
+#define AUDIO_S32MSB	0x9020  /**< As above, but big-endian byte order */
 #define AUDIO_S32	AUDIO_S32LSB
+/*@}*/
 
-/* float32 support new to SDL 1.3 */
-#define AUDIO_F32LSB	0x8120  /* 32-bit floating point samples */
-#define AUDIO_F32MSB	0x9120  /* As above, but big-endian byte order */
+/**
+ *  \name float32 support
+ *  
+ *  New to SDL 1.3.
+ */
+/*@{*/
+#define AUDIO_F32LSB	0x8120  /**< 32-bit floating point samples */
+#define AUDIO_F32MSB	0x9120  /**< As above, but big-endian byte order */
 #define AUDIO_F32	AUDIO_F32LSB
+/*@}*/
 
-/* Native audio byte ordering */
+/**
+ *  \name Native audio byte ordering
+ */
+/*@{*/
 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
 #define AUDIO_U16SYS	AUDIO_U16LSB
 #define AUDIO_S16SYS	AUDIO_S16LSB
@@ -128,91 +136,140 @@ typedef struct SDL_AudioSpec
 #define AUDIO_S32SYS	AUDIO_S32MSB
 #define AUDIO_F32SYS	AUDIO_F32MSB
 #endif
+/*@}*/
 
-/* Which audio format changes are allowed when opening a device */
+/** 
+ *  \name Allow change flags
+ *  
+ *  Which audio format changes are allowed when opening a device.
+ */
+/*@{*/
 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
 #define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
+/*@}*/
+
+/*@}*//*Audio flags*/
+
+/**
+ *  The calculated values in this structure are calculated by SDL_OpenAudio().
+ */
+typedef struct SDL_AudioSpec
+{
+    int freq;                   /**< DSP frequency -- samples per second */
+    SDL_AudioFormat format;     /**< Audio data format */
+    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
+    Uint8 silence;              /**< Audio buffer silence value (calculated) */
+    Uint16 samples;             /**< Audio buffer size in samples (power of 2) */
+    Uint16 padding;             /**< Necessary for some compile environments */
+    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
+    /**
+     *  This function is called when the audio device needs more data.
+     *
+     *  \param stream A pointer to the audio data buffer.
+     *  \param len    The length of that buffer in bytes.
+     *
+     *  Once the callback returns, the buffer will no longer be valid.
+     *  Stereo samples are stored in a LRLRLR ordering.
+     */
+    void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
+    void *userdata;
+} SDL_AudioSpec;
+
 
-/* A structure to hold a set of audio conversion filters and buffers */
 struct SDL_AudioCVT;
 typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
                                           SDL_AudioFormat format);
 
+/**
+ *  A structure to hold a set of audio conversion filters and buffers.
+ */
 typedef struct SDL_AudioCVT
 {
-    int needed;                 /* Set to 1 if conversion possible */
-    SDL_AudioFormat src_format; /* Source audio format */
-    SDL_AudioFormat dst_format; /* Target audio format */
-    double rate_incr;           /* Rate conversion increment */
-    Uint8 *buf;                 /* Buffer to hold entire audio data */
-    int len;                    /* Length of original audio buffer */
-    int len_cvt;                /* Length of converted audio buffer */
-    int len_mult;               /* buffer must be len*len_mult big */
-    double len_ratio;           /* Given len, final size is len*len_ratio */
-    SDL_AudioFilter filters[10];        /* Filter list */
-    int filter_index;           /* Current audio conversion function */
+    int needed;                 /**< Set to 1 if conversion possible */
+    SDL_AudioFormat src_format; /**< Source audio format */
+    SDL_AudioFormat dst_format; /**< Target audio format */
+    double rate_incr;           /**< Rate conversion increment */
+    Uint8 *buf;                 /**< Buffer to hold entire audio data */
+    int len;                    /**< Length of original audio buffer */
+    int len_cvt;                /**< Length of converted audio buffer */
+    int len_mult;               /**< buffer must be len*len_mult big */
+    double len_ratio;           /**< Given len, final size is len*len_ratio */
+    SDL_AudioFilter filters[10];        /**< Filter list */
+    int filter_index;           /**< Current audio conversion function */
 } SDL_AudioCVT;
 
 
 /* Function prototypes */
 
-/* These functions return the list of built in audio drivers, in the
+/**
+ *  \name Driver discovery functions
+ *  
+ *  These functions return the list of built in audio drivers, in the
  *  order that they are normally initialized by default.
  */
+/*@{*/
 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
+/*@}*/
 
-/* These functions are used internally, and should not be used unless you
- * have a specific need to specify the audio driver you want to use.
- * You should normally use SDL_Init() or SDL_InitSubSystem().
+/**
+ *  \name Initialization and cleanup
+ *  
+ *  \internal These functions are used internally, and should not be used unless
+ *            you have a specific need to specify the audio driver you want to 
+ *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
  */
+/*@{*/
 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
+/*@}*/
 
-/* This function returns the name of the current audio driver, or NULL
+/**
+ *  This function returns the name of the current audio driver, or NULL
  *  if no driver has been initialized.
  */
 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
 
-/*
+/**
  *  This function opens the audio device with the desired parameters, and
  *  returns 0 if successful, placing the actual hardware parameters in the
- * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
+ *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
  *  data passed to the callback function will be guaranteed to be in the
  *  requested format, and will be automatically converted to the hardware
  *  audio format if necessary.  This function returns -1 if it failed 
  *  to open the audio device, or couldn't set up the audio thread.
  *  
  *  When filling in the desired audio spec structure,
- *  'desired->freq' should be the desired audio frequency in samples-per-second.
- *  'desired->format' should be the desired audio format.
- *  'desired->samples' is the desired size of the audio buffer, in samples.
- *     This number should be a power of two, and may be adjusted by the audio
- *     driver to a value more suitable for the hardware.  Good values seem to
- *     range between 512 and 8096 inclusive, depending on the application and
- *     CPU speed.  Smaller values yield faster response time, but can lead
- *     to underflow if the application is doing heavy processing and cannot
- *     fill the audio buffer in time.  A stereo sample consists of both right
- *     and left channels in LR ordering.
+ *    - \c desired->freq should be the desired audio frequency in samples-per-
+ *      second.
+ *    - \c desired->format should be the desired audio format.
+ *    - \c desired->samples is the desired size of the audio buffer, in 
+ *      samples.  This number should be a power of two, and may be adjusted by 
+ *      the audio driver to a value more suitable for the hardware.  Good values
+ *      seem to range between 512 and 8096 inclusive, depending on the 
+ *      application and CPU speed.  Smaller values yield faster response time, 
+ *      but can lead to underflow if the application is doing heavy processing 
+ *      and cannot fill the audio buffer in time.  A stereo sample consists of 
+ *      both right and left channels in LR ordering.
  *      Note that the number of samples is directly related to time by the
- *     following formula:  ms = (samples*1000)/freq
- *  'desired->size' is the size in bytes of the audio buffer, and is
+ *      following formula:  \code ms = (samples*1000)/freq \endcode
+ *    - \c desired->size is the size in bytes of the audio buffer, and is
  *      calculated by SDL_OpenAudio().
- *  'desired->silence' is the value used to set the buffer to silence,
+ *    - \c desired->silence is the value used to set the buffer to silence,
  *      and is calculated by SDL_OpenAudio().
- *  'desired->callback' should be set to a function that will be called
+ *    - \c desired->callback should be set to a function that will be called
  *      when the audio device is ready for more data.  It is passed a pointer
  *      to the audio buffer, and the length in bytes of the audio buffer.
  *      This function usually runs in a separate thread, and so you should
  *      protect data structures that it accesses by calling SDL_LockAudio()
  *      and SDL_UnlockAudio() in your code.
- *  'desired->userdata' is passed as the first parameter to your callback
+ *    - \c desired->userdata is passed as the first parameter to your callback
  *      function.
  *  
  *  The audio device starts out playing silence when it's opened, and should
- * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
+ *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
  *  for your audio callback function to be called.  Since the audio driver
  *  may modify the requested size of the audio buffer, you should allocate
  *  any local mixing buffers after you open the audio device.
@@ -220,8 +277,9 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
                                           SDL_AudioSpec * obtained);
 
-/*
+/**
  *  SDL Audio Device IDs.
+ *  
  *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
  *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
  *  always returns devices >= 2 on success. The legacy calls are good both
@@ -230,20 +288,21 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
  */
 typedef Uint32 SDL_AudioDeviceID;
 
-/*
+/**
  *  Get the number of available devices exposed by the current driver.
  *  Only valid after a successfully initializing the audio subsystem.
  *  Returns -1 if an explicit list of devices can't be determined; this is
  *  not an error. For example, if SDL is set up to talk to a remote audio
  *  server, it can't list every one available on the Internet, but it will
  *  still allow a specific host to be specified to SDL_OpenAudioDevice().
+ *  
  *  In many common cases, when this function returns a value <= 0, it can still
  *  successfully open the default device (NULL for first argument of
  *  SDL_OpenAudioDevice()).
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
 
-/*
+/**
  *  Get the human-readable name of a specific audio device.
  *  Must be a value between 0 and (number of audio devices-1).
  *  Only valid after a successfully initializing the audio subsystem.
@@ -260,14 +319,17 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
                                                            int iscapture);
 
 
-/*
+/**
  *  Open a specific audio device. Passing in a device name of NULL requests
  *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
- * The device name is a UTF-8 string reported by SDL_GetAudioDevice(), but
+ *  
+ *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
  *  some drivers allow arbitrary and driver-specific strings, such as a
  *  hostname/IP address for a remote audio server, or a filename in the
  *  diskaudio driver.
- * Returns 0 on error, a valid device ID that is >= 2 on success.
+ *  
+ *  \return 0 on error, a valid device ID that is >= 2 on success.
+ *  
  *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
  */
 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
@@ -283,9 +345,12 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
 
 
 
-/*
- * Get the current audio state:
+/**
+ *  \name Audio state
+ *  
+ *  Get the current audio state.
  */
+/*@{*/
 typedef enum
 {
     SDL_AUDIO_STOPPED = 0,
@@ -296,28 +361,35 @@ extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
 
 extern DECLSPEC SDL_audiostatus SDLCALL
 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
+/*@}*//*Audio State*/
 
-/*
- * This function pauses and unpauses the audio callback processing.
- * It should be called with a parameter of 0 after opening the audio
+/**
+ *  \name Pause audio functions
+ *  
+ *  These functions pause and unpause the audio callback processing.
+ *  They should be called with a parameter of 0 after opening the audio
  *  device to start playing sound.  This is so you can safely initialize
  *  data for your callback function after opening the audio device.
  *  Silence will be written to the audio device during the pause.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
                                                   int pause_on);
+/*@}*//*Pause audio functions*/
 
-/*
+/**
  *  This function loads a WAVE from the data source, automatically freeing
- * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
+ *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
  *  you could do:
+ *  \code
  *  	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
+ *  \endcode
  *
  *  If this function succeeds, it returns the given SDL_AudioSpec,
  *  filled with the audio data format of the wave data, and sets
- * 'audio_buf' to a malloc()'d buffer containing the audio data,
- * and sets 'audio_len' to the length of that audio buffer, in bytes.
+ *  \c *audio_buf to a malloc()'d buffer containing the audio data,
+ *  and sets \c *audio_len to the length of that audio buffer, in bytes.
  *  You need to free the audio buffer with SDL_FreeWAV() when you are 
  *  done with it.
  *
@@ -331,21 +403,25 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
                                                       Uint8 ** audio_buf,
                                                       Uint32 * audio_len);
 
-/* Compatibility convenience function -- loads a WAV from a file */
+/** 
+ *  Loads a WAV from a file.
+ *  Compatibility convenience function.
+ */
 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
 	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
 
-/*
+/**
  *  This function frees data previously allocated with SDL_LoadWAV_RW()
  */
 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
 
-/*
+/**
  *  This function takes a source format and rate and a destination format
- * and rate, and initializes the 'cvt' structure with information needed
+ *  and rate, and initializes the \c cvt structure with information needed
  *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
  *  to the other.
- * Returns -1 if the format conversion is not supported, 0 if there's
+ *  
+ *  \return -1 if the format conversion is not supported, 0 if there's
  *  no conversion needed, or 1 if the audio filter is set up.
  */
 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
@@ -356,29 +432,31 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
                                               Uint8 dst_channels,
                                               int dst_rate);
 
-/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
- * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
+/**
+ *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
+ *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
  *  audio data in the source format, this function will convert it in-place
  *  to the desired format.
+ *  
  *  The data conversion may expand the size of the audio data, so the buffer
- * cvt->buf should be allocated after the cvt structure is initialized by
- * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long.
+ *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
+ *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
  */
 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
 
-/*
+#define SDL_MIX_MAXVOLUME 128
+/**
  *  This takes two audio buffers of the playing audio format and mixes
  *  them, performing addition, volume adjustment, and overflow clipping.
- * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
  *  for full audio volume.  Note this does not change hardware volume.
  *  This is provided for convenience -- you can mix your own audio data.
  */
-#define SDL_MIX_MAXVOLUME 128
 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
                                           Uint32 len, int volume);
 
-/*
- * This works like SDL_MixAudio, but you specify the audio format instead of
+/**
+ *  This works like SDL_MixAudio(), but you specify the audio format instead of
  *  using the format of audio device 1. Thus it can be used when no audio
  *  device is open at all.
  */
@@ -387,25 +465,29 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
                                                 SDL_AudioFormat format,
                                                 Uint32 len, int volume);
 
-/*
+/**
+ *  \name Audio lock functions
+ *  
  *  The lock manipulated by these functions protects the callback function.
- * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
- * callback function is not running.  Do not call these from the callback
+ *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that 
+ *  the callback function is not running.  Do not call these from the callback
  *  function or you will cause deadlock.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
+/*@}*//*Audio lock functions*/
 
-/*
+/**
  *  This function shuts down audio processing and closes the audio device.
  */
 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
 
-/*
- * Returns 1 if audio device is still functioning, zero if not, -1 on error.
+/**
+ * \return 1 if audio device is still functioning, zero if not, -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
 

include/SDL_compat.h

@@ -20,13 +20,26 @@
     slouken@libsdl.org
 */
 
-/* This file contains functions for backwards compatibility with SDL 1.2 */
+ /**
+ *  \defgroup Compatibility SDL 1.2 Compatibility API
+ */
+/*@{*/
 
-/* 
-   #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
-   SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
-   SDL 1.3/2.0
-*/
+/**
+ *  \file SDL_compat.h
+ *
+ *  This file contains functions for backwards compatibility with SDL 1.2.
+ */
+
+/**
+ *  \def SDL_NO_COMPAT
+ *
+ *  #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
+ *  SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
+ *  SDL 1.3/2.0.
+ */
+
+ /*@}*/
 
 #ifdef SDL_NO_COMPAT
 #define _SDL_compat_h
@@ -46,7 +59,16 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-#define SDL_SWSURFACE       0x00000000  /* Not used */
+/**
+ *  \addtogroup Compatibility
+ */
+/*@{*/
+
+/**
+ *  \name Surface flags
+ */
+/*@{*/
+#define SDL_SWSURFACE       0x00000000  /**< \note Not used */
 #define SDL_SRCALPHA        0x00010000
 #define SDL_SRCCOLORKEY     0x00020000
 #define SDL_ANYFORMAT       0x00100000
@@ -56,10 +78,11 @@ extern "C" {
 #define SDL_RESIZABLE       0x01000000
 #define SDL_NOFRAME         0x02000000
 #define SDL_OPENGL          0x04000000
-#define SDL_HWSURFACE       0x08000001  /* Not used */
-#define SDL_ASYNCBLIT       0x08000000  /* Not used */
-#define SDL_RLEACCELOK      0x08000000  /* Not used */
-#define SDL_HWACCEL         0x08000000  /* Not used */
+#define SDL_HWSURFACE       0x08000001  /**< \note Not used */
+#define SDL_ASYNCBLIT       0x08000000  /**< \note Not used */
+#define SDL_RLEACCELOK      0x08000000  /**< \note Not used */
+#define SDL_HWACCEL         0x08000000  /**< \note Not used */
+/*@}*//*Surface flags*/
 
 #define SDL_APPMOUSEFOCUS	0x01
 #define SDL_APPINPUTFOCUS	0x02
@@ -103,35 +126,51 @@ typedef struct SDL_VideoInfo
     int current_h;
 } SDL_VideoInfo;
 
-/* The most common video overlay formats.
-   For an explanation of these pixel formats, see:
-   http://www.webartz.com/fourcc/indexyuv.htm
-
-   For information on the relationship between color spaces, see:
-   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
+/**
+ *  \name Overlay formats
+ *
+ *  The most common video overlay formats.
+ *  
+ *  For an explanation of these pixel formats, see:
+ *  http://www.webartz.com/fourcc/indexyuv.htm
+ *  
+ *  For information on the relationship between color spaces, see:
+ *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
+ */
+/*@{*/
+#define SDL_YV12_OVERLAY  0x32315659    /**< Planar mode: Y + V + U  (3 planes) */
+#define SDL_IYUV_OVERLAY  0x56555949    /**< Planar mode: Y + U + V  (3 planes) */
+#define SDL_YUY2_OVERLAY  0x32595559    /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
+#define SDL_UYVY_OVERLAY  0x59565955    /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
+#define SDL_YVYU_OVERLAY  0x55595659    /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
+/*@}*//*Overlay formats*/
+
+/**
+ *  The YUV hardware video overlay.
  */
-#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
-#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
-#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
-#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
-#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
-
-/* The YUV hardware video overlay */
 typedef struct SDL_Overlay
 {
-    Uint32 format;              /* Read-only */
-    int w, h;                   /* Read-only */
-    int planes;                 /* Read-only */
-    Uint16 *pitches;            /* Read-only */
-    Uint8 **pixels;             /* Read-write */
-
-    /* Hardware-specific surface info */
+    Uint32 format;              /**< Read-only */
+    int w, h;                   /**< Read-only */
+    int planes;                 /**< Read-only */
+    Uint16 *pitches;            /**< Read-only */
+    Uint8 **pixels;             /**< Read-write */
+
+    /** 
+     *  \name Hardware-specific surface info
+     */
+    /*@{*/
     struct private_yuvhwfuncs *hwfuncs;
     struct private_yuvhwdata *hwdata;
+    /*@}*//*Hardware-specific surface info*/
 
-    /* Special flags */
-    Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
+    /** 
+     *  \name Special flags
+     */
+    /*@{*/
+    Uint32 hw_overlay:1;        /**< Flag: This overlay hardware accelerated? */
     Uint32 UnusedBits:31;
+    /*@}*//*Special flags*/
 } SDL_Overlay;
 
 typedef enum
@@ -143,9 +182,17 @@ typedef enum
 
 struct SDL_SysWMinfo;
 
-/* Obsolete or renamed key codes */
+/**
+ *  \name Obsolete or renamed key codes
+ */
+/*@{*/
 
-/* These key constants were renamed for clarity or consistency. */
+/** 
+ *  \name Renamed keys
+ *
+ *  These key constants were renamed for clarity or consistency. 
+ */
+/*@{*/
 #define SDLK_0	'0'
 #define SDLK_1	'1'
 #define SDLK_2	'2'
@@ -214,19 +261,35 @@ struct SDL_SysWMinfo;
 #define SDLK_NUMLOCK SDLK_NUMLOCKCLEAR
 #define SDLK_SCROLLOCK SDLK_SCROLLLOCK
 #define SDLK_PRINT SDLK_PRINTSCREEN
+/*@}*//*Renamed keys*/
 
-/* The META modifier is equivalent to the GUI modifier from the USB standard */
+/**
+ *  \name META modifier
+ *  
+ *  The META modifier is equivalent to the GUI modifier from the USB standard.
+ */
+/*@{*/
 #define KMOD_LMETA KMOD_LGUI
 #define KMOD_RMETA KMOD_RGUI
 #define KMOD_META KMOD_GUI
-
-/* These keys don't appear in the USB specification (or at least not under those names). I'm unsure if the following assignments make sense or if these codes should be defined as actual additional SDLK_ constants. */
+/*@}*//*META modifier*/
+
+/** 
+ *  \name Not in USB
+ *
+ *  These keys don't appear in the USB specification (or at least not under 
+ *  those names). I'm unsure if the following assignments make sense or if these
+ *  codes should be defined as actual additional SDLK_ constants.
+ */
+/*@{*/
 #define SDLK_LSUPER SDLK_LMETA
 #define SDLK_RSUPER SDLK_RMETA
 #define SDLK_COMPOSE SDLK_APPLICATION
 #define SDLK_BREAK SDLK_STOP
 #define SDLK_EURO SDLK_2
+/*@}*//*Not in USB*/
 
+/*@}*//*Obsolete or renamed key codes*/
 
 #define SDL_SetModuleHandle(x)
 #define SDL_AllocSurface    SDL_CreateRGBSurface
@@ -287,6 +350,8 @@ extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
 
+/*@}*//*Compatibility*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 /* *INDENT-OFF* */

include/SDL_config.h.default

@@ -25,7 +25,13 @@
 
 #include "SDL_platform.h"
 
-/* Add any platform that doesn't build using the configure system */
+/**
+ *  \file SDL_config.h.default
+ *
+ *  SDL_config.h for any platform that doesn't build using the configure system.
+ */
+ 
+/* Add any platform that doesn't build using the configure system. */
 #if defined(__NINTENDODS__)
 #include "SDL_config_nintendods.h"
 #elif defined(__IPHONEOS__) 

include/SDL_config.h.in

@@ -23,7 +23,11 @@
 #ifndef _SDL_config_h
 #define _SDL_config_h
 
-/* This is a set of defines to configure the SDL features */
+/**
+ *  \file SDL_config.h.in
+ *
+ *  This is a set of defines to configure the SDL features
+ */
 
 /* General platform specific identifiers */
 #include "SDL_platform.h"

include/SDL_config_minimal.h

@@ -25,7 +25,11 @@
 
 #include "SDL_platform.h"
 
-/* This is the minimal configuration that can be used to build SDL */
+/**
+ *  \file SDL_config_minimal.h
+ *  
+ *  This is the minimal configuration that can be used to build SDL.
+ */
 
 #include <stdarg.h>
 

include/SDL_cpuinfo.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_cpuinfo.h
  *  
- * CPU feature detection for SDL
+ *  CPU feature detection for SDL.
  */
 
 #ifndef _SDL_cpuinfo_h
@@ -39,35 +39,43 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* This function returns true if the CPU has the RDTSC instruction
+/**
+ *  This function returns true if the CPU has the RDTSC instruction.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
 
-/* This function returns true if the CPU has MMX features
+/**
+ *  This function returns true if the CPU has MMX features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
 
-/* This function returns true if the CPU has MMX Ext. features
+/**
+ *  This function returns true if the CPU has MMX Ext.\ features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMXExt(void);
 
-/* This function returns true if the CPU has 3DNow features
+/**
+ *  This function returns true if the CPU has 3DNow!\ features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
 
-/* This function returns true if the CPU has 3DNow! Ext. features
+/**
+ *  This function returns true if the CPU has 3DNow!\ Ext.\ features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNowExt(void);
 
-/* This function returns true if the CPU has SSE features
+/**
+ *  This function returns true if the CPU has SSE features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
 
-/* This function returns true if the CPU has SSE2 features
+/**
+ *  This function returns true if the CPU has SSE2 features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
 
-/* This function returns true if the CPU has AltiVec features
+/**
+ *  This function returns true if the CPU has AltiVec features.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
 

include/SDL_endian.h

@@ -31,9 +31,13 @@
 
 #include "SDL_stdinc.h"
 
-/* The two types of endianness */
+/**
+ *  \name The two types of endianness
+ */
+/*@{*/
 #define SDL_LIL_ENDIAN	1234
 #define SDL_BIG_ENDIAN	4321
+/*@}*/
 
 #ifndef SDL_BYTEORDER           /* Not defined in SDL_config.h? */
 #if defined(__hppa__) || \
@@ -56,11 +60,14 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* Use inline functions for compilers that support them, and static
-   functions for those that do not.  Because these functions become
-   static for compilers that do not support inline functions, this
-   header should only be included in files that actually use them.
-*/
+/**
+ *  \file SDL_endian.h
+ *  
+ *  Uses inline functions for compilers that support them, and static
+ *  functions for those that do not.  Because these functions become
+ *  static for compilers that do not support inline functions, this
+ *  header should only be included in files that actually use them.
+ */
 #if defined(__GNUC__) && defined(__i386__) && \
    !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
 static __inline__ Uint16
@@ -184,10 +191,11 @@ SDL_Swap64(Uint64 x)
 }
 #endif
 #else
-/* This is mainly to keep compilers from complaining in SDL code.
-   If there is no real 64-bit datatype, then compilers will complain about
-   the fake 64-bit datatype that SDL provides when it compiles user code.
-*/
+/**
+ *  This is mainly to keep compilers from complaining in SDL code.
+ *  If there is no real 64-bit datatype, then compilers will complain about
+ *  the fake 64-bit datatype that SDL provides when it compiles user code.
+ */
 #define SDL_Swap64(X)	(X)
 #endif /* SDL_HAS_64BIT_TYPE */
 
@@ -206,7 +214,11 @@ SDL_SwapFloat(float x)
 }
 
 
-/* Byteswap item from the specified endianness to the native endianness */
+/**
+ *  \name Swap to native
+ *  Byteswap item from the specified endianness to the native endianness.
+ */
+/*@{*/
 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
 #define SDL_SwapLE16(X)	(X)
 #define SDL_SwapLE32(X)	(X)
@@ -226,6 +238,7 @@ SDL_SwapFloat(float x)
 #define SDL_SwapBE64(X)	(X)
 #define SDL_SwapFloatBE(X)	(X)
 #endif
+/*@}*//*Swap to native*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_error.h

@@ -22,7 +22,8 @@
 
 /**
  *  \file SDL_error.h
- * Simple error message routines for SDL
+ *  
+ *  Simple error message routines for SDL.
  */
 
 #ifndef _SDL_error_h
@@ -43,7 +44,13 @@ extern DECLSPEC void SDLCALL SDL_SetError(const char *fmt, ...);
 extern DECLSPEC char *SDLCALL SDL_GetError(void);
 extern DECLSPEC void SDLCALL SDL_ClearError(void);
 
-/* Private error message function - used internally */
+/**
+ *  \name Internal error functions
+ *  
+ *  \internal 
+ *  Private error message function - used internally.
+ */
+/*@{*/
 #define SDL_OutOfMemory()	SDL_Error(SDL_ENOMEM)
 #define SDL_Unsupported()	SDL_Error(SDL_UNSUPPORTED)
 typedef enum
@@ -56,7 +63,7 @@ typedef enum
     SDL_LASTERROR
 } SDL_errorcode;
 extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
-
+/*@}*//*Internal error functions*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_events.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_events.h
  *  
- * Include file for SDL event handling
+ *  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.*)
  */
 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.*)
  */
 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.*)
  */
-#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.*)
  */
-#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.*)
  */
 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.*)
  */
 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.*)
  */
 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.*)
  */
 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.*)
  */
 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.*)
  */
 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.*)
  */
 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
  */
 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.*)
  */
 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_SysWMmsg;
+typedef struct SDL_SysWMmsg SDL_SysWMmsg;
+
 /**
- * \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
+ *  \note 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
 {
-    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,11 +336,12 @@ typedef struct SDL_ResizeEvent
     int w;
     int h;
 } SDL_ResizeEvent;
+/*@}*/
+
+/*@}*//*Compatibility*/
 #endif
 
 /**
- * \union SDL_Event
- *
  *  \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

include/SDL_haptic.h

@@ -27,18 +27,17 @@
  *         devices.
  *  
  *  The basic usage is as follows:
- *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
+ *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
  *   - Open a Haptic Device.
- *     - SDL_HapticOpen(...) to open from index.
- *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
- *   - Create an effect (SDL_HapticEffect).
- *   - Upload the effect with SDL_HapticNewEffect(...).
- *   - Run the effect with SDL_HapticRunEffect(...).
- *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
- *   - Close the haptic device with SDL_HapticClose(...).
- *
- * Example:
- *
+ *    - SDL_HapticOpen() to open from index.
+ *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
+ *   - Create an effect (::SDL_HapticEffect).
+ *   - Upload the effect with SDL_HapticNewEffect().
+ *   - Run the effect with SDL_HapticRunEffect().
+ *   - (optional) Free the effect with SDL_HapticDestroyEffect().
+ *   - Close the haptic device with SDL_HapticClose().
+ *
+ * \par Example:
  * \code
  * int test_haptic( SDL_Joystick * joystick ) {
  *    SDL_Haptic *haptic;
@@ -82,7 +81,6 @@
  *    return 0; // Success
  * }
  * \endcode
- *
  * \author Edgar Simo Serra
  */
 
@@ -114,178 +112,203 @@ struct _SDL_Haptic;
 typedef struct _SDL_Haptic SDL_Haptic;
 
 
-/*
+/**
+ *  \name Haptic features
+ *  
  *  Different haptic features a device can have.
  */
+/*@{*/
+
+/**
+ *  \name Haptic effects
+ */
+/*@{*/
+
 /**
- * \def SDL_HAPTIC_CONSTANT
+ *  \brief Constant effect supported.
  *
- * \brief Constant haptic effect.
+ *  Constant haptic effect.
  *  
  *  \sa SDL_HapticCondition
  */
-#define SDL_HAPTIC_CONSTANT   (1<<0)    /* Constant effect supported */
+#define SDL_HAPTIC_CONSTANT   (1<<0)
+
 /**
- * \def SDL_HAPTIC_SINE
+ *  \brief Sine wave effect supported.
  *  
- * \brief Periodic haptic effect that simulates sine waves.
+ *  Periodic haptic effect that simulates sine waves.
  *  
  *  \sa SDL_HapticPeriodic
  */
-#define SDL_HAPTIC_SINE       (1<<1)    /* Sine wave effect supported */
+#define SDL_HAPTIC_SINE       (1<<1)
+
 /**
- * \def SDL_HAPTIC_SQUARE
+ *  \brief Square wave effect supported.
  *  
- * \brief Periodic haptic effect that simulates square waves.
+ *  Periodic haptic effect that simulates square waves.
  * 
  *  \sa SDL_HapticPeriodic
  */
-#define SDL_HAPTIC_SQUARE     (1<<2)    /* Square wave effect supported */
+#define SDL_HAPTIC_SQUARE     (1<<2)
+
 /**
- * \def SDL_HAPTIC_TRIANGLE
+ *  \brief Triangle wave effect supported.
  *  
- * \brief Periodic haptic effect that simulates triangular waves.
+ *  Periodic haptic effect that simulates triangular waves.
  *  
  *  \sa SDL_HapticPeriodic
  */
-#define SDL_HAPTIC_TRIANGLE   (1<<3)    /* Triangle wave effect supported */
+#define SDL_HAPTIC_TRIANGLE   (1<<3)
+
 /**
- * \def SDL_HAPTIC_SAWTOOTHUP
+ *  \brief Sawtoothup wave effect supported.
  *  
- * \brief Periodic haptic effect that simulates saw tooth up waves.
+ *  Periodic haptic effect that simulates saw tooth up waves.
  *  
  *  \sa SDL_HapticPeriodic
  */
-#define SDL_HAPTIC_SAWTOOTHUP (1<<4)    /* Sawtoothup wave effect supported */
+#define SDL_HAPTIC_SAWTOOTHUP (1<<4)
+
 /**
- * \def SDL_HAPTIC_SAWTOOTHDOWN
+ *  \brief Sawtoothdown wave effect supported.
  *  
- * \brief Periodic haptic effect that simulates saw tooth down waves.
+ *  Periodic haptic effect that simulates saw tooth down waves.
  *  
  *  \sa SDL_HapticPeriodic
  */
-#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)  /* Sawtoothdown wave effect supported */
+#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
+
 /**
- * \def SDL_HAPTIC_RAMP
+ *  \brief Ramp effect supported.
  *  
- * \brief Ramp haptic effect.
+ *  Ramp haptic effect.
  *  
  *  \sa SDL_HapticRamp
  */
-#define SDL_HAPTIC_RAMP       (1<<6)    /* Ramp effect supported */
+#define SDL_HAPTIC_RAMP       (1<<6)
+
 /**
- * \def SDL_HAPTIC_SPRING
+ *  \brief Spring effect supported - uses axes position.
  *  
- * \brief Condition haptic effect that simulates a spring.  Effect is based on the
+ *  Condition haptic effect that simulates a spring.  Effect is based on the
  *  axes position.
  *
  *  \sa SDL_HapticCondition
  */
-#define SDL_HAPTIC_SPRING     (1<<7)    /* Spring effect supported - uses axes position */
+#define SDL_HAPTIC_SPRING     (1<<7)
+
 /**
- * \def SDL_HAPTIC_DAMPER
+ *  \brief Damper effect supported - uses axes velocity.
  *  
- * \brief Condition haptic effect that simulates dampening.  Effect is based on the
+ *  Condition haptic effect that simulates dampening.  Effect is based on the
  *  axes velocity.
  *  
  *  \sa SDL_HapticCondition
  */
-#define SDL_HAPTIC_DAMPER     (1<<8)    /* Damper effect supported - uses axes velocity */
+#define SDL_HAPTIC_DAMPER     (1<<8)
+
 /**
- * \def SDL_HAPTIC_INERTIA
+ *  \brief Inertia effect supported - uses axes acceleration.
  *  
- * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
+ *  Condition haptic effect that simulates inertia.  Effect is based on the axes
  *  acceleration.
  *
  *  \sa SDL_HapticCondition
  */
-#define SDL_HAPTIC_INERTIA    (1<<9)    /* Inertia effect supported - uses axes acceleration */
+#define SDL_HAPTIC_INERTIA    (1<<9)
+
 /**
- * \def SDL_HAPTIC_FRICTION
+ *  \brief Friction effect supported - uses axes movement.
  *  
- * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
- * movement.
+ *  Condition haptic effect that simulates friction.  Effect is based on the 
+ *  axes movement.
  *  
  *  \sa SDL_HapticCondition
  */
-#define SDL_HAPTIC_FRICTION   (1<<10)   /* Friction effect supported - uses axes movement */
+#define SDL_HAPTIC_FRICTION   (1<<10)
+
 /**
- * \def SDL_HAPTIC_CUSTOM
+ *  \brief Custom effect is supported.
  *  
- * \brief User defined custom haptic effect.
+ *  User defined custom haptic effect.
  */
-#define SDL_HAPTIC_CUSTOM     (1<<11)   /* Custom effect is supported */
-/* These last two are features the device has, not effects */
+#define SDL_HAPTIC_CUSTOM     (1<<11)
+
+/*@}*//*Haptic effects*/
+
+/* These last few are features the device has, not effects */
+
 /**
- * \def SDL_HAPTIC_GAIN
+ *  \brief Device can set global gain.
  *  
- * \brief Device supports setting the global gain.
+ *  Device supports setting the global gain.
  *  
  *  \sa SDL_HapticSetGain
  */
-#define SDL_HAPTIC_GAIN       (1<<12)   /* Device can set global gain */
+#define SDL_HAPTIC_GAIN       (1<<12)
+
 /**
- * \def SDL_HAPTIC_AUTOCENTER
+ *  \brief Device can set autocenter.
  *  
- * \brief Device supports setting autocenter.
+ *  Device supports setting autocenter.
  *  
  *  \sa SDL_HapticSetAutocenter
  */
-#define SDL_HAPTIC_AUTOCENTER (1<<13)   /* Device can set autocenter */
+#define SDL_HAPTIC_AUTOCENTER (1<<13)
+
 /**
- * \def SDL_HAPTIC_STATUS
- *
  *  \brief Device can be queried for effect status.
  *  
+ *  Device can be queried for effect status.
+ *  
  *  \sa SDL_HapticGetEffectStatus
  */
-#define SDL_HAPTIC_STATUS     (1<<14)   /* Device can be queried for effect status */
+#define SDL_HAPTIC_STATUS     (1<<14)
+
 /**
- * \def SDL_HAPTIC_PAUSE
- *
  *  \brief Device can be paused.
  *  
  *  \sa SDL_HapticPause
  *  \sa SDL_HapticUnpause
  */
-#define SDL_HAPTIC_PAUSE      (1<<15)   /* Device can be paused. */
+#define SDL_HAPTIC_PAUSE      (1<<15)
 
 
-/*
- * Direction encodings
+/**
+ * \name Direction encodings
  */
+/*@{*/
+
 /**
- * \def SDL_HAPTIC_POLAR
- *
  *  \brief Uses polar coordinates for the direction.
  *  
  *  \sa SDL_HapticDirection
  */
 #define SDL_HAPTIC_POLAR      0
+
 /**
- * \def SDL_HAPTIC_CARTESIAN
- *
  *  \brief Uses cartesian coordinates for the direction.
  *  
  *  \sa SDL_HapticDirection
  */
 #define SDL_HAPTIC_CARTESIAN  1
+
 /**
- * \def SDL_HAPTIC_SPHERICAL
- *
  *  \brief Uses spherical coordinates for the direction.
  *  
  *  \sa SDL_HapticDirection
  */
 #define SDL_HAPTIC_SPHERICAL  2
 
+/*@}*//*Direction encodings*/
+
+/*@}*//*Haptic features*/
 
 /*
  * Misc defines.
  */
+
 /**
- * \def SDL_HAPTIC_INFINITY
- *
  * \brief Used to play a device an infinite number of times.
  *
  * \sa SDL_HapticRunEffect
@@ -294,70 +317,69 @@ typedef struct _SDL_Haptic SDL_Haptic;
 
 
 /**
- * \struct SDL_HapticDirection
- *
  *  \brief Structure that represents a haptic direction.
  *  
  *  Directions can be specified by:
- *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
- *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
- *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
+ *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
+ *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
+ *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
  *
  *  Cardinal directions of the haptic device are relative to the positioning
  *  of the device.  North is considered to be away from the user.
  *
  *  The following diagram represents the cardinal directions:
- * \code
- *              .--.
- *              |__| .-------.
- *              |=.| |.-----.|
- *              |--| ||     ||
- *              |  | |'-----'|
- *              |__|~')_____('
- *                [ COMPUTER ]
- *
- *
- *                  North (0,-1)
- *                      ^
- *                      |
- *                      |
- * (1,0)  West <----[ HAPTIC ]----> East (-1,0)
- *                      |
- *                      |
- *                      v
- *                   South (0,1)
- *
- *
- *                   [ USER ]
- *                     \|||/
- *                     (o o)
- *               ---ooO-(_)-Ooo---
- * \endcode
- *
- * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
- *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
- *  the first dir parameter.  The cardinal directions would be:
+ *  \verbatim
+                 .--.
+                 |__| .-------.
+                 |=.| |.-----.|
+                 |--| ||     ||
+                 |  | |'-----'|
+                 |__|~')_____('
+                   [ COMPUTER ]
+    
+    
+                     North (0,-1)
+                         ^
+                         |
+                         |
+    (1,0)  West <----[ HAPTIC ]----> East (-1,0)
+                         |
+                         |
+                         v
+                      South (0,1)
+    
+    
+                      [ USER ]
+                        \|||/
+                        (o o)
+                  ---ooO-(_)-Ooo---
+    \endverbatim
+ *  
+ *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
+ *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
+ *  the first \c dir parameter.  The cardinal directions would be:
  *   - North: 0 (0 degrees)
  *   - East: 9000 (90 degrees)
  *   - South: 18000 (180 degrees)
  *   - West: 27000 (270 degrees)
  *  
- * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
- *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
- *  the first three dir parameters.  The cardinal directions would be:
+ *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
+ *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
+ *  the first three \c dir parameters.  The cardinal directions would be:
  *   - North:  0,-1, 0
  *   - East:  -1, 0, 0
  *   - South:  0, 1, 0
  *   - West:   1, 0, 0
+ *  
  *  The Z axis represents the height of the effect if supported, otherwise
- *  it's unused.  In cartesian encoding (1,2) would be the same as (2,4), you
+ *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
  *  can use any multiple you want, only the direction matters.
  *  
- * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
- *  The first two  dir parameters are used.  The dir parameters are as follows
- *  (all values are in hundredths of degrees):
- *    1) Degrees from (1, 0) rotated towards (0, 1).
- *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
+ *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
+ *  The first two \c dir parameters are used.  The \c dir parameters are as 
+ *  follows (all values are in hundredths of degrees):
+ *   - Degrees from (1, 0) rotated towards (0, 1).
+ *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
  *
  *
  *  Example of force coming from the south with all encodings (force coming
@@ -394,11 +416,9 @@ typedef struct SDL_HapticDirection
 
 
 /**
- * \struct SDL_HapticConstant
- *
  *  \brief A structure containing a template for a Constant effect.
  *  
- * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
+ *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
  *  
  *  A constant effect applies a constant force in the specified direction
  *  to the joystick.
@@ -409,7 +429,7 @@ typedef struct SDL_HapticDirection
 typedef struct SDL_HapticConstant
 {
     /* Header */
-    Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
+    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
     SDL_HapticDirection direction;  /**< Direction of the effect. */
 
     /* Replay */
@@ -429,17 +449,16 @@ typedef struct SDL_HapticConstant
     Uint16 fade_length;     /**< Duration of the fade. */
     Uint16 fade_level;      /**< Level at the end of the fade. */
 } SDL_HapticConstant;
+
 /**
- * \struct SDL_HapticPeriodic
- *
  *  \brief A structure containing a template for a Periodic effect.
  *  
  *  The struct handles the following effects:
- *   - SDL_HAPTIC_SINE
- *   - SDL_HAPTIC_SQUARE
- *   - SDL_HAPTIC_TRIANGLE
- *   - SDL_HAPTIC_SAWTOOTHUP
- *   - SDL_HAPTIC_SAWTOOTHDOWN
+ *   - ::SDL_HAPTIC_SINE
+ *   - ::SDL_HAPTIC_SQUARE
+ *   - ::SDL_HAPTIC_TRIANGLE
+ *   - ::SDL_HAPTIC_SAWTOOTHUP
+ *   - ::SDL_HAPTIC_SAWTOOTHDOWN
  *  
  *  A periodic effect consists in a wave-shaped effect that repeats itself
  *  over time.  The type determines the shape of the wave and the parameters
@@ -454,32 +473,32 @@ typedef struct SDL_HapticConstant
  *   - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
  *
  *  Examples:
- * \code
- * SDL_HAPTIC_SINE
- *   __      __      __      __
- *  /  \    /  \    /  \    /
- * /    \__/    \__/    \__/
- *
- * SDL_HAPTIC_SQUARE
- *  __    __    __    __    __
- * |  |  |  |  |  |  |  |  |  |
- * |  |__|  |__|  |__|  |__|  |
- *
- * SDL_HAPTIC_TRIANGLE
- *   /\    /\    /\    /\    /\
- *  /  \  /  \  /  \  /  \  /
- * /    \/    \/    \/    \/
- *
- * SDL_HAPTIC_SAWTOOTHUP
- *   /|  /|  /|  /|  /|  /|  /|
- *  / | / | / | / | / | / | / |
- * /  |/  |/  |/  |/  |/  |/  |
- *
- * SDL_HAPTIC_SAWTOOTHDOWN
- * \  |\  |\  |\  |\  |\  |\  |
- *  \ | \ | \ | \ | \ | \ | \ |
- *   \|  \|  \|  \|  \|  \|  \|
- * \endcode
+ *  \verbatim
+    SDL_HAPTIC_SINE
+      __      __      __      __
+     /  \    /  \    /  \    /
+    /    \__/    \__/    \__/
+    
+    SDL_HAPTIC_SQUARE
+     __    __    __    __    __
+    |  |  |  |  |  |  |  |  |  |
+    |  |__|  |__|  |__|  |__|  |
+    
+    SDL_HAPTIC_TRIANGLE
+      /\    /\    /\    /\    /\
+     /  \  /  \  /  \  /  \  /
+    /    \/    \/    \/    \/
+    
+    SDL_HAPTIC_SAWTOOTHUP
+      /|  /|  /|  /|  /|  /|  /|
+     / | / | / | / | / | / | / |
+    /  |/  |/  |/  |/  |/  |/  |
+    
+    SDL_HAPTIC_SAWTOOTHDOWN
+    \  |\  |\  |\  |\  |\  |\  |
+     \ | \ | \ | \ | \ | \ | \ |
+      \|  \|  \|  \|  \|  \|  \|
+    \endverbatim
  *  
  *  \sa SDL_HAPTIC_SINE
  *  \sa SDL_HAPTIC_SQUARE
@@ -491,9 +510,9 @@ typedef struct SDL_HapticConstant
 typedef struct SDL_HapticPeriodic
 {
     /* Header */
-    Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
-                             SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
-                             SDL_HAPTIC_SAWTOOTHDOWN */
+    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE,
+                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
+                             ::SDL_HAPTIC_SAWTOOTHDOWN */
     SDL_HapticDirection direction;  /**< Direction of the effect. */
 
     /* Replay */
@@ -516,23 +535,22 @@ typedef struct SDL_HapticPeriodic
     Uint16 fade_length; /**< Duration of the fade. */
     Uint16 fade_level;  /**< Level at the end of the fade. */
 } SDL_HapticPeriodic;
+
 /**
- * \struct SDL_HapticCondition
- *
  *  \brief A structure containing a template for a Condition effect.
  *  
  *  The struct handles the following effects:
- *   - SDL_HAPTIC_SPRING: Effect based on axes position.
- *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
- *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
- *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
+ *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
+ *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
+ *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
+ *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
  *  
  *  Direction is handled by condition internals instead of a direction member.
  *  The condition effect specific members have three parameters.  The first
  *  refers to the X axis, the second refers to the Y axis and the third
  *  refers to the Z axis.  The right terms refer to the positive side of the
  *  axis and the left terms refer to the negative side of the axis.  Please 
- *  refer to the SDL_HapticDirection  diagram for which side is positive and
+ *  refer to the ::SDL_HapticDirection diagram for which side is positive and
  *  which is negative.
  *  
  *  \sa SDL_HapticDirection
@@ -545,8 +563,8 @@ typedef struct SDL_HapticPeriodic
 typedef struct SDL_HapticCondition
 {
     /* Header */
-    Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
-                                 SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
+    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
+                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
     SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
 
     /* Replay */
@@ -565,12 +583,11 @@ typedef struct SDL_HapticCondition
     Uint16 deadband[3];     /**< Size of the dead zone. */
     Sint16 center[3];       /**< Position of the dead zone. */
 } SDL_HapticCondition;
+
 /**
- * \struct SDL_HapticRamp
- *
  *  \brief A structure containing a template for a Ramp effect.
  *  
- * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
+ *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
  *  
  *  The ramp effect starts at start strength and ends at end strength.
  *  It augments in linear fashion.  If you use attack and fade with a ramp
@@ -583,7 +600,7 @@ typedef struct SDL_HapticCondition
 typedef struct SDL_HapticRamp
 {
     /* Header */
-    Uint16 type;            /**< SDL_HAPTIC_RAMP */
+    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
     SDL_HapticDirection direction;  /**< Direction of the effect. */
 
     /* Replay */
@@ -604,10 +621,9 @@ typedef struct SDL_HapticRamp
     Uint16 fade_length;     /**< Duration of the fade. */
     Uint16 fade_level;      /**< Level at the end of the fade. */
 } SDL_HapticRamp;
+
 /**
- * \struct SDL_HapticCustom
- *
- * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
+ *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
  *  
  *  A custom force feedback effect is much like a periodic effect, where the
  *  application can define it's exact shape.  You will have to allocate the
@@ -622,7 +638,7 @@ typedef struct SDL_HapticRamp
 typedef struct SDL_HapticCustom
 {
     /* Header */
-    Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
+    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
     SDL_HapticDirection direction;  /**< Direction of the effect. */
 
     /* Replay */
@@ -645,20 +661,19 @@ typedef struct SDL_HapticCustom
     Uint16 fade_length;     /**< Duration of the fade. */
     Uint16 fade_level;      /**< Level at the end of the fade. */
 } SDL_HapticCustom;
+
 /**
- * \union SDL_HapticEffect
- *
  *  \brief The generic template for any haptic effect.
  *  
  *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
  *  Time values unless specified otherwise are in milliseconds.
  *  
- * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
- *  Neither delay, interval, attack_length nor fade_length support 
- *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
+ *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
+ *  value.  Neither delay, interval, attack_length nor fade_length support 
+ *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
  *  
- * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
- *  SDL_HAPTIC_INFINITY.
+ *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
+ *  ::SDL_HAPTIC_INFINITY.
  *  
  *  Button triggers may not be supported on all devices, it is advised to not
  *  use them if possible.  Buttons start at index 1 instead of index 0 like
@@ -686,26 +701,25 @@ typedef struct SDL_HapticCustom
  *
  *
  *  Here we have an example of a constant effect evolution in time:
- *
- * \code
- * Strength
- * ^
- * |
- * |    effect level -->  _________________
- * |                     /                 \
- * |                    /                   \
- * |                   /                     \
- * |                  /                       \ 
- * | attack_level --> |                        \
- * |                  |                        |  <---  fade_level
- * |
- * +--------------------------------------------------> Time
- *                    [--]                 [---]
- *                    attack_length        fade_length
- * 
- * [------------------][-----------------------]
- * delay               length
- * \endcode
+ *  \verbatim
+    Strength
+    ^
+    |
+    |    effect level -->  _________________
+    |                     /                 \
+    |                    /                   \
+    |                   /                     \
+    |                  /                       \ 
+    | attack_level --> |                        \
+    |                  |                        |  <---  fade_level
+    |
+    +--------------------------------------------------> Time
+                       [--]                 [---]
+                       attack_length        fade_length
+    
+    [------------------][-----------------------]
+    delay               length
+    \endverbatim
  *  
  *  Note either the attack_level or the fade_level may be above the actual
  *  effect level.
@@ -730,8 +744,6 @@ typedef union SDL_HapticEffect
 
 /* Function prototypes */
 /**
- * \fn int SDL_NumHaptics(void)
- *
  *  \brief Count the number of joysticks attached to the system.
  *  
  *  \return Number of haptic devices detected on the system.
@@ -739,9 +751,8 @@ typedef union SDL_HapticEffect
 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 
 /**
- * \fn const char * SDL_HapticName(int device_index)
- *
  *  \brief Get the implementation dependent name of a Haptic device.
+ *  
  *  This can be called before any joysticks are opened.
  *  If no name can be found, this function returns NULL.
  *  
@@ -753,14 +764,14 @@ extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 
 /**
- * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
+ *  \brief Opens a Haptic device for usage.
  *  
- * \brief Opens a Haptic device for usage - the index passed as an
- * argument refers to the N'th Haptic device on this system.
+ *  The index passed as an argument refers to the N'th Haptic device on this 
+ *  system.
  *
  *  When opening a haptic device, it's gain will be set to maximum and
  *  autocenter will be disabled.  To modify these values use
- *  SDL_HapticSetGain and SDL_HapticSetAutocenter
+ *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
  *
  *  \param device_index Index of the device to open.
  *  \return Device identifier or NULL on error.
@@ -777,8 +788,6 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
 
 /**
- * \fn int SDL_HapticOpened(int device_index)
- *
  *  \brief Checks if the haptic device at index has been opened.
  *  
  *  \param device_index Index to check to see if it has been opened.
@@ -790,8 +799,6 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
 
 /**
- * \fn int SDL_HapticIndex(SDL_Haptic * haptic)
- *
  *  \brief Gets the index of a haptic device.
  *  
  *  \param haptic Haptic device to get the index of.
@@ -803,8 +810,6 @@ extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
 
 /**
- * \fn int SDL_MouseIsHaptic(void)
- *
  *  \brief Gets whether or not the current mouse has haptic capabilities.
  *  
  *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
@@ -814,8 +819,6 @@ extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
 
 /**
- * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)
- *
  *  \brief Tries to open a haptic device from the current mouse.
  *  
  *  \return The haptic device identifier or NULL on error.
@@ -826,12 +829,10 @@ extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
 
 /**
- * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
- *
  *  \brief Checks to see if a joystick has haptic features.
  *  
  *  \param joystick Joystick to test for haptic capabilities.
- *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
+ *  \return 1 if the joystick is haptic, 0 if it isn't
  *          or -1 if an error ocurred.
  *  
  *  \sa SDL_HapticOpenFromJoystick
@@ -839,10 +840,10 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 
 /**
- * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
+ *  \brief Opens a Haptic device for usage from a Joystick device.
  *  
- * \brief Opens a Haptic device for usage from a Joystick device.  Still has
- * to be closed seperately to the joystick.
+ *  You must still close the haptic device seperately.  It will not be closed 
+ *  with the joystick.
  *  
  *  When opening from a joystick you should first close the haptic device before
  *  closing the joystick device.  If not, on some implementations the haptic
@@ -859,22 +860,18 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
                                                                joystick);
 
 /**
- * \fn void SDL_HapticClose(SDL_Haptic * haptic)
- *
- * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
+ *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
  *  
  *  \param haptic Haptic device to close.
  */
 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 
 /**
- * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
- *
  *  \brief Returns the number of effects a haptic device can store.
  *  
  *  On some platforms this isn't fully supported, and therefore is an
  *  aproximation.  Always check to see if your created effect was actually
- *  created and do not rely solely on HapticNumEffects.
+ *  created and do not rely solely on SDL_HapticNumEffects().
  *  
  *  \param haptic The haptic device to query effect max.
  *  \return The number of effects the haptic device can store or
@@ -886,14 +883,13 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 
 /**
- * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)
- *
- * \brief Returns the number of effects a haptic device can play at the same time.
+ *  \brief Returns the number of effects a haptic device can play at the same 
+ *         time.
  *  
- * This is not supported on all platforms, but will always return a value.  Added
- *  here for the sake of completness.
+ *  This is not supported on all platforms, but will always return a value.  
+ *  Added here for the sake of completness.
  *  
- *    \param haptic The haptic device to query maximum playing effect.s
+ *  \param haptic The haptic device to query maximum playing effects.
  *  \return The number of effects the haptic device can play at the same time
  *          or -1 on error.
  *
@@ -903,8 +899,6 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
 
 /**
- * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
- *
  *  \brief Gets the haptic devices supported features in bitwise matter.
  *  
  *  Example: 
@@ -914,7 +908,6 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
  *  }
  *  \endcode
  *  
- *
  *  \param haptic The haptic device to query.
  *  \return Haptic features in bitwise manner (OR'd).
  *  
@@ -925,8 +918,6 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 
 
 /**
- * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)
- *
  *  \brief Gets the number of haptic axes the device has.
  *  
  *  \sa SDL_HapticDirection
@@ -934,14 +925,11 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
 
 /**
- * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
- *
  *  \brief Checks to see if effect is supported by haptic.
  *  
  *  \param haptic Haptic device to check on.
  *  \param effect Effect to check to see if it is supported.
- *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
- *            -1 on error.
+ *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
  *  
  *  \sa SDL_HapticQuery
  *  \sa SDL_HapticNewEffect
@@ -951,8 +939,6 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
                                                       effect);
 
 /**
- * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
- *
  *  \brief Creates a new haptic effect on the device.
  *  
  *  \param haptic Haptic device to create the effect on.
@@ -967,14 +953,12 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
                                                 SDL_HapticEffect * effect);
 
 /**
- * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
- *
  *  \brief Updates the properties of an effect.
  *  
  *  Can be used dynamically, although behaviour when dynamically changing
  *  direction may be strange.  Specifically the effect may reupload itself
  *  and start playing from the start.  You cannot change the type either when
- * running UpdateEffect.
+ *  running SDL_HapticUpdateEffect().
  *  
  *  \param haptic Haptic device that has the effect.
  *  \param effect Effect to update.
@@ -990,19 +974,17 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
                                                    SDL_HapticEffect * data);
 
 /**
- * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)
- *
  *  \brief Runs the haptic effect on it's assosciated haptic device.
  *  
- * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
+ *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
  *  repeating the envelope (attack and fade) every time.  If you only want the
- *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
+ *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
  *  parameter.
  *  
  *  \param haptic Haptic device to run the effect on.
  *  \param effect Identifier of the haptic effect to run.
  *  \param iterations Number of iterations to run the effect. Use
- *           SDL_HAPTIC_INFINITY for infinity.
+ *         ::SDL_HAPTIC_INFINITY for infinity.
  *  \return 0 on success or -1 on error.
  *  
  *  \sa SDL_HapticStopEffect
@@ -1014,8 +996,6 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
                                                 Uint32 iterations);
 
 /**
- * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
- *
  *  \brief Stops the haptic effect on it's assosciated haptic device.
  *  
  *  \param haptic Haptic device to stop the effect on.
@@ -1029,11 +1009,10 @@ extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
                                                  int effect);
 
 /**
- * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
+ *  \brief Destroys a haptic effect on the device.
  *  
- * \brief Destroys a haptic effect on the device.  This will stop the effect
- * if it's running.  Effects are automatically destroyed when the device is
- * closed.
+ *  This will stop the effect if it's running.  Effects are automatically 
+ *  destroyed when the device is closed.
  *  
  *  \param haptic Device to destroy the effect on.
  *  \param effect Identifier of the effect to destroy.
@@ -1044,15 +1023,13 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
                                                      int effect);
 
 /**
- * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
- *
  *  \brief Gets the status of the current effect on the haptic device.
  *  
- * Device must support the SDL_HAPTIC_STATUS feature.
+ *  Device must support the ::SDL_HAPTIC_STATUS feature.
  *  
  *  \param haptic Haptic device to query the effect status on.
  *  \param effect Identifier of the effect to query it's status.
- *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
+ *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
  *          or -1 on error.
  *  
  *  \sa SDL_HapticRunEffect
@@ -1062,15 +1039,13 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
                                                       int effect);
 
 /**
- * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
- *
- * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
+ *  \brief Sets the global gain of the device.
  *  
- * Device must support the SDL_HAPTIC_GAIN feature.
+ *  Device must support the ::SDL_HAPTIC_GAIN feature.
  *  
  *  The user may specify the maxmimum gain by setting the environment variable
- *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
- *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the
+ *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
+ *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
  *  maximum.
  *  
  *  \param haptic Haptic device to set the gain on.
@@ -1082,12 +1057,12 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
 
 /**
- * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
+ *  \brief Sets the global autocenter of the device.
  *  
- * \brief Sets the global autocenter of the device.  Autocenter should be between
- * 0 and 100.  Setting it to 0 will disable autocentering.
+ *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
+ *  autocentering.
  *
- * Device must support the SDL_HAPTIC_AUTOCENTER feature.
+ *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
  *
  *  \param haptic Haptic device to set autocentering on.
  *  \param autocenter Value to set autocenter to, 0 disables autocentering.
@@ -1099,12 +1074,10 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
                                                     int autocenter);
 
 /**
- * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)
- *
  *  \brief Pauses a haptic device.
  *  
- * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause
- *  to resume playback.
+ *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
+ *  SDL_HapticUnpause() to resume playback.
  *  
  *  Do not modify the effects nor add new ones while the device is paused.
  *  That can cause all sorts of weird errors.
@@ -1117,11 +1090,9 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
 
 /**
- * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)
- *
  *  \brief Unpauses a haptic device.
  *  
- * Call to unpause after SDL_HapticPause.
+ *  Call to unpause after SDL_HapticPause().
  *  
  *  \param haptic Haptic device to pause.
  *  \return 0 on success or -1 on error.
@@ -1131,8 +1102,6 @@ extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
 
 /**
- * \fn extern DECSLPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic)
- *
  *  \brief Stops all the currently playing effects on a haptic device.
  *  
  *  \param haptic Haptic device to stop.

include/SDL_joystick.h

@@ -40,10 +40,13 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* In order to use these functions, SDL_Init() must have been called
-   with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
-   for joysticks, and load appropriate drivers.
-*/
+/**
+ *  \file SDL_joystick.h
+ *
+ *  In order to use these functions, SDL_Init() must have been called
+ *  with the ::SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
+ *  for joysticks, and load appropriate drivers.
+ */
 
 /* The joystick structure used to identify an SDL joystick */
 struct _SDL_Joystick;
@@ -51,87 +54,94 @@ typedef struct _SDL_Joystick SDL_Joystick;
 
 
 /* Function prototypes */
-/*
+/**
  *  Count the number of joysticks attached to the system
  */
 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
 
-/*
+/**
  *  Get the implementation dependent name of a joystick.
  *  This can be called before any joysticks are opened.
  *  If no name can be found, this function returns NULL.
  */
 extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index);
 
-/*
- * Open a joystick for use - the index passed as an argument refers to
- * the N'th joystick on the system.  This index is the value which will
- * identify this joystick in future joystick events.
+/**
+ *  Open a joystick for use.  
+ *  The index passed as an argument refers tothe N'th joystick on the system.  
+ *  This index is the value which will identify this joystick in future joystick
+ *  events.
  *  
- * This function returns a joystick identifier, or NULL if an error occurred.
+ *  \return A joystick identifier, or NULL if an error occurred.
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
 
-/*
+/**
  *  Returns 1 if the joystick has been opened, or 0 if it has not.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
 
-/*
+/**
  *  Get the device index of an opened joystick.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick);
 
-/*
- * Get the number of general axis controls on a joystick
+/**
+ *  Get the number of general axis controls on a joystick.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick);
 
-/*
- * Get the number of trackballs on a joystick
+/**
+ *  Get the number of trackballs on a joystick.
+ *  
  *  Joystick trackballs have only relative motion events associated
  *  with them and their state cannot be polled.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick);
 
-/*
- * Get the number of POV hats on a joystick
+/**
+ *  Get the number of POV hats on a joystick.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick);
 
-/*
- * Get the number of buttons on a joystick
+/**
+ *  Get the number of buttons on a joystick.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick);
 
-/*
+/**
  *  Update the current state of the open joysticks.
+ *  
  *  This is called automatically by the event loop if any joystick
  *  events are enabled.
  */
 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
 
-/*
+/**
  *  Enable/disable joystick event polling.
+ *  
  *  If joystick events are disabled, you must call SDL_JoystickUpdate()
  *  yourself and check the state of the joystick when you want joystick
  *  information.
- * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
+ *  
+ *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 
-/*
- * Get the current state of an axis control on a joystick
+/**
+ *  Get the current state of an axis control on a joystick.
+ *  
  *  The state is a value ranging from -32768 to 32767.
+ *  
  *  The axis indices start at index 0.
  */
 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
                                                    int axis);
 
-/*
- * Get the current state of a POV hat on a joystick
- * The return value is one of the following positions:
+/**
+ *  \name Hat positions
  */
+/*@{*/
 #define SDL_HAT_CENTERED	0x00
 #define SDL_HAT_UP		0x01
 #define SDL_HAT_RIGHT		0x02
@@ -141,29 +151,47 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
 #define SDL_HAT_RIGHTDOWN	(SDL_HAT_RIGHT|SDL_HAT_DOWN)
 #define SDL_HAT_LEFTUP		(SDL_HAT_LEFT|SDL_HAT_UP)
 #define SDL_HAT_LEFTDOWN	(SDL_HAT_LEFT|SDL_HAT_DOWN)
-/*
+/*@}*/
+
+/**
+ *  Get the current state of a POV hat on a joystick.
+ *
  *  The hat indices start at index 0.
+ *  
+ *  \return The return value is one of the following positions:
+ *           - ::SDL_HAT_CENTERED
+ *           - ::SDL_HAT_UP
+ *           - ::SDL_HAT_RIGHT
+ *           - ::SDL_HAT_DOWN
+ *           - ::SDL_HAT_LEFT
+ *           - ::SDL_HAT_RIGHTUP
+ *           - ::SDL_HAT_RIGHTDOWN
+ *           - ::SDL_HAT_LEFTUP
+ *           - ::SDL_HAT_LEFTDOWN
  */
 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick,
                                                  int hat);
 
-/*
- * Get the ball axis change since the last poll
- * This returns 0, or -1 if you passed it invalid parameters.
+/**
+ *  Get the ball axis change since the last poll.
+ *  
+ *  \return 0, or -1 if you passed it invalid parameters.
+ *  
  *  The ball indices start at index 0.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick,
                                                 int ball, int *dx, int *dy);
 
-/*
- * Get the current state of a button on a joystick
+/**
+ *  Get the current state of a button on a joystick.
+ *  
  *  The button indices start at index 0.
  */
 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick,
                                                     int button);
 
-/*
- * Close a joystick previously opened with SDL_JoystickOpen()
+/**
+ *  Close a joystick previously opened with SDL_JoystickOpen().
  */
 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick);
 

include/SDL_keyboard.h

@@ -42,8 +42,6 @@ extern "C" {
 #endif
 
 /**
- * \struct SDL_keysym
- *
  *  \brief The SDL keysym structure, used in key events.
  */
 typedef struct SDL_keysym
@@ -51,14 +49,12 @@ typedef struct SDL_keysym
     SDL_scancode scancode;      /**< SDL physical key code - see ::SDL_scancode for details */
     SDLKey sym;                 /**< SDL virtual key code - see ::SDLKey for details */
     Uint16 mod;                 /**< current key modifiers */
-    Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
+    Uint32 unicode;             /**< \deprecated use SDL_TextInputEvent instead */
 } SDL_keysym;
 
 /* Function prototypes */
 
 /**
- * \fn int SDL_GetNumKeyboards(void)
- *
  *  \brief Get the number of keyboard input devices available.
  *  
  *  \sa SDL_SelectKeyboard()
@@ -66,8 +62,6 @@ typedef struct SDL_keysym
 extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
 
 /**
- * \fn int SDL_SelectKeyboard(int index)
- *
  *  \brief Set the index of the currently selected keyboard.
  *  
  *  \return The index of the previously selected keyboard.
@@ -79,30 +73,28 @@ extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
 extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
 
 /**
- * \fn Uint8 *SDL_GetKeyboardState(int *numkeys)
- *
  *  \brief Get a snapshot of the current state of the selected keyboard.
  *  
  *  \param numkeys if non-NULL, receives the length of the returned array.
  *  
  *  \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
  *  
- * Example:
+ *  \b Example:
+ *  \code
  *  Uint8 *state = SDL_GetKeyboardState(NULL);
- *	if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed.
+ *  if ( state[SDL_SCANCODE_RETURN] )   {
+ *      printf("<RETURN> is pressed.\n");
+ *  }
+ *  \endcode
  */
 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
 
 /**
- * \fn SDLMod SDL_GetModState(void)
- *
  *  \brief Get the current key modifier state for the selected keyboard.
  */
 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 
 /**
- * \fn void SDL_SetModState(SDLMod modstate)
- *
  *  \brief Set the current key modifier state for the selected keyboard.
  *  
  *  \note This does not change the keyboard state, only the key modifier flags.
@@ -110,9 +102,8 @@ extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 
 /**
- * \fn SDLKey SDL_GetKeyFromScancode(SDL_scancode scancode)
- * 
- * \brief Get the key code corresponding to the given scancode according to the current keyboard layout.
+ *  \brief Get the key code corresponding to the given scancode according to the
+ *         current keyboard layout.
  *  
  *  See ::SDLKey for details.
  *  
@@ -121,9 +112,8 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
 
 /**
- * \fn SDL_scancode SDL_GetScancodeFromKey(SDLKey key)
- * 
- * \brief Get the scancode corresponding to the given key code according to the current keyboard layout.
+ *  \brief Get the scancode corresponding to the given key code according to the
+ *         current keyboard layout.
  *  
  *  See ::SDL_scancode for details.
  *  
@@ -132,11 +122,12 @@ extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
 extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key);
 
 /**
- * \fn const char *SDL_GetScancodeName(SDL_scancode scancode)
- * 
  *  \brief Get a human-readable name for a scancode.
  *  
- * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the scancode doesn't have a name, this function returns "".
+ *  \return A pointer to a UTF-8 string that stays valid at least until the next
+ *          call to this function. If you need it around any longer, you must 
+ *          copy it.  If the scancode doesn't have a name, this function returns
+ *          an empty string ("").
  *
  *  \sa SDL_scancode
  */
@@ -144,19 +135,18 @@ extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode
                                                         scancode);
 
 /**
- * \fn const char *SDL_GetKeyName(SDLKey key)
- * 
  *  \brief Get a human-readable name for a key.
  *  
- * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the key doesn't have a name, this function returns "".
+ *  \return A pointer to a UTF-8 string that stays valid at least until the next
+ *          call to this function. If you need it around any longer, you must 
+ *          copy it.  If the key doesn't have a name, this function returns an 
+ *          empty string ("").
  *  
  *  \sa SDLKey
  */
 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
 
 /**
- * \fn void SDL_StartTextInput(void)
- *
  *  \brief Start accepting Unicode text input events.
  *  
  *  \sa SDL_StopTextInput()
@@ -165,8 +155,6 @@ extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
 /**
- * \fn void SDL_StopTextInput(void)
- *
  *  \brief Stop receiving any text input events.
  *  
  *  \sa SDL_StartTextInput()
@@ -174,8 +162,6 @@ extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 
 /**
- * \fn void SDL_SetTextInputRect(SDL_Rect *rect)
- *
  *  \brief Set the rectangle used to type Unicode text inputs.
  *  
  *  \sa SDL_StartTextInput()

include/SDL_keysym.h

@@ -22,6 +22,8 @@
 
 /**
  *  \file SDL_keysym.h
+ *  
+ *  Defines constants which identify keyboard keys and modifiers.
  */
 
 #ifndef _SDL_keysym_h
@@ -31,8 +33,6 @@
 #include "SDL_scancode.h"
 
 /**
- * \typedef SDLKey
- *
  *  \brief The SDL virtual key representation.
  *  
  *  Values of this type are used to represent keyboard keys using the current
@@ -246,9 +246,7 @@ enum
 };
 
 /**
- * \enum SDLMod
- *
- * \brief Enumeration of valid key mods (possibly OR'd together)
+ * \brief Enumeration of valid key mods (possibly OR'd together).
  */
 typedef enum
 {

include/SDL_loadso.h

@@ -26,13 +26,13 @@
  *  System dependent library loading routines
  *
  *  Some things to keep in mind:                                        
- * - These functions only work on C function names.  Other languages may
+ *  \li These functions only work on C function names.  Other languages may
  *      have name mangling and intrinsic language support that varies from
  *      compiler to compiler.
- * - Make sure you declare your function pointers with the same calling
+ *  \li Make sure you declare your function pointers with the same calling
  *      convention as the actual library function.  Your code will crash
  *      mysteriously if you do not do this.
- * - Avoid namespace collisions.  If you load a symbol from the library,
+ *  \li Avoid namespace collisions.  If you load a symbol from the library,
  *      it is not defined whether or not it goes into the global symbol
  *      namespace for the application.  If it does and it conflicts with
  *      symbols in your code or other shared libraries, you will not get
@@ -53,20 +53,24 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* This function dynamically loads a shared object and returns a pointer
+/**
+ *  This function dynamically loads a shared object and returns a pointer
  *  to the object handle (or NULL if there was an error).
  *  The 'sofile' parameter is a system dependent name of the object file.
  */
 extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
 
-/* Given an object handle, this function looks up the address of the
+/**
+ *  Given an object handle, this function looks up the address of the
  *  named function in the shared object and returns it.  This address
  *  is no longer valid after calling SDL_UnloadObject().
  */
 extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
                                                const char *name);
 
-/* Unload a shared object from memory */
+/**
+ *  Unload a shared object from memory.
+ */
 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
 
 /* Ends C function definitions when using C++ */

include/SDL_main.h

@@ -25,7 +25,11 @@
 
 #include "SDL_stdinc.h"
 
-/* Redefine main() on some platforms so that it is called by SDL */
+/**
+ *  \file SDL_main.h
+ *  
+ *  Redefine main() on some platforms so that it is called by SDL.
+ */
 
 #if defined(__WIN32__) || \
     (defined(__MWERKS__) && !defined(__BEOS__)) || \
@@ -37,18 +41,26 @@
 #define C_LINKAGE
 #endif /* __cplusplus */
 
-/* The application's main() function must be called with C linkage,
-   and should be declared like this:
-#ifdef __cplusplus
-extern "C"
-#endif
-	int main(int argc, char *argv[])
-	{
-	}
+/**
+ *  \file SDL_main.h
+ *
+ *  The application's main() function must be called with C linkage,
+ *  and should be declared like this:
+ *  \code
+ *  #ifdef __cplusplus
+ *  extern "C"
+ *  #endif
+ *  int main(int argc, char *argv[])
+ *  {
+ *  }
+ *  \endcode
  */
+
 #define main	SDL_main
 
-/* The prototype for the application's main() function */
+/**
+ *  The prototype for the application's main() function
+ */
 extern C_LINKAGE int SDL_main(int argc, char *argv[]);
 
 
@@ -62,7 +74,9 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* This can be called to set the application class at startup */
+/**
+ *  This can be called to set the application class at startup
+ */
 extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style,
                                             void *hInst);
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);

include/SDL_mouse.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_mouse.h
  *  
- * Include file for SDL mouse event handling
+ *  Include file for SDL mouse event handling.
  */
 
 #ifndef _SDL_mouse_h
@@ -46,8 +46,6 @@ typedef struct SDL_Cursor SDL_Cursor;   /* Implementation dependent */
 /* Function prototypes */
 
 /**
- * \fn int SDL_GetNumMice(void)
- *
  *  \brief Get the number of mouse input devices available.
  *  
  *  \sa SDL_SelectMouse()
@@ -55,8 +53,6 @@ typedef struct SDL_Cursor SDL_Cursor;   /* Implementation dependent */
 extern DECLSPEC int SDLCALL SDL_GetNumMice(void);
 
 /**
- * \fn char* SDL_GetMouseName(int index)
- *
  *  \brief Gets the name of a mouse with the given index.
  *  
  *  \param index is the index of the mouse, which name is to be returned.
@@ -66,8 +62,6 @@ extern DECLSPEC int SDLCALL SDL_GetNumMice(void);
 extern DECLSPEC char *SDLCALL SDL_GetMouseName(int index);
 
 /**
- * \fn int SDL_SelectMouse(int index)
- *
  *  \brief Set the index of the currently selected mouse.
  *  
  *  \return The index of the previously selected mouse.
@@ -79,16 +73,12 @@ extern DECLSPEC char *SDLCALL SDL_GetMouseName(int index);
 extern DECLSPEC int SDLCALL SDL_SelectMouse(int index);
 
 /**
- * \fn SDL_WindowID SDL_GetMouseFocusWindow(int index)
- *
- * \brief Get the window which currently has focus for the currently selected mouse.
+ *  \brief Get the window which currently has focus for the specified mouse.
  */
 extern DECLSPEC SDL_WindowID SDLCALL SDL_GetMouseFocusWindow(int index);
 
 /**
- * \fn int SDL_SetRelativeMouseMode(int index, SDL_bool enabled)
- *
- * \brief Set relative mouse mode for the currently selected mouse.
+ *  \brief Set relative mouse mode for the specified mouse.
  *  
  *  \param enabled Whether or not to enable relative mode
  *  
@@ -107,18 +97,14 @@ extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(int index,
                                                      SDL_bool enabled);
 
 /**
- * \fn SDL_bool SDL_GetRelativeMouseMode(int index)
- *
- * \brief Query whether relative mouse mode is enabled for the currently selected mouse.
+ *  \brief Query whether relative mouse mode is enabled for the specified mouse.
  *  
  *  \sa SDL_SetRelativeMouseMode()
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(int index);
 
 /**
- * \fn Uint8 SDL_GetMouseState(int index, int *x, int *y)
- *
- * \brief Retrieve the current state of the currently selected mouse.
+ *  \brief Retrieve the current state of the specified mouse.
  *  
  *  The current button state is returned as a button bitmask, which can
  *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
@@ -128,9 +114,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(int index);
 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int index, int *x, int *y);
 
 /**
- * \fn Uint8 SDL_GetRelativeMouseState(int index, int *x, int *y)
- *
- * \brief Retrieve the state of the currently selected mouse.
+ *  \brief Retrieve the state of the specified mouse.
  *
  *  The current button state is returned as a button bitmask, which can
  *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
@@ -140,8 +124,6 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int index, int *x,
                                                         int *y);
 
 /**
- * \fn void SDL_WarpMouseInWindow(SDL_WindowID windowID, int x, int y)
- *
  *  \brief Moves the currently selected mouse to the given position within the window.
  *  
  *  \param windowID The window to move the mouse into, or 0 for the current mouse focus
@@ -154,19 +136,20 @@ extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_WindowID windowID,
                                                    int x, int y);
 
 /**
- * \fn SDL_Cursor *SDL_CreateCursor (const Uint8 * data, const Uint8 * mask, int w, int h, int hot_x, int hot_y)
- *
  *  \brief Create a cursor for the currently selected mouse, using the
  *         specified bitmap data and mask (in MSB format).
  *  
  *  The cursor width must be a multiple of 8 bits.
  *  
  *  The cursor is created in black and white according to the following:
- * data  mask    resulting pixel on screen
- *  0     1       White
- *  1     1       Black
- *  0     0       Transparent
- *  1     0       Inverted color if possible, black if not.
+ *  <table>
+ *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
+ *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
+ *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
+ *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
+ *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black 
+                                           if not. </td></tr>
+ *  </table>
  *  
  *  \sa SDL_FreeCursor()
  */
@@ -176,8 +159,6 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                      int hot_y);
 
 /**
- * \fn void SDL_SetCursor(SDL_Cursor * cursor)
- *
  *  \brief Set the active cursor for the currently selected mouse.
  *  
  *  \note The cursor must have been created for the selected mouse.
@@ -185,15 +166,11 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
 
 /**
- * \fn SDL_Cursor *SDL_GetCursor(void)
- *
  *  \brief Return the active cursor for the currently selected mouse.
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 
 /**
- * \fn void SDL_FreeCursor(SDL_Cursor * cursor)
- *
  *  \brief Frees a cursor created with SDL_CreateCursor().
  *  
  *  \sa SDL_CreateCursor()
@@ -201,53 +178,54 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
 
 /**
- * \fn int SDL_ShowCursor(int toggle)
- *
- * \brief Toggle whether or not the cursor is shown for the currently selected mouse.
+ *  \brief Toggle whether or not the cursor is shown for the currently selected 
+ *         mouse.
  *  
- * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current state.
+ *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current 
+ *                state.
  *  
  *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
  */
 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 
-/* Used as a mask when testing buttons in buttonstate
-   Button 1:	Left mouse button
-   Button 2:	Middle mouse button
-   Button 3:	Right mouse button
- */
-
 /**
- * \fn int SDL_GetCursorsNumber(int index)
- *
  *  \brief Gets the number of cursors a pointing device supports.
+ *  
  *  Useful for tablet users. Useful only under Windows.
  *  
  *  \param index is the index of the pointing device, which number of cursors we
  *               want to receive.
  *  
  *  \return the number of cursors supported by the pointing device. On Windows
- * if a device is a tablet it returns a number >=1. Normal mice always return 1.
+ *          if a device is a tablet it returns a number >=1. Normal mice always 
+ *          return 1.
+ *  
  *  On Linux every device reports one cursor.
  */
 extern DECLSPEC int SDLCALL SDL_GetCursorsNumber(int index);
 
 /**
- * \fn int SDL_GetCurrentCursor(int index)
- *
  *  \brief Returns the index of the current cursor used by a specific pointing
- * device. Useful only under Windows.
+ *         device.
+ *  
+ *  Useful only under Windows.
  *  
  *  \param index is the index of the pointing device, which cursor index we want
  *               to receive.
  *  
- * \return the index of the cursor currently used by a specific pointing device.
- * Always 0 under Linux. On Windows if the device isn't a tablet it returns 0.
- * If the device is the tablet it returns the cursor index.
- * 0 - stylus, 1 - eraser, 2 - cursor.
+ *  \return the index of the cursor currently used by a specific pointing 
+ *          device.  Always 0 under Linux. On Windows if the device isn't a 
+ *          tablet it returns 0.  If the device is the tablet it returns the 
+ *          cursor index.  0 - stylus, 1 - eraser, 2 - cursor.
  */
 extern DECLSPEC int SDLCALL SDL_GetCurrentCursor(int index);
 
+/**
+ *  Used as a mask when testing buttons in buttonstate.
+ *   - Button 1:  Left mouse button
+ *   - Button 2:  Middle mouse button
+ *   - Button 3:  Right mouse button
+ */
 #define SDL_BUTTON(X)		(1 << ((X)-1))
 #define SDL_BUTTON_LEFT		1
 #define SDL_BUTTON_MIDDLE	2

include/SDL_mutex.h

@@ -26,7 +26,7 @@
 /**
  *  \file SDL_mutex.h
  *  
- * Functions to provide thread synchronization primitives
+ *  Functions to provide thread synchronization primitives.
  */
 
 #include "SDL_stdinc.h"
@@ -40,123 +40,176 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* Synchronization functions which can time out return this value
-   if they time out.
-*/
+/**
+ *  Synchronization functions which can time out return this value
+ *  if they time out.
+ */
 #define SDL_MUTEX_TIMEDOUT	1
 
-/* This is the timeout value which corresponds to never time out */
+/**
+ *  This is the timeout value which corresponds to never time out.
+ */
 #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
 
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Mutex functions                                               */
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/**
+ *  \name Mutex functions
+ */
+/*@{*/
 
 /* The SDL mutex structure, defined in SDL_mutex.c */
 struct SDL_mutex;
 typedef struct SDL_mutex SDL_mutex;
 
-/* Create a mutex, initialized unlocked */
+/**
+ *  Create a mutex, initialized unlocked.
+ */
 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
 
-/* Lock the mutex  (Returns 0, or -1 on error) */
+/**
+ *  Lock the mutex.
+ *  
+ *  \return 0, or -1 on error.
+ */
 #define SDL_LockMutex(m)	SDL_mutexP(m)
 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
 
-/* Unlock the mutex  (Returns 0, or -1 on error)
-   It is an error to unlock a mutex that has not been locked by
-   the current thread, and doing so results in undefined behavior.
+/**
+ *  Unlock the mutex.
+ *  
+ *  \return 0, or -1 on error.
+ *  
+ *  \warning It is an error to unlock a mutex that has not been locked by
+ *           the current thread, and doing so results in undefined behavior.
  */
 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
 
-/* Destroy a mutex */
+/** 
+ *  Destroy a mutex.
+ */
 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
 
+/*@}*//*Mutex functions*/
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Semaphore functions                                           */
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/**
+ *  \name Semaphore functions
+ */
+/*@{*/
 
 /* The SDL semaphore structure, defined in SDL_sem.c */
 struct SDL_semaphore;
 typedef struct SDL_semaphore SDL_sem;
 
-/* Create a semaphore, initialized with value, returns NULL on failure. */
+/**
+ *  Create a semaphore, initialized with value, returns NULL on failure.
+ */
 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
 
-/* Destroy a semaphore */
+/**
+ *  Destroy a semaphore.
+ */
 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
 
-/* This function suspends the calling thread until the semaphore pointed 
- * to by sem has a positive count. It then atomically decreases the semaphore
- * count.
+/**
+ *  This function suspends the calling thread until the semaphore pointed 
+ *  to by \c sem has a positive count. It then atomically decreases the 
+ *  semaphore count.
  */
 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
 
-/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
-   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
-*/
+/**
+ *  Non-blocking variant of SDL_SemWait().
+ *  
+ *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would 
+ *          block, and -1 on error.
+ */
 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
 
-/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
-   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
-   the allotted time, and -1 on error.
-   On some platforms this function is implemented by looping with a delay
-   of 1 ms, and so should be avoided if possible.
-*/
+/**
+ *  Variant of SDL_SemWait() with a timeout in milliseconds.
+ *  
+ *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not 
+ *          succeed in the allotted time, and -1 on error.
+ *  
+ *  \warning On some platforms this function is implemented by looping with a 
+ *           delay of 1 ms, and so should be avoided if possible.
+ */
 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
 
-/* Atomically increases the semaphore's count (not blocking), returns 0,
-   or -1 on error.
+/**
+ *  Atomically increases the semaphore's count (not blocking).
+ *  
+ *  \return 0, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
 
-/* Returns the current count of the semaphore */
+/**
+ *  Returns the current count of the semaphore.
+ */
 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
 
+/*@}*//*Semaphore functions*/
+
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Condition variable functions                                  */
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/**
+ *  \name Condition variable functions
+ */
+/*@{*/
 
 /* The SDL condition variable structure, defined in SDL_cond.c */
 struct SDL_cond;
 typedef struct SDL_cond SDL_cond;
 
-/* Create a condition variable */
+/**
+ *  Create a condition variable.
+ */
 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
 
-/* Destroy a condition variable */
+/**
+ *  Destroy a condition variable.
+ */
 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
 
-/* Restart one of the threads that are waiting on the condition variable,
-   returns 0 or -1 on error.
+/**
+ *  Restart one of the threads that are waiting on the condition variable.
+ *  
+ *  \return 0 or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
 
-/* Restart all threads that are waiting on the condition variable,
-   returns 0 or -1 on error.
+/**
+ *  Restart all threads that are waiting on the condition variable.
+ *  \return 0 or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
 
-/* Wait on the condition variable, unlocking the provided mutex.
-   The mutex must be locked before entering this function!
-   The mutex is re-locked once the condition variable is signaled.
-   Returns 0 when it is signaled, or -1 on error.
+/**
+ *  Wait on the condition variable, unlocking the provided mutex.
+ *  
+ *  \warning The mutex must be locked before entering this function!
+ *  
+ *  The mutex is re-locked once the condition variable is signaled.
+ *  
+ *  \return 0 when it is signaled, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut);
 
-/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
-   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
-   signaled in the allotted time, and -1 on error.
-   On some platforms this function is implemented by looping with a delay
-   of 1 ms, and so should be avoided if possible.
-*/
+/**
+ *  Waits for at most \c ms milliseconds, and returns 0 if the condition
+ *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
+ *  signaled in the allotted time, and -1 on error.
+ *
+ *  \warning On some platforms this function is implemented by looping with a 
+ *           delay of 1 ms, and so should be avoided if possible.
+ */
 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
                                                 SDL_mutex * mutex, Uint32 ms);
 
+/*@}*//*Condition variable functions*/
+
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 /* *INDENT-OFF* */

include/SDL_opengl.h

@@ -20,7 +20,11 @@
     slouken@libsdl.org
 */
 
-/* This is a simple file to encapsulate the OpenGL API headers */
+/**
+ *  \file SDL_opengl.h
+ *  
+ *  This is a simple file to encapsulate the OpenGL API headers.
+ */
 
 #ifndef _SDL_opengl_h
 #define _SDL_opengl_h
@@ -49,11 +53,23 @@
 #undef __glext_h_
 #endif
 
-/* This file is included because glext.h is not available on some systems.
-   If you don't want this version included, simply define "NO_SDL_GLEXT"
-   The latest version is available from:
-	http://www.opengl.org/registry/
+/**
+ *  \file SDL_opengl.h
+ *  
+ *  This file is included because glext.h is not available on some systems.
+ *  If you don't want this version included, simply define ::NO_SDL_GLEXT.
+ *  
+ *  The latest version is available from:
+ *  	http://www.opengl.org/registry/
+ */
+
+/**
+ *  \def NO_SDL_GLEXT
+ *  
+ *  Define this if you have your own version of glext.h and want to disable the 
+ *  version included in SDL_opengl.h.
  */
+
 #if !defined(NO_SDL_GLEXT) && !defined(GL_GLEXT_LEGACY)
 /* *INDENT-OFF* */
 #ifndef __glext_h_

include/SDL_opengles.h

@@ -20,10 +20,13 @@
  slouken@libsdl.org
  */
 
-/*
-	This is a simple file to encapsulate the OpenGL ES API headers.
-	Headers copied from The Kronos Group website.
-	http://www.khronos.org/opengles/
+/**
+ *  \file SDL_opengles.h
+ *  
+ *  This is a simple file to encapsulate the OpenGL ES API headers.
+ *  
+ *  Headers copied from The Kronos Group website.
+ *  	http://www.khronos.org/opengles/
  */
 
 #ifndef __gles_h_

include/SDL_pixels.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_pixels.h
  *  
- * Header for the enumerated pixel format definitions
+ *  Header for the enumerated pixel format definitions.
  */
 
 #ifndef _SDL_pixels_h
@@ -37,12 +37,19 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* Transparency definitions: These define alpha as the opacity of a surface */
+/**
+ *  \name Transparency definitions
+ *  
+ *  These define alpha as the opacity of a surface.
+ */
+/*@{*/
 #define SDL_ALPHA_OPAQUE 255
 #define SDL_ALPHA_TRANSPARENT 0
+/*@}*/
 
+/** Pixel type. */
 enum
-{                               /* Pixel type */
+{
     SDL_PIXELTYPE_UNKNOWN,
     SDL_PIXELTYPE_INDEX1,
     SDL_PIXELTYPE_INDEX4,
@@ -57,14 +64,17 @@ enum
     SDL_PIXELTYPE_ARRAYF32
 };
 
+/** Bitmap pixel order, high bit -> low bit. */
 enum
-{                               /* bitmap pixel order, high bit -> low bit */
+{
     SDL_BITMAPORDER_NONE,
     SDL_BITMAPORDER_4321,
     SDL_BITMAPORDER_1234
 };
+
+/** Packed component order, high bit -> low bit. */
 enum
-{                               /* packed component order, high bit -> low bit */
+{
     SDL_PACKEDORDER_NONE,
     SDL_PACKEDORDER_XRGB,
     SDL_PACKEDORDER_RGBX,
@@ -75,8 +85,10 @@ enum
     SDL_PACKEDORDER_ABGR,
     SDL_PACKEDORDER_BGRA
 };
+
+/** Array component order, low byte -> high byte. */
 enum
-{                               /* array component order, low byte -> high byte */
+{
     SDL_ARRAYORDER_NONE,
     SDL_ARRAYORDER_RGB,
     SDL_ARRAYORDER_RGBA,
@@ -86,8 +98,9 @@ enum
     SDL_ARRAYORDER_ABGR
 };
 
+/** Packed component layout. */
 enum
-{                               /* Packed component layout */
+{
     SDL_PACKEDLAYOUT_NONE,
     SDL_PACKEDLAYOUT_332,
     SDL_PACKEDLAYOUT_4444,
@@ -201,15 +214,15 @@ enum
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
                                SDL_PACKEDLAYOUT_2101010, 32, 4),
 
-    SDL_PIXELFORMAT_YV12 =      /* Planar mode: Y + V + U  (3 planes) */
+    SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
         SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
-    SDL_PIXELFORMAT_IYUV =      /* Planar mode: Y + U + V  (3 planes) */
+    SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
         SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
-    SDL_PIXELFORMAT_YUY2 =      /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
+    SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
         SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
-    SDL_PIXELFORMAT_UYVY =      /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
+    SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
         SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
-    SDL_PIXELFORMAT_YVYU =      /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
+    SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
         SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
 };
 
@@ -241,7 +254,9 @@ struct SDL_Palette
     SDL_PaletteWatch *watch;
 };
 
-/* Everything in the pixel format structure is read-only */
+/**
+ *  \note Everything in the pixel format structure is read-only.
+ */
 typedef struct SDL_PixelFormat
 {
     SDL_Palette *palette;
@@ -262,8 +277,6 @@ typedef struct SDL_PixelFormat
 } SDL_PixelFormat;
 
 /**
- * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
- *
  *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
  *  
  *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
@@ -278,11 +291,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
                                                             Uint32 * Amask);
 
 /**
- * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
- *
  *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
  *  
- * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
+ *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion 
+ *          wasn't possible.
  *  
  *  \sa SDL_PixelFormatEnumToMasks()
  */
@@ -293,11 +305,10 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
                                                           Uint32 Amask);
 
 /**
- * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
- *
- * \brief Create a palette structure with the specified number of color entries.
+ *  \brief Create a palette structure with the specified number of color 
+ *         entries.
  *  
- * \return A new palette, or NULL if there wasn't enough memory
+ *  \return A new palette, or NULL if there wasn't enough memory.
  *  
  *  \note The palette entries are initialized to white.
  *  
@@ -306,8 +317,6 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
 
 /**
- * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
- *
  *  \brief Add a callback function which is called when the palette changes.
  *  
  *  \sa SDL_DelPaletteWatch()
@@ -317,9 +326,8 @@ extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
                                                 callback, void *userdata);
 
 /**
- * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
- *
- * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
+ *  \brief Remove a callback function previously added with 
+ *         SDL_AddPaletteWatch().
  *  
  *  \sa SDL_AddPaletteWatch()
  */
@@ -328,35 +336,28 @@ extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
                                                  callback, void *userdata);
 
 /**
- * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
- *
  *  \brief Set a range of colors in a palette.
  *  
- * \param palette The palette to modify
- * \param colors An array of colors to copy into the palette
- * \param firstcolor The index of the first palette entry to modify
- * \param ncolors The number of entries to modify
+ *  \param palette    The palette to modify.
+ *  \param colors     An array of colors to copy into the palette.
+ *  \param firstcolor The index of the first palette entry to modify.
+ *  \param ncolors    The number of entries to modify.
  *  
- * \return 0 on success, or -1 if not all of the colors could be set
+ *  \return 0 on success, or -1 if not all of the colors could be set.
  */
 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
                                                  const SDL_Color * colors,
                                                  int firstcolor, int ncolors);
 
 /**
- * \fn void SDL_FreePalette(SDL_Palette *palette)
- *
- * \brief Free a palette created with SDL_AllocPalette()
+ *  \brief Free a palette created with SDL_AllocPalette().
  *  
  *  \sa SDL_AllocPalette()
  */
 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
 
 /**
- * \fn Uint32 SDL_MapRGB(const SDL_PixelFormat *format,
- *                       Uint8 r, Uint8 g, Uint8 b)
- *
- * \brief Maps an RGB triple to an opaque pixel value for a given pixel format
+ *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
  *  
  *  \sa SDL_MapRGBA
  */
@@ -364,10 +365,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
                                           Uint8 r, Uint8 g, Uint8 b);
 
 /**
- * \fn Uint32 SDL_MapRGBA(const SDL_PixelFormat *fmt,
- *                        Uint8 r, Uint8 g, Uint8 b, Uint8 a)
- *
- * \brief Maps an RGBA quadruple to a pixel value for a given pixel format
+ *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
  *  
  *  \sa SDL_MapRGB
  */
@@ -376,10 +374,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
                                            Uint8 a);
 
 /**
- * \fn void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat * format,
- *                     Uint8 * r, Uint8 * g, Uint8 * b)
- *
- * \brief Maps a pixel value into the RGB components for a given pixel format
+ *  \brief Maps a pixel value into the RGB components for a given pixel format.
  *  
  *  \sa SDL_GetRGBA
  */
@@ -388,10 +383,7 @@ extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
                                         Uint8 * r, Uint8 * g, Uint8 * b);
 
 /**
- * \fn void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat * format,
- *                      Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a)
- *
- * \brief Maps a pixel value into the RGBA components for a given pixel format
+ *  \brief Maps a pixel value into the RGBA components for a given pixel format.
  *  
  *  \sa SDL_GetRGB
  */

include/SDL_platform.h

@@ -20,7 +20,11 @@
     slouken@libsdl.org
 */
 
-/* Try to get a standard set of platform defines */
+/**
+ *  \file SDL_platform.h
+ *  
+ *  Try to get a standard set of platform defines.
+ */
 
 #ifndef _SDL_platform_h
 #define _SDL_platform_h
@@ -133,7 +137,6 @@ extern "C" {
 #endif
 
 /**
- * \fn const char *SDL_GetPlatform(void)
  *  \brief Gets the name of the platform.
  */
 extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);

include/SDL_power.h

@@ -26,7 +26,7 @@
 /**
  *  \file SDL_power.h
  *  
- * Header for the SDL power management routines
+ *  Header for the SDL power management routines.
  */
 
 #include "SDL_stdinc.h"
@@ -40,8 +40,6 @@ extern "C" {
 #endif
 
 /**
- * \enum SDL_PowerState
- *
  *  \brief The basic state for the system's power supply.
  */
 typedef enum
@@ -55,8 +53,6 @@ typedef enum
 
 
 /**
- * \fn int SDL_GetPowerInfo(void)
- *
  *  \brief Get the current power supply details.
  *  
  *  \param secs Seconds of battery life left. You can pass a NULL here if

include/SDL_quit.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_quit.h
  *  
- * Include file for SDL quit event handling
+ *  Include file for SDL quit event handling.
  */
 
 #ifndef _SDL_quit_h
@@ -32,22 +32,27 @@
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
 
-/* 
-  An SDL_QUITEVENT is generated when the user tries to close the application
-  window.  If it is ignored or filtered out, the window will remain open.
-  If it is not ignored or filtered, it is queued normally and the window
-  is allowed to close.  When the window is closed, screen updates will 
-  complete, but have no effect.
-
-  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
-  and SIGTERM (system termination request), if handlers do not already
-  exist, that generate SDL_QUITEVENT events as well.  There is no way
-  to determine the cause of an SDL_QUITEVENT, but setting a signal
-  handler in your application will override the default generation of
-  quit events for that signal.
-*/
+/**
+ *  \file SDL_quit.h
+ *  
+ *  An ::SDL_QUIT event is generated when the user tries to close the application
+ *  window.  If it is ignored or filtered out, the window will remain open.
+ *  If it is not ignored or filtered, it is queued normally and the window
+ *  is allowed to close.  When the window is closed, screen updates will 
+ *  complete, but have no effect.
+ *
+ *  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
+ *  and SIGTERM (system termination request), if handlers do not already
+ *  exist, that generate ::SDL_QUIT events as well.  There is no way
+ *  to determine the cause of an ::SDL_QUIT event, but setting a signal
+ *  handler in your application will override the default generation of
+ *  quit events for that signal.
+ *  
+ *  \sa SDL_Quit()
+ */
 
 /* There are no functions directly affecting the quit event */
+
 #define SDL_QuitRequested() \
         (SDL_PumpEvents(), SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUITMASK))
 

include/SDL_rect.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_rect.h
  *  
- * Header file for SDL_rect definition and management functions
+ *  Header file for SDL_rect definition and management functions.
  */
 
 #ifndef _SDL_rect_h
@@ -43,8 +43,6 @@ extern "C" {
 #endif
 
 /**
- * \struct SDL_Rect
- *
  *  \brief A rectangle, with the origin at the upper left.
  *  
  *  \sa SDL_RectEmpty
@@ -60,23 +58,17 @@ typedef struct SDL_Rect
 } SDL_Rect;
 
 /**
- * \def SDL_RectEmpty()
- *
  *  \brief Returns true if the rectangle has no area.
  */
 #define SDL_RectEmpty(X)    (((X)->w <= 0) || ((X)->h <= 0))
 
 /**
- * \def SDL_RectEquals()
- *
  *  \brief Returns true if the two rectangles are equal.
  */
 #define SDL_RectEquals(A, B)   (((A)->x == (B)->x) && ((A)->y == (B)->y) && \
                                 ((A)->w == (B)->w) && ((A)->h == (B)->h))
 
 /**
- * \fn SDL_bool SDL_HasIntersection(const SDL_Rect * A, const SDL_Rect * B);
- *
  *  \brief Determine whether two rectangles intersect.
  *  
  *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
@@ -85,8 +77,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
                                                      const SDL_Rect * B);
 
 /**
- * \fn SDL_bool SDL_IntersectRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
- *
  *  \brief Calculate the intersection of two rectangles.
  *  
  *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
@@ -96,17 +86,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
                                                    SDL_Rect * result);
 
 /**
- * \fn void SDL_UnionRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
- *
- * \brief Calculate the union of two rectangles
+ *  \brief Calculate the union of two rectangles.
  */
 extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
                                            const SDL_Rect * B,
                                            SDL_Rect * result);
 
 /**
- * \fn SDL_bool SDL_IntersectRectAndLine(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2)
- *
  *  \brief Calculate the intersection of a rectangle and line segment.
  *  
  *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

include/SDL_rwops.h

@@ -41,33 +41,42 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* This is the read/write operation structure -- very basic */
-
+/**
+ * This is the read/write operation structure -- very basic.
+ */
 typedef struct SDL_RWops
 {
-    /* Seek to 'offset' relative to whence, one of stdio's whence values:
-       RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
-       Returns the final offset in the data source.
+    /**
+     *  Seek to \c offset relative to \c whence, one of stdio's whence values:
+     *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
+     *  
+     *  \return the final offset in the data source.
      */
     long (SDLCALL * seek) (struct SDL_RWops * context, long offset,
                            int whence);
 
-    /* Read up to 'num' objects each of size 'objsize' from the data
-       source to the area pointed at by 'ptr'.
-       Returns the number of objects read, or 0 at error or end of file.
+    /**
+     *  Read up to \c num objects each of size \c objsize from the data
+     *  source to the area pointed at by \c ptr.
+     *  
+     *  \return the number of objects read, or 0 at error or end of file.
      */
     size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr,
                             size_t size, size_t maxnum);
 
-    /* Write exactly 'num' objects each of size 'objsize' from the area
-       pointed at by 'ptr' to data source.
-       Returns the number of objects written, or 0 at error or end of file.
+    /**
+     *  Write exactly \c num objects each of size \c objsize from the area
+     *  pointed at by \c ptr to data source.
+     *  
+     *  \return the number of objects written, or 0 at error or end of file.
      */
     size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
                              size_t size, size_t num);
 
-    /* Close and free an allocated SDL_RWops structure.
-       Returns 0 if successful or -1 on write error when flushing data.
+    /**
+     *  Close and free an allocated SDL_RWops structure.
+     *  
+     *  \return 0 if successful or -1 on write error when flushing data.
      */
     int (SDLCALL * close) (struct SDL_RWops * context);
 
@@ -109,7 +118,12 @@ typedef struct SDL_RWops
 } SDL_RWops;
 
 
-/* Functions to create SDL_RWops structures from various data sources */
+/**
+ *  \name RWFrom functions
+ *  
+ *  Functions to create SDL_RWops structures from various data sources.
+ */
+/*@{*/
 
 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
                                                   const char *mode);
@@ -123,36 +137,57 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
                                                       int size);
 
+/*@}*//*RWFrom functions*/
+
+
 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
 
-#define RW_SEEK_SET	0       /* Seek from the beginning of data */
-#define RW_SEEK_CUR	1       /* Seek relative to current read point */
-#define RW_SEEK_END	2       /* Seek relative to the end of data */
+#define RW_SEEK_SET	0       /**< Seek from the beginning of data */
+#define RW_SEEK_CUR	1       /**< Seek relative to current read point */
+#define RW_SEEK_END	2       /**< Seek relative to the end of data */
 
-/* Macros to easily read and write from an SDL_RWops structure */
+/**
+ *  \name Read/write macros
+ *  
+ *  Macros to easily read and write from an SDL_RWops structure.
+ */
+/*@{*/
 #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
 #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
 #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
 #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
 #define SDL_RWclose(ctx)		(ctx)->close(ctx)
+/*@}*//*Read/write macros*/
 
 
-/* Read an item of the specified endianness and return in native format */
+/** 
+ *  \name Read endian functions
+ *  
+ *  Read an item of the specified endianness and return in native format.
+ */
+/*@{*/
 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
+/*@}*//*Read endian functions*/
 
-/* Write an item of native format to the specified endianness */
+/** 
+ *  \name Write endian functions
+ *  
+ *  Write an item of native format to the specified endianness.
+ */
+/*@{*/
 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
+/*@}*//*Write endian functions*/
 
 
 /* Ends C function definitions when using C++ */

include/SDL_scancode.h

@@ -22,6 +22,8 @@
 
 /**
  *  \file SDL_scancode.h
+ *  
+ *  Defines keyboard scancodes.
  */
 
 #ifndef _SDL_scancode_h
@@ -30,8 +32,6 @@
 #include "SDL_stdinc.h"
 
 /**
- * \enum SDL_scancode
- *
  *  \brief The SDL keyboard scancode representation.
  *  
  *  Values of this type are used to represent keyboard keys, among other places
@@ -45,7 +45,12 @@ typedef enum
 {
     SDL_SCANCODE_UNKNOWN = 0,
 
-    /* These values are from usage page 0x07 (USB keyboard page) */
+    /** 
+     *  \name Usage page 0x07
+     *  
+     *  These values are from usage page 0x07 (USB keyboard page).
+     */
+    /*@{*/
 
     SDL_SCANCODE_A = 4,
     SDL_SCANCODE_B = 5,
@@ -95,11 +100,51 @@ typedef enum
     SDL_SCANCODE_EQUALS = 46,
     SDL_SCANCODE_LEFTBRACKET = 47,
     SDL_SCANCODE_RIGHTBRACKET = 48,
-    SDL_SCANCODE_BACKSLASH = 49, /**< Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout. */
-    SDL_SCANCODE_NONUSHASH = 50, /**< ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDL_SCANCODE_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards. */
+    SDL_SCANCODE_BACKSLASH = 49, /**< Located at the lower left of the return 
+                                  *   key on ISO keyboards and at the right end 
+                                  *   of the QWERTY row on ANSI keyboards. 
+                                  *   Produces REVERSE SOLIDUS (backslash) and 
+                                  *   VERTICAL LINE in a US layout, REVERSE 
+                                  *   SOLIDUS and VERTICAL LINE in a UK Mac 
+                                  *   layout, NUMBER SIGN and TILDE in a UK 
+                                  *   Windows layout, DOLLAR SIGN and POUND SIGN
+                                  *   in a Swiss German layout, NUMBER SIGN and 
+                                  *   APOSTROPHE in a German layout, GRAVE 
+                                  *   ACCENT and POUND SIGN in a French Mac 
+                                  *   layout, and ASTERISK and MICRO SIGN in a 
+                                  *   French Windows layout.
+                                  */
+    SDL_SCANCODE_NONUSHASH = 50, /**< ISO USB keyboards actually use this code 
+                                  *   instead of 49 for the same key, but all 
+                                  *   OSes I've seen treat the two codes 
+                                  *   identically. So, as an implementor, unless
+                                  *   your keyboard generates both of those 
+                                  *   codes and your OS treats them differently,
+                                  *   you should generate SDL_SCANCODE_BACKSLASH
+                                  *   instead of this code. As a user, you 
+                                  *   should not rely on this code because SDL 
+                                  *   will never generate it with most (all?) 
+                                  *   keyboards. 
+                                  */
     SDL_SCANCODE_SEMICOLON = 51,
     SDL_SCANCODE_APOSTROPHE = 52,
-    SDL_SCANCODE_GRAVE = 53, /**< Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards. */
+    SDL_SCANCODE_GRAVE = 53, /**< Located in the top left corner (on both ANSI 
+                              *   and ISO keyboards). Produces GRAVE ACCENT and 
+                              *   TILDE in a US Windows layout and in US and UK 
+                              *   Mac layouts on ANSI keyboards, GRAVE ACCENT 
+                              *   and NOT SIGN in a UK Windows layout, SECTION 
+                              *   SIGN and PLUS-MINUS SIGN in US and UK Mac 
+                              *   layouts on ISO keyboards, SECTION SIGN and 
+                              *   DEGREE SIGN in a Swiss German layout (Mac: 
+                              *   only on ISO keyboards), CIRCUMFLEX ACCENT and 
+                              *   DEGREE SIGN in a German layout (Mac: only on 
+                              *   ISO keyboards), SUPERSCRIPT TWO and TILDE in a
+                              *   French Windows layout, COMMERCIAL AT and 
+                              *   NUMBER SIGN in a French Mac layout on ISO 
+                              *   keyboards, and LESS-THAN SIGN and GREATER-THAN
+                              *   SIGN in a Swiss German, German, or French Mac 
+                              *   layout on ANSI keyboards.
+                              */
     SDL_SCANCODE_COMMA = 54,
     SDL_SCANCODE_PERIOD = 55,
     SDL_SCANCODE_SLASH = 56,
@@ -122,7 +167,8 @@ typedef enum
     SDL_SCANCODE_PRINTSCREEN = 70,
     SDL_SCANCODE_SCROLLLOCK = 71,
     SDL_SCANCODE_PAUSE = 72,
-    SDL_SCANCODE_INSERT = 73, /**< insert on PC, help on some Mac keyboards (but does send code 73, not 117) */
+    SDL_SCANCODE_INSERT = 73, /**< insert on PC, help on some Mac keyboards (but
+                                   does send code 73, not 117) */
     SDL_SCANCODE_HOME = 74,
     SDL_SCANCODE_PAGEUP = 75,
     SDL_SCANCODE_DELETE = 76,
@@ -133,7 +179,8 @@ typedef enum
     SDL_SCANCODE_DOWN = 81,
     SDL_SCANCODE_UP = 82,
 
-    SDL_SCANCODE_NUMLOCKCLEAR = 83, /**< num lock on PC, clear on Mac keyboards */
+    SDL_SCANCODE_NUMLOCKCLEAR = 83, /**< num lock on PC, clear on Mac keyboards 
+                                     */
     SDL_SCANCODE_KP_DIVIDE = 84,
     SDL_SCANCODE_KP_MULTIPLY = 85,
     SDL_SCANCODE_KP_MINUS = 86,
@@ -151,9 +198,20 @@ typedef enum
     SDL_SCANCODE_KP_0 = 98,
     SDL_SCANCODE_KP_PERIOD = 99,
 
-    SDL_SCANCODE_NONUSBACKSLASH = 100, /**< This is the additional key that ISO keyboards have over ANSI ones, located between left shift and Y. Produces GRAVE ACCENT and TILDE in a US or UK Mac layout, REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US or UK Windows layout, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French layout. */
+    SDL_SCANCODE_NONUSBACKSLASH = 100, /**< This is the additional key that ISO 
+                                        *   keyboards have over ANSI ones, 
+                                        *   located between left shift and Y. 
+                                        *   Produces GRAVE ACCENT and TILDE in a
+                                        *   US or UK Mac layout, REVERSE SOLIDUS
+                                        *   (backslash) and VERTICAL LINE in a 
+                                        *   US or UK Windows layout, and 
+                                        *   LESS-THAN SIGN and GREATER-THAN SIGN
+                                        *   in a Swiss German, German, or French
+                                        *   layout. */
     SDL_SCANCODE_APPLICATION = 101, /**< windows contextual menu, compose */
-    SDL_SCANCODE_POWER = 102, /**< The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key. */
+    SDL_SCANCODE_POWER = 102, /**< The USB document says this is a status flag, 
+                               *   not a physical key - but some Mac keyboards 
+                               *   do have a power key. */
     SDL_SCANCODE_KP_EQUALS = 103,
     SDL_SCANCODE_F13 = 104,
     SDL_SCANCODE_F14 = 105,
@@ -172,7 +230,7 @@ typedef enum
     SDL_SCANCODE_MENU = 118,
     SDL_SCANCODE_SELECT = 119,
     SDL_SCANCODE_STOP = 120,
-    SDL_SCANCODE_AGAIN = 121,   /*!< redo */
+    SDL_SCANCODE_AGAIN = 121,   /**< redo */
     SDL_SCANCODE_UNDO = 122,
     SDL_SCANCODE_CUT = 123,
     SDL_SCANCODE_COPY = 124,
@@ -188,7 +246,8 @@ typedef enum
     SDL_SCANCODE_KP_COMMA = 133,
     SDL_SCANCODE_KP_EQUALSAS400 = 134,
 
-    SDL_SCANCODE_INTERNATIONAL1 = 135, /**< used on Asian keyboards, see footnotes in USB doc */
+    SDL_SCANCODE_INTERNATIONAL1 = 135, /**< used on Asian keyboards, see 
+                                            footnotes in USB doc */
     SDL_SCANCODE_INTERNATIONAL2 = 136,
     SDL_SCANCODE_INTERNATIONAL3 = 137, /**< Yen */
     SDL_SCANCODE_INTERNATIONAL4 = 138,
@@ -276,9 +335,19 @@ typedef enum
     SDL_SCANCODE_RALT = 230, /**< alt gr, option */
     SDL_SCANCODE_RGUI = 231, /**< windows, command (apple), meta */
 
-    SDL_SCANCODE_MODE = 257,    /* I'm not sure if this is really not covered by any of the above, but since there's a special KMOD_MODE for it I'm adding it here */
+    SDL_SCANCODE_MODE = 257,    /**< I'm not sure if this is really not covered 
+                                 *   by any of the above, but since there's a 
+                                 *   special KMOD_MODE for it I'm adding it here
+                                 */
+    
+    /*@}*//*Usage page 0x07*/
 
-    /* These values are mapped from usage page 0x0C (USB consumer page) */
+    /**
+     *  \name Usage page 0x0C
+     *  
+     *  These values are mapped from usage page 0x0C (USB consumer page).
+     */
+    /*@{*/
 
     SDL_SCANCODE_AUDIONEXT = 258,
     SDL_SCANCODE_AUDIOPREV = 259,
@@ -298,20 +367,31 @@ typedef enum
     SDL_SCANCODE_AC_REFRESH = 273,
     SDL_SCANCODE_AC_BOOKMARKS = 274,
     
-    /* These are values that Christian Walther added (for mac keyboard?) */
+    /*@}*//*Usage page 0x0C*/
+
+    /**
+     *  \name Walther keys
+     *  
+     *  These are values that Christian Walther added (for mac keyboard?).
+     */
+    /*@{*/
 
     SDL_SCANCODE_BRIGHTNESSDOWN = 275,
     SDL_SCANCODE_BRIGHTNESSUP = 276,
-    SDL_SCANCODE_DISPLAYSWITCH = 277, /**< display mirroring/dual display switch, video mode switch */
+    SDL_SCANCODE_DISPLAYSWITCH = 277, /**< display mirroring/dual display 
+                                           switch, video mode switch */
     SDL_SCANCODE_KBDILLUMTOGGLE = 278,
     SDL_SCANCODE_KBDILLUMDOWN = 279,
     SDL_SCANCODE_KBDILLUMUP = 280,
     SDL_SCANCODE_EJECT = 281,
     SDL_SCANCODE_SLEEP = 282,
     
-    /* Add any other keys here */
+    /*@}*//*Walther keys*/
+
+    /* Add any other keys here. */
 
-    SDL_NUM_SCANCODES = 512 /**< (not a key, just marks the number of scancodes for array bounds) */
+    SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes 
+                                 for array bounds */
 } SDL_scancode;
 
 #endif /* _SDL_scancode_h */

include/SDL_stdinc.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_stdinc.h
  *  
- * This is a general header that includes C language support
+ *  This is a general header that includes C language support.
  */
 
 #ifndef _SDL_stdinc_h
@@ -79,12 +79,19 @@
 # include <iconv.h>
 #endif
 
-/* The number of elements in an array */
+/**
+ *  The number of elements in an array.
+ */
 #define SDL_arraysize(array)	(sizeof(array)/sizeof(array[0]))
 #define SDL_TABLESIZE(table)	SDL_arraysize(table)
 
-/* Use proper C++ casts when compiled as C++ to be compatible with the option
- -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above. */
+/**
+ *  \name Cast operators
+ *  
+ *  Use proper C++ casts when compiled as C++ to be compatible with the option
+ *  -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above).
+ */
+/*@{*/
 #ifdef __cplusplus
 #define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
 #define SDL_static_cast(type, expression) static_cast<type>(expression)
@@ -92,8 +99,13 @@
 #define SDL_reinterpret_cast(type, expression) ((type)(expression))
 #define SDL_static_cast(type, expression) ((type)(expression))
 #endif
+/*@}*//*Cast operators*/
+
+/**
+ *  \name Basic data types
+ */
+/*@{*/
 
-/* Basic data types */
 typedef enum
 {
     SDL_FALSE = 0,
@@ -101,45 +113,37 @@ typedef enum
 } SDL_bool;
 
 /**
- * \typedef Sint8
  * \brief A signed 8-bit integer type.
  */
 typedef int8_t Sint8;
 /**
- * \typedef Uint8
  * \brief An unsigned 8-bit integer type.
  */
 typedef uint8_t Uint8;
 /**
- * \typedef Sint16
  * \brief A signed 16-bit integer type.
  */
 typedef int16_t Sint16;
 /**
- * \typedef Uint16
  * \brief An unsigned 16-bit integer type.
  */
 typedef uint16_t Uint16;
 /**
- * \typedef Sint32
  * \brief A signed 32-bit integer type.
  */
 typedef int32_t Sint32;
 /**
- * \typedef Uint32
  * \brief An unsigned 32-bit integer type.
  */
 typedef uint32_t Uint32;
 
 #ifdef SDL_HAS_64BIT_TYPE
 /**
- * \typedef Sint64
  * \brief A signed 64-bit integer type.
  * \warning On platforms without any sort of 64-bit datatype, this is equivalent to Sint32!
  */
 typedef int64_t Sint64;
 /**
- * \typedef Uint64
  * \brief An unsigned 64-bit integer type.
  * \warning On platforms without any sort of 64-bit datatype, this is equivalent to Uint32!
  */
@@ -150,9 +154,12 @@ typedef Sint32 Sint64;
 typedef Uint32 Uint64;
 #endif
 
-/* Make sure the types really have the right sizes */
+/*@}*//*Basic data types*/
+
+
 #define SDL_COMPILE_TIME_ASSERT(name, x)               \
        typedef int SDL_dummy_ ## name[(x) * 2 - 1]
+/** \cond */
 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
 SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1);
 SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1);
@@ -167,6 +174,7 @@ SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8);
 SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
 #endif
 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
+/** \endcond */
 
 /* Check to make sure enums are the size of ints, for structure packing.
    For both Watcom C/C++ and Borland C/C++ the compiler option that makes
@@ -178,6 +186,7 @@ SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
 #pragma enumsalwaysint on
 #endif
 
+/** \cond */
 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
 #ifndef __NINTENDODS__          /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */
 typedef enum
@@ -188,6 +197,7 @@ typedef enum
 SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
 #endif
 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
+/** \endcond */
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -748,9 +758,10 @@ extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
 extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
                                          size_t * inbytesleft, char **outbuf,
                                          size_t * outbytesleft);
-/* This function converts a string between encodings in one pass, returning a
-   string that must be freed with SDL_free() or NULL on error.
-*/
+/**
+ *  This function converts a string between encodings in one pass, returning a
+ *  string that must be freed with SDL_free() or NULL on error.
+ */
 extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
                                                const char *fromcode,
                                                const char *inbuf,

include/SDL_surface.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_surface.h
  *  
- * Header file for SDL_surface definition and management functions
+ *  Header file for ::SDL_surface definition and management functions.
  */
 
 #ifndef _SDL_surface_h
@@ -42,21 +42,28 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/** These are the currently supported flags for the SDL_surface
- *  \internal Used internally (read-only) 
+/**
+ *  \name Surface flags
+ *  
+ *  These are the currently supported flags for the ::SDL_surface.
+ *  
+ *  \internal
+ *  Used internally (read-only).
  */
 /*@{*/
 #define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
 #define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
-/*@}*/
+/*@}*//*Surface flags*/
 
-/** Evaluates to true if the surface needs to be locked before access */
+/**
+ *  Evaluates to true if the surface needs to be locked before access.
+ */
 #define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
 
 /**
- * \brief A collection of pixels used in software blitting
+ * \brief A collection of pixels used in software blitting.
  *
- * \note  This structure should be treated as read-only, except for 'pixels',
+ * \note  This structure should be treated as read-only, except for \c pixels,
  *        which, if not NULL, contains the raw pixel data for the surface.
  */
 typedef struct SDL_Surface
@@ -67,40 +74,42 @@ typedef struct SDL_Surface
     int pitch;                  /**< Read-only */
     void *pixels;               /**< Read-write */
 
-    /* Application data associated with the surfade */
+    /** Application data associated with the surfade */
     void *userdata;             /**< Read-write */
 
-    /* information needed for surfaces requiring locks */
+    /** information needed for surfaces requiring locks */
     int locked;                 /**< Read-only */
     void *lock_data;            /**< Read-only */
 
-    /* clipping information */
+    /** clipping information */
     SDL_Rect clip_rect;         /**< Read-only */
 
-    /* info for fast blit mapping to other surfaces */
+    /** info for fast blit mapping to other surfaces */
     struct SDL_BlitMap *map;    /**< Private */
 
-    /* format version, bumped at every change to invalidate blit maps */
+    /** format version, bumped at every change to invalidate blit maps */
     unsigned int format_version;        /**< Private */
 
-    /* Reference count -- used when freeing surface */
+    /** Reference count -- used when freeing surface */
     int refcount;               /**< Read-mostly */
 } SDL_Surface;
 
 /**
- * \brief The type of function used for surface blitting functions
+ * \brief The type of function used for surface blitting functions.
  */
 typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
                          struct SDL_Surface * dst, SDL_Rect * dstrect);
 
 /**
- * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
+ *  Allocate and free an RGB surface (must be called after SDL_SetVideoMode).
+ *  
  *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
  *  If the depth is greater than 8 bits, the pixel format is set using the
  *  flags '[RGB]mask'.
+ *  
  *  If the function runs out of memory, it will return NULL.
  *  
- * \param flags The 'flags' are obsolete and should be set to 0.
+ *  \param flags The \c flags are obsolete and should be set to 0.
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
     (Uint32 flags, int width, int height, int depth,
@@ -129,9 +138,9 @@ extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
 /**
  *  \brief Sets up a surface for directly accessing the pixels.
  *  
- * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
- * to and read from 'surface->pixels', using the pixel format stored in 
- * 'surface->format'.  Once you are done accessing the surface, you should 
+ *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
+ *  to and read from \c surface->pixels, using the pixel format stored in 
+ *  \c surface->format.  Once you are done accessing the surface, you should 
  *  use SDL_UnlockSurface() to release it.
  *  
  *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
@@ -150,26 +159,39 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
 
 /**
- * Load a surface from a seekable SDL data source (memory or file.)
- * If 'freesrc' is non-zero, the source will be closed after being read.
- * Returns the new surface, or NULL if there was an error.
+ *  Load a surface from a seekable SDL data source (memory or file).
+ *  
+ *  If \c freesrc is non-zero, the source will be closed after being read.
+ *  
  *  The new surface should be freed with SDL_FreeSurface().
+ *  
+ *  \return the new surface, or NULL if there was an error.
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
                                                     int freesrc);
 
-/** Convenience macro -- load a surface from a file */
+/**
+ *  Load a surface from a file.
+ *  
+ *  Convenience macro.
+ */
 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
 
 /**
- * Save a surface to a seekable SDL data source (memory or file.)
- * If 'freedst' is non-zero, the source will be closed after being written.
- * Returns 0 if successful or -1 if there was an error.
+ *  Save a surface to a seekable SDL data source (memory or file).
+ *  
+ *  If \c freedst is non-zero, the source will be closed after being written.
+ *  
+ *  \return 0 if successful or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
     (SDL_Surface * surface, SDL_RWops * dst, int freedst);
 
-/** Convenience macro -- save a surface to a file */
+/** 
+ *  Save a surface to a file.
+ *  
+ *  Convenience macro.
+ */
 #define SDL_SaveBMP(surface, file) \
 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
 
@@ -200,22 +222,24 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
  *  \brief Sets the color key (transparent pixel) in a blittable surface.
  *  
  *  \param surface The surface to update
- * \param key A pointer filled in with the transparent pixel in the native surface format
+ *  \param key A pointer filled in with the transparent pixel in the native 
+ *             surface format
  *  
- * \return 0 on success, or -1 if the surface is not valid or colorkey is not enabled.
+ *  \return 0 on success, or -1 if the surface is not valid or colorkey is not 
+ *          enabled.
  */
 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
                                             Uint32 * key);
 
 /**
- * \brief Set an additional color value used in blit operations
+ *  \brief Set an additional color value used in blit operations.
  *  
- * \param surface The surface to update
- * \param r The red source color value multiplied into blit operations
- * \param g The green source color value multiplied into blit operations
- * \param b The blue source color value multiplied into blit operations
+ *  \param surface The surface to update.
+ *  \param r The red source color value multiplied into blit operations.
+ *  \param g The green source color value multiplied into blit operations.
+ *  \param b The blue source color value multiplied into blit operations.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_GetSurfaceColorMod()
  */
@@ -224,14 +248,14 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
 
 
 /**
- * \brief Get the additional color value used in blit operations
+ *  \brief Get the additional color value used in blit operations.
  *  
- * \param surface The surface to query
- * \param r A pointer filled in with the source red color value
- * \param g A pointer filled in with the source green color value
- * \param b A pointer filled in with the source blue color value
+ *  \param surface The surface to query.
+ *  \param r A pointer filled in with the source red color value.
+ *  \param g A pointer filled in with the source green color value.
+ *  \param b A pointer filled in with the source blue color value.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_SetSurfaceColorMod()
  */
@@ -240,12 +264,12 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
                                                    Uint8 * b);
 
 /**
- * \brief Set an additional alpha value used in blit operations
+ *  \brief Set an additional alpha value used in blit operations.
  *  
- * \param surface The surface to update
+ *  \param surface The surface to update.
  *  \param alpha The source alpha value multiplied into blit operations.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_GetSurfaceAlphaMod()
  */
@@ -253,12 +277,12 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
                                                    Uint8 alpha);
 
 /**
- * \brief Get the additional alpha value used in blit operations
+ *  \brief Get the additional alpha value used in blit operations.
  *  
- * \param surface The surface to query
- * \param alpha A pointer filled in with the source alpha value
+ *  \param surface The surface to query.
+ *  \param alpha A pointer filled in with the source alpha value.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_SetSurfaceAlphaMod()
  */
@@ -266,12 +290,12 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
                                                    Uint8 * alpha);
 
 /**
- * \brief Set the blend mode used for blit operations
+ *  \brief Set the blend mode used for blit operations.
  *  
- * \param surface The surface to update
- * \param blendMode SDL_TextureBlendMode to use for blit blending
+ *  \param surface The surface to update.
+ *  \param blendMode ::SDL_BlendMode to use for blit blending.
  *  
- * \return 0 on success, or -1 if the parameters are not valid
+ *  \return 0 on success, or -1 if the parameters are not valid.
  *  
  *  \sa SDL_GetSurfaceBlendMode()
  */
@@ -279,12 +303,12 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
                                                     int blendMode);
 
 /**
- * \brief Get the blend mode used for blit operations
+ *  \brief Get the blend mode used for blit operations.
  *  
- * \param surface The surface to query
- * \param blendMode A pointer filled in with the current blend mode
+ *  \param surface   The surface to query.
+ *  \param blendMode A pointer filled in with the current blend mode.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_SetSurfaceBlendMode()
  */
@@ -292,14 +316,17 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
                                                     int *blendMode);
 
 /**
- * \brief Set the scale mode used for blit operations
+ *  \brief Set the scale mode used for blit operations.
  *  
- * \param surface The surface to update
- * \param scaleMode SDL_TextureScaleMode to use for blit scaling
+ *  \param surface   The surface to update.
+ *  \param scaleMode ::SDL_TextureScaleMode to use for blit scaling.
  *  
- * \return 0 on success, or -1 if the surface is not valid or the scale mode is not supported
+ *  \return 0 on success, or -1 if the surface is not valid or the scale mode is
+ *          not supported.
  *  
- * \note If the scale mode is not supported, the closest supported mode is chosen.  Currently only SDL_TEXTURESCALEMODE_FAST is supported on surfaces.
+ *  \note If the scale mode is not supported, the closest supported mode is 
+ *        chosen.  Currently only ::SDL_TEXTURESCALEMODE_FAST is supported on 
+ *        surfaces.
  *  
  *  \sa SDL_GetSurfaceScaleMode()
  */
@@ -307,12 +334,12 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
                                                     int scaleMode);
 
 /**
- * \brief Get the scale mode used for blit operations
+ *  \brief Get the scale mode used for blit operations.
  *  
- * \param surface The surface to query
- * \param scaleMode A pointer filled in with the current scale mode
+ *  \param surface   The surface to query.
+ *  \param scaleMode A pointer filled in with the current scale mode.
  *  
- * \return 0 on success, or -1 if the surface is not valid
+ *  \return 0 on success, or -1 if the surface is not valid.
  *  
  *  \sa SDL_SetSurfaceScaleMode()
  */
@@ -323,6 +350,7 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
  *  Sets the clipping rectangle for the destination surface in a blit.
  *  
  *  If the clip rectangle is NULL, clipping will be disabled.
+ *  
  *  If the clip rectangle doesn't intersect the surface, the function will
  *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
  *  function returns SDL_TRUE and blits to the surface will be clipped to
@@ -336,7 +364,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
 
 /**
  *  Gets the clipping rectangle for the destination surface in a blit.
- * 'rect' must be a pointer to a valid rectangle which will be filled
+ *  
+ *  \c rect must be a pointer to a valid rectangle which will be filled
  *  with the correct values.
  */
 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
@@ -347,8 +376,8 @@ extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
  *  the given surface to it so the blit of the converted surface will be as 
  *  fast as possible.  If this function fails, it returns NULL.
  *  
- * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
- * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
+ *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
+ *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
  *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
  *  surface.
  *  
@@ -358,58 +387,72 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
     (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
 
 /**
- * This function draws a point with 'color'
+ *  Draws a point with \c color.
+ *
  *  The color should be a pixel of the format used by the surface, and 
  *  can be generated by the SDL_MapRGB() function.
- * \return This function returns 0 on success, or -1 on error.
+ *  
+ *  \return 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_DrawPoint
     (SDL_Surface * dst, int x, int y, Uint32 color);
 
 /**
- * This function blends a point with an RGBA value
+ *  Blends a point with an RGBA value.
+ *  
  *  The color should be a pixel of the format used by the surface, and 
  *  can be generated by the SDL_MapRGB() function.
- * \return This function returns 0 on success, or -1 on error.
+ *  
+ *  \return 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_BlendPoint
     (SDL_Surface * dst, int x, int y, int blendMode,
      Uint8 r, Uint8 g, Uint8 b, Uint8 a);
 
 /**
- * This function draws a line with 'color'
+ *  Draws a line with \c color.
+ *  
  *  The color should be a pixel of the format used by the surface, and 
  *  can be generated by the SDL_MapRGB() function.
- * \return This function returns 0 on success, or -1 on error.
+ *  
+ *  \return 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_DrawLine
     (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
 
 /**
- * This function blends an RGBA value along a line
- * \return This function returns 0 on success, or -1 on error.
+ *  Blends an RGBA value along a line.
+ *  
+ *  \return 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_BlendLine
     (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
      Uint8 r, Uint8 g, Uint8 b, Uint8 a);
 
 /**
- * This function performs a fast fill of the given rectangle with 'color'
+ *  Performs a fast fill of the given rectangle with \c color.
+ *  
  *  The given rectangle is clipped to the destination surface clip area
  *  and the final fill rectangle is saved in the passed in pointer.
- * If 'dstrect' is NULL, the whole surface will be filled with 'color'
+ *  
+ *  If \c dstrect is NULL, the whole surface will be filled with \c color.
+ *  
  *  The color should be a pixel of the format used by the surface, and 
  *  can be generated by the SDL_MapRGB() function.
- * \return This function returns 0 on success, or -1 on error.
+ *  
+ *  \return 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_FillRect
     (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
 
 /**
- * This function blends an RGBA value into the given rectangle.
+ *  Blends an RGBA value into the given rectangle.
+ *  
  *  The given rectangle is clipped to the destination surface clip area
  *  and the final fill rectangle is saved in the passed in pointer.
- * If 'dstrect' is NULL, the whole surface will be filled with 'color'
+ *  
+ *  If \c dstrect is NULL, the whole surface will be filled with \c color.
+ *  
  *  \return This function returns 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_BlendRect
@@ -417,57 +460,60 @@ extern DECLSPEC int SDLCALL SDL_BlendRect
      Uint8 b, Uint8 a);
 
 /**
- * This performs a fast blit from the source surface to the destination
- * surface.  It assumes that the source and destination rectangles are
- * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
- * surface (src or dst) is copied.  The final blit rectangles are saved
- * in 'srcrect' and 'dstrect' after all clipping is performed.
- * If the blit is successful, it returns 0, otherwise it returns -1.
+ *  Performs a fast blit from the source surface to the destination surface.
+ *  
+ *  This assumes that the source and destination rectangles are
+ *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
+ *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
+ *  in \c srcrect and \c dstrect after all clipping is performed.
+ *  
+ *  \return If the blit is successful, it returns 0, otherwise it returns -1.
  *
  *  The blit function should not be called on a locked surface.
  *
  *  The blit semantics for surfaces with and without alpha and colorkey
  *  are defined as follows:
- *
- * RGBA->RGB:
- *     SDL_SRCALPHA set:
- * 	alpha-blend (using alpha-channel).
- * 	SDL_SRCCOLORKEY ignored.
- *     SDL_SRCALPHA not set:
- * 	copy RGB.
- * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
- * 	RGB values of the source colour key, ignoring alpha in the
- * 	comparison.
- * 
- * RGB->RGBA:
- *     SDL_SRCALPHA set:
- * 	alpha-blend (using the source per-surface alpha value);
- * 	set destination alpha to opaque.
- *     SDL_SRCALPHA not set:
- * 	copy RGB, set destination alpha to source per-surface alpha value.
- *     both:
- * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
- * 	source colour key.
- * 
- * RGBA->RGBA:
- *     SDL_SRCALPHA set:
- * 	alpha-blend (using the source alpha channel) the RGB values;
- * 	leave destination alpha untouched. [Note: is this correct?]
- * 	SDL_SRCCOLORKEY ignored.
- *     SDL_SRCALPHA not set:
- * 	copy all of RGBA to the destination.
- * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
- * 	RGB values of the source colour key, ignoring alpha in the
- * 	comparison.
- * 
- * RGB->RGB: 
- *     SDL_SRCALPHA set:
- * 	alpha-blend (using the source per-surface alpha value).
- *     SDL_SRCALPHA not set:
- * 	copy RGB.
- *     both:
- * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
- * 	source colour key.
+ *  \verbatim
+    RGBA->RGB:
+      SDL_SRCALPHA set:
+        alpha-blend (using alpha-channel).
+        SDL_SRCCOLORKEY ignored.
+      SDL_SRCALPHA not set:
+        copy RGB.
+        if SDL_SRCCOLORKEY set, only copy the pixels matching the
+        RGB values of the source colour key, ignoring alpha in the
+        comparison.
+   
+    RGB->RGBA:
+      SDL_SRCALPHA set:
+        alpha-blend (using the source per-surface alpha value);
+        set destination alpha to opaque.
+      SDL_SRCALPHA not set:
+        copy RGB, set destination alpha to source per-surface alpha value.
+      both:
+        if SDL_SRCCOLORKEY set, only copy the pixels matching the
+        source colour key.
+   
+    RGBA->RGBA:
+      SDL_SRCALPHA set:
+        alpha-blend (using the source alpha channel) the RGB values;
+        leave destination alpha untouched. [Note: is this correct?]
+        SDL_SRCCOLORKEY ignored.
+      SDL_SRCALPHA not set:
+        copy all of RGBA to the destination.
+        if SDL_SRCCOLORKEY set, only copy the pixels matching the
+        RGB values of the source colour key, ignoring alpha in the
+       comparison.
+   
+    RGB->RGB: 
+      SDL_SRCALPHA set:
+        alpha-blend (using the source per-surface alpha value).
+      SDL_SRCALPHA not set:
+        copy RGB.
+      both:
+        if SDL_SRCCOLORKEY set, only copy the pixels matching the
+        source colour key.
+    \endverbatim
  *  
  *  If either of the surfaces were in video memory, and the blit returns -2,
  *  the video memory was lost, so it should be reloaded with artwork and 
@@ -490,14 +536,16 @@ extern DECLSPEC int SDLCALL SDL_BlendRect
  */
 #define SDL_BlitSurface SDL_UpperBlit
 
-/** This is the public blit function, SDL_BlitSurface(), and it performs
+/**
+ *  This is the public blit function, SDL_BlitSurface(), and it performs
  *  rectangle validation and clipping before passing it to SDL_LowerBlit()
  */
 extern DECLSPEC int SDLCALL SDL_UpperBlit
     (SDL_Surface * src, SDL_Rect * srcrect,
      SDL_Surface * dst, SDL_Rect * dstrect);
 
-/** This is a semi-private blit function and it performs low-level surface
+/**
+ *  This is a semi-private blit function and it performs low-level surface
  *  blitting only.
  */
 extern DECLSPEC int SDLCALL SDL_LowerBlit
@@ -505,7 +553,8 @@ extern DECLSPEC int SDLCALL SDL_LowerBlit
      SDL_Surface * dst, SDL_Rect * dstrect);
 
 /**
- * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
+ *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
+ *         same pixel format.
  *  
  *  \note This function uses a static buffer, and is not thread-safe.
  */

include/SDL_syswm.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_syswm.h
  *  
- * Include file for SDL custom system window manager hooks
+ *  Include file for SDL custom system window manager hooks.
  */
 
 #ifndef _SDL_syswm_h
@@ -42,11 +42,14 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
-   which contains window-manager specific information and arrives whenever
-   an unhandled window event occurs.  This event is ignored by default, but
-   you can enable it with SDL_EventState()
-*/
+/**
+ *  \file SDL_syswm.h
+ *  
+ *  Your application has access to a special type of event ::SDL_SYSWMEVENT,
+ *  which contains window-manager specific information and arrives whenever
+ *  an unhandled window event occurs.  This event is ignored by default, but
+ *  you can enable it with SDL_EventState().
+ */
 #ifdef SDL_PROTOTYPES_ONLY
 struct SDL_SysWMinfo;
 #else
@@ -66,13 +69,17 @@ struct SDL_SysWMinfo;
 #undef Cursor
 #endif
 
-/* These are the various supported subsystems under UNIX */
+/** 
+ *  These are the various supported subsystems under UNIX.
+ */
 typedef enum
 {
     SDL_SYSWM_X11
 } SDL_SYSWM_TYPE;
 
-/* The UNIX custom event structure */
+/**
+ *  The UNIX custom event structure.
+ */
 struct SDL_SysWMmsg
 {
     SDL_version version;
@@ -83,9 +90,11 @@ struct SDL_SysWMmsg
     } event;
 };
 
-/* The UNIX custom window manager information structure.
-   When this structure is returned, it holds information about which
-   low level system it is using, and will be one of SDL_SYSWM_TYPE.
+/**
+ *  The UNIX custom window manager information structure.
+ *
+ *  When this structure is returned, it holds information about which
+ *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
  */
 struct SDL_SysWMinfo
 {
@@ -95,19 +104,26 @@ struct SDL_SysWMinfo
     {
         struct
         {
-            Display *display;   /* The X11 display */
-            Window window;      /* The X11 display window */
-            /* These locking functions should be called around
-               any X11 functions using the display variable.
-               They lock the event thread, so should not be
-               called around event functions or from event filters.
+            Display *display;   /**< The X11 display */
+            Window window;      /**< The X11 display window */
+            /**
+             *  These locking functions should be called around
+             *  any X11 functions using the display variable.
+             *  They lock the event thread, so should not be
+             *  called around event functions or from event filters.
              */
+            /*@{*/
             void (*lock_func) (void);
             void (*unlock_func) (void);
+            /*@}*/
 
-            /* Introduced in SDL 1.0.2 */
-            Window fswindow;    /* The X11 fullscreen window */
-            Window wmwindow;    /* The X11 managed input window */
+            /**
+             *  Introduced in SDL 1.0.2.
+             */
+            /*@{*/
+            Window fswindow;    /**< The X11 fullscreen window */
+            Window wmwindow;    /**< The X11 managed input window */
+            /*@}*/
         } x11;
     } info;
 };
@@ -116,40 +132,48 @@ struct SDL_SysWMinfo
 #define WIN32_LEAN_AND_MEAN
 #include <windows.h>
 
-/* The windows custom event structure */
+/**
+ *  The windows custom event structure.
+ */
 struct SDL_SysWMmsg
 {
     SDL_version version;
-    HWND hwnd;                  /* The window for the message */
-    UINT msg;                   /* The type of message */
-    WPARAM wParam;              /* WORD message parameter */
-    LPARAM lParam;              /* LONG message parameter */
+    HWND hwnd;                  /**< The window for the message */
+    UINT msg;                   /**< The type of message */
+    WPARAM wParam;              /**< WORD message parameter */
+    LPARAM lParam;              /**< LONG message parameter */
 };
 
-/* The windows custom window manager information structure */
+/**
+ *  The windows custom window manager information structure.
+ */
 struct SDL_SysWMinfo
 {
     SDL_version version;
-    HWND window;                /* The Win32 display window */
+    HWND window;                /**< The Win32 display window */
 };
 
 #elif defined(SDL_VIDEO_DRIVER_RISCOS)
 
-/* RISC OS custom event structure */
+/**
+ *  RISC OS custom event structure.
+ */
 struct SDL_SysWMmsg
 {
     SDL_version version;
-    int eventCode;              /* The window for the message */
+    int eventCode;              /**< The window for the message */
     int pollBlock[64];
 };
 
-/* The RISC OS custom window manager information structure */
+/**
+ *  The RISC OS custom window manager information structure.
+ */
 struct SDL_SysWMinfo
 {
     SDL_version version;
-    int wimpVersion;            /* Wimp version running under */
-    int taskHandle;             /* The RISC OS task handle */
-    int window;                 /* The RISC OS display window */
+    int wimpVersion;            /**< Wimp version running under */
+    int taskHandle;             /**< The RISC OS task handle */
+    int window;                 /**< The RISC OS display window */
 };
 
 #elif defined(SDL_VIDEO_DRIVER_PHOTON) || defined(SDL_VIDEO_DRIVER_QNXGF)
@@ -159,14 +183,18 @@ struct SDL_SysWMinfo
 #endif /* SDL_VIDEO_OPENGL_ES */
 #include <Ph.h>
 
-/* The QNX custom event structure */
+/**
+ * The QNX custom event structure.
+ */
 struct SDL_SysWMmsg
 {
     SDL_version version;
     int data;
 };
 
-/* The QNX Photon custom window manager information structure */
+/**
+ *  The QNX Photon custom window manager information structure.
+ */
 struct SDL_SysWMinfo
 {
     SDL_version version;
@@ -175,14 +203,18 @@ struct SDL_SysWMinfo
 
 #else
 
-/* The generic custom event structure */
+/**
+ *  The generic custom event structure.
+ */
 struct SDL_SysWMmsg
 {
     SDL_version version;
     int data;
 };
 
-/* The generic custom window manager information structure */
+/**
+ *  The generic custom window manager information structure.
+ */
 struct SDL_SysWMinfo
 {
     SDL_version version;
@@ -197,14 +229,14 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo;
 
 /* Function prototypes */
 /**
- * \fn SDL_bool SDL_GetWindowWMInfo (SDL_WindowID windowID, SDL_SysWMinfo * info)
- *
  *  \brief This function allows access to driver-dependent window information.
  *  
  *  \param windowID The window about which information is being requested
- * \param info This structure must be initialized with the SDL version, and is then filled in with information about the given window.
+ *  \param info This structure must be initialized with the SDL version, and is 
+ *              then filled in with information about the given window.
  *  
- * \return SDL_TRUE if the function is implemented and the version member of the 'info' struct is valid, SDL_FALSE otherwise.
+ *  \return SDL_TRUE if the function is implemented and the version member of 
+ *          the \c info struct is valid, SDL_FALSE otherwise.
  *  
  *  You typically use this function like this:
  *  \code

include/SDL_thread.h

@@ -26,7 +26,7 @@
 /**
  *  \file SDL_thread.h
  *  
- * Header for the SDL thread management routines 
+ *  Header for the SDL thread management routines.
  */
 
 #include "SDL_stdinc.h"
@@ -47,21 +47,27 @@ extern "C" {
 struct SDL_Thread;
 typedef struct SDL_Thread SDL_Thread;
 
-/* Create a thread */
 #if defined(__WIN32__) && !defined(HAVE_LIBC)
-/*
-   We compile SDL into a DLL. This means, that it's the DLL which
-   creates a new thread for the calling process with the SDL_CreateThread()
-   API. There is a problem with this, that only the RTL of the SDL.DLL will
-   be initialized for those threads, and not the RTL of the calling application!
-   To solve this, we make a little hack here.
-   We'll always use the caller's _beginthread() and _endthread() APIs to
-   start a new thread. This way, if it's the SDL.DLL which uses this API,
-   then the RTL of SDL.DLL will be used to create the new thread, and if it's
-   the application, then the RTL of the application will be used.
-   So, in short:
-   Always use the _beginthread() and _endthread() of the calling runtime library!
-*/
+/**
+ *  \file SDL_thread.h
+ *  
+ *  We compile SDL into a DLL. This means, that it's the DLL which
+ *  creates a new thread for the calling process with the SDL_CreateThread()
+ *  API. There is a problem with this, that only the RTL of the SDL.DLL will
+ *  be initialized for those threads, and not the RTL of the calling 
+ *  application!
+ *  
+ *  To solve this, we make a little hack here.
+ *  
+ *  We'll always use the caller's _beginthread() and _endthread() APIs to
+ *  start a new thread. This way, if it's the SDL.DLL which uses this API,
+ *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
+ *  the application, then the RTL of the application will be used.
+ *  
+ *  So, in short:
+ *  Always use the _beginthread() and _endthread() of the calling runtime 
+ *  library!
+ */
 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
 #ifndef _WIN32_WCE
 #include <process.h>            /* This has _beginthread() and _endthread() defined! */
@@ -87,40 +93,66 @@ typedef uintptr_t(__cdecl * pfnSDL_CurrentBeginThread) (void *, unsigned,
 typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
 #endif
 
+/**
+ *  Create a thread.
+ */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThread(int (SDLCALL * f) (void *), void *data,
                  pfnSDL_CurrentBeginThread pfnBeginThread,
                  pfnSDL_CurrentEndThread pfnEndThread);
 
 #if defined(_WIN32_WCE)
+
+/**
+ *  Create a thread.
+ */
 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL)
+
 #else
+
+/**
+ *  Create a thread.
+ */
 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex)
+
 #endif
 #else
+
+/**
+ *  Create a thread.
+ */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThread(int (SDLCALL * fn) (void *), void *data);
+
 #endif
 
-/* Get the 32-bit thread identifier for the current thread */
+/**
+ *  Get the 32-bit thread identifier for the current thread.
+ */
 extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
 
-/* Get the 32-bit thread identifier for the specified thread,
-   equivalent to SDL_ThreadID() if the specified thread is NULL.
+/**
+ *  Get the 32-bit thread identifier for the specified thread.
+ *  
+ *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread * thread);
 
-/* Wait for a thread to finish.
-   The return code for the thread function is placed in the area
-   pointed to by 'status', if 'status' is not NULL.
+/**
+ *  Wait for a thread to finish.
+ *  
+ *  The return code for the thread function is placed in the area
+ *  pointed to by \c status, if \c status is not NULL.
  */
 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
 
-/* This function is here for binary compatibility with legacy apps, but
-   in SDL 1.3 and later, it's a no-op. You cannot forcibly kill a thread
-   in a safe manner on many platforms. You should instead find a way to
-   alert your thread that it is time to terminate, and then have it gracefully
-   exit on its own. Do not ever call this function!
+/**
+ *  \deprecated This function is here for binary compatibility with legacy apps,
+ *              but in SDL 1.3 and later, it's a no-op.
+ *  
+ *  You cannot forcibly kill a thread in a safe manner on many platforms. You 
+ *  should instead find a way to alert your thread that it is time to terminate,
+ *  and then have it gracefully exit on its own. Do not ever call this function!
  */
 extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread * thread);
 

include/SDL_timer.h

@@ -26,7 +26,7 @@
 /**
  *  \file SDL_timer.h
  *  
- * Header for the SDL time management routines
+ *  Header for the SDL time management routines.
  */
 
 #include "SDL_stdinc.h"
@@ -40,31 +40,43 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* This is the OS scheduler timeslice, in milliseconds */
+/**
+ *  This is the OS scheduler timeslice, in milliseconds.
+ */
 #define SDL_TIMESLICE		10
 
-/* This is the maximum resolution of the SDL timer on all platforms */
-#define TIMER_RESOLUTION	10      /* Experimentally determined */
+/**
+ *  This is the maximum resolution of the SDL timer on all platforms.
+ */
+#define TIMER_RESOLUTION	10      /**< Experimentally determined */
 
-/* Get the number of milliseconds since the SDL library initialization.
+/**
+ *  Get the number of milliseconds since the SDL library initialization.
+ *  
  *  Note that this value wraps if the program runs for more than ~49 days.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
 
-/* Wait a specified number of milliseconds before returning */
+/**
+ *  Wait a specified number of milliseconds before returning.
+ */
 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
 
-/* Function prototype for the timer callback function */
+/**
+ *  Function prototype for the timer callback function.
+ */
 typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
 
-/* Set a callback to run after the specified number of milliseconds has
+/**
+ *  Set a callback to run after the specified number of milliseconds has
  *  elapsed. The callback function is passed the current timer interval
  *  and returns the next timer interval.  If the returned value is the 
  *  same as the one passed in, the periodic alarm continues, otherwise a
  *  new alarm is scheduled.  If the callback returns 0, the periodic alarm
  *  is cancelled.
  *  
- * To cancel a currently running timer, call SDL_SetTimer(0, NULL);
+ *  To cancel a currently running timer, call 
+ *  \code SDL_SetTimer(0, NULL); \endcode
  *  
  *  The timer callback function may run in a different thread than your
  *  main code, and so shouldn't call any functions from within itself.
@@ -74,25 +86,32 @@ typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
  *  later on an unloaded system.  If you wanted to set a flag signaling
  *  a frame update at 30 frames per second (every 33 ms), you might set a 
  *  timer for 30 ms:
+ *  \code
  *    SDL_SetTimer((33/10)*10, flag_update);
+ *  \endcode
  *  
- * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
+ *  If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
  *  
  *  Under UNIX, you should not use raise or use SIGALRM and this function
  *  in the same program, as it is implemented using setitimer().  You also
  *  should not use this function in multi-threaded applications as signals
  *  to multi-threaded apps have undefined behavior in some implementations.
  *  
- * This function returns 0 if successful, or -1 if there was an error.
+ *  \return 0 if successful, or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
                                          SDL_TimerCallback callback);
 
-/* New timer API, supports multiple timers
+/**
+ *  \name Peter timers
+ *  New timer API, supports multiple timers
  *  Written by Stephane Peter <megastep@lokigames.com>
  */
+/*@{*/
 
-/* Function prototype for the new timer callback function.
+/**
+ *  Function prototype for the new timer callback function.
+ *  
  *  The callback function is passed the current timer interval and returns
  *  the next timer interval.  If the returned value is the same as the one
  *  passed in, the periodic alarm continues, otherwise a new alarm is
@@ -100,21 +119,27 @@ extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
  */
 typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
 
-/* Definition of the timer ID type */
+/**
+ *  Definition of the timer ID type.
+ */
 typedef struct _SDL_TimerID *SDL_TimerID;
 
-/* Add a new timer to the pool of timers already running.
-   Returns a timer ID, or NULL when an error occurs.
+/**
+ *  Add a new timer to the pool of timers already running.
+ *  \return A timer ID, or NULL when an error occurs.
  */
 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
                                                  SDL_NewTimerCallback
                                                  callback, void *param);
 
-/* Remove one of the multiple timers knowing its ID.
- * Returns a boolean value indicating success.
+/**
+ *  Remove one of the multiple timers knowing its ID.
+ *  \return A boolean value indicating success or failure.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
 
+/*@}*//*Peter timers*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 /* *INDENT-OFF* */

include/SDL_types.h

@@ -20,5 +20,11 @@
     slouken@libsdl.org
 */
 
+/**
+ *  \file SDL_types.h
+ *  
+ *  \deprecated
+ */
+
 /* DEPRECATED */
 #include "SDL_stdinc.h"

include/SDL_version.h

@@ -23,7 +23,7 @@
 /**
  *  \file SDL_version.h
  *  
- * This header defines the current SDL version
+ *  This header defines the current SDL version.
  */
 
 #ifndef _SDL_version_h
@@ -41,7 +41,6 @@ extern "C" {
 #endif
 
 /**
- * \struct SDL_version
  *  \brief Information the version of SDL in use.
  *  
  *  Represents the library's version as three levels: major revision
@@ -67,14 +66,13 @@ typedef struct SDL_version
 #define SDL_PATCHLEVEL		0
 
 /**
- * \def SDL_VERSION(x)
  *  \brief Macro to determine SDL version program was compiled against.
  *  
  *  This macro fills in a SDL_version structure with the version of the
  *  library you compiled against. This is determined by what header the
  *  compiler uses. Note that if you dynamically linked the library, you might
  *  have a slightly newer or older version at runtime. That version can be
- *  determined with SDL_GetVersion(), which, unlike SDL_VERSION,
+ *  determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
  *  is not a macro.
  *  
  *  \param x A pointer to a SDL_version struct to initialize.
@@ -89,29 +87,36 @@ typedef struct SDL_version
 	(x)->patch = SDL_PATCHLEVEL;					\
 }
 
-/* This macro turns the version numbers into a numeric value:
+/**
+ *  This macro turns the version numbers into a numeric value:
+ *  \verbatim
     (1,2,3) -> (1203)
-   This assumes that there will never be more than 100 patchlevels
-*/
+    \endverbatim
+ *  
+ *  This assumes that there will never be more than 100 patchlevels.
+ */
 #define SDL_VERSIONNUM(X, Y, Z)						\
 	((X)*1000 + (Y)*100 + (Z))
 
-/* This is the version number macro for the current SDL version */
+/**
+ *  This is the version number macro for the current SDL version.
+ */
 #define SDL_COMPILEDVERSION \
 	SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL)
 
-/* This macro will evaluate to true if compiled with SDL at least X.Y.Z */
+/**
+ *  This macro will evaluate to true if compiled with SDL at least X.Y.Z.
+ */
 #define SDL_VERSION_ATLEAST(X, Y, Z) \
 	(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
 
 /**
- * \fn void SDL_GetVersion(SDL_version *ver)
  *  \brief Get the version of SDL that is linked against your program.
  *  
  *  If you are using a shared library (DLL) version of SDL, then it is
  *  possible that it will be different than the version you compiled against.
  *
- * This is a real function; the macro SDL_VERSION tells you what version
+ *  This is a real function; the macro SDL_VERSION() tells you what version
  *  of SDL you compiled against:
  *  
  *  \code
@@ -133,7 +138,6 @@ typedef struct SDL_version
 extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
 
 /**
- * \fn int SDL_GetRevision(void)
  *  \brief Get the code revision of SDL that is linked against your program.
  */
 extern DECLSPEC int SDLCALL SDL_GetRevision(void);

include/SDL_video.h

@@ -43,8 +43,6 @@ extern "C" {
 #endif
 
 /**
- * \struct SDL_DisplayMode
- *
  *  \brief  The structure that defines a display mode
  *  
  *  \sa SDL_GetNumDisplayModes()
@@ -64,8 +62,6 @@ typedef struct
 } SDL_DisplayMode;
 
 /**
- * \typedef SDL_WindowID
- *
  *  \brief The type used to identify a window
  *  
  *  \sa SDL_CreateWindow()
@@ -94,8 +90,6 @@ typedef struct
 typedef Uint32 SDL_WindowID;
 
 /**
- * \enum SDL_WindowFlags
- *
  *  \brief The flags on a window
  *  
  *  \sa SDL_GetWindowFlags()
@@ -116,19 +110,16 @@ typedef enum
 } SDL_WindowFlags;
 
 /**
- * \def SDL_WINDOWPOS_UNDEFINED
  *  \brief Used to indicate that you don't care what the window position is.
  */
 #define SDL_WINDOWPOS_UNDEFINED 0x7FFFFFF
+
 /**
- * \def SDL_WINDOWPOS_CENTERED
  *  \brief Used to indicate that the window position should be centered.
  */
 #define SDL_WINDOWPOS_CENTERED  0x7FFFFFE
 
 /**
- * \enum SDL_WindowEventID
- *
  *  \brief Event subtype for window events
  */
 typedef enum
@@ -136,44 +127,63 @@ typedef enum
     SDL_WINDOWEVENT_NONE,           /**< Never used */
     SDL_WINDOWEVENT_SHOWN,          /**< Window has been shown */
     SDL_WINDOWEVENT_HIDDEN,         /**< Window has been hidden */
-    SDL_WINDOWEVENT_EXPOSED,            /**< Window has been exposed and should be redrawn */
-    SDL_WINDOWEVENT_MOVED,              /**< Window has been moved to data1,data2 */
+    SDL_WINDOWEVENT_EXPOSED,        /**< Window has been exposed and should be 
+                                         redrawn */
+    SDL_WINDOWEVENT_MOVED,          /**< Window has been moved to data1, data2 
+                                     */
     SDL_WINDOWEVENT_RESIZED,        /**< Window size changed to data1xdata2 */
     SDL_WINDOWEVENT_MINIMIZED,      /**< Window has been minimized */
     SDL_WINDOWEVENT_MAXIMIZED,      /**< Window has been maximized */
-    SDL_WINDOWEVENT_RESTORED,           /**< Window has been restored to normal size and position */
+    SDL_WINDOWEVENT_RESTORED,       /**< Window has been restored to normal size
+                                         and position */
     SDL_WINDOWEVENT_ENTER,          /**< The window has gained mouse focus */
     SDL_WINDOWEVENT_LEAVE,          /**< The window has lost mouse focus */
     SDL_WINDOWEVENT_FOCUS_GAINED,   /**< The window has gained keyboard focus */
     SDL_WINDOWEVENT_FOCUS_LOST,     /**< The window has lost keyboard focus */
-    SDL_WINDOWEVENT_CLOSE               /**< The window manager requests that the window be closed */
+    SDL_WINDOWEVENT_CLOSE           /**< The window manager requests that the 
+                                         window be closed */
 } SDL_WindowEventID;
 
 /**
- * \enum SDL_RendererFlags
- *
  *  \brief Flags used when creating a rendering context
  */
 typedef enum
 {
-    SDL_RENDERER_SINGLEBUFFER = 0x00000001,     /**< Render directly to the window, if possible */
-    SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
-    SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
-    SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
-    SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents of the backbuffer undefined */
-    SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized with the refresh rate */
-    SDL_RENDERER_ACCELERATED = 0x00000040       /**< The renderer uses hardware acceleration */
-} SDL_RendererFlags;
+    SDL_RENDERER_SINGLEBUFFER = 0x00000001,     /**< Render directly to the 
+                                                     window, if possible */
+    
+    SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from 
+                                                     back buffer to the front 
+                                                     buffer */
+    
+    SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, 
+                                                     swapping back buffer and 
+                                                     front buffer */
+    
+    SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, 
+                                                     rotating between two back 
+                                                     buffers and a front buffer
+                                                 */
+    
+    SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents
+                                                     of the backbuffer undefined
+                                                 */
+    
+    SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized 
+                                                     with the refresh rate */
+    
+    SDL_RENDERER_ACCELERATED = 0x00000040       /**< The renderer uses hardware 
+                                                     acceleration */
+    
+    } SDL_RendererFlags;
 
 /**
- * \struct SDL_RendererInfo
- *
- * \brief Information on the capabilities of a render driver or context
+ *  \brief Information on the capabilities of a render driver or context.
  */
 typedef struct SDL_RendererInfo
 {
     const char *name;           /**< The name of the renderer */
-    Uint32 flags;               /**< Supported SDL_RendererFlags */
+    Uint32 flags;               /**< Supported ::SDL_RendererFlags */
     Uint32 mod_modes;           /**< A mask of supported channel modulation */
     Uint32 blend_modes;         /**< A mask of supported blend modes */
     Uint32 scale_modes;         /**< A mask of supported scale modes */
@@ -184,9 +194,7 @@ typedef struct SDL_RendererInfo
 } SDL_RendererInfo;
 
 /**
- * \enum SDL_TextureAccess
- *
- * \brief The access pattern allowed for a texture
+ *  \brief The access pattern allowed for a texture.
  */
 typedef enum
 {
@@ -195,9 +203,7 @@ typedef enum
 } SDL_TextureAccess;
 
 /**
- * \enum SDL_TextureModulate
- *
- * \brief The texture channel modulation used in SDL_RenderCopy()
+ *  \brief The texture channel modulation used in SDL_RenderCopy().
  */
 typedef enum
 {
@@ -207,49 +213,48 @@ typedef enum
 } SDL_TextureModulate;
 
 /**
- * \enum SDL_BlendMode
- *
- * \brief The blend mode used in SDL_RenderCopy() and drawing operations
+ *  \brief The blend mode used in SDL_RenderCopy() and drawing operations.
  */
 typedef enum
 {
     SDL_BLENDMODE_NONE = 0x00000000,     /**< No blending */
-    SDL_BLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst (alpha is mask) */
+    SDL_BLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst 
+                                              (alpha is mask) */
+    
     SDL_BLENDMODE_BLEND = 0x00000002,    /**< dst = (src * A) + (dst * (1-A)) */
     SDL_BLENDMODE_ADD = 0x00000004,      /**< dst = (src * A) + dst */
     SDL_BLENDMODE_MOD = 0x00000008       /**< dst = src * dst */
 } SDL_BlendMode;
 
 /**
- * \enum SDL_TextureScaleMode
- *
- * \brief The texture scale mode used in SDL_RenderCopy()
+ *  \brief The texture scale mode used in SDL_RenderCopy().
  */
 typedef enum
 {
-    SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must match dimensions */
-    SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or equivalent algorithm */
-    SDL_TEXTURESCALEMODE_SLOW = 0x00000002,     /**< Linear filtering or equivalent algorithm */
-    SDL_TEXTURESCALEMODE_BEST = 0x00000004      /**< Bicubic filtering or equivalent algorithm */
+    SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must
+                                                     match dimensions */
+    
+    SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or 
+                                                     equivalent algorithm */
+    
+    SDL_TEXTURESCALEMODE_SLOW = 0x00000002,     /**< Linear filtering or 
+                                                     equivalent algorithm */
+    
+    SDL_TEXTURESCALEMODE_BEST = 0x00000004      /**< Bicubic filtering or 
+                                                     equivalent algorithm */
 } SDL_TextureScaleMode;
 
 /**
- * \typedef SDL_TextureID
- *
  *  \brief An efficient driver-specific representation of pixel data
  */
 typedef Uint32 SDL_TextureID;
 
 /**
- * \typedef SDL_GLContext
- *
  *  \brief An opaque handle to an OpenGL context.
  */
 typedef void *SDL_GLContext;
 
 /**
- * \enum SDL_GLattr
- *
  *  \brief OpenGL configuration attributes
  */
 typedef enum
@@ -279,8 +284,6 @@ typedef enum
 /* Function prototypes */
 
 /**
- * \fn int SDL_GetNumVideoDrivers(void)
- *
  *  \brief Get the number of video drivers compiled into SDL
  *  
  *  \sa SDL_GetVideoDriver()
@@ -288,8 +291,6 @@ typedef enum
 extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
 
 /**
- * \fn const char *SDL_GetVideoDriver(int index)
- *
  *  \brief Get the name of a built in video driver.
  *  
  *  \note The video drivers are presented in the order in which they are
@@ -300,11 +301,11 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
 extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
 
 /**
- * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags)
- *
  *  \brief Initialize the video subsystem, optionally specifying a video driver.
  *  
- * \param driver_name Initialize a specific driver by name, or NULL for the default video driver.
+ *  \param driver_name Initialize a specific driver by name, or NULL for the 
+ *                     default video driver.
+ *  
  *  \param flags FIXME: Still needed?
  *  
  *  \return 0 on success, -1 on error
@@ -319,8 +320,6 @@ extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name,
                                           Uint32 flags);
 
 /**
- * \fn void SDL_VideoQuit(void)
- *
  *  \brief Shuts down the video subsystem.
  *  
  *  This function closes all windows, and restores the original video mode.
@@ -330,8 +329,6 @@ extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name,
 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
 
 /**
- * \fn const char *SDL_GetCurrentVideoDriver(void)
- *
  *  \brief Returns the name of the currently initialized video driver.
  *  
  *  \return The name of the current video driver or NULL if no driver
@@ -343,8 +340,6 @@ extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
 extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
 
 /**
- * \fn int SDL_GetNumVideoDisplays(void)
- *
  *  \brief Returns the number of available video displays.
  *  
  *  \sa SDL_SelectVideoDisplay()
@@ -352,8 +347,6 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
 extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
 
 /**
- * \fn int SDL_SelectVideoDisplay(int index)
- *
  *  \brief Set the index of the currently selected display.
  *  
  *  \return 0 on success, or -1 if the index is out of range.
@@ -364,8 +357,6 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
 extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
 
 /**
- * \fn int SDL_GetCurrentVideoDisplay(void)
- *
  *  \brief Get the index of the currently selected display.
  *  
  *  \return The index of the currently selected display.
@@ -376,8 +367,6 @@ extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
 extern DECLSPEC int SDLCALL SDL_GetCurrentVideoDisplay(void);
 
 /**
- * \fn int SDL_GetNumDisplayModes(void)
- *
  *  \brief Returns the number of available display modes for the current display.
  *  
  *  \sa SDL_GetDisplayMode()
@@ -385,8 +374,6 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentVideoDisplay(void);
 extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void);
 
 /**
- * \fn int SDL_GetDisplayMode(int index, SDL_DisplayMode *mode)
- *
  *  \brief Fill in information about a specific display mode.
  *  
  *  \note The display modes are sorted in this priority:
@@ -401,31 +388,33 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int index,
                                                SDL_DisplayMode * mode);
 
 /**
- * \fn int SDL_GetDesktopDisplayMode(SDL_DisplayMode *mode)
- *
- * \brief Fill in information about the desktop display mode for the current display.
+ *  \brief Fill in information about the desktop display mode for the current 
+ *         display.
  */
 extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayMode * mode);
 
 /**
- * \fn int SDL_GetCurrentDisplayMode(SDL_DisplayMode *mode)
- *
  *  \brief Fill in information about the current display mode.
  */
 extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayMode * mode);
 
 
 /**
- * \fn SDL_DisplayMode SDL_GetClosestDisplayMode(const SDL_DisplayMode mode, SDL_DisplayMode closest)
- *
  *  \brief Get the closest match to the requested display mode.
  *  
  *  \param mode The desired display mode
- * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes.
+ *  \param closest A pointer to a display mode to be filled in with the closest 
+ *                 match of the available display modes.
  *  
- * \return The passed in value 'closest', or NULL if no matching video mode was available.
+ *  \return The passed in value \c closest, or NULL if no matching video mode 
+ *          was available.
  *  
- * The available display modes are scanned, and 'closest' is filled in with the closest mode matching the requested mode and returned.  The mode format and refresh_rate default to the desktop mode if they are 0.  The modes are scanned with size being first priority, format being second priority, and finally checking the refresh_rate.  If all the available modes are too small, then NULL is returned.
+ *  The available display modes are scanned, and \c closest is filled in with the
+ *  closest mode matching the requested mode and returned.  The mode format and 
+ *  refresh_rate default to the desktop mode if they are 0.  The modes are 
+ *  scanned with size being first priority, format being second priority, and 
+ *  finally checking the refresh_rate.  If all the available modes are too 
+ *  small, then NULL is returned.
  *  
  *  \sa SDL_GetNumDisplayModes()
  *  \sa SDL_GetDisplayMode()
@@ -437,8 +426,6 @@ extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const
                                                                    * closest);
 
 /**
- * \fn int SDL_SetFullscreenDisplayMode(const SDL_DisplayMode *mode)
- *
  *  \brief Set the display mode used when a fullscreen window is visible
  *         on the currently selected display.
  *  
@@ -452,8 +439,6 @@ extern DECLSPEC int SDLCALL SDL_SetFullscreenDisplayMode(const SDL_DisplayMode
                                                          * mode);
 
 /**
- * \fn int SDL_GetFullscreenDisplayMode(SDL_DisplayMode *mode)
- *
  *  \brief Fill in information about the display mode used when a fullscreen
  *         window is visible on the currently selected display.
  */
@@ -461,19 +446,16 @@ extern DECLSPEC int SDLCALL SDL_GetFullscreenDisplayMode(SDL_DisplayMode *
                                                          mode);
 
 /**
- * \fn int SDL_SetDisplayPalette(const SDL_Color *colors, int firstcolor, int ncolors)
- *
  *  \brief Set the palette entries for indexed display modes.
  *  
- * \return 0 on success, or -1 if the display mode isn't palettized or the colors couldn't be set.
+ *  \return 0 on success, or -1 if the display mode isn't palettized or the 
+ *          colors couldn't be set.
  */
 extern DECLSPEC int SDLCALL SDL_SetDisplayPalette(const SDL_Color * colors,
                                                   int firstcolor,
                                                   int ncolors);
 
 /**
- * \fn int SDL_GetDisplayPalette(SDL_Color *colors, int firstcolor, int ncolors)
- *
  *  \brief Gets the palette entries for indexed display modes.
  *  
  *  \return 0 on success, or -1 if the display mode isn't palettized
@@ -483,9 +465,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors,
                                                   int ncolors);
 
 /**
- * \fn int SDL_SetGamma(float red, float green, float blue)
- *
- * \brief Set the gamma correction for each of the color channels on the currently selected display.
+ *  \brief Set the gamma correction for each of the color channels on the 
+ *         currently selected display.
  *  
  *  \return 0 on success, or -1 if setting the gamma isn't supported.
  *  
@@ -494,13 +475,11 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors,
 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
 
 /**
- * \fn int SDL_SetGammaRamp(const Uint16 * red, const Uint16 * green, const Uint16 * blue)
- *
  *  \brief Set the gamma ramp for the currently selected display.
  *  
- * \param red The translation table for the red channel, or NULL
- * \param green The translation table for the green channel, or NULL
- * \param blue The translation table for the blue channel, or NULL
+ *  \param red The translation table for the red channel, or NULL.
+ *  \param green The translation table for the green channel, or NULL.
+ *  \param blue The translation table for the blue channel, or NULL.
  *  
  *  \return 0 on success, or -1 if gamma ramps are unsupported.
  *  
@@ -517,13 +496,14 @@ extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 * red,
                                              const Uint16 * blue);
 
 /**
- * \fn int SDL_GetGammaRamp(Uint16 * red, Uint16 * green, Uint16 * blue)
- *
  *  \brief Get the gamma ramp for the currently selected display.
  *  
- * \param red A pointer to a 256 element array of 16-bit quantities to hold the translation table for the red channel, or NULL.
- * \param green A pointer to a 256 element array of 16-bit quantities to hold the translation table for the green channel, or NULL.
- * \param blue A pointer to a 256 element array of 16-bit quantities to hold the translation table for the blue channel, or NULL.
+ *  \param red   A pointer to a 256 element array of 16-bit quantities to hold 
+ *               the translation table for the red channel, or NULL.
+ *  \param green A pointer to a 256 element array of 16-bit quantities to hold 
+ *               the translation table for the green channel, or NULL.
+ *  \param blue  A pointer to a 256 element array of 16-bit quantities to hold 
+ *               the translation table for the blue channel, or NULL.
  *   
  *  \return 0 on success, or -1 if gamma ramps are unsupported.
  *  
@@ -534,16 +514,20 @@ extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 * red, Uint16 * green,
 
 
 /**
- * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags)
- *
  *  \brief Create a window with the specified position, dimensions, and flags.
  *  
- * \param title The title of the window, in UTF-8 encoding
- * \param x The x position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
- * \param y The y position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
- * \param w The width of the window
- * \param h The height of the window
- * \param flags The flags for the window, a mask of any of the following: SDL_WINDOW_FULLSCREEN, SDL_WINDOW_OPENGL, SDL_WINDOW_SHOWN, SDL_WINDOW_BORDERLESS, SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, SDL_WINDOW_MINIMIZED, SDL_WINDOW_INPUT_GRABBED
+ *  \param title The title of the window, in UTF-8 encoding.
+ *  \param x     The x position of the window, ::SDL_WINDOWPOS_CENTERED, or 
+ *               ::SDL_WINDOWPOS_UNDEFINED.
+ *  \param y     The y position of the window, ::SDL_WINDOWPOS_CENTERED, or 
+ *               ::SDL_WINDOWPOS_UNDEFINED.
+ *  \param w     The width of the window.
+ *  \param h     The height of the window.
+ *  \param flags The flags for the window, a mask of any of the following: 
+ *               ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL, 
+ *               ::SDL_WINDOW_SHOWN,      ::SDL_WINDOW_BORDERLESS, 
+ *               ::SDL_WINDOW_RESIZABLE,  ::SDL_WINDOW_MAXIMIZED, 
+ *               ::SDL_WINDOW_MINIMIZED,  ::SDL_WINDOW_INPUT_GRABBED.
  *  
  *  \return The id of the window created, or zero if window creation failed.
  *  
@@ -554,8 +538,6 @@ extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow(const char *title,
                                                       int h, Uint32 flags);
 
 /**
- * \fn SDL_WindowID SDL_CreateWindowFrom(void *data)
- *
  *  \brief Create an SDL window struct from an existing native window.
  *  
  *  \param data A pointer to driver-dependent window creation data
@@ -569,15 +551,11 @@ extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow(const char *title,
 extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindowFrom(const void *data);
 
 /**
- * \fn Uint32 SDL_GetWindowFlags(SDL_WindowID windowID)
- *
  *  \brief Get the window flags.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_SetWindowTitle(SDL_WindowID windowID, const char *title)
- *
  *  \brief Set the title of the window, in UTF-8 format.
  *  
  *  \sa SDL_GetWindowTitle()
@@ -586,8 +564,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_WindowID windowID,
                                                 const char *title);
 
 /**
- * \fn const char *SDL_GetWindowTitle(SDL_WindowID windowID)
- *
  *  \brief Get the title of the window, in UTF-8 format.
  *  
  *  \sa SDL_SetWindowTitle()
@@ -595,18 +571,14 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_WindowID windowID,
 extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_SetWindowIcon(SDL_WindowID windowID, SDL_Surface *icon)
- *
  *  \brief Set the icon of the window.
  *  
- * \param icon The icon for the window
+ *  \param icon The icon for the window.
  */
 extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_WindowID windowID,
                                                SDL_Surface * icon);
 
 /**
- * \fn void SDL_SetWindowData(SDL_WindowID windowID, void *userdata)
- *
  *  \brief Associate an arbitrary pointer with the window.
  *  
  *  \sa SDL_GetWindowData()
@@ -615,8 +587,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_WindowID windowID,
                                                void *userdata);
 
 /**
- * \fn void *SDL_GetWindowData(SDL_WindowID windowID)
- *
  *  \brief Retrieve the data pointer associated with the window.
  *  
  *  \sa SDL_SetWindowData()
@@ -624,13 +594,13 @@ extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_WindowID windowID,
 extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_SetWindowPosition(SDL_WindowID windowID, int x, int y)
- *
  *  \brief Set the position of the window.
  *  
- * \param windowID The window to reposition
- * \param x The x coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
- * \param y The y coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED
+ *  \param windowID The window to reposition.
+ *  \param x        The x coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
+                    ::SDL_WINDOWPOS_UNDEFINED.
+ *  \param y        The y coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
+                    ::SDL_WINDOWPOS_UNDEFINED.
  *  
  *  \note The window coordinate origin is the upper left of the display.
  *  
@@ -640,8 +610,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_WindowID windowID,
                                                    int x, int y);
 
 /**
- * \fn void SDL_GetWindowPosition(SDL_WindowID windowID, int *x, int *y)
- *
  *  \brief Get the position of the window.
  *  
  *  \sa SDL_SetWindowPosition()
@@ -650,8 +618,6 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_WindowID windowID,
                                                    int *x, int *y);
 
 /**
- * \fn void SDL_SetWindowSize(SDL_WindowID windowID, int w, int w)
- *
  *  \brief Set the size of the window's client area.
  *  
  *  \note You can't change the size of a fullscreen window, it automatically
@@ -663,8 +629,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_WindowID windowID, int w,
                                                int h);
 
 /**
- * \fn void SDL_GetWindowSize(SDL_WindowID windowID, int *w, int *h)
- *
  *  \brief Get the size of the window's client area.
  *  
  *  \sa SDL_SetWindowSize()
@@ -673,33 +637,25 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_WindowID windowID, int *w,
                                                int *h);
 
 /**
- * \fn void SDL_ShowWindow(SDL_WindowID windowID)
- *
- * \brief Show the window
+ *  \brief Show the window.
  *  
  *  \sa SDL_HideWindow()
  */
 extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_HideWindow(SDL_WindowID windowID)
- *
- * \brief Hide the window
+ *  \brief Hide the window.
  *  
  *  \sa SDL_ShowWindow()
  */
 extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_RaiseWindow(SDL_WindowID windowID)
- *
  *  \brief Raise the window above other windows and set the input focus.
  */
 extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_MaximizeWindow(SDL_WindowID windowID)
- *
  *  \brief Make the window as large as possible.
  *  
  *  \sa SDL_RestoreWindow()
@@ -707,8 +663,6 @@ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_WindowID windowID);
 extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_MinimizeWindow(SDL_WindowID windowID)
- *
  *  \brief Minimize the window to an iconic representation.
  *  
  *  \sa SDL_RestoreWindow()
@@ -716,8 +670,6 @@ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_WindowID windowID);
 extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_RestoreWindow(SDL_WindowID windowID)
- *
  *  \brief Restore the size and position of a minimized or maximized window.
  *  
  *  \sa SDL_MaximizeWindow()
@@ -726,8 +678,6 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_WindowID windowID);
 extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_WindowID windowID);
 
 /**
- * \fn int SDL_SetWindowFullscreen(SDL_WindowID windowID, int fullscreen)
- *
  *  \brief Set the window's fullscreen state.
  *  
  *  \return 0 on success, or -1 if setting the display mode failed.
@@ -738,8 +688,6 @@ extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_WindowID windowID,
                                                     int fullscreen);
 
 /**
- * \fn void SDL_SetWindowGrab(SDL_WindowID windowID, int mode)
- *
  *  \brief Set the window's input grab mode.
  *  
  *  \param mode This is 1 to grab input, and 0 to release input.
@@ -750,8 +698,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_WindowID windowID,
                                                int mode);
 
 /**
- * \fn int SDL_GetWindowGrab(SDL_WindowID windowID)
- *
  *  \brief Get the window's input grab mode.
  *  
  *  \return This returns 1 if input is grabbed, and 0 otherwise.
@@ -761,8 +707,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_WindowID windowID,
 extern DECLSPEC int SDLCALL SDL_GetWindowGrab(SDL_WindowID windowID);
 
 /**
- * \fn SDL_bool SDL_GetWindowWMInfo(SDL_WindowID windowID, struct SDL_SysWMinfo * info)
- *
  *  \brief Get driver specific information about a window.
  *  
  *  \note Include SDL_syswm.h for the declaration of SDL_SysWMinfo.
@@ -773,16 +717,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID,
                                                      *info);
 
 /**
- * \fn void SDL_DestroyWindow(SDL_WindowID windowID)
- *
  *  \brief Destroy a window.
  */
 extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
 
 /**
- * \fn int SDL_GetNumRenderDrivers(void)
- *
- * \brief Get the number of 2D rendering drivers available for the current display.
+ *  \brief Get the number of 2D rendering drivers available for the current 
+ *         display.
  *  
  *  A render driver is a set of code that handles rendering and texture
  *  management on a particular display.  Normally there is only one, but
@@ -794,14 +735,14 @@ extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
 extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
 
 /**
- * \fn int SDL_GetRenderDriverInfo(int index, SDL_RendererInfo *info)
- *
- * \brief Get information about a specific 2D rendering driver for the current display.
+ *  \brief Get information about a specific 2D rendering driver for the current 
+ *         display.
  *  
  *  \param index The index of the driver to query information about.
- * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the rendering driver.
+ *  \param info  A pointer to an SDL_RendererInfo struct to be filled with 
+ *               information on the rendering driver.
  *  
- * \return 0 on success, -1 if the index was out of range
+ *  \return 0 on success, -1 if the index was out of range.
  *  
  *  \sa SDL_CreateRenderer()
  */
@@ -809,13 +750,12 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
                                                     SDL_RendererInfo * info);
 
 /**
- * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
- *
  *  \brief Create and make active a 2D rendering context for a window.
  *  
- * \param windowID The window used for rendering
- * \param index The index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags.
- * \param flags SDL_RendererFlags
+ *  \param windowID The window used for rendering.
+ *  \param index    The index of the rendering driver to initialize, or -1 to 
+ *                  initialize the first one supporting the requested flags.
+ *  \param flags    ::SDL_RendererFlags.
  *  
  *  \return 0 on success, -1 if there was an error creating the renderer.
  *  
@@ -827,8 +767,6 @@ extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
                                                int index, Uint32 flags);
 
 /**
- * \fn int SDL_SelectRenderer(SDL_WindowID windowID)
- *
  *  \brief Select the rendering context for a particular window.
  *  
  *  \return 0 on success, -1 if the selected window doesn't have a
@@ -837,23 +775,21 @@ extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
 extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
 
 /**
- * \fn int SDL_GetRendererInfo(SDL_RendererInfo *info)
- *
  *  \brief Get information about the current rendering context.
  */
 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_RendererInfo * info);
 
 /**
- * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
- *
  *  \brief Create a texture for the current rendering context.
  *  
- * \param format The format of the texture
- * \param access One of the enumerated values in SDL_TextureAccess
- * \param w The width of the texture in pixels
- * \param h The height of the texture in pixels
+ *  \param format The format of the texture.
+ *  \param access One of the enumerated values in ::SDL_TextureAccess.
+ *  \param w      The width of the texture in pixels.
+ *  \param h      The height of the texture in pixels.
  *  
- * \return The created texture is returned, or 0 if no rendering context was active,  the format was unsupported, or the width or height were out of range.
+ *  \return The created texture is returned, or 0 if no rendering context was 
+ *          active,  the format was unsupported, or the width or height were out
+ *          of range.
  *  
  *  \sa SDL_QueryTexture()
  *  \sa SDL_DestroyTexture()
@@ -863,14 +799,14 @@ extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
                                                         int h);
 
 /**
- * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, SDL_Surface *surface)
- *
  *  \brief Create a texture from an existing surface.
  *  
- * \param format The format of the texture, or 0 to pick an appropriate format
- * \param surface The surface containing pixel data used to fill the texture
+ *  \param format The format of the texture, or 0 to pick an appropriate format.
+ *  \param surface The surface containing pixel data used to fill the texture.
  *  
- * \return The created texture is returned, or 0 if no rendering context was active,  the format was unsupported, or the surface width or height were out of range.
+ *  \return The created texture is returned, or 0 if no rendering context was 
+ *          active,  the format was unsupported, or the surface width or height 
+ *          were out of range.
  *  
  *  \note The surface is not modified or freed by this function.
  *  
@@ -883,47 +819,48 @@ extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32
                                                                    * surface);
 
 /**
- * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h)
- *
  *  \brief Query the attributes of a texture
  *  
- * \param texture A texture to be queried
- * \param format A pointer filled in with the raw format of the texture.  The actual format may differ, but pixel transfers will use this format.
+ *  \param textureID A texture to be queried.
+ *  \param format  A pointer filled in with the raw format of the texture.  The 
+ *                 actual format may differ, but pixel transfers will use this 
+ *                 format.
  *  \param access  A pointer filled in with the actual access to the texture.
- * \param w A pointer filled in with the width of the texture in pixels
- * \param h A pointer filled in with the height of the texture in pixels
+ *  \param w       A pointer filled in with the width of the texture in pixels.
+ *  \param h       A pointer filled in with the height of the texture in pixels.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  */
 extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_TextureID textureID,
                                              Uint32 * format, int *access,
                                              int *w, int *h);
 
 /**
- * \fn int SDL_QueryTexturePixels(SDL_TextureID textureID, void **pixels, int pitch)
- *
- * \brief Query the pixels of a texture, if the texture does not need to be locked for pixel access.
+ *  \brief Query the pixels of a texture, if the texture does not need to be 
+ *         locked for pixel access.
  *  
- * \param texture A texture to be queried, which was created with SDL_TEXTUREACCESS_STREAMING
- * \param pixels A pointer filled with a pointer to the pixels for the texture 
- * \param pitch A pointer filled in with the pitch of the pixel data
+ *  \param textureID A texture to be queried, which was created with 
+ *                   ::SDL_TEXTUREACCESS_STREAMING.
+ *  \param pixels    A pointer filled with a pointer to the pixels for the 
+ *                   texture.
+ *  \param pitch     A pointer filled in with the pitch of the pixel data.
  *  
- * \return 0 on success, or -1 if the texture is not valid, or must be locked for pixel access.
+ *  \return 0 on success, or -1 if the texture is not valid, or must be locked 
+ *          for pixel access.
  */
 extern DECLSPEC int SDLCALL SDL_QueryTexturePixels(SDL_TextureID textureID,
                                                    void **pixels, int *pitch);
 
 /**
- * \fn int SDL_SetTexturePalette(SDL_TextureID textureID, const SDL_Color * colors, int firstcolor, int ncolors)
- *
  *  \brief Set the color palette of an indexed texture.
  *  
- * \param texture The texture to update
- * \param colors The array of RGB color data
- * \param firstcolor The first index to update
- * \param ncolors The number of palette entries to fill with the color data
+ *  \param textureID  The texture to update.
+ *  \param colors     The array of RGB color data.
+ *  \param firstcolor The first index to update.
+ *  \param ncolors    The number of palette entries to fill with the color data.
  *  
- * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
+ *  \return 0 on success, or -1 if the texture is not valid or not an indexed 
+ *          texture.
  */
 extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID,
                                                   const SDL_Color * colors,
@@ -931,16 +868,15 @@ extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID,
                                                   int ncolors);
 
 /**
- * \fn int SDL_GetTexturePalette(SDL_TextureID textureID, SDL_Color * colors, int firstcolor, int ncolors)
- *
  *  \brief Get the color palette from an indexed texture if it has one.
  *  
- * \param texture The texture to update
- * \param colors The array to fill with RGB color data
- * \param firstcolor The first index to retrieve
- * \param ncolors The number of palette entries to retrieve
+ *  \param textureID  The texture to update.
+ *  \param colors     The array to fill with RGB color data.
+ *  \param firstcolor The first index to retrieve.
+ *  \param ncolors    The number of palette entries to retrieve.
  *  
- * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
+ *  \return 0 on success, or -1 if the texture is not valid or not an indexed 
+ *          texture.
  */
 extern DECLSPEC int SDLCALL SDL_GetTexturePalette(SDL_TextureID textureID,
                                                   SDL_Color * colors,
@@ -948,16 +884,15 @@ extern DECLSPEC int SDLCALL SDL_GetTexturePalette(SDL_TextureID textureID,
                                                   int ncolors);
 
 /**
- * \fn int SDL_SetTextureColorMod(SDL_TextureID textureID, Uint8 r, Uint8 g, Uint8 b)
+ *  \brief Set an additional color value used in render copy operations.
  *  
- * \brief Set an additional color value used in render copy operations
+ *  \param textureID The texture to update.
+ *  \param r       The red source color value multiplied into copy operations.
+ *  \param g       The green source color value multiplied into copy operations.
+ *  \param b       The blue source color value multiplied into copy operations.
  *  
- * \param texture The texture to update
- * \param r The red source color value multiplied into copy operations
- * \param g The green source color value multiplied into copy operations
- * \param b The blue source color value multiplied into copy operations
- *
- * \return 0 on success, or -1 if the texture is not valid or color modulation is not supported
+ *  \return 0 on success, or -1 if the texture is not valid or color modulation 
+ *          is not supported.
  *  
  *  \sa SDL_GetTextureColorMod()
  */
@@ -966,16 +901,14 @@ extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_TextureID textureID,
 
 
 /**
- * \fn int SDL_GetTextureColorMod(SDL_TextureID textureID, Uint8 *r, Uint8 *g, Uint8 *b)
- *
- * \brief Get the additional color value used in render copy operations
+ *  \brief Get the additional color value used in render copy operations.
  *  
- * \param texture The texture to query
- * \param r A pointer filled in with the source red color value
- * \param g A pointer filled in with the source green color value
- * \param b A pointer filled in with the source blue color value
+ *  \param textureID The texture to query.
+ *  \param r         A pointer filled in with the source red color value.
+ *  \param g         A pointer filled in with the source green color value.
+ *  \param b         A pointer filled in with the source blue color value.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  *  
  *  \sa SDL_SetTextureColorMod()
  */
@@ -984,14 +917,13 @@ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_TextureID textureID,
                                                    Uint8 * b);
 
 /**
- * \fn int SDL_SetTextureAlphaMod(SDL_TextureID textureID, Uint8 alpha)
+ *  \brief Set an additional alpha value used in render copy operations.
  *  
- * \brief Set an additional alpha value used in render copy operations
- *
- * \param texture The texture to update
+ *  \param textureID The texture to update.
  *  \param alpha     The source alpha value multiplied into copy operations.
  *  
- * \return 0 on success, or -1 if the texture is not valid or alpha modulation is not supported
+ *  \return 0 on success, or -1 if the texture is not valid or alpha modulation 
+ *          is not supported.
  *  
  *  \sa SDL_GetTextureAlphaMod()
  */
@@ -999,14 +931,12 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_TextureID textureID,
                                                    Uint8 alpha);
 
 /**
- * \fn int SDL_GetTextureAlphaMod(SDL_TextureID textureID, Uint8 *alpha)
- *
- * \brief Get the additional alpha value used in render copy operations
+ *  \brief Get the additional alpha value used in render copy operations.
  *  
- * \param texture The texture to query
- * \param alpha A pointer filled in with the source alpha value
+ *  \param textureID The texture to query.
+ *  \param alpha     A pointer filled in with the source alpha value.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  *  
  *  \sa SDL_SetTextureAlphaMod()
  */
@@ -1014,16 +944,16 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_TextureID textureID,
                                                    Uint8 * alpha);
 
 /**
- * \fn int SDL_SetTextureBlendMode(SDL_TextureID textureID, int blendMode)
+ *  \brief Set the blend mode used for texture copy operations.
  *  
- * \brief Set the blend mode used for texture copy operations
+ *  \param textureID The texture to update.
+ *  \param blendMode ::SDL_BlendMode to use for texture blending.
  *  
- * \param texture The texture to update
- * \param blendMode SDL_TextureBlendMode to use for texture blending
+ *  \return 0 on success, or -1 if the texture is not valid or the blend mode is
+ *          not supported.
  *  
- * \return 0 on success, or -1 if the texture is not valid or the blend mode is not supported
- *
- * \note If the blend mode is not supported, the closest supported mode is chosen.
+ *  \note If the blend mode is not supported, the closest supported mode is
+ *        chosen.
  *  
  *  \sa SDL_GetTextureBlendMode()
  */
@@ -1031,14 +961,12 @@ extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_TextureID textureID,
                                                     int blendMode);
 
 /**
- * \fn int SDL_GetTextureBlendMode(SDL_TextureID textureID, int *blendMode)
- *
- * \brief Get the blend mode used for texture copy operations
+ *  \brief Get the blend mode used for texture copy operations.
  *  
- * \param texture The texture to query
- * \param blendMode A pointer filled in with the current blend mode
+ *  \param textureID The texture to query.
+ *  \param blendMode A pointer filled in with the current blend mode.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  *  
  *  \sa SDL_SetTextureBlendMode()
  */
@@ -1046,16 +974,16 @@ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_TextureID textureID,
                                                     int *blendMode);
 
 /**
- * \fn int SDL_SetTextureScaleMode(SDL_TextureID textureID, int scaleMode)
+ *  \brief Set the scale mode used for texture copy operations.
  *  
- * \brief Set the scale mode used for texture copy operations
+ *  \param textureID The texture to update.
+ *  \param scaleMode ::SDL_TextureScaleMode to use for texture scaling.
  *  
- * \param texture The texture to update
- * \param scaleMode SDL_TextureScaleMode to use for texture scaling
+ *  \return 0 on success, or -1 if the texture is not valid or the scale mode is
+ *          not supported.
  *  
- * \return 0 on success, or -1 if the texture is not valid or the scale mode is not supported
- *
- * \note If the scale mode is not supported, the closest supported mode is chosen.
+ *  \note If the scale mode is not supported, the closest supported mode is
+ *        chosen.
  *  
  *  \sa SDL_GetTextureScaleMode()
  */
@@ -1063,14 +991,12 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_TextureID textureID,
                                                     int scaleMode);
 
 /**
- * \fn int SDL_GetTextureScaleMode(SDL_TextureID textureID, int *scaleMode)
- *
- * \brief Get the scale mode used for texture copy operations
+ *  \brief Get the scale mode used for texture copy operations.
  *  
- * \param texture The texture to query
- * \param scaleMode A pointer filled in with the current scale mode
+ *  \param textureID The texture to query.
+ *  \param scaleMode A pointer filled in with the current scale mode.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  *  
  *  \sa SDL_SetTextureScaleMode()
  */
@@ -1078,16 +1004,15 @@ extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_TextureID textureID,
                                                     int *scaleMode);
 
 /**
- * \fn int SDL_UpdateTexture(SDL_TextureID textureID, const SDL_Rect *rect, const void *pixels, int pitch)
- *
  *  \brief Update the given texture rectangle with new pixel data.
  *  
- * \param texture The texture to update
- * \param rect A pointer to the rectangle of pixels to update, or NULL to update the entire texture.
- * \param pixels The raw pixel data
- * \param pitch The number of bytes between rows of pixel data
+ *  \param textureID The texture to update
+ *  \param rect      A pointer to the rectangle of pixels to update, or NULL to 
+ *                   update the entire texture.
+ *  \param pixels    The raw pixel data.
+ *  \param pitch     The number of bytes between rows of pixel data.
  *  
- * \return 0 on success, or -1 if the texture is not valid
+ *  \return 0 on success, or -1 if the texture is not valid.
  *  
  *  \note This is a fairly slow function.
  */
@@ -1096,17 +1021,20 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID,
                                               const void *pixels, int pitch);
 
 /**
- * \fn void SDL_LockTexture(SDL_TextureID textureID, const SDL_Rect *rect, int markDirty, void **pixels, int *pitch)
- *
  *  \brief Lock a portion of the texture for pixel access.
  *  
- * \param textureID The texture to lock for access, which was created with SDL_TEXTUREACCESS_STREAMING.
- * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.
- * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked.
- * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
+ *  \param textureID The texture to lock for access, which was created with 
+ *                   ::SDL_TEXTUREACCESS_STREAMING.
+ *  \param rect      A pointer to the rectangle to lock for access. If the rect 
+ *                   is NULL, the entire texture will be locked.
+ *  \param markDirty If this is nonzero, the locked area will be marked dirty 
+ *                   when the texture is unlocked.
+ *  \param pixels    This is filled in with a pointer to the locked pixels, 
+ *                   appropriately offset by the locked area.
  *  \param pitch     This is filled in with the pitch of the locked pixels.
  *  
- * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TEXTUREACCESS_STATIC
+ *  \return 0 on success, or -1 if the texture is not valid or was created with 
+ *          ::SDL_TEXTUREACCESS_STATIC.
  *  
  *  \sa SDL_DirtyTexture()
  *  \sa SDL_UnlockTexture()
@@ -1117,8 +1045,6 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
                                             int *pitch);
 
 /**
- * \fn void SDL_UnlockTexture(SDL_TextureID textureID)
- *
  *  \brief Unlock a texture, uploading the changes to video memory, if needed.
  *  
  *  \sa SDL_LockTexture()
@@ -1127,11 +1053,10 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
 extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_TextureID textureID);
 
 /**
- * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, const SDL_Rect * rects)
- *
  *  \brief Mark the specified rectangles of the texture as dirty.
  *  
- * \param textureID The texture to mark dirty, which was created with SDL_TEXTUREACCESS_STREAMING.
+ *  \param textureID The texture to mark dirty, which was created with 
+ *                   ::SDL_TEXTUREACCESS_STREAMING.
  *  \param numrects  The number of rectangles pointed to by rects.
  *  \param rects     The pointer to an array of dirty rectangles.
  *  
@@ -1143,121 +1068,114 @@ extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
                                               const SDL_Rect * rects);
 
 /**
- * \fn int SDL_SetRenderDrawColor(Uint8 r, Uint8 g, Uint8 b, Uint8 a)
- *
  *  \brief Set the color used for drawing operations (Fill and Line).
  *  
- * \param r The red value used to draw on the rendering target
- * \param g The green value used to draw on the rendering target
- * \param b The blue value used to draw on the rendering target
- * \param a The alpha value used to draw on the rendering target, usually SDL_ALPHA_OPAQUE (255)
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \param r The red value used to draw on the rendering target.
+ *  \param g The green value used to draw on the rendering target.
+ *  \param b The blue value used to draw on the rendering target.
+ *  \param a The alpha value used to draw on the rendering target, usually 
+ *           ::SDL_ALPHA_OPAQUE (255).
+ *  
+ *  \return 0 on success, or -1 if there is no rendering context current.
  */
 extern DECLSPEC int SDL_SetRenderDrawColor(Uint8 r, Uint8 g, Uint8 b,
                                            Uint8 a);
 
 /**
- * \fn int SDL_GetRenderDrawColor(Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a)
- *
  *  \brief Get the color used for drawing operations (Fill and Line).
  *  
- * \param r A pointer to the red value used to draw on the rendering target
- * \param g A pointer to the green value used to draw on the rendering target
- * \param b A pointer to the blue value used to draw on the rendering target
- * \param a A pointer to the alpha value used to draw on the rendering target, usually SDL_ALPHA_OPAQUE (255)
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \param r A pointer to the red value used to draw on the rendering target.
+ *  \param g A pointer to the green value used to draw on the rendering target.
+ *  \param b A pointer to the blue value used to draw on the rendering target.
+ *  \param a A pointer to the alpha value used to draw on the rendering target, 
+ *           usually ::SDL_ALPHA_OPAQUE (255).
+ *  
+ *  \return 0 on success, or -1 if there is no rendering context current.
  */
 extern DECLSPEC int SDL_GetRenderDrawColor(Uint8 * r, Uint8 * g, Uint8 * b,
                                            Uint8 * a);
 
 /**
- * \fn int SDL_SetRenderDrawBlendMode(int blendMode)
- *
  *  \brief Set the blend mode used for drawing operations (Fill and Line).
  *  
- * \param blendMode SDL_BlendMode to use for blending
+ *  \param blendMode ::SDL_BlendMode to use for blending.
  *  
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \return 0 on success, or -1 if there is no rendering context current.
  *  
- * \note If the blend mode is not supported, the closest supported mode is chosen.
+ *  \note If the blend mode is not supported, the closest supported mode is 
+ *        chosen.
  *  
- * \sa SDL_SetRenderDrawBlendMode()
+ *  \sa SDL_GetRenderDrawBlendMode()
  */
 extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(int blendMode);
 
 /**
- * \fn int SDL_GetRenderDrawBlendMode(int *blendMode)
+ *  \brief Get the blend mode used for drawing operations.
  *  
- * \brief Get the blend mode used for drawing operations
+ *  \param blendMode A pointer filled in with the current blend mode.
  *  
- * \param blendMode A pointer filled in with the current blend mode
- *
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \return 0 on success, or -1 if there is no rendering context current.
  *  
  *  \sa SDL_SetRenderDrawBlendMode()
  */
 extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(int *blendMode);
 
 /**
- * \fn int SDL_RenderPoint(int x, int y)
- *
  *  \brief Draw a point on the current rendering target.
  *  
- * \param x The x coordinate of the point
- * \param y The y coordinate of the point
+ *  \param x The x coordinate of the point.
+ *  \param y The y coordinate of the point.
  *  
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \return 0 on success, or -1 if there is no rendering context current.
  */
 extern DECLSPEC int SDLCALL SDL_RenderPoint(int x, int y);
 
 /**
- * \fn int SDL_RenderLine(int x1, int y1, int x2, int y2)
- *
  *  \brief Draw a line on the current rendering target.
  *  
- * \param x1 The x coordinate of the start point
- * \param y1 The y coordinate of the start point
- * \param x2 The x coordinate of the end point
- * \param y2 The y coordinate of the end point
+ *  \param x1 The x coordinate of the start point.
+ *  \param y1 The y coordinate of the start point.
+ *  \param x2 The x coordinate of the end point.
+ *  \param y2 The y coordinate of the end point.
  *  
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \return 0 on success, or -1 if there is no rendering context current.
  */
 extern DECLSPEC int SDLCALL SDL_RenderLine(int x1, int y1, int x2, int y2);
 
 /**
- * \fn void SDL_RenderFill(const SDL_Rect *rect)
- *
  *  \brief Fill the current rendering target with the drawing color.
  *  
- * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
+ *  \param rect A pointer to the destination rectangle, or NULL for the entire 
+ *              rendering target.
  *  
- * \return 0 on success, or -1 if there is no rendering context current
+ *  \return 0 on success, or -1 if there is no rendering context current.
  */
 extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect);
 
 /**
- * \fn int SDL_RenderCopy(SDL_TextureID textureID, const SDL_Rect *srcrect, const SDL_Rect *dstrect)
- *
  *  \brief Copy a portion of the texture to the current rendering target.
  *  
- * \param texture The source texture.
- * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
- * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
+ *  \param textureID The source texture.
+ *  \param srcrect   A pointer to the source rectangle, or NULL for the entire 
+ *                   texture.
+ *  \param dstrect   A pointer to the destination rectangle, or NULL for the 
+ *                   entire rendering target.
  *  
- * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
+ *  \return 0 on success, or -1 if there is no rendering context current, or the
+ *          driver doesn't support the requested operation.
  */
 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
                                            const SDL_Rect * srcrect,
                                            const SDL_Rect * dstrect);
 
 /**
- * \fn int SDL_RenderReadPixels(const SDL_Rect *rect, void *pixels, int pitch)
- *
  *  \brief Read pixels from the current rendering target.
  *  
- * \param rect A pointer to the rectangle to read, or NULL for the entire render target
- * \param pixels A pointer to be filled in with the pixel data in the rendering target format
- * \param pitch The pitch of the pixels parameter
+ *  \param rect   A pointer to the rectangle to read, or NULL for the entire 
+ *                render target.
+ *  \param pixels A pointer to be filled in with the pixel data in the rendering
+ *                target format.
+ *  \param pitch  The pitch of the pixels parameter.
  *  
  *  \return 0 on success, or -1 if pixel reading is not supported.
  *  
@@ -1267,13 +1185,12 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(const SDL_Rect * rect,
                                                  void *pixels, int pitch);
 
 /**
- * \fn int SDL_RenderWritePixels(const SDL_Rect *rect, const void *pixels, int pitch)
- *
  *  \brief Write pixels to the current rendering target.
  *  
- * \param rect A pointer to the rectangle to write, or NULL for the entire render target
- * \param pixels A pointer to the pixel data to write
- * \param pitch The pitch of the pixels parameter
+ *  \param rect   A pointer to the rectangle to write, or NULL for the entire 
+ *                render target.
+ *  \param pixels A pointer to the pixel data to write.
+ *  \param pitch  The pitch of the pixels parameter.
  *  
  *  \return 0 on success, or -1 if pixel writing is not supported.
  *  
@@ -1284,15 +1201,11 @@ extern DECLSPEC int SDLCALL SDL_RenderWritePixels(const SDL_Rect * rect,
                                                   int pitch);
 
 /**
- * \fn void SDL_RenderPresent(void)
- *
  *  \brief Update the screen with rendering performed.
  */
 extern DECLSPEC void SDLCALL SDL_RenderPresent(void);
 
 /**
- * \fn void SDL_DestroyTexture(SDL_TextureID textureID);
- *
  *  \brief Destroy the specified texture.
  *  
  *  \sa SDL_CreateTexture()
@@ -1301,8 +1214,6 @@ extern DECLSPEC void SDLCALL SDL_RenderPresent(void);
 extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID);
 
 /**
- * \fn void SDL_DestroyRenderer(SDL_WindowID windowID);
- *
  *  \brief Destroy the rendering context for a window and free associated
  *         textures.
  *  
@@ -1311,8 +1222,6 @@ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID);
 extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID);
 
 /**
- * \fn SDL_bool SDL_IsScreenSaverEnabled();
- *
  *  \brief Returns whether the screensaver is currently enabled (default off).
  *  
  *  \sa SDL_EnableScreenSaver()
@@ -1321,8 +1230,6 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID);
 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
 
 /**
- * \fn void SDL_EnableScreenSaver();
- *
  *  \brief Allow the screen to be blanked by a screensaver
  *  
  *  \sa SDL_IsScreenSaverEnabled()
@@ -1331,8 +1238,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
 extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
 
 /**
- * \fn void SDL_DisableScreenSaver();
- *
  *  \brief Prevent the screen from being blanked by a screensaver
  *  
  *  \sa SDL_IsScreenSaverEnabled()
@@ -1341,18 +1246,18 @@ extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
 extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
 
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* OpenGL support functions.                                                 */
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/**
+ *  \name OpenGL support functions
+ */
+/*@{*/
 
 /**
- * \fn int SDL_GL_LoadLibrary(const char *path)
- *
  *  \brief Dynamically load an OpenGL library.
  *  
- * \param path The platform dependent OpenGL library name, or NULL to open the default OpenGL library
+ *  \param path The platform dependent OpenGL library name, or NULL to open the 
+ *              default OpenGL library.
  *  
- * \return 0 on success, or -1 if the library couldn't be loaded
+ *  \return 0 on success, or -1 if the library couldn't be loaded.
  *  
  *  This should be done after initializing the video driver, but before
  *  creating any OpenGL windows.  If no OpenGL library is loaded, the default
@@ -1367,47 +1272,37 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
 
 /**
- * \fn void *SDL_GL_GetProcAddress(const char *proc)
- *
  *  \brief Get the address of an OpenGL function.
  */
 extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
 
 /**
- * \fn void SDL_GL_UnloadLibrary(void)
- *
- * \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary()
+ *  \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
  *  
  *  \sa SDL_GL_LoadLibrary()
  */
 extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
 
 /**
- * \fn SDL_bool SDL_GL_ExtensionSupported(const char *extension)
- *
- * \brief Return true if an OpenGL extension is supported for the current context.
+ *  \brief Return true if an OpenGL extension is supported for the current 
+ *         context.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
                                                            *extension);
 
 /**
- * \fn int SDL_GL_SetAttribute(SDL_GLattr attr, int value)
- *
  *  \brief Set an OpenGL window attribute before window creation.
  */
 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
 
 /**
- * \fn int SDL_GL_GetWindowAttribute(SDL_WindowID windowID, SDL_GLattr attr, int *value)
- *
  *  \brief Get the actual value for an attribute from the current context.
  */
 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
 
 /**
- * \fn SDL_GLContext SDL_GL_CreateContext(SDL_WindowID windowID)
- *
- * \brief Create an OpenGL context for use with an OpenGL window, and make it current.
+ *  \brief Create an OpenGL context for use with an OpenGL window, and make it 
+ *         current.
  *  
  *  \sa SDL_GL_DeleteContext()
  */
@@ -1415,8 +1310,6 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_WindowID
                                                            windowID);
 
 /**
- * \fn int SDL_GL_MakeCurrent(SDL_WindowID windowID, SDL_GLContext context)
- *
  *  \brief Set up an OpenGL context for rendering into an OpenGL window.
  *  
  *  \note The context must have been created with a compatible window.
@@ -1425,11 +1318,10 @@ extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_WindowID windowID,
                                                SDL_GLContext context);
 
 /**
- * \fn int SDL_GL_SetSwapInterval(int interval)
- *
  *  \brief Set the swap interval for the current OpenGL context.
  *  
- * \param interval 0 for immediate updates, 1 for updates synchronized with the vertical retrace
+ *  \param interval 0 for immediate updates, 1 for updates synchronized with the
+ *                  vertical retrace.
  *  
  *  \return 0 on success, or -1 if setting the swap interval is not supported.
  *  
@@ -1438,32 +1330,31 @@ extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_WindowID windowID,
 extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
 
 /**
- * \fn int SDL_GL_GetSwapInterval(void)
- *
  *  \brief Get the swap interval for the current OpenGL context.
  *  
- * \return 0 if there is no vertical retrace synchronization, 1 if the buffer swap is synchronized with the vertical retrace, and -1 if getting the swap interval is not supported.
+ *  \return 0 if there is no vertical retrace synchronization, 1 if the buffer 
+ *          swap is synchronized with the vertical retrace, and -1 if getting 
+ *          the swap interval is not supported.
  *  
  *  \sa SDL_GL_SetSwapInterval()
  */
 extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
 
 /**
- * \fn void SDL_GL_SwapWindow(SDL_WindowID windowID)
- *
- * \brief Swap the OpenGL buffers for the window, if double-buffering is supported.
+ * \brief Swap the OpenGL buffers for the window, if double-buffering is 
+ *        supported.
  */
 extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_WindowID windowID);
 
 /**
- * \fn void SDL_GL_DeleteContext(SDL_GLContext context)
- *
  *  \brief Delete an OpenGL context.
  *  
  *  \sa SDL_GL_CreateContext()
  */
 extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
 
+/*@}*//*OpenGL support functions*/
+
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/begin_code.h

@@ -20,10 +20,13 @@
     slouken@libsdl.org
 */
 
-/* This file sets things up for C dynamic library function definitions,
-   static inlined functions, and structures aligned at 4-byte alignment.
-   If you don't like ugly C preprocessor code, don't look at this file. :)
-*/
+/**
+ *  \file begin_code.h
+ *
+ *  This file sets things up for C dynamic library function definitions,
+ *  static inlined functions, and structures aligned at 4-byte alignment.
+ *  If you don't like ugly C preprocessor code, don't look at this file. :)
+ */
 
 /* This shouldn't be nested -- included it around code only. */
 #ifdef _begin_code_h

include/close_code.h

@@ -20,9 +20,12 @@
     slouken@libsdl.org
 */
 
-/* This file reverses the effects of begin_code.h and should be included
-   after you finish any function and structure declarations in your headers
-*/
+/**
+ *  \file close_code.h
+ *  
+ *  This file reverses the effects of begin_code.h and should be included
+ *  after you finish any function and structure declarations in your headers
+ */
 
 #undef _begin_code_h