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

@@ -21,54 +21,55 @@
 */
 
 /**
- * \file SDL.h
- *
- * Main include header for the SDL library
+ *  \file SDL.h
+ *  
+ *  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)
+/**
+ *  \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)
  */
 
 #ifndef _SDL_H
@@ -102,44 +103,52 @@ 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)
+ *  This function loads the SDL dynamically linked library and initializes 
+ *  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);
 
 /**
- * This function initializes specific SDL subsystems
+ *  This function initializes specific SDL subsystems
  */
 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);
 
 /**
- * This function cleans up all initialized subsystems and unloads the
- * dynamically linked library.  You should call it upon all exit conditions.
+ *  This function cleans up all initialized subsystems and unloads the
+ *  dynamically linked library.  You should call it upon all exit conditions.
  */
 extern DECLSPEC void SDLCALL SDL_Quit(void);
 

include/SDL_atomic.h

@@ -23,9 +23,19 @@
  */
 
 /**
- * \file SDL_atomic.h
- *
- * Atomic operations.
+ *  \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.
- * 
- * The spin lock functions and type are required and can not be
- * emulated because they are used in the emulation code.
+ *  \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.
- *
+ *  \brief Lock a spin lock by setting it to a none zero value.
+ *  
+ *  \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.
+ *  \brief Unlock a spin lock by setting it to 0. Always returns immediately
  *
+ *  \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.
- *
- * \return SDL_True if the value pointed to by ptr was zero and
- * SDL_False if it was not zero
- *
- * \param ptr points to the value to be tested and set.
- *
+ *  \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 \c ptr was zero and
+ *          SDL_False if it was not zero
+ *  
+ *  \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
- * value in place.
- *
- * \return the value before it was incremented.
- *
- * \param ptr address of the value to fetch and increment
- *
+ *  \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
  */
 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.
- *
- * \param ptr address of the value to fetch and drement
- *
+ *  \brief Fetch \c *ptr and then decrement the value in place.
+ *  
+ *  \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 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. 
- *
+ *  \brief Fetch the current value at \c ptr and then add \c value to \c *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.
- *
- * \return *ptr before the subtraction took place.
- *
- * \param ptr the address of the data being changed.
- * \param value the value to subtract from *ptr.
- *
+ *  \brief Fetch \c *ptr and then subtract \c value from it.
+ *  
+ *  \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.
- *
- * \return the incremented value.
- *
- * \param ptr address of the data to increment.
- *
+ *  \brief Add one to the data pointed to by \c ptr and return that value.
+ *  
+ *  \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.
- *
- * \return The decremented value.
- *
- * \param ptr The address of the data to decrement.
- *
+ *  \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.
- *
- * \return The sum of *ptr and value.
- *
- * \param ptr The address of the data to be modified.
- * \param value The value to be added.
- *
+ *  \brief Add \c value to the data pointed to by \c ptr and return result.
+ *  
+ *  \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 value from the data pointed to by ptr and return the result.
- *
- * \return the difference between *ptr and value.
- *
- * \param ptr The address of the data to be modified.
- * \param value The value to be subtracted.
- *
+ *  \brief Subtract \c value from the data pointed to by \c ptr and return the result.
+ *  
+ *  \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_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

@@ -21,9 +21,9 @@
 */
 
 /**
- * \file SDL_cpuinfo.h
- *
- * CPU feature detection for SDL
+ *  \file SDL_cpuinfo.h
+ *  
+ *  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

@@ -21,9 +21,9 @@
 */
 
 /**
- * \file SDL_endian.h
- *
- * Functions for reading and writing endian-specific values
+ *  \file SDL_endian.h
+ *  
+ *  Functions for reading and writing endian-specific values
  */
 
 #ifndef _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

@@ -21,8 +21,9 @@
 */
 
 /**
- * \file SDL_error.h
- * Simple error message routines for SDL
+ *  \file SDL_error.h
+ *  
+ *  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_joystick.h

@@ -21,9 +21,9 @@
 */
 
 /**
- * \file SDL_joystick.h
- *
- * Include file for SDL joystick event handling
+ *  \file SDL_joystick.h
+ *  
+ *  Include file for SDL joystick event handling
  */
 
 #ifndef _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
+/**
+ *  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.
+/**
+ *  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.
- *
- * This function returns a joystick identifier, or NULL if an error occurred.
+/**
+ *  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.
+ *  
+ *  \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.
+/**
+ *  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.
+/**
+ *  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
- * Joystick trackballs have only relative motion events associated
- * with them and their state cannot be polled.
+/**
+ *  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.
+/**
+ *  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.
+/**
+ *  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.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 
-/*
- * 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.
+/**
+ *  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)
-/*
- * The hat indices start at index 0.
+/*@}*/
+
+/**
+ *  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.
- * The ball indices start at index 0.
+/**
+ *  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
- * The button indices start at index 0.
+/**
+ *  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

@@ -21,9 +21,9 @@
 */
 
 /**
- * \file SDL_keyboard.h
- *
- * Include file for SDL keyboard event handling
+ *  \file SDL_keyboard.h
+ *  
+ *  Include file for SDL keyboard event handling
  */
 
 #ifndef _SDL_keyboard_h
@@ -42,143 +42,129 @@ extern "C" {
 #endif
 
 /**
- * \struct SDL_keysym
- *
- * \brief The SDL keysym structure, used in key events.
+ *  \brief The SDL keysym structure, used in key events.
  */
 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()
+ *  \brief Get the number of keyboard input devices available.
+ *  
+ *  \sa SDL_SelectKeyboard()
  */
 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.
- *
- * \note You can query the currently selected keyboard by passing an index of -1.
- *
- * \sa SDL_GetNumKeyboards()
+ *  \brief Set the index of the currently selected keyboard.
+ *  
+ *  \return The index of the previously selected keyboard.
+ *  
+ *  \note You can query the currently selected keyboard by passing an index of -1.
+ *  
+ *  \sa SDL_GetNumKeyboards()
  */
 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:
- * 	Uint8 *state = SDL_GetKeyboardState(NULL);
- *	if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed.
+ *  \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.
+ *  
+ *  \b Example:
+ *  \code
+ *  Uint8 *state = SDL_GetKeyboardState(NULL);
+ *  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.
+ *  \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.
+ *  \brief Set the current key modifier state for the selected keyboard.
+ *  
+ *  \note This does not change the keyboard state, only the key modifier flags.
  */
 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.
- *
- * See ::SDLKey for details.
- *
- * \sa SDL_GetKeyName()
+ *  \brief Get the key code corresponding to the given scancode according to the
+ *         current keyboard layout.
+ *  
+ *  See ::SDLKey for details.
+ *  
+ *  \sa SDL_GetKeyName()
  */
 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.
- *
- * See ::SDL_scancode for details.
- *
- * \sa SDL_GetScancodeName()
+ *  \brief Get the scancode corresponding to the given key code according to the
+ *         current keyboard layout.
+ *  
+ *  See ::SDL_scancode for details.
+ *  
+ *  \sa SDL_GetScancodeName()
  */
 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 "".
- *
- * \sa SDL_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
+ *          an empty string ("").
+ *
+ *  \sa SDL_scancode
  */
 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 "".
- *
- * \sa SDLKey
+ *  \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 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()
- * \sa SDL_SetTextInputRect()
+ *  \brief Start accepting Unicode text input events.
+ *  
+ *  \sa SDL_StopTextInput()
+ *  \sa SDL_SetTextInputRect()
  */
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
 /**
- * \fn void SDL_StopTextInput(void)
- *
- * \brief Stop receiving any text input events.
- *
- * \sa SDL_StartTextInput()
+ *  \brief Stop receiving any text input events.
+ *  
+ *  \sa SDL_StartTextInput()
  */
 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()
+ *  \brief Set the rectangle used to type Unicode text inputs.
+ *  
+ *  \sa SDL_StartTextInput()
  */
 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
 

include/SDL_keysym.h

@@ -21,7 +21,9 @@
 */
 
 /**
- * \file SDL_keysym.h
+ *  \file SDL_keysym.h
+ *  
+ *  Defines constants which identify keyboard keys and modifiers.
  */
 
 #ifndef _SDL_keysym_h
@@ -31,14 +33,12 @@
 #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
- * layout of the keyboard.  These values include Unicode values representing
- * the unmodified character that would be generated by pressing the key, or
- * an SDLK_* constant for those keys that do not generate characters.
+ *  \brief The SDL virtual key representation.
+ *  
+ *  Values of this type are used to represent keyboard keys using the current
+ *  layout of the keyboard.  These values include Unicode values representing
+ *  the unmodified character that would be generated by pressing the key, or
+ *  an SDLK_* constant for those keys that do not generate characters.
  */
 typedef Sint32 SDLKey;
 
@@ -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

@@ -21,22 +21,22 @@
 */
 
 /**
- * \file SDL_loadso.h
+ *  \file SDL_loadso.h
  *
- * System dependent library loading routines
+ *  System dependent library loading routines
  *
- * Some things to keep in mind:                                        
- * - 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
- *   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,
- *   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
- *   the results you expect. :)
+ *  Some things to keep in mind:                                        
+ *  \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.
+ *  \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.
+ *  \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
+ *      the results you expect. :)
  */
 
 #ifndef _SDL_loadso_h
@@ -53,20 +53,24 @@ extern "C" {
 /* *INDENT-ON* */
 #endif
 
-/* 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.
+/**
+ *  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
- * named function in the shared object and returns it.  This address
- * is no longer valid after calling SDL_UnloadObject().
+/**
+ *  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_mutex.h

@@ -24,9 +24,9 @@
 #define _SDL_mutex_h
 
 /**
- * \file SDL_mutex.h
- *
- * Functions to provide thread synchronization primitives
+ *  \file SDL_mutex.h
+ *  
+ *  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_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,8 +137,7 @@ extern "C" {
 #endif
 
 /**
- * \fn const char *SDL_GetPlatform(void)
- * \brief Gets the name of the platform.
+ *  \brief Gets the name of the platform.
  */
 extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
 

include/SDL_power.h

@@ -24,9 +24,9 @@
 #define _SDL_power_h
 
 /**
- * \file SDL_power.h
- *
- * Header for the SDL power management routines
+ *  \file SDL_power.h
+ *  
+ *  Header for the SDL power management routines.
  */
 
 #include "SDL_stdinc.h"
@@ -40,9 +40,7 @@ extern "C" {
 #endif
 
 /**
- * \enum SDL_PowerState
- *
- * \brief The basic state for the system's power supply.
+ *  \brief The basic state for the system's power supply.
  */
 typedef enum
 {
@@ -55,19 +53,17 @@ 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
- *                you don't care. Will return -1 if we can't determine a
- *                value, or we're not running on a battery.
- *
- * \param pct Percentage of battery life left, between 0 and 100. You can
- *                pass a NULL here if you don't care. Will return -1 if we
- *                can't determine a value, or we're not running on a battery.
- *
- * \return The state of the battery (if any).
+ *  \brief Get the current power supply details.
+ *  
+ *  \param secs Seconds of battery life left. You can pass a NULL here if
+ *              you don't care. Will return -1 if we can't determine a
+ *              value, or we're not running on a battery.
+ *  
+ *  \param pct Percentage of battery life left, between 0 and 100. You can
+ *             pass a NULL here if you don't care. Will return -1 if we
+ *             can't determine a value, or we're not running on a battery.
+ *  
+ *  \return The state of the battery (if any).
  */
 extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
 

include/SDL_types.h

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