We are currently migrating Bugzilla to GitHub issues.
Any changes made to the bug tracker now will be lost, so please do not post new bugs or make changes to them.
When we're done, all bug URLs will redirect to their equivalent location on the new bug tracker.

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

doc.diff (text/plain), 146.40 KB, created by Ken Bull on 2009-02-25 13:22:02 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Ken Bull

Created: 2009-02-25 13:22:02 UTC

Size: 146.40 KB

patch

obsolete

>Index: SDL-1.2/include/SDL_error.h
>===================================================================
>--- SDL-1.2/include/SDL_error.h	(revision 4446)
>+++ SDL-1.2/include/SDL_error.h	(working copy)
>@@ -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,8 +61,8 @@
> 	SDL_LASTERROR
> } SDL_errorcode;
> extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
>+/*@}*/
> 
>-
> /* Ends C function definitions when using C++ */
> #ifdef __cplusplus
> }
>Index: SDL-1.2/include/SDL_audio.h
>===================================================================
>--- SDL-1.2/include/SDL_audio.h	(revision 4446)
>+++ SDL-1.2/include/SDL_audio.h	(working copy)
>@@ -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 @@
> #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 @@
>  * 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 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 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_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);
>Index: SDL-1.2/include/SDL_cpuinfo.h
>===================================================================
>--- SDL-1.2/include/SDL_cpuinfo.h	(revision 4446)
>+++ SDL-1.2/include/SDL_cpuinfo.h	(working copy)
>@@ -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++ */
>Index: SDL-1.2/include/SDL_events.h
>===================================================================
>--- SDL-1.2/include/SDL_events.h	(revision 4446)
>+++ SDL-1.2/include/SDL_events.h	(working copy)
>@@ -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 @@
> 	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 @@
> 	SDL_SysWMmsg *msg;
> } SDL_SysWMEvent;
> 
>-/* General event structure */
>+/** General event structure */
> typedef union SDL_Event {
> 	Uint8 type;
> 	SDL_ActiveEvent active;
>@@ -237,97 +244,109 @@
> 
> /* 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
> }
>Index: SDL-1.2/include/SDL_video.h
>===================================================================
>--- SDL-1.2/include/SDL_video.h	(revision 4446)
>+++ SDL-1.2/include/SDL_video.h	(working copy)
>@@ -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 @@
> 	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 @@
> 	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 */
>+	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 */
>+	/** 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 */
>+/** @name SDL_Surface Flags
>+ *  These are the currently supported flags for the SDL_surface
>+ */
>+/*@{*/
> 
>-/* Evaluates to true if the surface needs to be locked before access */
>+/** 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 */
>+	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 */
>+	/** @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 @@
>     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 @@
>  */
> 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 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 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 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 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_Surface * SDLCALL SDL_SetVideoMode
> 			(int width, int height, int bpp, Uint32 flags);
> 
>-/*
>+/** @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.
>- * These functions should not be called while 'screen' is locked.
>  */
>-extern DECLSPEC void SDLCALL SDL_UpdateRects
>-		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
> 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 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_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_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_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_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,33 +486,35 @@
> 				   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, SDL_PixelFormat *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, SDL_PixelFormat *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
>@@ -503,16 +548,16 @@
>  * 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 
>@@ -533,7 +578,7 @@
> 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.
>@@ -541,10 +586,10 @@
>  */
> 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.
>@@ -552,11 +597,11 @@
> 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.
>@@ -568,7 +613,7 @@
> 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
>@@ -585,7 +630,7 @@
>  */
> 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.
>@@ -599,14 +644,14 @@
>  */
> 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.
>@@ -621,7 +666,7 @@
> 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
>@@ -677,35 +722,38 @@
>  * 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.
>@@ -717,7 +765,7 @@
> 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()
>@@ -730,7 +778,7 @@
>  */
> 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.
>@@ -746,38 +794,39 @@
> 
> 
> /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
>-/* 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
>@@ -785,17 +834,17 @@
>  */
> 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
>@@ -806,30 +855,38 @@
>  */
> 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.
>@@ -837,14 +894,14 @@
>  */
> 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.
>@@ -861,24 +918,25 @@
>  */
> 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);
>                     
>Index: SDL-1.2/include/SDL_thread.h
>===================================================================
>--- SDL-1.2/include/SDL_thread.h	(revision 4446)
>+++ SDL-1.2/include/SDL_thread.h	(working copy)
>@@ -23,11 +23,12 @@
> #ifndef _SDL_thread_h
> #define _SDL_thread_h
> 
>-/* Header for the SDL thread management routines 
>+/** @file SDL_thread.h
>+ *  Header for the SDL thread management routines 
>+ *
>+ *  @note These are independent of the other SDL routines.
>+ */
> 
>-	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 *), 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);
> 
> 
>Index: SDL-1.2/include/SDL_rwops.h
>===================================================================
>--- SDL-1.2/include/SDL_rwops.h	(revision 4446)
>+++ SDL-1.2/include/SDL_rwops.h	(working copy)
>@@ -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 @@
> } 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,35 +108,44 @@
> 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 */
>+/*@}*/
> 
>-/* Macros to easily read and write from an SDL_RWops structure */
>+/** @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 */
>+/*@}*/
>+
>+/** @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
> }
>Index: SDL-1.2/include/SDL_active.h
>===================================================================
>--- SDL-1.2/include/SDL_active.h	(revision 4446)
>+++ SDL-1.2/include/SDL_active.h	(working copy)
>@@ -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
>Index: SDL-1.2/include/begin_code.h
>===================================================================
>--- SDL-1.2/include/begin_code.h	(revision 4446)
>+++ SDL-1.2/include/begin_code.h	(working copy)
>@@ -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__)
> #  if defined(__GNUC__)
>@@ -68,14 +76,20 @@
> # 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
> #else
> #ifdef __OS2__
>-/* But on OS/2, we use the _System calling convention */
>-/* to be compatible with every compiler */
>+/**
>+ *  @def SDLCALL
>+ *  But on OS/2, we use the _System calling convention
>+ *  to be compatible with every compiler
>+ */
> #define SDLCALL _System
> #else
> #define SDLCALL
>@@ -93,10 +107,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
>@@ -111,7 +127,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
>@@ -136,15 +155,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
>Index: SDL-1.2/include/SDL_timer.h
>===================================================================
>--- SDL-1.2/include/SDL_timer.h	(revision 4446)
>+++ SDL-1.2/include/SDL_timer.h	(working copy)
>@@ -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 @@
>  * 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 @@
>  */
> 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 @@
>  */
> 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
> }
>Index: SDL-1.2/include/SDL_opengl.h
>===================================================================
>--- SDL-1.2/include/SDL_opengl.h	(revision 4446)
>+++ SDL-1.2/include/SDL_opengl.h	(working copy)
>@@ -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 @@
> 
> #endif
> #endif /* NO_SDL_GLEXT */
>+/*@}*/
>\ No newline at end of file
>Index: SDL-1.2/include/SDL_stdinc.h
>===================================================================
>--- SDL-1.2/include/SDL_stdinc.h	(revision 4446)
>+++ SDL-1.2/include/SDL_stdinc.h	(working copy)
>@@ -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 @@
> } 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(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,8 +140,8 @@
> #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++ */
> #ifdef __cplusplus
>@@ -564,11 +572,15 @@
> 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
>@@ -580,9 +592,9 @@
> 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)
>Index: SDL-1.2/include/SDL_main.h
>===================================================================
>--- SDL-1.2/include/SDL_main.h	(revision 4446)
>+++ SDL-1.2/include/SDL_main.h	(working copy)
>@@ -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" {
> #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 "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 @@
> #endif
> #include "close_code.h"
> #endif
>+/*@}*/
> 
> #endif /* Need to redefine main()? */
> 
>Index: SDL-1.2/include/SDL_version.h
>===================================================================
>--- SDL-1.2/include/SDL_version.h	(revision 4446)
>+++ SDL-1.2/include/SDL_version.h	(working copy)
>@@ -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		13
>+/*@}*/
> 
> typedef struct SDL_version {
> 	Uint8 major;
>@@ -45,7 +50,8 @@
> 	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 @@
> 	(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);
> 
>Index: SDL-1.2/include/SDL_getenv.h
>===================================================================
>--- SDL-1.2/include/SDL_getenv.h	(revision 4446)
>+++ SDL-1.2/include/SDL_getenv.h	(working copy)
>@@ -20,5 +20,9 @@
>     slouken@libsdl.org
> */
> 
>+/** @file SDL_getenv.h
>+ *  @deprecated Use SDL_stdinc.h instead
>+ */
>+
> /* DEPRECATED */
> #include "SDL_stdinc.h"
>Index: SDL-1.2/include/SDL_mouse.h
>===================================================================
>--- SDL-1.2/include/SDL_mouse.h	(revision 4446)
>+++ SDL-1.2/include/SDL_mouse.h	(working copy)
>@@ -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 @@
>  */
> 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_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 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 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,8 +132,8 @@
> #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
> }
>Index: SDL-1.2/include/close_code.h
>===================================================================
>--- SDL-1.2/include/close_code.h	(revision 4446)
>+++ SDL-1.2/include/close_code.h	(working copy)
>@@ -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
>Index: SDL-1.2/include/SDL_endian.h
>===================================================================
>--- SDL-1.2/include/SDL_endian.h	(revision 4446)
>+++ SDL-1.2/include/SDL_endian.h	(working copy)
>@@ -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 @@
> #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 @@
> #define SDL_SwapBE32(X)	(X)
> #define SDL_SwapBE64(X)	(X)
> #endif
>+/*@}*/
> 
> /* Ends C function definitions when using C++ */
> #ifdef __cplusplus
>Index: SDL-1.2/include/SDL_byteorder.h
>===================================================================
>--- SDL-1.2/include/SDL_byteorder.h	(revision 4446)
>+++ SDL-1.2/include/SDL_byteorder.h	(working copy)
>@@ -20,5 +20,10 @@
>     slouken@libsdl.org
> */
> 
>+/**
>+ *  @file SDL_byteorder.h
>+ *  @deprecated Use SDL_endian.h instead
>+ */
>+
> /* DEPRECATED */
> #include "SDL_endian.h"
>Index: SDL-1.2/include/SDL_joystick.h
>===================================================================
>--- SDL-1.2/include/SDL_joystick.h	(revision 4446)
>+++ SDL-1.2/include/SDL_joystick.h	(working copy)
>@@ -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 @@
> #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);
>Index: SDL-1.2/include/SDL_keyboard.h
>===================================================================
>--- SDL-1.2/include/SDL_keyboard.h	(revision 4446)
>+++ SDL-1.2/include/SDL_keyboard.h	(working copy)
>@@ -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);
>Index: SDL-1.2/include/SDL_mutex.h
>===================================================================
>--- SDL-1.2/include/SDL_mutex.h	(revision 4446)
>+++ SDL-1.2/include/SDL_mutex.h	(working copy)
>@@ -23,11 +23,12 @@
> #ifndef _SDL_mutex_h
> #define _SDL_mutex_h
> 
>-/* Functions to provide thread synchronization primitives
>+/** @file SDL_mutex.h
>+ *  Functions to provide thread synchronization primitives
>+ *
>+ *  @note These are independent of the other SDL routines.
>+ */
> 
>-	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.
>  */
>-#define SDL_UnlockMutex(m)	SDL_mutexV(m)
> extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
> 
>-/* Destroy a mutex */
>+/** Destroy a mutex */
> extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
> 
>+/*@}*/
> 
> /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
>-/* 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 @@
> #include "close_code.h"
> 
> #endif /* _SDL_mutex_h */
>+
>Index: SDL-1.2/include/SDL_types.h
>===================================================================
>--- SDL-1.2/include/SDL_types.h	(revision 4446)
>+++ SDL-1.2/include/SDL_types.h	(working copy)
>@@ -20,5 +20,9 @@
>     slouken@libsdl.org
> */
> 
>+/** @file SDL_types.h
>+ *  @deprecated Use SDL_stdinc.h instead.
>+ */
>+
> /* DEPRECATED */
> #include "SDL_stdinc.h"
>Index: SDL-1.2/include/SDL_cdrom.h
>===================================================================
>--- SDL-1.2/include/SDL_cdrom.h	(revision 4446)
>+++ SDL-1.2/include/SDL_cdrom.h	(working copy)
>@@ -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 @@
> 	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 */
>+	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 */
>+	/** 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 @@
> 	*(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);
> 
> 
>Index: SDL-1.2/include/SDL.h
>===================================================================
>--- SDL-1.2/include/SDL.h	(revision 4446)
>+++ SDL-1.2/include/SDL.h	(working copy)
>@@ -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);
> 
>Index: SDL-1.2/include/SDL_loadso.h
>===================================================================
>--- SDL-1.2/include/SDL_loadso.h	(revision 4446)
>+++ SDL-1.2/include/SDL_loadso.h	(working copy)
>@@ -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++ */
>Index: SDL-1.2/include/SDL_keysym.h
>===================================================================
>--- SDL-1.2/include/SDL_keysym.h	(revision 4446)
>+++ SDL-1.2/include/SDL_keysym.h	(working copy)
>@@ -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 @@
> 	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 @@
> 	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 @@
> 	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 @@
> 	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 @@
> 	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 @@
> 	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,
>Index: SDL-1.2/include/SDL_quit.h
>===================================================================
>--- SDL-1.2/include/SDL_quit.h	(revision 4446)
>+++ SDL-1.2/include/SDL_quit.h	(working copy)
>@@ -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.
>+/** @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.
>+ */
> 
>-  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))
> 
>Index: SDL-1.2/include/SDL_syswm.h
>===================================================================
>--- SDL-1.2/include/SDL_syswm.h	(revision 4446)
>+++ SDL-1.2/include/SDL_syswm.h	(working copy)
>@@ -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 @@
> #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 @@
> 	} 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 */
>+		/** @name 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.2.12 */
>+                /*@{*/
>+		Display *gfxdisplay;	/**< The X11 display to which rendering is done */
>+                /*@}*/
> 	    } x11;
> 	} info;
> } SDL_SysWMinfo;
>@@ -107,13 +116,13 @@
> #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 @@
> #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 @@
> 
> #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 @@
> #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);
> 
>Index: SDL-1.2/include/SDL_platform.h
>===================================================================
>--- SDL-1.2/include/SDL_platform.h	(revision 4446)
>+++ SDL-1.2/include/SDL_platform.h	(working copy)
>@@ -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

Actions: View | Diff

Attachments on bug 706: 301 | 303

We are currently migrating Bugzilla to GitHub issues.Any changes made to the bug tracker now will be lost, so please do not post new bugs or make changes to them.When we're done, all bug URLs will redirect to their equivalent location on the new bug tracker.

We are currently migrating Bugzilla to GitHub issues.
Any changes made to the bug tracker now will be lost, so please do not post new bugs or make changes to them.
When we're done, all bug URLs will redirect to their equivalent location on the new bug tracker.