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,41 +49,46 @@
 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 
- * 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 '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
- * 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_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_audio.h

@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Access to the raw audio mixing buffer for the SDL library */
+/**
+ *  @file SDL_audio.h
+ *  Access to the raw audio mixing buffer for the SDL library
+ */
 
 #ifndef _SDL_audio_h
 #define _SDL_audio_h
@@ -38,36 +41,75 @@
 extern "C" {
 #endif
 
-/* The calculated values in this structure are calculated by SDL_OpenAudio() */
+/**
+ * When filling in the desired audio spec structure,
+ * - 'desired->freq' should be the desired audio frequency in samples-per-second.
+ * - 'desired->format' should be the desired audio format.
+ * - 'desired->samples' is the desired size of the audio buffer, in samples.
+ *     This number should be a power of two, and may be adjusted by the audio
+ *     driver to a value more suitable for the hardware.  Good values seem to
+ *     range between 512 and 8096 inclusive, depending on the application and
+ *     CPU speed.  Smaller values yield faster response time, but can lead
+ *     to underflow if the application is doing heavy processing and cannot
+ *     fill the audio buffer in time.  A stereo sample consists of both right
+ *     and left channels in LR ordering.
+ *     Note that the number of samples is directly related to time by the
+ *     following formula:  ms = (samples*1000)/freq
+ * - 'desired->size' is the size in bytes of the audio buffer, and is
+ *     calculated by SDL_OpenAudio().
+ * - 'desired->silence' is the value used to set the buffer to silence,
+ *     and is calculated by SDL_OpenAudio().
+ * - 'desired->callback' should be set to a function that will be called
+ *     when the audio device is ready for more data.  It is passed a pointer
+ *     to the audio buffer, and the length in bytes of the audio buffer.
+ *     This function usually runs in a separate thread, and so you should
+ *     protect data structures that it accesses by calling SDL_LockAudio()
+ *     and SDL_UnlockAudio() in your code.
+ * - 'desired->userdata' is passed as the first parameter to your callback
+ *     function.
+ *
+ * @note The calculated values in this structure are calculated by SDL_OpenAudio()
+ *
+ */
 typedef struct SDL_AudioSpec {
-	int freq;		/* DSP frequency -- samples per second */
-	Uint16 format;		/* Audio data format */
-	Uint8  channels;	/* Number of channels: 1 mono, 2 stereo */
-	Uint8  silence;		/* Audio buffer silence value (calculated) */
-	Uint16 samples;		/* Audio buffer size in samples (power of 2) */
-	Uint16 padding;		/* Necessary for some compile environments */
-	Uint32 size;		/* Audio buffer size in bytes (calculated) */
-	/* This function is called when the audio device needs more data.
-	   'stream' is a pointer to the audio data buffer
-	   'len' is the length of that buffer in bytes.
-	   Once the callback returns, the buffer will no longer be valid.
-	   Stereo samples are stored in a LRLRLR ordering.
-	*/
+	int freq;		/**< DSP frequency -- samples per second */
+	Uint16 format;		/**< Audio data format */
+	Uint8  channels;	/**< Number of channels: 1 mono, 2 stereo */
+	Uint8  silence;		/**< Audio buffer silence value (calculated) */
+	Uint16 samples;		/**< Audio buffer size in samples (power of 2) */
+	Uint16 padding;		/**< Necessary for some compile environments */
+	Uint32 size;		/**< Audio buffer size in bytes (calculated) */
+	/**
+	 *  This function is called when the audio device needs more data.
+	 *
+	 *  @param[out] stream	A pointer to the audio data buffer
+	 *  @param[in]  len	The length of the audio buffer in bytes.
+	 *
+	 *  Once the callback returns, the buffer will no longer be valid.
+	 *  Stereo samples are stored in a LRLRLR ordering.
+	 */
 	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
 	void  *userdata;
 } SDL_AudioSpec;
 
-/* Audio format flags (defaults to LSB byte order) */
-#define AUDIO_U8	0x0008	/* Unsigned 8-bit samples */
-#define AUDIO_S8	0x8008	/* Signed 8-bit samples */
-#define AUDIO_U16LSB	0x0010	/* Unsigned 16-bit samples */
-#define AUDIO_S16LSB	0x8010	/* Signed 16-bit samples */
-#define AUDIO_U16MSB	0x1010	/* As above, but big-endian byte order */
-#define AUDIO_S16MSB	0x9010	/* As above, but big-endian byte order */
+/**
+ *  @name Audio format flags
+ *  defaults to LSB byte order
+ */
+/*@{*/
+#define AUDIO_U8	0x0008	/**< Unsigned 8-bit samples */
+#define AUDIO_S8	0x8008	/**< Signed 8-bit samples */
+#define AUDIO_U16LSB	0x0010	/**< Unsigned 16-bit samples */
+#define AUDIO_S16LSB	0x8010	/**< Signed 16-bit samples */
+#define AUDIO_U16MSB	0x1010	/**< As above, but big-endian byte order */
+#define AUDIO_S16MSB	0x9010	/**< As above, but big-endian byte order */
 #define AUDIO_U16	AUDIO_U16LSB
 #define AUDIO_S16	AUDIO_S16LSB
 
-/* Native audio byte ordering */
+/**
+ *  @name Native audio byte ordering
+ */
+/*@{*/
 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
 #define AUDIO_U16SYS	AUDIO_U16LSB
 #define AUDIO_S16SYS	AUDIO_S16LSB
@@ -75,40 +117,48 @@ typedef struct SDL_AudioSpec {
 #define AUDIO_U16SYS	AUDIO_U16MSB
 #define AUDIO_S16SYS	AUDIO_S16MSB
 #endif
+/*@}*/
+
+/*@}*/
 
 
-/* A structure to hold a set of audio conversion filters and buffers */
+/** A structure to hold a set of audio conversion filters and buffers */
 typedef struct SDL_AudioCVT {
-	int needed;			/* Set to 1 if conversion possible */
-	Uint16 src_format;		/* Source audio format */
-	Uint16 dst_format;		/* Target audio format */
-	double rate_incr;		/* Rate conversion increment */
-	Uint8 *buf;			/* Buffer to hold entire audio data */
-	int    len;			/* Length of original audio buffer */
-	int    len_cvt;			/* Length of converted audio buffer */
-	int    len_mult;		/* buffer must be len*len_mult big */
-	double len_ratio; 	/* Given len, final size is len*len_ratio */
+	int needed;			/**< Set to 1 if conversion possible */
+	Uint16 src_format;		/**< Source audio format */
+	Uint16 dst_format;		/**< Target audio format */
+	double rate_incr;		/**< Rate conversion increment */
+	Uint8 *buf;			/**< Buffer to hold entire audio data */
+	int    len;			/**< Length of original audio buffer */
+	int    len_cvt;			/**< Length of converted audio buffer */
+	int    len_mult;		/**< buffer must be len*len_mult big */
+	double len_ratio; 	/**< Given len, final size is len*len_ratio */
 	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
-	int filter_index;		/* Current audio conversion function */
+	int filter_index;		/**< Current audio conversion function */
 } SDL_AudioCVT;
 
 
 /* Function prototypes */
 
-/* These functions are used internally, and should not be used unless you
+/**
+ * @name Audio Init and Quit
+ * These functions are used internally, and should not be used unless you
  * have a specific need to specify the audio driver you want to use.
  * You should normally use SDL_Init() or SDL_InitSubSystem().
  */
+/*@{*/
 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
+/*@}*/
 
-/* This function fills the given character buffer with the name of the
+/**
+ * This function fills the given character buffer with the name of the
  * current audio driver, and returns a pointer to it if the audio driver has
  * been initialized.  It returns NULL if no driver has been initialized.
  */
 extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
 
-/*
+/**
  * This function opens the audio device with the desired parameters, and
  * returns 0 if successful, placing the actual hardware parameters in the
  * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
@@ -117,51 +167,26 @@ extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
  * audio format if necessary.  This function returns -1 if it failed 
  * to open the audio device, or couldn't set up the audio thread.
  *
- * When filling in the desired audio spec structure,
- *  'desired->freq' should be the desired audio frequency in samples-per-second.
- *  'desired->format' should be the desired audio format.
- *  'desired->samples' is the desired size of the audio buffer, in samples.
- *     This number should be a power of two, and may be adjusted by the audio
- *     driver to a value more suitable for the hardware.  Good values seem to
- *     range between 512 and 8096 inclusive, depending on the application and
- *     CPU speed.  Smaller values yield faster response time, but can lead
- *     to underflow if the application is doing heavy processing and cannot
- *     fill the audio buffer in time.  A stereo sample consists of both right
- *     and left channels in LR ordering.
- *     Note that the number of samples is directly related to time by the
- *     following formula:  ms = (samples*1000)/freq
- *  'desired->size' is the size in bytes of the audio buffer, and is
- *     calculated by SDL_OpenAudio().
- *  'desired->silence' is the value used to set the buffer to silence,
- *     and is calculated by SDL_OpenAudio().
- *  'desired->callback' should be set to a function that will be called
- *     when the audio device is ready for more data.  It is passed a pointer
- *     to the audio buffer, and the length in bytes of the audio buffer.
- *     This function usually runs in a separate thread, and so you should
- *     protect data structures that it accesses by calling SDL_LockAudio()
- *     and SDL_UnlockAudio() in your code.
- *  'desired->userdata' is passed as the first parameter to your callback
- *     function.
- *
  * The audio device starts out playing silence when it's opened, and should
  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
  * for your audio callback function to be called.  Since the audio driver
  * may modify the requested size of the audio buffer, you should allocate
  * any local mixing buffers after you open the audio device.
+ *
+ * @sa SDL_AudioSpec
  */
 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
 
-/*
- * Get the current audio state:
- */
 typedef enum {
 	SDL_AUDIO_STOPPED = 0,
 	SDL_AUDIO_PLAYING,
 	SDL_AUDIO_PAUSED
 } SDL_audiostatus;
+
+/** Get the current audio state */
 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
 
-/*
+/**
  * This function pauses and unpauses the audio callback processing.
  * It should be called with a parameter of 0 after opening the audio
  * device to start playing sound.  This is so you can safely initialize
@@ -170,11 +195,11 @@ extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
  */
 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
 
-/*
+/**
  * This function loads a WAVE from the data source, automatically freeing
  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
  * you could do:
- *	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
+ *	@code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode
  *
  * If this function succeeds, it returns the given SDL_AudioSpec,
  * filled with the audio data format of the wave data, and sets
@@ -189,27 +214,29 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
  */
 extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
 
-/* Compatibility convenience function -- loads a WAV from a file */
+/** Compatibility convenience function -- loads a WAV from a file */
 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
 	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
 
-/*
+/**
  * This function frees data previously allocated with SDL_LoadWAV_RW()
  */
 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf);
 
-/*
+/**
  * This function takes a source format and rate and a destination format
  * and rate, and initializes the 'cvt' structure with information needed
  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
  * to the other.
- * This function returns 0, or -1 if there was an error.
+ *
+ * @return This function returns 0, or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
 		Uint16 src_format, Uint8 src_channels, int src_rate,
 		Uint16 dst_format, Uint8 dst_channels, int dst_rate);
 
-/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
+/**
+ * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
  * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
  * audio data in the source format, this function will convert it in-place
  * to the desired format.
@@ -219,26 +246,30 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
  */
 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt);
 
-/*
+
+#define SDL_MIX_MAXVOLUME 128
+/**
  * This takes two audio buffers of the playing audio format and mixes
  * them, performing addition, volume adjustment, and overflow clipping.
  * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
  * for full audio volume.  Note this does not change hardware volume.
  * This is provided for convenience -- you can mix your own audio data.
  */
-#define SDL_MIX_MAXVOLUME 128
 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume);
 
-/*
+/**
+ * @name Audio Locks
  * The lock manipulated by these functions protects the callback function.
  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
  * callback function is not running.  Do not call these from the callback
  * function or you will cause deadlock.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
+/*@}*/
 
-/*
+/**
  * This function shuts down audio processing and closes the audio device.
  */
 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);

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_events.h

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

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);
 
-/*
- * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
- * 'delay' is the initial delay in ms between the time when a key is
- * pressed, and keyboard repeat begins.
- * '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.
+/**
+ * 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.
+ *
+ *  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/SDL_video.h

@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Header file for access to the SDL raw framebuffer window */
+/** @file SDL_video.h
+ *  Header file for access to the SDL raw framebuffer window
+ */
 
 #ifndef _SDL_video_h
 #define _SDL_video_h
@@ -35,11 +37,16 @@
 extern "C" {
 #endif
 
-/* Transparency definitions: These define alpha as the opacity of a surface */
+/** @name Transparency definitions
+ *  These define alpha as the opacity of a surface
+ */
+/*@{*/
 #define SDL_ALPHA_OPAQUE 255
 #define SDL_ALPHA_TRANSPARENT 0
+/*@}*/
 
-/* Useful data types */
+/** @name Useful data types */
+/*@{*/
 typedef struct SDL_Rect {
 	Sint16 x, y;
 	Uint16 w, h;
@@ -57,8 +64,9 @@ typedef struct SDL_Palette {
 	int       ncolors;
 	SDL_Color *colors;
 } SDL_Palette;
+/*@}*/
 
-/* Everything in the pixel format structure is read-only */
+/** Everything in the pixel format structure is read-only */
 typedef struct SDL_PixelFormat {
 	SDL_Palette *palette;
 	Uint8  BitsPerPixel;
@@ -76,128 +84,149 @@ typedef struct SDL_PixelFormat {
 	Uint32 Bmask;
 	Uint32 Amask;
 
-	/* RGB color key information */
+	/** RGB color key information */
 	Uint32 colorkey;
-	/* Alpha value information (per-surface alpha) */
+	/** Alpha value information (per-surface alpha) */
 	Uint8  alpha;
 } SDL_PixelFormat;
 
-/* This structure should be treated as read-only, except for 'pixels',
-   which, if not NULL, contains the raw pixel data for the surface.
-*/
+/** This structure should be treated as read-only, except for 'pixels',
+ *  which, if not NULL, contains the raw pixel data for the surface.
+ */
 typedef struct SDL_Surface {
-	Uint32 flags;				/* Read-only */
-	SDL_PixelFormat *format;		/* Read-only */
-	int w, h;				/* Read-only */
-	Uint16 pitch;				/* Read-only */
-	void *pixels;				/* Read-write */
-	int offset;				/* Private */
-
-	/* Hardware-specific surface info */
+	Uint32 flags;				/**< Read-only */
+	SDL_PixelFormat *format;		/**< Read-only */
+	int w, h;				/**< Read-only */
+	Uint16 pitch;				/**< Read-only */
+	void *pixels;				/**< Read-write */
+	int offset;				/**< Private */
+
+	/** Hardware-specific surface info */
 	struct private_hwdata *hwdata;
 
-	/* clipping information */
-	SDL_Rect clip_rect;			/* Read-only */
-	Uint32 unused1;				/* for binary compatibility */
+	/** clipping information */
+	SDL_Rect clip_rect;			/**< Read-only */
+	Uint32 unused1;				/**< for binary compatibility */
 
-	/* Allow recursive locks */
-	Uint32 locked;				/* Private */
+	/** Allow recursive locks */
+	Uint32 locked;				/**< Private */
 
-	/* info for fast blit mapping to other surfaces */
-	struct SDL_BlitMap *map;		/* Private */
+	/** info for fast blit mapping to other surfaces */
+	struct SDL_BlitMap *map;		/**< Private */
 
-	/* format version, bumped at every change to invalidate blit maps */
-	unsigned int format_version;		/* Private */
+	/** format version, bumped at every change to invalidate blit maps */
+	unsigned int format_version;		/**< Private */
 
-	/* Reference count -- used when freeing surface */
-	int refcount;				/* Read-mostly */
+	/** Reference count -- used when freeing surface */
+	int refcount;				/**< Read-mostly */
 } SDL_Surface;
 
-/* These are the currently supported flags for the SDL_surface */
-/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
-#define SDL_SWSURFACE	0x00000000	/* Surface is in system memory */
-#define SDL_HWSURFACE	0x00000001	/* Surface is in video memory */
-#define SDL_ASYNCBLIT	0x00000004	/* Use asynchronous blits if possible */
-/* Available for SDL_SetVideoMode() */
-#define SDL_ANYFORMAT	0x10000000	/* Allow any video depth/pixel-format */
-#define SDL_HWPALETTE	0x20000000	/* Surface has exclusive palette */
-#define SDL_DOUBLEBUF	0x40000000	/* Set up double-buffered video mode */
-#define SDL_FULLSCREEN	0x80000000	/* Surface is a full screen display */
-#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
-#define SDL_OPENGLBLIT	0x0000000A	/* Create an OpenGL rendering context and use it for blitting */
-#define SDL_RESIZABLE	0x00000010	/* This video mode may be resized */
-#define SDL_NOFRAME	0x00000020	/* No window caption or edge frame */
-/* Used internally (read-only) */
-#define SDL_HWACCEL	0x00000100	/* Blit uses hardware acceleration */
-#define SDL_SRCCOLORKEY	0x00001000	/* Blit uses a source color key */
-#define SDL_RLEACCELOK	0x00002000	/* Private flag */
-#define SDL_RLEACCEL	0x00004000	/* Surface is RLE encoded */
-#define SDL_SRCALPHA	0x00010000	/* Blit uses source alpha blending */
-#define SDL_PREALLOC	0x01000000	/* Surface uses preallocated memory */
-
-/* Evaluates to true if the surface needs to be locked before access */
+/** @name SDL_Surface Flags
+ *  These are the currently supported flags for the SDL_surface
+ */
+/*@{*/
+
+/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
+/*@{*/
+#define SDL_SWSURFACE	0x00000000	/**< Surface is in system memory */
+#define SDL_HWSURFACE	0x00000001	/**< Surface is in video memory */
+#define SDL_ASYNCBLIT	0x00000004	/**< Use asynchronous blits if possible */
+/*@}*/
+
+/** Available for SDL_SetVideoMode() */
+/*@{*/
+#define SDL_ANYFORMAT	0x10000000	/**< Allow any video depth/pixel-format */
+#define SDL_HWPALETTE	0x20000000	/**< Surface has exclusive palette */
+#define SDL_DOUBLEBUF	0x40000000	/**< Set up double-buffered video mode */
+#define SDL_FULLSCREEN	0x80000000	/**< Surface is a full screen display */
+#define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
+#define SDL_OPENGLBLIT	0x0000000A	/**< Create an OpenGL rendering context and use it for blitting */
+#define SDL_RESIZABLE	0x00000010	/**< This video mode may be resized */
+#define SDL_NOFRAME	0x00000020	/**< No window caption or edge frame */
+/*@}*/
+
+/** Used internally (read-only) */
+/*@{*/
+#define SDL_HWACCEL	0x00000100	/**< Blit uses hardware acceleration */
+#define SDL_SRCCOLORKEY	0x00001000	/**< Blit uses a source color key */
+#define SDL_RLEACCELOK	0x00002000	/**< Private flag */
+#define SDL_RLEACCEL	0x00004000	/**< Surface is RLE encoded */
+#define SDL_SRCALPHA	0x00010000	/**< Blit uses source alpha blending */
+#define SDL_PREALLOC	0x01000000	/**< Surface uses preallocated memory */
+/*@}*/
+
+/*@}*/
+
+/** Evaluates to true if the surface needs to be locked before access */
 #define SDL_MUSTLOCK(surface)	\
   (surface->offset ||		\
   ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
 
-/* typedef for private surface blitting functions */
+/** typedef for private surface blitting functions */
 typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
 			struct SDL_Surface *dst, SDL_Rect *dstrect);
 
 
-/* Useful for determining the video hardware capabilities */
+/** Useful for determining the video hardware capabilities */
 typedef struct SDL_VideoInfo {
-	Uint32 hw_available :1;	/* Flag: Can you create hardware surfaces? */
-	Uint32 wm_available :1;	/* Flag: Can you talk to a window manager? */
+	Uint32 hw_available :1;	/**< Flag: Can you create hardware surfaces? */
+	Uint32 wm_available :1;	/**< Flag: Can you talk to a window manager? */
 	Uint32 UnusedBits1  :6;
 	Uint32 UnusedBits2  :1;
-	Uint32 blit_hw      :1;	/* Flag: Accelerated blits HW --> HW */
-	Uint32 blit_hw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
-	Uint32 blit_hw_A    :1;	/* Flag: Accelerated blits with Alpha */
-	Uint32 blit_sw      :1;	/* Flag: Accelerated blits SW --> HW */
-	Uint32 blit_sw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
-	Uint32 blit_sw_A    :1;	/* Flag: Accelerated blits with Alpha */
-	Uint32 blit_fill    :1;	/* Flag: Accelerated color fill */
+	Uint32 blit_hw      :1;	/**< Flag: Accelerated blits HW --> HW */
+	Uint32 blit_hw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
+	Uint32 blit_hw_A    :1;	/**< Flag: Accelerated blits with Alpha */
+	Uint32 blit_sw      :1;	/**< Flag: Accelerated blits SW --> HW */
+	Uint32 blit_sw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
+	Uint32 blit_sw_A    :1;	/**< Flag: Accelerated blits with Alpha */
+	Uint32 blit_fill    :1;	/**< Flag: Accelerated color fill */
 	Uint32 UnusedBits3  :16;
-	Uint32 video_mem;	/* The total amount of video memory (in K) */
-	SDL_PixelFormat *vfmt;	/* Value: The format of the video surface */
-	int    current_w;	/* Value: The current video mode width */
-	int    current_h;	/* Value: The current video mode height */
+	Uint32 video_mem;	/**< The total amount of video memory (in K) */
+	SDL_PixelFormat *vfmt;	/**< Value: The format of the video surface */
+	int    current_w;	/**< Value: The current video mode width */
+	int    current_h;	/**< Value: The current video mode height */
 } 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) */
+/*@{*/
+#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 */
+/** 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;
+        /*@{*/
 
-	/* 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;
+        /*@}*/
 } SDL_Overlay;
 
 
-/* Public enumeration for setting the OpenGL window attributes. */
+/** Public enumeration for setting the OpenGL window attributes. */
 typedef enum {
     SDL_GL_RED_SIZE,
     SDL_GL_GREEN_SIZE,
@@ -218,17 +247,23 @@ typedef enum {
     SDL_GL_SWAP_CONTROL
 } SDL_GLattr;
 
-/* flags for SDL_SetPalette() */
+/** @name flags for SDL_SetPalette() */
+/*@{*/
 #define SDL_LOGPAL 0x01
 #define SDL_PHYSPAL 0x02
+/*@}*/
 
 /* Function prototypes */
 
-/* These functions are used internally, and should not be used unless you
+/**
+ * @name Video Init and Quit
+ * These functions are used internally, and should not be used unless you
  * have a specific need to specify the video driver you want to use.
  * You should normally use SDL_Init() or SDL_InitSubSystem().
- *
- * SDL_VideoInit() initializes the video subsystem -- sets up a connection
+ */
+/*@{*/
+/**
+ * Initializes the video subsystem. Sets up a connection
  * to the window manager, etc, and determines the current video mode and
  * pixel format, but does not initialize a window or graphics mode.
  * Note that event handling is activated by this routine.
@@ -239,14 +274,16 @@ typedef enum {
  */
 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
+/*@}*/
 
-/* This function fills the given character buffer with the name of the
+/**
+ * This function fills the given character buffer with the name of the
  * video driver, and returns a pointer to it if the video driver has
  * been initialized.  It returns NULL if no driver has been initialized.
  */
 extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
 
-/*
+/**
  * This function returns a pointer to the current display surface.
  * If SDL is doing format conversion on the display surface, this
  * function returns the publicly visible surface, not the real video
@@ -254,7 +291,7 @@ extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
 
-/*
+/**
  * This function returns a read-only pointer to information about the
  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
  * member of the returned structure will contain the pixel format of the
@@ -262,7 +299,7 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
  */
 extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
 
-/* 
+/**
  * Check to see if a particular video mode is supported.
  * It returns 0 if the requested mode is not supported under any bit depth,
  * or returns the bits-per-pixel of the closest available mode with the
@@ -275,7 +312,7 @@ extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
  */
 extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
 
-/*
+/**
  * Return a pointer to an array of available screen dimensions for the
  * given format and video flags, sorted largest to smallest.  Returns 
  * NULL if there are no dimensions available for a particular format, 
@@ -286,7 +323,7 @@ extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint
  */
 extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
 
-/*
+/**
  * Set up a video mode with the specified width, height and bits-per-pixel.
  *
  * If 'bpp' is 0, it is treated as the current display bits per pixel.
@@ -347,18 +384,24 @@ extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint3
 extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
 			(int width, int height, int bpp, Uint32 flags);
 
-/*
- * Makes sure the given list of rectangles is updated on the given screen.
- * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
- * screen.
+/** @name SDL_Update Functions
  * These functions should not be called while 'screen' is locked.
  */
+/*@{*/
+/**
+ * Makes sure the given list of rectangles is updated on the given screen.
+ */
 extern DECLSPEC void SDLCALL SDL_UpdateRects
 		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
+/**
+ * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
+ * screen.
+ */
 extern DECLSPEC void SDLCALL SDL_UpdateRect
 		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
+/*@}*/
 
-/*
+/**
  * On hardware that supports double-buffering, this function sets up a flip
  * and returns.  The hardware will wait for vertical retrace, and then swap
  * video buffers before the next video surface blit or lock will return.
@@ -370,7 +413,7 @@ extern DECLSPEC void SDLCALL SDL_UpdateRect
  */
 extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
 
-/*
+/**
  * Set the gamma correction for each of the color channels.
  * The gamma values range (approximately) between 0.1 and 10.0
  * 
@@ -380,7 +423,7 @@ extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
  */
 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
 
-/*
+/**
  * Set the gamma translation table for the red, green, and blue channels
  * of the video hardware.  Each table is an array of 256 16-bit quantities,
  * representing a mapping between the input and output for that channel.
@@ -394,7 +437,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
  */
 extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
 
-/*
+/**
  * Retrieve the current values of the gamma translation tables.
  * 
  * You must pass in valid pointers to arrays of 256 16-bit quantities.
@@ -405,7 +448,7 @@ extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *gr
  */
 extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
 
-/*
+/**
  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
  * is not a palettized surface, this function does nothing, returning 0.
  * If all of the colors were set as passed to SDL_SetColors(), it will
@@ -423,7 +466,7 @@ extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16
 extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
 			SDL_Color *colors, int firstcolor, int ncolors);
 
-/*
+/**
  * Sets a portion of the colormap for a given 8-bit surface.
  * 'flags' is one or both of:
  * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
@@ -443,35 +486,37 @@ extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
 				   SDL_Color *colors, int firstcolor,
 				   int ncolors);
 
-/*
+/**
  * Maps an RGB triple to an opaque pixel value for a given pixel format
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
 (const SDL_PixelFormat * const format,
  const Uint8 r, const Uint8 g, const Uint8 b);
 
-/*
+/**
  * Maps an RGBA quadruple to a pixel value for a given pixel format
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
 (const SDL_PixelFormat * const format,
  const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
 
-/*
+/**
  * Maps a pixel value into the RGB components for a given pixel format
  */
 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
 				const SDL_PixelFormat * const fmt,
 				Uint8 *r, Uint8 *g, Uint8 *b);
 
-/*
+/**
  * Maps a pixel value into the RGBA components for a given pixel format
  */
 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
 				const SDL_PixelFormat * const fmt,
 				Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
 
-/*
+/** @sa SDL_CreateRGBSurface */
+#define SDL_AllocSurface    SDL_CreateRGBSurface
+/**
  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
  * If the depth is greater than 8 bits, the pixel format is set using the
@@ -505,16 +550,16 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
  * reason the surface could not be placed in video memory, it will not have
  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
  */
-#define SDL_AllocSurface    SDL_CreateRGBSurface
 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
 			(Uint32 flags, int width, int height, int depth, 
 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
+/** @sa SDL_CreateRGBSurface */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
 			int width, int height, int depth, int pitch,
 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
 
-/*
+/**
  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
  * to and read from 'surface->pixels', using the pixel format stored in 
@@ -535,7 +580,7 @@ extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
 
-/*
+/**
  * Load a surface from a seekable SDL data source (memory or file.)
  * If 'freesrc' is non-zero, the source will be closed after being read.
  * Returns the new surface, or NULL if there was an error.
@@ -543,10 +588,10 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
 
-/* Convenience macro -- load a surface from a file */
+/** Convenience macro -- load a surface from a file */
 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
 
-/*
+/**
  * Save a surface to a seekable SDL data source (memory or file.)
  * If 'freedst' is non-zero, the source will be closed after being written.
  * Returns 0 if successful or -1 if there was an error.
@@ -554,11 +599,11 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc
 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
 		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
 
-/* Convenience macro -- save a surface to a file */
+/** Convenience macro -- save a surface to a file */
 #define SDL_SaveBMP(surface, file) \
 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
 
-/*
+/**
  * Sets the color key (transparent pixel) in a blittable surface.
  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
  * 'key' will be the transparent pixel in the source image of a blit.
@@ -570,7 +615,7 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
 extern DECLSPEC int SDLCALL SDL_SetColorKey
 			(SDL_Surface *surface, Uint32 flag, Uint32 key);
 
-/*
+/**
  * This function sets the alpha value for the entire surface, as opposed to
  * using the alpha component of each pixel. This value measures the range
  * of transparency of the surface, 0 being completely transparent to 255
@@ -587,7 +632,7 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey
  */
 extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
 
-/*
+/**
  * Sets the clipping rectangle for the destination surface in a blit.
  *
  * If the clip rectangle is NULL, clipping will be disabled.
@@ -601,14 +646,14 @@ extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
 
-/*
+/**
  * Gets the clipping rectangle for the destination surface in a blit.
  * 'rect' must be a pointer to a valid rectangle which will be filled
  * with the correct values.
  */
 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
 
-/*
+/**
  * Creates a new surface of the specified format, and then copies and maps 
  * the given surface to it so the blit of the converted surface will be as 
  * fast as possible.  If this function fails, it returns NULL.
@@ -623,7 +668,7 @@ extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rec
 extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
 			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
 
-/*
+/**
  * This performs a fast blit from the source surface to the destination
  * surface.  It assumes that the source and destination rectangles are
  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
@@ -679,35 +724,38 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
  * If either of the surfaces were in video memory, and the blit returns -2,
  * the video memory was lost, so it should be reloaded with artwork and 
  * re-blitted:
-	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
-		while ( SDL_LockSurface(image) < 0 )
-			Sleep(10);
-		-- Write image pixels to image->pixels --
-		SDL_UnlockSurface(image);
-	}
+ * @code
+ *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
+ *		while ( SDL_LockSurface(image) < 0 )
+ *			Sleep(10);
+ *		-- Write image pixels to image->pixels --
+ *		SDL_UnlockSurface(image);
+ *	}
+ * @endcode
+ *
  * This happens under DirectX 5.0 when the system switches away from your
  * fullscreen application.  The lock will also fail until you have access
  * to the video memory again.
+ *
+ * You should call SDL_BlitSurface() unless you know exactly how SDL
+ * blitting works internally and how to use the other blit functions.
  */
-/* You should call SDL_BlitSurface() unless you know exactly how SDL
-   blitting works internally and how to use the other blit functions.
-*/
 #define SDL_BlitSurface SDL_UpperBlit
 
-/* This is the public blit function, SDL_BlitSurface(), and it performs
-   rectangle validation and clipping before passing it to SDL_LowerBlit()
-*/
+/** This is the public blit function, SDL_BlitSurface(), and it performs
+ *  rectangle validation and clipping before passing it to SDL_LowerBlit()
+ */
 extern DECLSPEC int SDLCALL SDL_UpperBlit
 			(SDL_Surface *src, SDL_Rect *srcrect,
 			 SDL_Surface *dst, SDL_Rect *dstrect);
-/* This is a semi-private blit function and it performs low-level surface
-   blitting only.
-*/
+/** This is a semi-private blit function and it performs low-level surface
+ *  blitting only.
+ */
 extern DECLSPEC int SDLCALL SDL_LowerBlit
 			(SDL_Surface *src, SDL_Rect *srcrect,
 			 SDL_Surface *dst, SDL_Rect *dstrect);
 
-/*
+/**
  * This function performs a fast fill of the given rectangle with 'color'
  * The given rectangle is clipped to the destination surface clip area
  * and the final fill rectangle is saved in the passed in pointer.
@@ -719,7 +767,7 @@ extern DECLSPEC int SDLCALL SDL_LowerBlit
 extern DECLSPEC int SDLCALL SDL_FillRect
 		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
 
-/* 
+/**
  * This function takes a surface and copies it to a new surface of the
  * pixel format and colors of the video framebuffer, suitable for fast
  * blitting onto the display surface.  It calls SDL_ConvertSurface()
@@ -732,7 +780,7 @@ extern DECLSPEC int SDLCALL SDL_FillRect
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
 
-/* 
+/**
  * This function takes a surface and copies it to a new surface of the
  * pixel format and colors of the video framebuffer (if possible),
  * suitable for fast alpha blitting onto the display surface.
@@ -748,38 +796,39 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surfac
 
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* YUV video surface overlay functions                                       */
+/** @name YUV video surface overlay functions                                */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* This function creates a video output overlay
-   Calling the returned surface an overlay is something of a misnomer because
-   the contents of the display surface underneath the area where the overlay
-   is shown is undefined - it may be overwritten with the converted YUV data.
-*/
+/** This function creates a video output overlay
+ *  Calling the returned surface an overlay is something of a misnomer because
+ *  the contents of the display surface underneath the area where the overlay
+ *  is shown is undefined - it may be overwritten with the converted YUV data.
+ */
 extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
 				Uint32 format, SDL_Surface *display);
 
-/* Lock an overlay for direct access, and unlock it when you are done */
+/** Lock an overlay for direct access, and unlock it when you are done */
 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
 
-/* Blit a video overlay to the display surface.
-   The contents of the video surface underneath the blit destination are
-   not defined.  
-   The width and height of the destination rectangle may be different from
-   that of the overlay, but currently only 2x scaling is supported.
-*/
+/** Blit a video overlay to the display surface.
+ *  The contents of the video surface underneath the blit destination are
+ *  not defined.  
+ *  The width and height of the destination rectangle may be different from
+ *  that of the overlay, but currently only 2x scaling is supported.
+ */
 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
 
-/* Free a video overlay */
+/** Free a video overlay */
 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* OpenGL support functions.                                                 */
+/** @name OpenGL support functions.                                          */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*
+/**
  * Dynamically load an OpenGL library, or the default one if path is NULL
  *
  * If you do this, you need to retrieve all of the GL functions used in
@@ -787,17 +836,17 @@ extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
  */
 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
 
-/*
+/**
  * Get the address of a GL function
  */
 extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
 
-/*
+/**
  * Set an attribute of the OpenGL subsystem before intialization.
  */
 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
 
-/*
+/**
  * Get an attribute of the OpenGL subsystem from the windowing
  * interface, such as glX. This is of course different from getting
  * the values from SDL's internal OpenGL subsystem, which only
@@ -808,30 +857,38 @@ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  */
 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
 
-/*
+/**
  * Swap the OpenGL buffers, if double-buffering is supported.
  */
 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
 
-/*
+/** @name OpenGL Internal Functions
  * Internal functions that should not be called unless you have read
  * and understood the source code for these functions.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
 extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
 extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
+/*@}*/
+
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* These functions allow interaction with the window manager, if any.        */
+/** @name Window Manager Functions                                           */
+/** These functions allow interaction with the window manager, if any.       */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*
- * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
+/**
+ * Sets the title and icon text of the display window (UTF-8 encoded)
  */
 extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
+/**
+ * Gets the title and icon text of the display window (UTF-8 encoded)
+ */
 extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
 
-/*
+/**
  * Sets the icon for the display window.
  * This function must be called before the first call to SDL_SetVideoMode().
  * It takes an icon surface, and a mask in MSB format.
@@ -839,14 +896,14 @@ extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
  */
 extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
 
-/*
+/**
  * This function iconifies the window, and returns 1 if it succeeded.
  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
  * This function is a noop and returns 0 in non-windowed environments.
  */
 extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
 
-/*
+/**
  * Toggle fullscreen mode without changing the contents of the screen.
  * If the display surface does not require locking before accessing
  * the pixel information, then the memory pointers will not change.
@@ -863,24 +920,25 @@ extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
  */
 extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
 
-/*
- * This function allows you to set and query the input grab state of
- * the application.  It returns the new input grab state.
- */
 typedef enum {
 	SDL_GRAB_QUERY = -1,
 	SDL_GRAB_OFF = 0,
 	SDL_GRAB_ON = 1,
-	SDL_GRAB_FULLSCREEN	/* Used internally */
+	SDL_GRAB_FULLSCREEN	/**< Used internally */
 } SDL_GrabMode;
-/*
+/**
+ * This function allows you to set and query the input grab state of
+ * the application.  It returns the new input grab state.
+ *
  * Grabbing means that the mouse is confined to the application window,
  * and nearly all keyboard input is passed directly to the application,
  * and not interpreted by a window manager, if any.
  */
 extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
 
-/* Not in public API at the moment - do not use! */
+/*@}*/
+
+/** @internal Not in public API at the moment - do not use! */
 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
                                     SDL_Surface *dst, SDL_Rect *dstrect);
                     

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

include/doxyfile

+# Doxyfile 1.2.16
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+#       TAG = value [value, ...]
+# For lists items can also be appended using:
+#       TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# General configuration options
+#---------------------------------------------------------------------------
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME           = SDL
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER         = 1.2.14
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY       = docs
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Brazilian, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch,
+# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean,
+# Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovene,
+# Spanish, Swedish and Ukrainian.
+
+OUTPUT_LANGUAGE        = English
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL            = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE        = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC         = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES  = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS     = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these class will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES     = NO
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC      = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF           = YES
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC    = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
+# members of a class in the documentation of that class as if those members were
+# ordinary class members. Constructors, destructors and assignment operators of
+# the base classes will not be shown.
+
+INLINE_INHERITED_MEMB  = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES        = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. It is allowed to use relative paths in the argument list.
+
+STRIP_FROM_PATH        =
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS          = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS    = YES
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower case letters. If set to YES upper case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# users are adviced to set this option to NO.
+
+CASE_SENSE_NAMES       = YES
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES            = NO
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES       = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS       = YES
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES     = YES
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments  will behave just like the Qt-style comments (thus requiring an
+# explict @brief command for a brief description.
+
+JAVADOC_AUTOBRIEF      = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP         = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# reimplements.
+
+INHERIT_DOCS           = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO            = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS       = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC   = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE               = 4
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST      = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST      = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST       = YES
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES                =
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS       =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consist of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES  = 30
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
+# only. Doxygen will then generate output that is more tailored for C.
+# For instance some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
+# only. Doxygen will then generate output that is more tailored for Java.
+# For instance namespaces will be presented as packages, qualified scopes
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA   = NO
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES        = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET                  = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS               = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED   = YES
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text.
+
+WARN_FORMAT            = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE           =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT                  = include
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
+# *.h++ *.idl *.odl
+
+FILE_PATTERNS          = *.h
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE              = NO
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE                =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
+# that are symbolic links (a Unix filesystem feature) are excluded from the input.
+
+EXCLUDE_SYMLINKS       = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories.
+
+EXCLUDE_PATTERNS       =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH           =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS       =
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE      = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH             =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output.
+
+INPUT_FILTER           =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse.
+
+FILTER_SOURCE_FILES    = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+
+SOURCE_BROWSER         = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES         = NO
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default)
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default)
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION    = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX     = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX    = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX          =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML          = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT            = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION    = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER            =
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER            =
+
+# The HTML_STYLESHEET tag can be used to specify a user defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet
+
+HTML_STYLESHEET        =
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS     = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP      = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI           = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC             = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the Html help documentation and to the tree view.
+
+TOC_EXPAND             = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX          = NO
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE   = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript and frames is required (for instance Mozilla, Netscape 4.0+,
+# or Internet explorer 4.0+). Note that for large projects the tree generation
+# can take a very long time. In such cases it is better to disable this feature.
+# Windows users are probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW      = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH         = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX         = NO
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT           = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME         = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME     = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX          = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE             = a4wide
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES         =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER           =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS         = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX           = NO
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE        = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimised for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF           = YES
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT             = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF            = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS         = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assigments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE    =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE    =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN           = YES
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT             = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION          = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS              = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_XML           = NO
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF   = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING   = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION        = YES
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_PREDEFINED tags.
+
+EXPAND_ONLY_PREDEF     = YES
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH           =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS  =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed.
+
+PREDEFINED             = DOXYGEN_SHOULD_IGNORE_THIS=1 SDLCALL= SNDDECLSPEC=
+
+# If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED      =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line and do not end with a semicolon. Such function macros are typically
+# used for boiler-plate code, and will confuse the parser if not removed.
+
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration::addtions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES tag can be used to specify one or more tagfiles.
+
+TAGFILES               =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE       =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS           = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS        = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in Html, RTF and LaTeX) for classes with base or
+# super classes. Setting the tag to NO turns the diagrams off. Note that this
+# option is superceded by the HAVE_DOT option below. This is only a fallback. It is
+# recommended to install and use dot, since it yields more powerful graphs.
+
+CLASS_DIAGRAMS         = NO
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS   = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT               = NO
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH            = NO
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH    = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS     = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH          = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH      = YES
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY    = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT       = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found on the path.
+
+DOT_PATH               =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS           =
+
+# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_WIDTH    = 1024
+
+# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_HEIGHT   = 1024
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND        = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermedate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP            = YES
+
+#---------------------------------------------------------------------------
+# Configuration::addtions related to the search engine
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE           = NO
+
+# The CGI_NAME tag should be the name of the CGI script that
+# starts the search engine (doxysearch) with the correct parameters.
+# A script with this name will be generated by doxygen.
+
+CGI_NAME               = search.cgi
+
+# The CGI_URL tag should be the absolute URL to the directory where the
+# cgi binaries are located. See the documentation of your http daemon for
+# details.
+
+CGI_URL                =
+
+# The DOC_URL tag should be the absolute URL to the directory where the
+# documentation is located. If left blank the absolute path to the
+# documentation, with file:// prepended to it, will be used.
+
+DOC_URL                =
+
+# The DOC_ABSPATH tag should be the absolute path to the directory where the
+# documentation is located. If left blank the directory on the local machine
+# will be used.
+
+DOC_ABSPATH            =
+
+# The BIN_ABSPATH tag must point to the directory where the doxysearch binary
+# is installed.
+
+BIN_ABSPATH            = /usr/local/bin/
+
+# The EXT_DOC_PATHS tag can be used to specify one or more paths to
+# documentation generated for other projects. This allows doxysearch to search
+# the documentation for these projects as well.
+
+EXT_DOC_PATHS          =