Fixed bug #706

 Ken Bull      2009-02-25 13:22:02 PST

Adds Doxygen support for all headers (except config and boilerplate headers) in
the include folder for SDL-1.2 revision 4446.

While in general SDL is quite thoroughly commented, none of these comments are
correctly formatted for Doxygen and are generally inconsistent in their
formatting.

--HG--
branch : SDL-1.2
extra : convert_revision : svn%3Ac70aab31-4412-0410-b14c-859654838e24/branches/SDL-1.2%403857

include/SDL.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Main include header for the SDL library */
+/** @file SDL.h
+ *  Main include header for the SDL library
+ */
 
 #ifndef _SDL_H
 #define _SDL_H
@@ -47,40 +49,45 @@
 extern "C" {
 #endif
 
-/* As of version 0.5, SDL is loaded dynamically into the application */
+/** @file SDL.h
+ *  @note 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 Flags
+ *  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_CDROM		0x00000100
 #define SDL_INIT_JOYSTICK	0x00000200
-#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 
+/** 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)
  */
 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 '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
+/** 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_active.h

@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL application focus event handling */
+/**
+ *  @file SDL_active.h
+ *  Include file for SDL application focus event handling 
+ */
 
 #ifndef _SDL_active_h
 #define _SDL_active_h
@@ -34,13 +37,15 @@
 extern "C" {
 #endif
 
-/* The available application states */
-#define SDL_APPMOUSEFOCUS	0x01		/* The app has mouse coverage */
-#define SDL_APPINPUTFOCUS	0x02		/* The app has input focus */
-#define SDL_APPACTIVE		0x04		/* The application is active */
+/** @name The available application states */
+/*@{*/
+#define SDL_APPMOUSEFOCUS	0x01		/**< The app has mouse coverage */
+#define SDL_APPINPUTFOCUS	0x02		/**< The app has input focus */
+#define SDL_APPACTIVE		0x04		/**< The application is active */
+/*@}*/
 
 /* Function prototypes */
-/* 
+/** 
  * This function returns the current state of the application, which is a
  * bitwise combination of SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and
  * SDL_APPACTIVE.  If SDL_APPACTIVE is set, then the user is able to

include/SDL_byteorder.h

@@ -20,5 +20,10 @@
     slouken@libsdl.org
 */
 
+/**
+ *  @file SDL_byteorder.h
+ *  @deprecated Use SDL_endian.h instead
+ */
+
 /* DEPRECATED */
 #include "SDL_endian.h"

include/SDL_cdrom.h

@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* This is the CD-audio control API for Simple DirectMedia Layer */
+/**
+ *  @file SDL_cdrom.h
+ *  This is the CD-audio control API for Simple DirectMedia Layer
+ */
 
 #ifndef _SDL_cdrom_h
 #define _SDL_cdrom_h
@@ -34,19 +37,25 @@
 extern "C" {
 #endif
 
-/* In order to use these functions, SDL_Init() must have been called
-   with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
-   for CD-ROM drives, and load appropriate drivers.
-*/
+/**
+ *  @file SDL_cdrom.h
+ *  In order to use these functions, SDL_Init() must have been called
+ *  with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
+ *  for CD-ROM drives, and load appropriate drivers.
+ */
 
-/* The maximum number of CD-ROM tracks on a disk */
+/** The maximum number of CD-ROM tracks on a disk */
 #define SDL_MAX_TRACKS	99
 
-/* The types of CD-ROM track possible */
+/** @name Track Types
+ *  The types of CD-ROM track possible
+ */
+/*@{*/
 #define SDL_AUDIO_TRACK	0x00
 #define SDL_DATA_TRACK	0x04
+/*@}*/
 
-/* The possible states which a CD-ROM drive can be in. */
+/** The possible states which a CD-ROM drive can be in. */
 typedef enum {
 	CD_TRAYEMPTY,
 	CD_STOPPED,
@@ -55,30 +64,35 @@ typedef enum {
 	CD_ERROR = -1
 } CDstatus;
 
-/* Given a status, returns true if there's a disk in the drive */
+/** Given a status, returns true if there's a disk in the drive */
 #define CD_INDRIVE(status)	((int)(status) > 0)
 
 typedef struct SDL_CDtrack {
-	Uint8 id;		/* Track number */
-	Uint8 type;		/* Data or audio track */
+	Uint8 id;		/**< Track number */
+	Uint8 type;		/**< Data or audio track */
 	Uint16 unused;
-	Uint32 length;		/* Length, in frames, of this track */
-	Uint32 offset;		/* Offset, in frames, from start of disk */
+	Uint32 length;		/**< Length, in frames, of this track */
+	Uint32 offset;		/**< Offset, in frames, from start of disk */
 } SDL_CDtrack;
 
-/* This structure is only current as of the last call to SDL_CDStatus() */
+/** This structure is only current as of the last call to SDL_CDStatus() */
 typedef struct SDL_CD {
-	int id;			/* Private drive identifier */
-	CDstatus status;	/* Current drive status */
-
-	/* The rest of this structure is only valid if there's a CD in drive */
-	int numtracks;		/* Number of tracks on disk */
-	int cur_track;		/* Current track position */
-	int cur_frame;		/* Current frame offset within current track */
+	int id;			/**< Private drive identifier */
+	CDstatus status;	/**< Current drive status */
+
+	/** The rest of this structure is only valid if there's a CD in drive */
+        /*@{*/
+	int numtracks;		/**< Number of tracks on disk */
+	int cur_track;		/**< Current track position */
+	int cur_frame;		/**< Current frame offset within current track */
 	SDL_CDtrack track[SDL_MAX_TRACKS+1];
+        /*@}*/
 } SDL_CD;
 
-/* Conversion functions from frames to Minute/Second/Frames and vice versa */
+/** @name Frames / MSF Conversion Functions
+ *  Conversion functions from frames to Minute/Second/Frames and vice versa
+ */
+/*@{*/
 #define CD_FPS	75
 #define FRAMES_TO_MSF(f, M,S,F)	{					\
 	int value = f;							\
@@ -89,76 +103,93 @@ typedef struct SDL_CD {
 	*(M) = value;							\
 }
 #define MSF_TO_FRAMES(M, S, F)	((M)*60*CD_FPS+(S)*CD_FPS+(F))
+/*@}*/
 
 /* CD-audio API functions: */
 
-/* Returns the number of CD-ROM drives on the system, or -1 if
-   SDL_Init() has not been called with the SDL_INIT_CDROM flag.
+/**
+ *  Returns the number of CD-ROM drives on the system, or -1 if
+ *  SDL_Init() has not been called with the SDL_INIT_CDROM flag.
  */
 extern DECLSPEC int SDLCALL SDL_CDNumDrives(void);
 
-/* Returns a human-readable, system-dependent identifier for the CD-ROM.
-   Example:
-	"/dev/cdrom"
-	"E:"
-	"/dev/disk/ide/1/master"
-*/
+/**
+ *  Returns a human-readable, system-dependent identifier for the CD-ROM.
+ *  Example:
+ *   - "/dev/cdrom"
+ *   - "E:"
+ *   - "/dev/disk/ide/1/master"
+ */
 extern DECLSPEC const char * SDLCALL SDL_CDName(int drive);
 
-/* Opens a CD-ROM drive for access.  It returns a drive handle on success,
-   or NULL if the drive was invalid or busy.  This newly opened CD-ROM
-   becomes the default CD used when other CD functions are passed a NULL
-   CD-ROM handle.
-   Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
-*/
+/**
+ *  Opens a CD-ROM drive for access.  It returns a drive handle on success,
+ *  or NULL if the drive was invalid or busy.  This newly opened CD-ROM
+ *  becomes the default CD used when other CD functions are passed a NULL
+ *  CD-ROM handle.
+ *  Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
+ */
 extern DECLSPEC SDL_CD * SDLCALL SDL_CDOpen(int drive);
 
-/* This function returns the current status of the given drive.
-   If the drive has a CD in it, the table of contents of the CD and current
-   play position of the CD will be stored in the SDL_CD structure.
-*/
+/**
+ *  This function returns the current status of the given drive.
+ *  If the drive has a CD in it, the table of contents of the CD and current
+ *  play position of the CD will be stored in the SDL_CD structure.
+ */
 extern DECLSPEC CDstatus SDLCALL SDL_CDStatus(SDL_CD *cdrom);
 
-/* Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
-   tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
-   until the end of the CD.  This function will skip data tracks.
-   This function should only be called after calling SDL_CDStatus() to 
-   get track information about the CD.
-   For example:
-	// Play entire CD:
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
-		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
-	// Play last track:
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
-		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
-	}
-	// Play first and second track and 10 seconds of third track:
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
-		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
-
-   This function returns 0, or -1 if there was an error.
-*/
+/**
+ *  Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
+ *  tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
+ *  until the end of the CD.  This function will skip data tracks.
+ *  This function should only be called after calling SDL_CDStatus() to 
+ *  get track information about the CD.
+ *  For example:
+ *      @code
+ *	// Play entire CD:
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
+ *		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
+ *	// Play last track:
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
+ *		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
+ *	}
+ *	// Play first and second track and 10 seconds of third track:
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
+ *		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
+ *      @endcode
+ *
+ *  @return This function returns 0, or -1 if there was an error.
+ */
 extern DECLSPEC int SDLCALL SDL_CDPlayTracks(SDL_CD *cdrom,
 		int start_track, int start_frame, int ntracks, int nframes);
 
-/* Play the given CD starting at 'start' frame for 'length' frames.
-   It returns 0, or -1 if there was an error.
-*/
+/**
+ *  Play the given CD starting at 'start' frame for 'length' frames.
+ *  @return It returns 0, or -1 if there was an error.
+ */
 extern DECLSPEC int SDLCALL SDL_CDPlay(SDL_CD *cdrom, int start, int length);
 
-/* Pause play -- returns 0, or -1 on error */
+/** Pause play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDPause(SDL_CD *cdrom);
 
-/* Resume play -- returns 0, or -1 on error */
+/** Resume play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDResume(SDL_CD *cdrom);
 
-/* Stop play -- returns 0, or -1 on error */
+/** Stop play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDStop(SDL_CD *cdrom);
 
-/* Eject CD-ROM -- returns 0, or -1 on error */
+/** Eject CD-ROM
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDEject(SDL_CD *cdrom);
 
-/* Closes the handle for the CD-ROM drive */
+/** Closes the handle for the CD-ROM drive */
 extern DECLSPEC void SDLCALL SDL_CDClose(SDL_CD *cdrom);
 
 

include/SDL_cpuinfo.h

@@ -20,8 +20,10 @@
     slouken@libsdl.org
 */
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* CPU feature detection for SDL                                       */
+/**
+ *  @file SDL_cpuinfo.h
+ *  CPU feature detection for SDL
+ */
 
 #ifndef _SDL_cpuinfo_h
 #define _SDL_cpuinfo_h
@@ -34,36 +36,28 @@
 extern "C" {
 #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);
 
 /* Ends C function definitions when using C++ */

include/SDL_endian.h

@@ -20,16 +20,23 @@
     slouken@libsdl.org
 */
 
-/* Functions for reading and writing endian-specific values */
+/**
+ *  @file SDL_endian.h
+ *  Functions for reading and writing endian-specific values
+ */
 
 #ifndef _SDL_endian_h
 #define _SDL_endian_h
 
 #include "SDL_stdinc.h"
 
-/* The two types of endianness */
+/** @name SDL_ENDIANs
+ *  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__) || \
@@ -50,11 +57,14 @@
 extern "C" {
 #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.
-*/
+/**
+ *  @name SDL_Swap Functions
+ *  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.
+ */
+/*@{*/
 #if defined(__GNUC__) && defined(__i386__) && \
    !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 static __inline__ Uint16 SDL_Swap16(Uint16 x)
@@ -161,14 +171,18 @@ static __inline__ Uint64 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.
-*/
+ * 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 */
+/*@}*/
 
-
-/* Byteswap item from the specified endianness to the native endianness */
+/**
+ *  @name SDL_SwapLE and SDL_SwapBE Functions
+ *  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)
@@ -184,6 +198,7 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
 #define SDL_SwapBE32(X)	(X)
 #define SDL_SwapBE64(X)	(X)
 #endif
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_error.h

@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Simple error message routines for SDL */
+/**
+ *  @file SDL_error.h
+ *  Simple error message routines for SDL
+ */
 
 #ifndef _SDL_error_h
 #define _SDL_error_h
@@ -33,12 +36,20 @@
 extern "C" {
 #endif
 
-/* Public functions */
+/** 
+ *  @name Public functions
+ */
+/*@{*/
 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 Private functions
+ *  @internal Private error message function - used internally
+ */
+/*@{*/
 #define SDL_OutOfMemory()	SDL_Error(SDL_ENOMEM)
 #define SDL_Unsupported()	SDL_Error(SDL_UNSUPPORTED)
 typedef enum {
@@ -50,7 +61,7 @@ typedef enum {
 	SDL_LASTERROR
 } SDL_errorcode;
 extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
-
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_getenv.h

@@ -20,5 +20,9 @@
     slouken@libsdl.org
 */
 
+/** @file SDL_getenv.h
+ *  @deprecated Use SDL_stdinc.h instead
+ */
+
 /* DEPRECATED */
 #include "SDL_stdinc.h"

include/SDL_joystick.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL joystick event handling */
+/** @file SDL_joystick.h
+ *  Include file for SDL joystick event handling
+ */
 
 #ifndef _SDL_joystick_h
 #define _SDL_joystick_h
@@ -34,97 +36,108 @@
 extern "C" {
 #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
+ *  @note 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 */
+/** The joystick structure used to identify an SDL joystick */
 struct _SDL_Joystick;
 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
+/**
+ * Open a joystick for use.
+ *
+ * @param[in] device_index
+ * 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.
+ * @return This function returns 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
  */
 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.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *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
  */
 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.
+ *
+ * @param[in] state 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.
+ *
+ * @param[in] axis The axis indices start at index 0.
+ *
+ * @return The state is a value ranging from -32768 to 32767.
  */
 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
+ *  The return value of SDL_JoystickGetHat() is one of the following positions:
  */
+/*@{*/
 #define SDL_HAT_CENTERED	0x00
 #define SDL_HAT_UP		0x01
 #define SDL_HAT_RIGHT		0x02
@@ -134,25 +147,32 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int a
 #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
+ *
+ *  @param[in] hat The hat indices start at index 0.
  */
 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.
+ *
+ * @param[in] ball The ball indices start at index 0.
+ *
+ * @return This returns 0, or -1 if you passed it invalid parameters.
  */
 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.
+ *
+ * @param[in] button 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()
  */
 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);

include/SDL_keyboard.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL keyboard event handling */
+/** @file SDL_keyboard.h
+ *  Include file for SDL keyboard event handling
+ */
 
 #ifndef _SDL_keyboard_h
 #define _SDL_keyboard_h
@@ -35,78 +37,90 @@
 extern "C" {
 #endif
 
-/* Keysym structure
-   - The scancode is hardware dependent, and should not be used by general
-     applications.  If no hardware scancode is available, it will be 0.
-
-   - The 'unicode' translated character is only available when character
-     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
-     this is a UNICODE character corresponding to the keypress.  If the
-     high 9 bits of the character are 0, then this maps to the equivalent
-     ASCII character:
-	char ch;
-	if ( (keysym.unicode & 0xFF80) == 0 ) {
-		ch = keysym.unicode & 0x7F;
-	} else {
-		An international character..
-	}
+/** Keysym structure
+ *
+ *  - The scancode is hardware dependent, and should not be used by general
+ *    applications.  If no hardware scancode is available, it will be 0.
+ *
+ *  - The 'unicode' translated character is only available when character
+ *    translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
+ *    this is a UNICODE character corresponding to the keypress.  If the
+ *    high 9 bits of the character are 0, then this maps to the equivalent
+ *    ASCII character:
+ *      @code
+ *	char ch;
+ *	if ( (keysym.unicode & 0xFF80) == 0 ) {
+ *		ch = keysym.unicode & 0x7F;
+ *	} else {
+ *		An international character..
+ *	}
+ *      @endcode
  */
 typedef struct SDL_keysym {
-	Uint8 scancode;			/* hardware specific scancode */
-	SDLKey sym;			/* SDL virtual keysym */
-	SDLMod mod;			/* current key modifiers */
-	Uint16 unicode;			/* translated character */
+	Uint8 scancode;			/**< hardware specific scancode */
+	SDLKey sym;			/**< SDL virtual keysym */
+	SDLMod mod;			/**< current key modifiers */
+	Uint16 unicode;			/**< translated character */
 } SDL_keysym;
 
-/* This is the mask which refers to all hotkey bindings */
+/** This is the mask which refers to all hotkey bindings */
 #define SDL_ALL_HOTKEYS		0xFFFFFFFF
 
 /* Function prototypes */
-/*
+/**
  * Enable/Disable UNICODE translation of keyboard input.
+ *
  * This translation has some overhead, so translation defaults off.
+ *
+ * @param[in] enable
  * If 'enable' is 1, translation is enabled.
  * If 'enable' is 0, translation is disabled.
  * If 'enable' is -1, the translation state is not changed.
- * It returns the previous state of keyboard translation.
+ *
+ * @return It returns the previous state of keyboard translation.
  */
 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
 
-/*
+#define SDL_DEFAULT_REPEAT_DELAY	500
+#define SDL_DEFAULT_REPEAT_INTERVAL	30
+/**
  * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
+ *
+ *  @param[in] delay
  *  'delay' is the initial delay in ms between the time when a key is
  *  pressed, and keyboard repeat begins.
+ *
+ *  @param[in] interval
  *  'interval' is the time in ms between keyboard repeat events.
- */
-#define SDL_DEFAULT_REPEAT_DELAY	500
-#define SDL_DEFAULT_REPEAT_INTERVAL	30
-/*
+ *
  *  If 'delay' is set to 0, keyboard repeat is disabled.
  */
 extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
 
-/*
+/**
  * Get a snapshot of the current state of the keyboard.
  * Returns an array of keystates, indexed by the SDLK_* syms.
- * Used:
+ * Usage:
+ *	@code
  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
- *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
+ *	if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
+ *	@endcode
  */
 extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
 
-/*
+/**
  * Get the current key modifier state
  */
 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 
-/*
- * Set the current key modifier state
+/**
+ * Set the current key modifier state.
  * This does not change the keyboard state, only the key modifier flags.
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 
-/*
+/**
  * Get the name of an SDL virtual keysym
  */
 extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);

include/SDL_keysym.h

@@ -23,14 +23,16 @@
 #ifndef _SDL_keysym_h
 #define _SDL_keysym_h
 
-/* What we really want is a mapping of every raw key on the keyboard.
-   To support international keyboards, we use the range 0xA1 - 0xFF
-   as international virtual keycodes.  We'll follow in the footsteps of X11...
-   The names of the keys
+/** What we really want is a mapping of every raw key on the keyboard.
+ *  To support international keyboards, we use the range 0xA1 - 0xFF
+ *  as international virtual keycodes.  We'll follow in the footsteps of X11...
+ *  @brief The names of the keys
  */
- 
 typedef enum {
-	/* The keyboard syms have been cleverly chosen to map to ASCII */
+        /** @name ASCII mapped keysyms
+         *  The keyboard syms have been cleverly chosen to map to ASCII
+         */
+        /*@{*/
 	SDLK_UNKNOWN		= 0,
 	SDLK_FIRST		= 0,
 	SDLK_BACKSPACE		= 8,
@@ -108,8 +110,10 @@ typedef enum {
 	SDLK_z			= 122,
 	SDLK_DELETE		= 127,
 	/* End of ASCII mapped keysyms */
+        /*@}*/
 
-	/* International keyboard syms */
+	/** @name International keyboard syms */
+        /*@{*/
 	SDLK_WORLD_0		= 160,		/* 0xA0 */
 	SDLK_WORLD_1		= 161,
 	SDLK_WORLD_2		= 162,
@@ -206,8 +210,10 @@ typedef enum {
 	SDLK_WORLD_93		= 253,
 	SDLK_WORLD_94		= 254,
 	SDLK_WORLD_95		= 255,		/* 0xFF */
+        /*@}*/
 
-	/* Numeric keypad */
+	/** @name Numeric keypad */
+        /*@{*/
 	SDLK_KP0		= 256,
 	SDLK_KP1		= 257,
 	SDLK_KP2		= 258,
@@ -225,8 +231,10 @@ typedef enum {
 	SDLK_KP_PLUS		= 270,
 	SDLK_KP_ENTER		= 271,
 	SDLK_KP_EQUALS		= 272,
+        /*@}*/
 
-	/* Arrows + Home/End pad */
+	/** @name Arrows + Home/End pad */
+        /*@{*/
 	SDLK_UP			= 273,
 	SDLK_DOWN		= 274,
 	SDLK_RIGHT		= 275,
@@ -236,8 +244,10 @@ typedef enum {
 	SDLK_END		= 279,
 	SDLK_PAGEUP		= 280,
 	SDLK_PAGEDOWN		= 281,
+        /*@}*/
 
-	/* Function keys */
+	/** @name Function keys */
+        /*@{*/
 	SDLK_F1			= 282,
 	SDLK_F2			= 283,
 	SDLK_F3			= 284,
@@ -253,8 +263,10 @@ typedef enum {
 	SDLK_F13		= 294,
 	SDLK_F14		= 295,
 	SDLK_F15		= 296,
+        /*@}*/
 
-	/* Key state modifier keys */
+	/** @name Key state modifier keys */
+        /*@{*/
 	SDLK_NUMLOCK		= 300,
 	SDLK_CAPSLOCK		= 301,
 	SDLK_SCROLLOCK		= 302,
@@ -266,27 +278,30 @@ typedef enum {
 	SDLK_LALT		= 308,
 	SDLK_RMETA		= 309,
 	SDLK_LMETA		= 310,
-	SDLK_LSUPER		= 311,		/* Left "Windows" key */
-	SDLK_RSUPER		= 312,		/* Right "Windows" key */
-	SDLK_MODE		= 313,		/* "Alt Gr" key */
-	SDLK_COMPOSE		= 314,		/* Multi-key compose key */
+	SDLK_LSUPER		= 311,		/**< Left "Windows" key */
+	SDLK_RSUPER		= 312,		/**< Right "Windows" key */
+	SDLK_MODE		= 313,		/**< "Alt Gr" key */
+	SDLK_COMPOSE		= 314,		/**< Multi-key compose key */
+        /*@}*/
 
-	/* Miscellaneous function keys */
+	/** @name Miscellaneous function keys */
+        /*@{*/
 	SDLK_HELP		= 315,
 	SDLK_PRINT		= 316,
 	SDLK_SYSREQ		= 317,
 	SDLK_BREAK		= 318,
 	SDLK_MENU		= 319,
-	SDLK_POWER		= 320,		/* Power Macintosh power key */
-	SDLK_EURO		= 321,		/* Some european keyboards */
-	SDLK_UNDO		= 322,		/* Atari keyboard has Undo */
+	SDLK_POWER		= 320,		/**< Power Macintosh power key */
+	SDLK_EURO		= 321,		/**< Some european keyboards */
+	SDLK_UNDO		= 322,		/**< Atari keyboard has Undo */
+        /*@}*/
 
 	/* Add any other keys here */
 
 	SDLK_LAST
 } SDLKey;
 
-/* Enumeration of valid key mods (possibly OR'd together) */
+/** Enumeration of valid key mods (possibly OR'd together) */
 typedef enum {
 	KMOD_NONE  = 0x0000,
 	KMOD_LSHIFT= 0x0001,

include/SDL_loadso.h

@@ -20,22 +20,24 @@
     slouken@libsdl.org
 */
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* System dependent library loading routines                           */
+/** @file SDL_loadso.h
+ *  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. :)
-*/
+/** @file SDL_loadso.h
+ *  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. :)
+ */
 
 
 #ifndef _SDL_loadso_h
@@ -50,19 +52,21 @@
 extern "C" {
 #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,9 @@
 
 #include "SDL_stdinc.h"
 
-/* Redefine main() on Win32 and MacOS so that it is called by winmain.c */
+/** @file SDL_main.h
+ *  Redefine main() on Win32 and MacOS so that it is called by winmain.c
+ */
 
 #if defined(__WIN32__) || \
     (defined(__MWERKS__) && !defined(__BEOS__)) || \
@@ -38,22 +40,25 @@
 #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[])
-	{
-	}
+/** 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[]);
 
 
-/* From the SDL library code -- needed for registering the app on Win32 */
+/** @name From the SDL library code -- needed for registering the app on Win32 */
+/*@{*/
 #ifdef __WIN32__
 
 #include "begin_code.h"
@@ -61,19 +66,21 @@ extern C_LINKAGE int SDL_main(int argc, char *argv[]);
 extern "C" {
 #endif
 
-/* This should be called from your WinMain() function, if any */
+/** This should be called from your WinMain() function, if any */
 extern DECLSPEC void SDLCALL SDL_SetModuleHandle(void *hInst);
-/* This can also be called, but is no longer necessary */
+/** This can also be called, but is no longer necessary */
 extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
-/* This can also be called, but is no longer necessary (SDL_Quit calls it) */
+/** This can also be called, but is no longer necessary (SDL_Quit calls it) */
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 #ifdef __cplusplus
 }
 #endif
 #include "close_code.h"
 #endif
+/*@}*/
 
-/* From the SDL library code -- needed for registering QuickDraw on MacOS */
+/** @name From the SDL library code -- needed for registering QuickDraw on MacOS */
+/*@{*/
 #if defined(__MACOS__)
 
 #include "begin_code.h"
@@ -81,10 +88,10 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 extern "C" {
 #endif
 
-/* Forward declaration so we don't need to include QuickDraw.h */
+/** Forward declaration so we don't need to include QuickDraw.h */
 struct QDGlobals;
 
-/* This should be called from your main() function, if any */
+/** This should be called from your main() function, if any */
 extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
 
 #ifdef __cplusplus
@@ -92,6 +99,7 @@ extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
 #endif
 #include "close_code.h"
 #endif
+/*@}*/
 
 #endif /* Need to redefine main()? */
 

include/SDL_mouse.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL mouse event handling */
+/** @file SDL_mouse.h
+ *  Include file for SDL mouse event handling
+ */
 
 #ifndef _SDL_mouse_h
 #define _SDL_mouse_h
@@ -35,18 +37,18 @@
 extern "C" {
 #endif
 
-typedef struct WMcursor WMcursor;	/* Implementation dependent */
+typedef struct WMcursor WMcursor;	/**< Implementation dependent */
 typedef struct SDL_Cursor {
-	SDL_Rect area;			/* The area of the mouse cursor */
-	Sint16 hot_x, hot_y;		/* The "tip" of the cursor */
-	Uint8 *data;			/* B/W cursor data */
-	Uint8 *mask;			/* B/W cursor mask */
-	Uint8 *save[2];			/* Place to save cursor area */
-	WMcursor *wm_cursor;		/* Window-manager cursor */
+	SDL_Rect area;			/**< The area of the mouse cursor */
+	Sint16 hot_x, hot_y;		/**< The "tip" of the cursor */
+	Uint8 *data;			/**< B/W cursor data */
+	Uint8 *mask;			/**< B/W cursor mask */
+	Uint8 *save[2];			/**< Place to save cursor area */
+	WMcursor *wm_cursor;		/**< Window-manager cursor */
 } SDL_Cursor;
 
 /* Function prototypes */
-/*
+/**
  * Retrieve the current state of the 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
@@ -54,7 +56,7 @@ typedef struct SDL_Cursor {
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
 
-/*
+/**
  * Retrieve the current state of the 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
@@ -62,12 +64,12 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
 
-/*
+/**
  * Set the position of the mouse cursor (generates a mouse motion event)
  */
 extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
 
-/*
+/**
  * Create a cursor using the specified data and mask (in MSB format).
  * The cursor width must be a multiple of 8 bits.
  *
@@ -83,24 +85,24 @@ extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
 extern DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor
 		(Uint8 *data, Uint8 *mask, int w, int h, int hot_x, int hot_y);
 
-/*
+/**
  * Set the currently active cursor to the specified one.
  * If the cursor is currently visible, the change will be immediately 
  * represented on the display.
  */
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
 
-/*
+/**
  * Returns the currently active cursor.
  */
 extern DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
 
-/*
+/**
  * Deallocates a cursor created with SDL_CreateCursor().
  */
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
 
-/*
+/**
  * Toggle whether or not the cursor is shown on the screen.
  * The cursor start off displayed, but can be turned off.
  * SDL_ShowCursor() returns 1 if the cursor was being displayed
@@ -109,12 +111,13 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
  */
 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
-   Button 4:	Mouse wheel up	 (may also be a real button)
-   Button 5:	Mouse wheel down (may also be a real button)
+/*@{*/
+/** Used as a mask when testing buttons in buttonstate
+ *  Button 1:	Left mouse button
+ *  Button 2:	Middle mouse button
+ *  Button 3:	Right mouse button
+ *  Button 4:	Mouse wheel up	 (may also be a real button)
+ *  Button 5:	Mouse wheel down (may also be a real button)
  */
 #define SDL_BUTTON(X)		(1 << ((X)-1))
 #define SDL_BUTTON_LEFT		1
@@ -129,7 +132,7 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 #define SDL_BUTTON_RMASK	SDL_BUTTON(SDL_BUTTON_RIGHT)
 #define SDL_BUTTON_X1MASK	SDL_BUTTON(SDL_BUTTON_X1)
 #define SDL_BUTTON_X2MASK	SDL_BUTTON(SDL_BUTTON_X2)
-
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_mutex.h

@@ -23,10 +23,11 @@
 #ifndef _SDL_mutex_h
 #define _SDL_mutex_h
 
-/* Functions to provide thread synchronization primitives
-
-	These are independent of the other SDL routines.
-*/
+/** @file SDL_mutex.h
+ *  Functions to provide thread synchronization primitives
+ *
+ *  @note These are independent of the other SDL routines.
+ */
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -37,122 +38,135 @@
 extern "C" {
 #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 */
+/** 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) */
 #define SDL_LockMutex(m)	SDL_mutexP(m)
+/** Lock the mutex
+ *  @return 0, or -1 on error
+ */
 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.
- */
 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
+/** Unlock the mutex
+ *  @return 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.
+ */
 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
 
-/* Destroy a mutex */
+/** Destroy a mutex */
 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Semaphore functions                                           */
+/** @name Semaphore functions                                    */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* The SDL semaphore structure, defined in SDL_sem.c */
+/** 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 
+/**
+ * This function suspends the calling thread until the semaphore pointed 
  * to by 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, 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.
+ */
 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);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Condition variable functions                                  */
+/** @name Condition_variable_functions                           */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* The SDL condition variable structure, defined in SDL_cond.c */
+/*@{*/
+/** 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.
+ *  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 '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.
+ */
 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
 
+/*@}*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }
@@ -160,3 +174,4 @@ extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex
 #include "close_code.h"
 
 #endif /* _SDL_mutex_h */
+

include/SDL_opengl.h

@@ -20,7 +20,9 @@
     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
+ */
 
 #include "SDL_config.h"
 
@@ -48,10 +50,12 @@
 #undef __glext_h_
 #endif
 
-/* This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
-   It is included here because glext.h is not available on some systems.
-   If you don't want this version included, simply define "NO_SDL_GLEXT"
+/** @name GLext.h
+ *  This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
+ *  It is included here because glext.h is not available on some systems.
+ *  If you don't want this version included, simply define "NO_SDL_GLEXT"
  */
+/*@{*/
 #ifndef NO_SDL_GLEXT
 #if !defined(__glext_h_) && !defined(GL_GLEXT_LEGACY)
 #define __glext_h_
@@ -6549,3 +6553,4 @@ typedef void (APIENTRYP PFNGLSTRINGMARKERGREMEDYPROC) (GLsizei len, const GLvoid
 
 #endif
 #endif /* NO_SDL_GLEXT */
+/*@}*/
\ No newline at end of file

include/SDL_platform.h

@@ -20,7 +20,9 @@
     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

include/SDL_quit.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL quit event handling */
+/** @file SDL_quit.h
+ *  Include file for SDL quit event handling
+ */
 
 #ifndef _SDL_quit_h
 #define _SDL_quit_h
@@ -28,22 +30,25 @@
 #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_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
+ *  There are no functions directly affecting the quit event 
+ */
 
-/* There are no functions directly affecting the quit event */
 #define SDL_QuitRequested() \
         (SDL_PumpEvents(), SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUITMASK))
 

include/SDL_rwops.h

@@ -20,9 +20,10 @@
     slouken@libsdl.org
 */
 
-/* This file provides a general interface for SDL to read and write
-   data sources.  It can easily be extended to files, memory, etc.
-*/
+/** @file SDL_rwops.h
+ *  This file provides a general interface for SDL to read and write
+ *  data sources.  It can easily be extended to files, memory, etc.
+ */
 
 #ifndef _SDL_rwops_h
 #define _SDL_rwops_h
@@ -36,28 +37,28 @@
 extern "C" {
 #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:
-		SEEK_SET, SEEK_CUR, SEEK_END
-	   Returns the final offset in the data source.
+	/** Seek to 'offset' relative to whence, one of stdio's whence values:
+	 *	SEEK_SET, SEEK_CUR, SEEK_END
+	 *  Returns the final offset in the data source.
 	 */
 	int (SDLCALL *seek)(struct SDL_RWops *context, int offset, int whence);
 
-	/* Read up to 'maxnum' objects each of size 'size' from the data
-	   source to the area pointed at by 'ptr'.
-	   Returns the number of objects read, or -1 if the read failed.
+	/** Read up to 'maxnum' objects each of size 'size' from the data
+	 *  source to the area pointed at by 'ptr'.
+	 *  Returns the number of objects read, or -1 if the read failed.
 	 */
 	int (SDLCALL *read)(struct SDL_RWops *context, void *ptr, int size, int maxnum);
 
-	/* Write exactly 'num' objects each of size 'objsize' from the area
-	   pointed at by 'ptr' to data source.
-	   Returns 'num', or -1 if the write failed.
+	/** Write exactly 'num' objects each of size 'objsize' from the area
+	 *  pointed at by 'ptr' to data source.
+	 *  Returns 'num', or -1 if the write failed.
 	 */
 	int (SDLCALL *write)(struct SDL_RWops *context, const void *ptr, int size, int num);
 
-	/* Close and free an allocated SDL_FSops structure */
+	/** Close and free an allocated SDL_FSops structure */
 	int (SDLCALL *close)(struct SDL_RWops *context);
 
 	Uint32 type;
@@ -92,7 +93,8 @@ typedef struct SDL_RWops {
 } SDL_RWops;
 
 
-/* Functions to create SDL_RWops structures from various data sources */
+/** @name Functions to create SDL_RWops structures from various data sources */
+/*@{*/
 
 extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromFile(const char *file, const char *mode);
 
@@ -106,34 +108,43 @@ extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromConstMem(const void *mem, int size
 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 */
+/*@}*/
+
+/** @name Seek Reference Points */
+/*@{*/
+#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 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 an item of the specified endianness and return in native format */
+/** @name 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);
+/*@}*/
 
-/* Write an item of native format to the specified endianness */
+/** @name Write an item of native format to the specified endianness */
+/*@{*/
 extern DECLSPEC int SDLCALL SDL_WriteLE16(SDL_RWops *dst, Uint16 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE16(SDL_RWops *dst, Uint16 value);
 extern DECLSPEC int SDLCALL SDL_WriteLE32(SDL_RWops *dst, Uint32 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE32(SDL_RWops *dst, Uint32 value);
 extern DECLSPEC int SDLCALL SDL_WriteLE64(SDL_RWops *dst, Uint64 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE64(SDL_RWops *dst, Uint64 value);
-
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL_stdinc.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This is a general header that includes C language support */
+/** @file SDL_stdinc.h
+ *  This is a general header that includes C language support
+ */
 
 #ifndef _SDL_stdinc_h
 #define _SDL_stdinc_h
@@ -72,11 +74,12 @@
 # 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)
 
-/* Basic data types */
+/** @name Basic data types */
+/*@{*/
 typedef enum SDL_bool {
 	SDL_FALSE = 0,
 	SDL_TRUE  = 1
@@ -102,7 +105,10 @@ typedef struct {
 } Uint64, Sint64;
 #endif
 
-/* Make sure the types really have the right sizes */
+/*@}*/
+
+/** @name Make sure the types really have the right sizes */
+/*@{*/
 #define SDL_COMPILE_TIME_ASSERT(name, x)               \
        typedef int SDL_dummy_ ## name[(x) * 2 - 1]
 
@@ -114,12 +120,14 @@ SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4);
 SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4);
 SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8);
 SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
-
-/* 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
-   enums having the size of an int must be enabled.
-   This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
-*/
+/*@}*/
+
+/** @name Enum Size Check
+ *  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
+ *  enums having the size of an int must be enabled.
+ *  This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
+ */
 /* Enable enums always int in CodeWarrior (for MPW use "-enum int") */
 #ifdef __MWERKS__
 #pragma enumsalwaysint on
@@ -132,7 +140,7 @@ typedef enum {
 #ifndef __NDS__
 SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
 #endif
-
+/*@}*/
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -565,11 +573,15 @@ extern DECLSPEC int SDLCALL SDL_snprintf(char *text, size_t maxlen, const char *
 extern DECLSPEC int SDLCALL SDL_vsnprintf(char *text, size_t maxlen, const char *fmt, va_list ap);
 #endif
 
-/* The SDL implementation of iconv() returns these error codes */
+/** @name SDL_ICONV Error Codes
+ *  The SDL implementation of iconv() returns these error codes 
+ */
+/*@{*/
 #define SDL_ICONV_ERROR		(size_t)-1
 #define SDL_ICONV_E2BIG		(size_t)-2
 #define SDL_ICONV_EILSEQ	(size_t)-3
 #define SDL_ICONV_EINVAL	(size_t)-4
+/*@}*/
 
 #ifdef HAVE_ICONV
 #define SDL_iconv_t     iconv_t
@@ -581,9 +593,9 @@ extern DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, const cha
 extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
 #endif
 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, size_t inbytesleft);
 #define SDL_iconv_utf8_locale(S)	SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
 #define SDL_iconv_utf8_ucs2(S)		(Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1)

include/SDL_syswm.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL custom system window manager hooks */
+/** @file SDL_syswm.h
+ *  Include file for SDL custom system window manager hooks
+ */
 
 #ifndef _SDL_syswm_h
 #define _SDL_syswm_h
@@ -35,11 +37,12 @@
 extern "C" {
 #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;
 typedef struct SDL_SysWMinfo SDL_SysWMinfo;
@@ -60,12 +63,12 @@ typedef struct SDL_SysWMinfo 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;
 	SDL_SYSWM_TYPE subsystem;
@@ -74,32 +77,38 @@ 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.
  */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	SDL_SYSWM_TYPE subsystem;
 	union {
 	    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, 
-                   but not the gfxdisplay 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, 
+                 *  but not the gfxdisplay 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.2.12 */
-		Display *gfxdisplay;	/* The X11 display to which rendering is done */
+                /*@}*/
+
+		/** @name Introduced in SDL 1.0.2 */
+                /*@{*/
+	    	Window fswindow;	/**< The X11 fullscreen window */
+	    	Window wmwindow;	/**< The X11 managed input window */
+                /*@}*/
+
+		/** @name Introduced in SDL 1.2.12 */
+                /*@{*/
+		Display *gfxdisplay;	/**< The X11 display to which rendering is done */
+                /*@}*/
 	    } x11;
 	} info;
 } SDL_SysWMinfo;
@@ -107,13 +116,13 @@ typedef struct SDL_SysWMinfo {
 #elif defined(SDL_VIDEO_DRIVER_NANOX)
 #include <microwin/nano-X.h>
 
-/* The generic custom event structure */
+/** The generic custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	int data;
 };
 
-/* The windows custom window manager information structure */
+/** The windows custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version ;
 	GR_WINDOW_ID window ;	/* The display window */
@@ -123,50 +132,50 @@ typedef 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 */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
-	HWND window;			/* The Win32 display window */
-	HGLRC hglrc;			/* The OpenGL context, if any */
+	HWND window;			/**< The Win32 display window */
+	HGLRC hglrc;			/**< The OpenGL context, if any */
 } SDL_SysWMinfo;
 
 #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 */
 typedef 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 */
 } SDL_SysWMinfo;
 
 #elif defined(SDL_VIDEO_DRIVER_PHOTON)
 #include <sys/neutrino.h>
 #include <Ph.h>
 
-/* The QNX custom event structure */
+/** The QNX custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	int data;
 };
 
-/* The QNX custom window manager information structure */
+/** The QNX custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	int data;
@@ -174,13 +183,13 @@ typedef 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 */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	int data;
@@ -191,16 +200,18 @@ typedef struct SDL_SysWMinfo {
 #endif /* SDL_PROTOTYPES_ONLY */
 
 /* Function prototypes */
-/*
+/**
  * This function gives you custom hooks into the window manager information.
  * It fills the structure pointed to by 'info' with custom information and
  * returns 1 if the function is implemented.  If it's not implemented, or
  * the version member of the 'info' structure is invalid, it returns 0. 
  *
  * You typically use this function like this:
+ * @code
  * SDL_SysWMInfo info;
  * SDL_VERSION(&info.version);
  * if ( SDL_GetWMInfo(&info) ) { ... }
+ * @endcode
  */
 extern DECLSPEC int SDLCALL SDL_GetWMInfo(SDL_SysWMinfo *info);
 

include/SDL_thread.h

@@ -23,10 +23,11 @@
 #ifndef _SDL_thread_h
 #define _SDL_thread_h
 
-/* Header for the SDL thread management routines 
-
-	These are independent of the other SDL routines.
-*/
+/** @file SDL_thread.h
+ *  Header for the SDL thread management routines 
+ *
+ *  @note These are independent of the other SDL routines.
+ */
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -40,25 +41,25 @@
 extern "C" {
 #endif
 
-/* The SDL thread structure, defined in SDL_thread.c */
+/** The SDL thread structure, defined in SDL_thread.c */
 struct SDL_Thread;
 typedef struct SDL_Thread SDL_Thread;
 
-/* Create a thread */
+/** Create a thread */
 #if ((defined(__WIN32__) && !defined(HAVE_LIBC)) || defined(__OS2__)) &&  !defined(__SYMBIAN32__)
-/*
-   We compile SDL into a DLL on OS/2. 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!
-*/
+/**
+ *  We compile SDL into a DLL on OS/2. 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! */
@@ -92,21 +93,21 @@ extern DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(int (SDLCALL *fn)(void *),
 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 'status', if 'status' is not NULL.
  */
 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status);
 
-/* Forcefully kill a thread without worrying about its state */
+/** Forcefully kill a thread without worrying about its state */
 extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread *thread);
 
 

include/SDL_timer.h

@@ -23,7 +23,9 @@
 #ifndef _SDL_timer_h
 #define _SDL_timer_h
 
-/* Header for the SDL time management routines */
+/** @file SDL_timer.h
+ *  Header for the SDL time management routines
+ */
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -34,24 +36,26 @@
 extern "C" {
 #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
@@ -68,7 +72,7 @@ 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:
- *   SDL_SetTimer((33/10)*10, flag_update);
+ *   @code SDL_SetTimer((33/10)*10, flag_update); @endcode
  *
  * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
  *
@@ -81,11 +85,14 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
  */
 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback callback);
 
-/* New timer API, supports multiple timers
+/** @name New timer API
+ * 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
@@ -93,19 +100,22 @@ extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback call
  */
 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.
+ *  Returns 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.
+/**
+ * Remove one of the multiple timers knowing its ID.
  * Returns a boolean value indicating success.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
 
+/*@}*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

include/SDL_types.h

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

include/SDL_version.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This header defines the current SDL version */
+/** @file SDL_version.h
+ *  This header defines the current SDL version
+ */
 
 #ifndef _SDL_version_h
 #define _SDL_version_h
@@ -33,11 +35,14 @@
 extern "C" {
 #endif
 
-/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
-*/
+/** @name Version Number
+ *  Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
+ */
+/*@{*/
 #define SDL_MAJOR_VERSION	1
 #define SDL_MINOR_VERSION	2
 #define SDL_PATCHLEVEL		14
+/*@}*/
 
 typedef struct SDL_version {
 	Uint8 major;
@@ -45,7 +50,8 @@ typedef struct SDL_version {
 	Uint8 patch;
 } SDL_version;
 
-/* This macro can be used to fill a version structure with the compile-time
+/**
+ * This macro can be used to fill a version structure with the compile-time
  * version of the SDL library.
  */
 #define SDL_VERSION(X)							\
@@ -55,24 +61,24 @@ typedef struct SDL_version {
 	(X)->patch = SDL_PATCHLEVEL;					\
 }
 
-/* This macro turns the version numbers into a numeric value:
-   (1,2,3) -> (1203)
-   This assumes that there will never be more than 100 patchlevels
-*/
+/** This macro turns the version numbers into a numeric value:
+ *  (1,2,3) -> (1203)
+ *  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))
 
-/* This function gets the version of the dynamically linked SDL library.
-   it should NOT be used to fill a version structure, instead you should
-   use the SDL_Version() macro.
+/** This function gets the version of the dynamically linked SDL library.
+ *  it should NOT be used to fill a version structure, instead you should
+ *  use the SDL_Version() macro.
  */
 extern DECLSPEC const SDL_version * SDLCALL SDL_Linked_Version(void);
 

include/begin_code.h

@@ -20,18 +20,26 @@
     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. */
+/** 
+ *  @file begin_code.h
+ *  This shouldn't be nested -- included it around code only.
+ */
 #ifdef _begin_code_h
 #error Nested inclusion of begin_code.h
 #endif
 #define _begin_code_h
 
-/* Some compilers use a special export keyword */
+/** 
+ *  @def DECLSPEC
+ *  Some compilers use a special export keyword
+ */
 #ifndef DECLSPEC
 # if defined(__BEOS__) || defined(__HAIKU__)
 #  if defined(__GNUC__)
@@ -77,7 +85,10 @@
 # endif
 #endif
 
-/* By default SDL uses the C calling convention */
+/** 
+ *  @def SDLCALL
+ *  By default SDL uses the C calling convention
+ */
 #ifndef SDLCALL
 # if defined(__WIN32__) && !defined(__GNUC__)
 #  define SDLCALL __cdecl
@@ -107,10 +118,12 @@
 #endif /* !EKA2 */
 #endif /* __SYMBIAN32__ */
 
-/* Force structure packing at 4 byte alignment.
-   This is necessary if the header is included in code which has structure
-   packing set to an alternate value, say for loading structures from disk.
-   The packing is reset to the previous value in close_code.h
+/**
+ *  @file begin_code.h
+ *  Force structure packing at 4 byte alignment.
+ *  This is necessary if the header is included in code which has structure
+ *  packing set to an alternate value, say for loading structures from disk.
+ *  The packing is reset to the previous value in close_code.h 
  */
 #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__)
 #ifdef _MSC_VER
@@ -125,7 +138,10 @@
 #pragma enumsalwaysint on
 #endif /* Compiler needs structure packing set */
 
-/* Set up compiler-specific options for inlining functions */
+/**
+ *  @def SDL_INLINE_OKAY
+ *  Set up compiler-specific options for inlining functions
+ */
 #ifndef SDL_INLINE_OKAY
 #ifdef __GNUC__
 #define SDL_INLINE_OKAY
@@ -150,15 +166,20 @@
 #endif /* GNU C */
 #endif /* SDL_INLINE_OKAY */
 
-/* If inlining isn't supported, remove "__inline__", turning static
-   inlined functions into static functions (resulting in code bloat
-   in all files which include the offending header files)
-*/
+/**
+ *  @def __inline__
+ *  If inlining isn't supported, remove "__inline__", turning static
+ *  inlined functions into static functions (resulting in code bloat
+ *  in all files which include the offending header files)
+ */
 #ifndef SDL_INLINE_OKAY
 #define __inline__
 #endif
 
-/* Apparently this is needed by several Windows compilers */
+/**
+ *  @def NULL
+ *  Apparently this is needed by several Windows compilers
+ */
 #if !defined(__MACH__)
 #ifndef NULL
 #ifdef __cplusplus

include/close_code.h

@@ -20,13 +20,18 @@
     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
 
-/* Reset structure packing at previous byte alignment */
+/**
+ *  @file close_code.h
+ *  Reset structure packing at previous byte alignment
+ */
 #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__WATCOMC__)  || defined(__BORLANDC__)
 #ifdef __BORLANDC__
 #pragma nopackwarning