Fixed bug #706 SDL-1.2
authorSam Lantinga <slouken@libsdl.org>
Mon, 21 Sep 2009 09:38:10 +0000
branchSDL-1.2
changeset 42174c4113c2162c
parent 4216 5b99971a27b4
child 4218 50b4ab8f8271
Fixed bug #706

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

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

While in general SDL is quite thoroughly commented, none of these comments are
correctly formatted for Doxygen and are generally inconsistent in their
formatting.
include/SDL.h
include/SDL_active.h
include/SDL_audio.h
include/SDL_byteorder.h
include/SDL_cdrom.h
include/SDL_cpuinfo.h
include/SDL_endian.h
include/SDL_error.h
include/SDL_events.h
include/SDL_getenv.h
include/SDL_joystick.h
include/SDL_keyboard.h
include/SDL_keysym.h
include/SDL_loadso.h
include/SDL_main.h
include/SDL_mouse.h
include/SDL_mutex.h
include/SDL_opengl.h
include/SDL_platform.h
include/SDL_quit.h
include/SDL_rwops.h
include/SDL_stdinc.h
include/SDL_syswm.h
include/SDL_thread.h
include/SDL_timer.h
include/SDL_types.h
include/SDL_version.h
include/SDL_video.h
include/begin_code.h
include/close_code.h
include/doxyfile
     1.1 --- a/include/SDL.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -20,7 +20,9 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Main include header for the SDL library */
     1.8 +/** @file SDL.h
     1.9 + *  Main include header for the SDL library
    1.10 + */
    1.11  
    1.12  #ifndef _SDL_H
    1.13  #define _SDL_H
    1.14 @@ -47,41 +49,46 @@
    1.15  extern "C" {
    1.16  #endif
    1.17  
    1.18 -/* As of version 0.5, SDL is loaded dynamically into the application */
    1.19 +/** @file SDL.h
    1.20 + *  @note As of version 0.5, SDL is loaded dynamically into the application
    1.21 + */
    1.22  
    1.23 -/* These are the flags which may be passed to SDL_Init() -- you should
    1.24 -   specify the subsystems which you will be using in your application.
    1.25 -*/
    1.26 +/** @name SDL_INIT Flags
    1.27 + *  These are the flags which may be passed to SDL_Init() -- you should
    1.28 + *  specify the subsystems which you will be using in your application.
    1.29 + */
    1.30 +/*@{*/
    1.31  #define	SDL_INIT_TIMER		0x00000001
    1.32  #define SDL_INIT_AUDIO		0x00000010
    1.33  #define SDL_INIT_VIDEO		0x00000020
    1.34  #define SDL_INIT_CDROM		0x00000100
    1.35  #define SDL_INIT_JOYSTICK	0x00000200
    1.36 -#define SDL_INIT_NOPARACHUTE	0x00100000	/* Don't catch fatal signals */
    1.37 -#define SDL_INIT_EVENTTHREAD	0x01000000	/* Not supported on all OS's */
    1.38 +#define SDL_INIT_NOPARACHUTE	0x00100000	/**< Don't catch fatal signals */
    1.39 +#define SDL_INIT_EVENTTHREAD	0x01000000	/**< Not supported on all OS's */
    1.40  #define SDL_INIT_EVERYTHING	0x0000FFFF
    1.41 +/*@}*/
    1.42  
    1.43 -/* This function loads the SDL dynamically linked library and initializes 
    1.44 - * the subsystems specified by 'flags' (and those satisfying dependencies)
    1.45 - * Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
    1.46 - * signal handlers for some commonly ignored fatal signals (like SIGSEGV)
    1.47 +/** This function loads the SDL dynamically linked library and initializes 
    1.48 + *  the subsystems specified by 'flags' (and those satisfying dependencies)
    1.49 + *  Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
    1.50 + *  signal handlers for some commonly ignored fatal signals (like SIGSEGV)
    1.51   */
    1.52  extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
    1.53  
    1.54 -/* This function initializes specific SDL subsystems */
    1.55 +/** This function initializes specific SDL subsystems */
    1.56  extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
    1.57  
    1.58 -/* This function cleans up specific SDL subsystems */
    1.59 +/** This function cleans up specific SDL subsystems */
    1.60  extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
    1.61  
    1.62 -/* This function returns mask of the specified subsystems which have
    1.63 -   been initialized.
    1.64 -   If 'flags' is 0, it returns a mask of all initialized subsystems.
    1.65 -*/
    1.66 +/** This function returns mask of the specified subsystems which have
    1.67 + *  been initialized.
    1.68 + *  If 'flags' is 0, it returns a mask of all initialized subsystems.
    1.69 + */
    1.70  extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
    1.71  
    1.72 -/* This function cleans up all initialized subsystems and unloads the
    1.73 - * dynamically linked library.  You should call it upon all exit conditions.
    1.74 +/** This function cleans up all initialized subsystems and unloads the
    1.75 + *  dynamically linked library.  You should call it upon all exit conditions.
    1.76   */
    1.77  extern DECLSPEC void SDLCALL SDL_Quit(void);
    1.78  
     2.1 --- a/include/SDL_active.h	Mon Sep 21 09:27:08 2009 +0000
     2.2 +++ b/include/SDL_active.h	Mon Sep 21 09:38:10 2009 +0000
     2.3 @@ -20,7 +20,10 @@
     2.4      slouken@libsdl.org
     2.5  */
     2.6  
     2.7 -/* Include file for SDL application focus event handling */
     2.8 +/**
     2.9 + *  @file SDL_active.h
    2.10 + *  Include file for SDL application focus event handling 
    2.11 + */
    2.12  
    2.13  #ifndef _SDL_active_h
    2.14  #define _SDL_active_h
    2.15 @@ -34,13 +37,15 @@
    2.16  extern "C" {
    2.17  #endif
    2.18  
    2.19 -/* The available application states */
    2.20 -#define SDL_APPMOUSEFOCUS	0x01		/* The app has mouse coverage */
    2.21 -#define SDL_APPINPUTFOCUS	0x02		/* The app has input focus */
    2.22 -#define SDL_APPACTIVE		0x04		/* The application is active */
    2.23 +/** @name The available application states */
    2.24 +/*@{*/
    2.25 +#define SDL_APPMOUSEFOCUS	0x01		/**< The app has mouse coverage */
    2.26 +#define SDL_APPINPUTFOCUS	0x02		/**< The app has input focus */
    2.27 +#define SDL_APPACTIVE		0x04		/**< The application is active */
    2.28 +/*@}*/
    2.29  
    2.30  /* Function prototypes */
    2.31 -/* 
    2.32 +/** 
    2.33   * This function returns the current state of the application, which is a
    2.34   * bitwise combination of SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and
    2.35   * SDL_APPACTIVE.  If SDL_APPACTIVE is set, then the user is able to
     3.1 --- a/include/SDL_audio.h	Mon Sep 21 09:27:08 2009 +0000
     3.2 +++ b/include/SDL_audio.h	Mon Sep 21 09:38:10 2009 +0000
     3.3 @@ -20,7 +20,10 @@
     3.4      slouken@libsdl.org
     3.5  */
     3.6  
     3.7 -/* Access to the raw audio mixing buffer for the SDL library */
     3.8 +/**
     3.9 + *  @file SDL_audio.h
    3.10 + *  Access to the raw audio mixing buffer for the SDL library
    3.11 + */
    3.12  
    3.13  #ifndef _SDL_audio_h
    3.14  #define _SDL_audio_h
    3.15 @@ -38,89 +41,11 @@
    3.16  extern "C" {
    3.17  #endif
    3.18  
    3.19 -/* The calculated values in this structure are calculated by SDL_OpenAudio() */
    3.20 -typedef struct SDL_AudioSpec {
    3.21 -	int freq;		/* DSP frequency -- samples per second */
    3.22 -	Uint16 format;		/* Audio data format */
    3.23 -	Uint8  channels;	/* Number of channels: 1 mono, 2 stereo */
    3.24 -	Uint8  silence;		/* Audio buffer silence value (calculated) */
    3.25 -	Uint16 samples;		/* Audio buffer size in samples (power of 2) */
    3.26 -	Uint16 padding;		/* Necessary for some compile environments */
    3.27 -	Uint32 size;		/* Audio buffer size in bytes (calculated) */
    3.28 -	/* This function is called when the audio device needs more data.
    3.29 -	   'stream' is a pointer to the audio data buffer
    3.30 -	   'len' is the length of that buffer in bytes.
    3.31 -	   Once the callback returns, the buffer will no longer be valid.
    3.32 -	   Stereo samples are stored in a LRLRLR ordering.
    3.33 -	*/
    3.34 -	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
    3.35 -	void  *userdata;
    3.36 -} SDL_AudioSpec;
    3.37 -
    3.38 -/* Audio format flags (defaults to LSB byte order) */
    3.39 -#define AUDIO_U8	0x0008	/* Unsigned 8-bit samples */
    3.40 -#define AUDIO_S8	0x8008	/* Signed 8-bit samples */
    3.41 -#define AUDIO_U16LSB	0x0010	/* Unsigned 16-bit samples */
    3.42 -#define AUDIO_S16LSB	0x8010	/* Signed 16-bit samples */
    3.43 -#define AUDIO_U16MSB	0x1010	/* As above, but big-endian byte order */
    3.44 -#define AUDIO_S16MSB	0x9010	/* As above, but big-endian byte order */
    3.45 -#define AUDIO_U16	AUDIO_U16LSB
    3.46 -#define AUDIO_S16	AUDIO_S16LSB
    3.47 -
    3.48 -/* Native audio byte ordering */
    3.49 -#if SDL_BYTEORDER == SDL_LIL_ENDIAN
    3.50 -#define AUDIO_U16SYS	AUDIO_U16LSB
    3.51 -#define AUDIO_S16SYS	AUDIO_S16LSB
    3.52 -#else
    3.53 -#define AUDIO_U16SYS	AUDIO_U16MSB
    3.54 -#define AUDIO_S16SYS	AUDIO_S16MSB
    3.55 -#endif
    3.56 -
    3.57 -
    3.58 -/* A structure to hold a set of audio conversion filters and buffers */
    3.59 -typedef struct SDL_AudioCVT {
    3.60 -	int needed;			/* Set to 1 if conversion possible */
    3.61 -	Uint16 src_format;		/* Source audio format */
    3.62 -	Uint16 dst_format;		/* Target audio format */
    3.63 -	double rate_incr;		/* Rate conversion increment */
    3.64 -	Uint8 *buf;			/* Buffer to hold entire audio data */
    3.65 -	int    len;			/* Length of original audio buffer */
    3.66 -	int    len_cvt;			/* Length of converted audio buffer */
    3.67 -	int    len_mult;		/* buffer must be len*len_mult big */
    3.68 -	double len_ratio; 	/* Given len, final size is len*len_ratio */
    3.69 -	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
    3.70 -	int filter_index;		/* Current audio conversion function */
    3.71 -} SDL_AudioCVT;
    3.72 -
    3.73 -
    3.74 -/* Function prototypes */
    3.75 -
    3.76 -/* These functions are used internally, and should not be used unless you
    3.77 - * have a specific need to specify the audio driver you want to use.
    3.78 - * You should normally use SDL_Init() or SDL_InitSubSystem().
    3.79 - */
    3.80 -extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
    3.81 -extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
    3.82 -
    3.83 -/* This function fills the given character buffer with the name of the
    3.84 - * current audio driver, and returns a pointer to it if the audio driver has
    3.85 - * been initialized.  It returns NULL if no driver has been initialized.
    3.86 - */
    3.87 -extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
    3.88 -
    3.89 -/*
    3.90 - * This function opens the audio device with the desired parameters, and
    3.91 - * returns 0 if successful, placing the actual hardware parameters in the
    3.92 - * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
    3.93 - * data passed to the callback function will be guaranteed to be in the
    3.94 - * requested format, and will be automatically converted to the hardware
    3.95 - * audio format if necessary.  This function returns -1 if it failed 
    3.96 - * to open the audio device, or couldn't set up the audio thread.
    3.97 - *
    3.98 +/**
    3.99   * When filling in the desired audio spec structure,
   3.100 - *  'desired->freq' should be the desired audio frequency in samples-per-second.
   3.101 - *  'desired->format' should be the desired audio format.
   3.102 - *  'desired->samples' is the desired size of the audio buffer, in samples.
   3.103 + * - 'desired->freq' should be the desired audio frequency in samples-per-second.
   3.104 + * - 'desired->format' should be the desired audio format.
   3.105 + * - 'desired->samples' is the desired size of the audio buffer, in samples.
   3.106   *     This number should be a power of two, and may be adjusted by the audio
   3.107   *     driver to a value more suitable for the hardware.  Good values seem to
   3.108   *     range between 512 and 8096 inclusive, depending on the application and
   3.109 @@ -130,38 +55,138 @@
   3.110   *     and left channels in LR ordering.
   3.111   *     Note that the number of samples is directly related to time by the
   3.112   *     following formula:  ms = (samples*1000)/freq
   3.113 - *  'desired->size' is the size in bytes of the audio buffer, and is
   3.114 + * - 'desired->size' is the size in bytes of the audio buffer, and is
   3.115   *     calculated by SDL_OpenAudio().
   3.116 - *  'desired->silence' is the value used to set the buffer to silence,
   3.117 + * - 'desired->silence' is the value used to set the buffer to silence,
   3.118   *     and is calculated by SDL_OpenAudio().
   3.119 - *  'desired->callback' should be set to a function that will be called
   3.120 + * - 'desired->callback' should be set to a function that will be called
   3.121   *     when the audio device is ready for more data.  It is passed a pointer
   3.122   *     to the audio buffer, and the length in bytes of the audio buffer.
   3.123   *     This function usually runs in a separate thread, and so you should
   3.124   *     protect data structures that it accesses by calling SDL_LockAudio()
   3.125   *     and SDL_UnlockAudio() in your code.
   3.126 - *  'desired->userdata' is passed as the first parameter to your callback
   3.127 + * - 'desired->userdata' is passed as the first parameter to your callback
   3.128   *     function.
   3.129   *
   3.130 + * @note The calculated values in this structure are calculated by SDL_OpenAudio()
   3.131 + *
   3.132 + */
   3.133 +typedef struct SDL_AudioSpec {
   3.134 +	int freq;		/**< DSP frequency -- samples per second */
   3.135 +	Uint16 format;		/**< Audio data format */
   3.136 +	Uint8  channels;	/**< Number of channels: 1 mono, 2 stereo */
   3.137 +	Uint8  silence;		/**< Audio buffer silence value (calculated) */
   3.138 +	Uint16 samples;		/**< Audio buffer size in samples (power of 2) */
   3.139 +	Uint16 padding;		/**< Necessary for some compile environments */
   3.140 +	Uint32 size;		/**< Audio buffer size in bytes (calculated) */
   3.141 +	/**
   3.142 +	 *  This function is called when the audio device needs more data.
   3.143 +	 *
   3.144 +	 *  @param[out] stream	A pointer to the audio data buffer
   3.145 +	 *  @param[in]  len	The length of the audio buffer in bytes.
   3.146 +	 *
   3.147 +	 *  Once the callback returns, the buffer will no longer be valid.
   3.148 +	 *  Stereo samples are stored in a LRLRLR ordering.
   3.149 +	 */
   3.150 +	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
   3.151 +	void  *userdata;
   3.152 +} SDL_AudioSpec;
   3.153 +
   3.154 +/**
   3.155 + *  @name Audio format flags
   3.156 + *  defaults to LSB byte order
   3.157 + */
   3.158 +/*@{*/
   3.159 +#define AUDIO_U8	0x0008	/**< Unsigned 8-bit samples */
   3.160 +#define AUDIO_S8	0x8008	/**< Signed 8-bit samples */
   3.161 +#define AUDIO_U16LSB	0x0010	/**< Unsigned 16-bit samples */
   3.162 +#define AUDIO_S16LSB	0x8010	/**< Signed 16-bit samples */
   3.163 +#define AUDIO_U16MSB	0x1010	/**< As above, but big-endian byte order */
   3.164 +#define AUDIO_S16MSB	0x9010	/**< As above, but big-endian byte order */
   3.165 +#define AUDIO_U16	AUDIO_U16LSB
   3.166 +#define AUDIO_S16	AUDIO_S16LSB
   3.167 +
   3.168 +/**
   3.169 + *  @name Native audio byte ordering
   3.170 + */
   3.171 +/*@{*/
   3.172 +#if SDL_BYTEORDER == SDL_LIL_ENDIAN
   3.173 +#define AUDIO_U16SYS	AUDIO_U16LSB
   3.174 +#define AUDIO_S16SYS	AUDIO_S16LSB
   3.175 +#else
   3.176 +#define AUDIO_U16SYS	AUDIO_U16MSB
   3.177 +#define AUDIO_S16SYS	AUDIO_S16MSB
   3.178 +#endif
   3.179 +/*@}*/
   3.180 +
   3.181 +/*@}*/
   3.182 +
   3.183 +
   3.184 +/** A structure to hold a set of audio conversion filters and buffers */
   3.185 +typedef struct SDL_AudioCVT {
   3.186 +	int needed;			/**< Set to 1 if conversion possible */
   3.187 +	Uint16 src_format;		/**< Source audio format */
   3.188 +	Uint16 dst_format;		/**< Target audio format */
   3.189 +	double rate_incr;		/**< Rate conversion increment */
   3.190 +	Uint8 *buf;			/**< Buffer to hold entire audio data */
   3.191 +	int    len;			/**< Length of original audio buffer */
   3.192 +	int    len_cvt;			/**< Length of converted audio buffer */
   3.193 +	int    len_mult;		/**< buffer must be len*len_mult big */
   3.194 +	double len_ratio; 	/**< Given len, final size is len*len_ratio */
   3.195 +	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
   3.196 +	int filter_index;		/**< Current audio conversion function */
   3.197 +} SDL_AudioCVT;
   3.198 +
   3.199 +
   3.200 +/* Function prototypes */
   3.201 +
   3.202 +/**
   3.203 + * @name Audio Init and Quit
   3.204 + * These functions are used internally, and should not be used unless you
   3.205 + * have a specific need to specify the audio driver you want to use.
   3.206 + * You should normally use SDL_Init() or SDL_InitSubSystem().
   3.207 + */
   3.208 +/*@{*/
   3.209 +extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   3.210 +extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   3.211 +/*@}*/
   3.212 +
   3.213 +/**
   3.214 + * This function fills the given character buffer with the name of the
   3.215 + * current audio driver, and returns a pointer to it if the audio driver has
   3.216 + * been initialized.  It returns NULL if no driver has been initialized.
   3.217 + */
   3.218 +extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
   3.219 +
   3.220 +/**
   3.221 + * This function opens the audio device with the desired parameters, and
   3.222 + * returns 0 if successful, placing the actual hardware parameters in the
   3.223 + * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
   3.224 + * data passed to the callback function will be guaranteed to be in the
   3.225 + * requested format, and will be automatically converted to the hardware
   3.226 + * audio format if necessary.  This function returns -1 if it failed 
   3.227 + * to open the audio device, or couldn't set up the audio thread.
   3.228 + *
   3.229   * The audio device starts out playing silence when it's opened, and should
   3.230   * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   3.231   * for your audio callback function to be called.  Since the audio driver
   3.232   * may modify the requested size of the audio buffer, you should allocate
   3.233   * any local mixing buffers after you open the audio device.
   3.234 + *
   3.235 + * @sa SDL_AudioSpec
   3.236   */
   3.237  extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
   3.238  
   3.239 -/*
   3.240 - * Get the current audio state:
   3.241 - */
   3.242  typedef enum {
   3.243  	SDL_AUDIO_STOPPED = 0,
   3.244  	SDL_AUDIO_PLAYING,
   3.245  	SDL_AUDIO_PAUSED
   3.246  } SDL_audiostatus;
   3.247 +
   3.248 +/** Get the current audio state */
   3.249  extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   3.250  
   3.251 -/*
   3.252 +/**
   3.253   * This function pauses and unpauses the audio callback processing.
   3.254   * It should be called with a parameter of 0 after opening the audio
   3.255   * device to start playing sound.  This is so you can safely initialize
   3.256 @@ -170,11 +195,11 @@
   3.257   */
   3.258  extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   3.259  
   3.260 -/*
   3.261 +/**
   3.262   * This function loads a WAVE from the data source, automatically freeing
   3.263   * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   3.264   * you could do:
   3.265 - *	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   3.266 + *	@code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode
   3.267   *
   3.268   * If this function succeeds, it returns the given SDL_AudioSpec,
   3.269   * filled with the audio data format of the wave data, and sets
   3.270 @@ -189,27 +214,29 @@
   3.271   */
   3.272  extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
   3.273  
   3.274 -/* Compatibility convenience function -- loads a WAV from a file */
   3.275 +/** Compatibility convenience function -- loads a WAV from a file */
   3.276  #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   3.277  	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   3.278  
   3.279 -/*
   3.280 +/**
   3.281   * This function frees data previously allocated with SDL_LoadWAV_RW()
   3.282   */
   3.283  extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf);
   3.284  
   3.285 -/*
   3.286 +/**
   3.287   * This function takes a source format and rate and a destination format
   3.288   * and rate, and initializes the 'cvt' structure with information needed
   3.289   * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   3.290   * to the other.
   3.291 - * This function returns 0, or -1 if there was an error.
   3.292 + *
   3.293 + * @return This function returns 0, or -1 if there was an error.
   3.294   */
   3.295  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
   3.296  		Uint16 src_format, Uint8 src_channels, int src_rate,
   3.297  		Uint16 dst_format, Uint8 dst_channels, int dst_rate);
   3.298  
   3.299 -/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   3.300 +/**
   3.301 + * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   3.302   * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
   3.303   * audio data in the source format, this function will convert it in-place
   3.304   * to the desired format.
   3.305 @@ -219,26 +246,30 @@
   3.306   */
   3.307  extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt);
   3.308  
   3.309 -/*
   3.310 +
   3.311 +#define SDL_MIX_MAXVOLUME 128
   3.312 +/**
   3.313   * This takes two audio buffers of the playing audio format and mixes
   3.314   * them, performing addition, volume adjustment, and overflow clipping.
   3.315   * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
   3.316   * for full audio volume.  Note this does not change hardware volume.
   3.317   * This is provided for convenience -- you can mix your own audio data.
   3.318   */
   3.319 -#define SDL_MIX_MAXVOLUME 128
   3.320  extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume);
   3.321  
   3.322 -/*
   3.323 +/**
   3.324 + * @name Audio Locks
   3.325   * The lock manipulated by these functions protects the callback function.
   3.326   * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   3.327   * callback function is not running.  Do not call these from the callback
   3.328   * function or you will cause deadlock.
   3.329   */
   3.330 +/*@{*/
   3.331  extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   3.332  extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   3.333 +/*@}*/
   3.334  
   3.335 -/*
   3.336 +/**
   3.337   * This function shuts down audio processing and closes the audio device.
   3.338   */
   3.339  extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
     4.1 --- a/include/SDL_byteorder.h	Mon Sep 21 09:27:08 2009 +0000
     4.2 +++ b/include/SDL_byteorder.h	Mon Sep 21 09:38:10 2009 +0000
     4.3 @@ -20,5 +20,10 @@
     4.4      slouken@libsdl.org
     4.5  */
     4.6  
     4.7 +/**
     4.8 + *  @file SDL_byteorder.h
     4.9 + *  @deprecated Use SDL_endian.h instead
    4.10 + */
    4.11 +
    4.12  /* DEPRECATED */
    4.13  #include "SDL_endian.h"
     5.1 --- a/include/SDL_cdrom.h	Mon Sep 21 09:27:08 2009 +0000
     5.2 +++ b/include/SDL_cdrom.h	Mon Sep 21 09:38:10 2009 +0000
     5.3 @@ -20,7 +20,10 @@
     5.4      slouken@libsdl.org
     5.5  */
     5.6  
     5.7 -/* This is the CD-audio control API for Simple DirectMedia Layer */
     5.8 +/**
     5.9 + *  @file SDL_cdrom.h
    5.10 + *  This is the CD-audio control API for Simple DirectMedia Layer
    5.11 + */
    5.12  
    5.13  #ifndef _SDL_cdrom_h
    5.14  #define _SDL_cdrom_h
    5.15 @@ -34,19 +37,25 @@
    5.16  extern "C" {
    5.17  #endif
    5.18  
    5.19 -/* In order to use these functions, SDL_Init() must have been called
    5.20 -   with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
    5.21 -   for CD-ROM drives, and load appropriate drivers.
    5.22 -*/
    5.23 +/**
    5.24 + *  @file SDL_cdrom.h
    5.25 + *  In order to use these functions, SDL_Init() must have been called
    5.26 + *  with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
    5.27 + *  for CD-ROM drives, and load appropriate drivers.
    5.28 + */
    5.29  
    5.30 -/* The maximum number of CD-ROM tracks on a disk */
    5.31 +/** The maximum number of CD-ROM tracks on a disk */
    5.32  #define SDL_MAX_TRACKS	99
    5.33  
    5.34 -/* The types of CD-ROM track possible */
    5.35 +/** @name Track Types
    5.36 + *  The types of CD-ROM track possible
    5.37 + */
    5.38 +/*@{*/
    5.39  #define SDL_AUDIO_TRACK	0x00
    5.40  #define SDL_DATA_TRACK	0x04
    5.41 +/*@}*/
    5.42  
    5.43 -/* The possible states which a CD-ROM drive can be in. */
    5.44 +/** The possible states which a CD-ROM drive can be in. */
    5.45  typedef enum {
    5.46  	CD_TRAYEMPTY,
    5.47  	CD_STOPPED,
    5.48 @@ -55,30 +64,35 @@
    5.49  	CD_ERROR = -1
    5.50  } CDstatus;
    5.51  
    5.52 -/* Given a status, returns true if there's a disk in the drive */
    5.53 +/** Given a status, returns true if there's a disk in the drive */
    5.54  #define CD_INDRIVE(status)	((int)(status) > 0)
    5.55  
    5.56  typedef struct SDL_CDtrack {
    5.57 -	Uint8 id;		/* Track number */
    5.58 -	Uint8 type;		/* Data or audio track */
    5.59 +	Uint8 id;		/**< Track number */
    5.60 +	Uint8 type;		/**< Data or audio track */
    5.61  	Uint16 unused;
    5.62 -	Uint32 length;		/* Length, in frames, of this track */
    5.63 -	Uint32 offset;		/* Offset, in frames, from start of disk */
    5.64 +	Uint32 length;		/**< Length, in frames, of this track */
    5.65 +	Uint32 offset;		/**< Offset, in frames, from start of disk */
    5.66  } SDL_CDtrack;
    5.67  
    5.68 -/* This structure is only current as of the last call to SDL_CDStatus() */
    5.69 +/** This structure is only current as of the last call to SDL_CDStatus() */
    5.70  typedef struct SDL_CD {
    5.71 -	int id;			/* Private drive identifier */
    5.72 -	CDstatus status;	/* Current drive status */
    5.73 +	int id;			/**< Private drive identifier */
    5.74 +	CDstatus status;	/**< Current drive status */
    5.75  
    5.76 -	/* The rest of this structure is only valid if there's a CD in drive */
    5.77 -	int numtracks;		/* Number of tracks on disk */
    5.78 -	int cur_track;		/* Current track position */
    5.79 -	int cur_frame;		/* Current frame offset within current track */
    5.80 +	/** The rest of this structure is only valid if there's a CD in drive */
    5.81 +        /*@{*/
    5.82 +	int numtracks;		/**< Number of tracks on disk */
    5.83 +	int cur_track;		/**< Current track position */
    5.84 +	int cur_frame;		/**< Current frame offset within current track */
    5.85  	SDL_CDtrack track[SDL_MAX_TRACKS+1];
    5.86 +        /*@}*/
    5.87  } SDL_CD;
    5.88  
    5.89 -/* Conversion functions from frames to Minute/Second/Frames and vice versa */
    5.90 +/** @name Frames / MSF Conversion Functions
    5.91 + *  Conversion functions from frames to Minute/Second/Frames and vice versa
    5.92 + */
    5.93 +/*@{*/
    5.94  #define CD_FPS	75
    5.95  #define FRAMES_TO_MSF(f, M,S,F)	{					\
    5.96  	int value = f;							\
    5.97 @@ -89,76 +103,93 @@
    5.98  	*(M) = value;							\
    5.99  }
   5.100  #define MSF_TO_FRAMES(M, S, F)	((M)*60*CD_FPS+(S)*CD_FPS+(F))
   5.101 +/*@}*/
   5.102  
   5.103  /* CD-audio API functions: */
   5.104  
   5.105 -/* Returns the number of CD-ROM drives on the system, or -1 if
   5.106 -   SDL_Init() has not been called with the SDL_INIT_CDROM flag.
   5.107 +/**
   5.108 + *  Returns the number of CD-ROM drives on the system, or -1 if
   5.109 + *  SDL_Init() has not been called with the SDL_INIT_CDROM flag.
   5.110   */
   5.111  extern DECLSPEC int SDLCALL SDL_CDNumDrives(void);
   5.112  
   5.113 -/* Returns a human-readable, system-dependent identifier for the CD-ROM.
   5.114 -   Example:
   5.115 -	"/dev/cdrom"
   5.116 -	"E:"
   5.117 -	"/dev/disk/ide/1/master"
   5.118 -*/
   5.119 +/**
   5.120 + *  Returns a human-readable, system-dependent identifier for the CD-ROM.
   5.121 + *  Example:
   5.122 + *   - "/dev/cdrom"
   5.123 + *   - "E:"
   5.124 + *   - "/dev/disk/ide/1/master"
   5.125 + */
   5.126  extern DECLSPEC const char * SDLCALL SDL_CDName(int drive);
   5.127  
   5.128 -/* Opens a CD-ROM drive for access.  It returns a drive handle on success,
   5.129 -   or NULL if the drive was invalid or busy.  This newly opened CD-ROM
   5.130 -   becomes the default CD used when other CD functions are passed a NULL
   5.131 -   CD-ROM handle.
   5.132 -   Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
   5.133 -*/
   5.134 +/**
   5.135 + *  Opens a CD-ROM drive for access.  It returns a drive handle on success,
   5.136 + *  or NULL if the drive was invalid or busy.  This newly opened CD-ROM
   5.137 + *  becomes the default CD used when other CD functions are passed a NULL
   5.138 + *  CD-ROM handle.
   5.139 + *  Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
   5.140 + */
   5.141  extern DECLSPEC SDL_CD * SDLCALL SDL_CDOpen(int drive);
   5.142  
   5.143 -/* This function returns the current status of the given drive.
   5.144 -   If the drive has a CD in it, the table of contents of the CD and current
   5.145 -   play position of the CD will be stored in the SDL_CD structure.
   5.146 -*/
   5.147 +/**
   5.148 + *  This function returns the current status of the given drive.
   5.149 + *  If the drive has a CD in it, the table of contents of the CD and current
   5.150 + *  play position of the CD will be stored in the SDL_CD structure.
   5.151 + */
   5.152  extern DECLSPEC CDstatus SDLCALL SDL_CDStatus(SDL_CD *cdrom);
   5.153  
   5.154 -/* Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
   5.155 -   tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
   5.156 -   until the end of the CD.  This function will skip data tracks.
   5.157 -   This function should only be called after calling SDL_CDStatus() to 
   5.158 -   get track information about the CD.
   5.159 -   For example:
   5.160 -	// Play entire CD:
   5.161 -	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
   5.162 -		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
   5.163 -	// Play last track:
   5.164 -	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
   5.165 -		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
   5.166 -	}
   5.167 -	// Play first and second track and 10 seconds of third track:
   5.168 -	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
   5.169 -		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
   5.170 -
   5.171 -   This function returns 0, or -1 if there was an error.
   5.172 -*/
   5.173 +/**
   5.174 + *  Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
   5.175 + *  tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
   5.176 + *  until the end of the CD.  This function will skip data tracks.
   5.177 + *  This function should only be called after calling SDL_CDStatus() to 
   5.178 + *  get track information about the CD.
   5.179 + *  For example:
   5.180 + *      @code
   5.181 + *	// Play entire CD:
   5.182 + *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
   5.183 + *		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
   5.184 + *	// Play last track:
   5.185 + *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
   5.186 + *		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
   5.187 + *	}
   5.188 + *	// Play first and second track and 10 seconds of third track:
   5.189 + *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
   5.190 + *		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
   5.191 + *      @endcode
   5.192 + *
   5.193 + *  @return This function returns 0, or -1 if there was an error.
   5.194 + */
   5.195  extern DECLSPEC int SDLCALL SDL_CDPlayTracks(SDL_CD *cdrom,
   5.196  		int start_track, int start_frame, int ntracks, int nframes);
   5.197  
   5.198 -/* Play the given CD starting at 'start' frame for 'length' frames.
   5.199 -   It returns 0, or -1 if there was an error.
   5.200 -*/
   5.201 +/**
   5.202 + *  Play the given CD starting at 'start' frame for 'length' frames.
   5.203 + *  @return It returns 0, or -1 if there was an error.
   5.204 + */
   5.205  extern DECLSPEC int SDLCALL SDL_CDPlay(SDL_CD *cdrom, int start, int length);
   5.206  
   5.207 -/* Pause play -- returns 0, or -1 on error */
   5.208 +/** Pause play
   5.209 + *  @return returns 0, or -1 on error
   5.210 + */
   5.211  extern DECLSPEC int SDLCALL SDL_CDPause(SDL_CD *cdrom);
   5.212  
   5.213 -/* Resume play -- returns 0, or -1 on error */
   5.214 +/** Resume play
   5.215 + *  @return returns 0, or -1 on error
   5.216 + */
   5.217  extern DECLSPEC int SDLCALL SDL_CDResume(SDL_CD *cdrom);
   5.218  
   5.219 -/* Stop play -- returns 0, or -1 on error */
   5.220 +/** Stop play
   5.221 + *  @return returns 0, or -1 on error
   5.222 + */
   5.223  extern DECLSPEC int SDLCALL SDL_CDStop(SDL_CD *cdrom);
   5.224  
   5.225 -/* Eject CD-ROM -- returns 0, or -1 on error */
   5.226 +/** Eject CD-ROM
   5.227 + *  @return returns 0, or -1 on error
   5.228 + */
   5.229  extern DECLSPEC int SDLCALL SDL_CDEject(SDL_CD *cdrom);
   5.230  
   5.231 -/* Closes the handle for the CD-ROM drive */
   5.232 +/** Closes the handle for the CD-ROM drive */
   5.233  extern DECLSPEC void SDLCALL SDL_CDClose(SDL_CD *cdrom);
   5.234  
   5.235  
     6.1 --- a/include/SDL_cpuinfo.h	Mon Sep 21 09:27:08 2009 +0000
     6.2 +++ b/include/SDL_cpuinfo.h	Mon Sep 21 09:38:10 2009 +0000
     6.3 @@ -20,8 +20,10 @@
     6.4      slouken@libsdl.org
     6.5  */
     6.6  
     6.7 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
     6.8 -/* CPU feature detection for SDL                                       */
     6.9 +/**
    6.10 + *  @file SDL_cpuinfo.h
    6.11 + *  CPU feature detection for SDL
    6.12 + */
    6.13  
    6.14  #ifndef _SDL_cpuinfo_h
    6.15  #define _SDL_cpuinfo_h
    6.16 @@ -34,36 +36,28 @@
    6.17  extern "C" {
    6.18  #endif
    6.19  
    6.20 -/* This function returns true if the CPU has the RDTSC instruction
    6.21 - */
    6.22 +/** This function returns true if the CPU has the RDTSC instruction */
    6.23  extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
    6.24  
    6.25 -/* This function returns true if the CPU has MMX features
    6.26 - */
    6.27 +/** This function returns true if the CPU has MMX features */
    6.28  extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
    6.29  
    6.30 -/* This function returns true if the CPU has MMX Ext. features
    6.31 - */
    6.32 +/** This function returns true if the CPU has MMX Ext. features */
    6.33  extern DECLSPEC SDL_bool SDLCALL SDL_HasMMXExt(void);
    6.34  
    6.35 -/* This function returns true if the CPU has 3DNow features
    6.36 - */
    6.37 +/** This function returns true if the CPU has 3DNow features */
    6.38  extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
    6.39  
    6.40 -/* This function returns true if the CPU has 3DNow! Ext. features
    6.41 - */
    6.42 +/** This function returns true if the CPU has 3DNow! Ext. features */
    6.43  extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNowExt(void);
    6.44  
    6.45 -/* This function returns true if the CPU has SSE features
    6.46 - */
    6.47 +/** This function returns true if the CPU has SSE features */
    6.48  extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
    6.49  
    6.50 -/* This function returns true if the CPU has SSE2 features
    6.51 - */
    6.52 +/** This function returns true if the CPU has SSE2 features */
    6.53  extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
    6.54  
    6.55 -/* This function returns true if the CPU has AltiVec features
    6.56 - */
    6.57 +/** This function returns true if the CPU has AltiVec features */
    6.58  extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
    6.59  
    6.60  /* Ends C function definitions when using C++ */
     7.1 --- a/include/SDL_endian.h	Mon Sep 21 09:27:08 2009 +0000
     7.2 +++ b/include/SDL_endian.h	Mon Sep 21 09:38:10 2009 +0000
     7.3 @@ -20,16 +20,23 @@
     7.4      slouken@libsdl.org
     7.5  */
     7.6  
     7.7 -/* Functions for reading and writing endian-specific values */
     7.8 +/**
     7.9 + *  @file SDL_endian.h
    7.10 + *  Functions for reading and writing endian-specific values
    7.11 + */
    7.12  
    7.13  #ifndef _SDL_endian_h
    7.14  #define _SDL_endian_h
    7.15  
    7.16  #include "SDL_stdinc.h"
    7.17  
    7.18 -/* The two types of endianness */
    7.19 +/** @name SDL_ENDIANs
    7.20 + *  The two types of endianness 
    7.21 + */
    7.22 +/*@{*/
    7.23  #define SDL_LIL_ENDIAN	1234
    7.24  #define SDL_BIG_ENDIAN	4321
    7.25 +/*@}*/
    7.26  
    7.27  #ifndef SDL_BYTEORDER	/* Not defined in SDL_config.h? */
    7.28  #if defined(__hppa__) || \
    7.29 @@ -50,11 +57,14 @@
    7.30  extern "C" {
    7.31  #endif
    7.32  
    7.33 -/* Use inline functions for compilers that support them, and static
    7.34 -   functions for those that do not.  Because these functions become
    7.35 -   static for compilers that do not support inline functions, this
    7.36 -   header should only be included in files that actually use them.
    7.37 -*/
    7.38 +/**
    7.39 + *  @name SDL_Swap Functions
    7.40 + *  Use inline functions for compilers that support them, and static
    7.41 + *  functions for those that do not.  Because these functions become
    7.42 + *  static for compilers that do not support inline functions, this
    7.43 + *  header should only be included in files that actually use them.
    7.44 + */
    7.45 +/*@{*/
    7.46  #if defined(__GNUC__) && defined(__i386__) && \
    7.47     !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
    7.48  static __inline__ Uint16 SDL_Swap16(Uint16 x)
    7.49 @@ -161,14 +171,18 @@
    7.50  #endif
    7.51  #else
    7.52  /* This is mainly to keep compilers from complaining in SDL code.
    7.53 -   If there is no real 64-bit datatype, then compilers will complain about
    7.54 -   the fake 64-bit datatype that SDL provides when it compiles user code.
    7.55 -*/
    7.56 + * If there is no real 64-bit datatype, then compilers will complain about
    7.57 + * the fake 64-bit datatype that SDL provides when it compiles user code.
    7.58 + */
    7.59  #define SDL_Swap64(X)	(X)
    7.60  #endif /* SDL_HAS_64BIT_TYPE */
    7.61 +/*@}*/
    7.62  
    7.63 -
    7.64 -/* Byteswap item from the specified endianness to the native endianness */
    7.65 +/**
    7.66 + *  @name SDL_SwapLE and SDL_SwapBE Functions
    7.67 + *  Byteswap item from the specified endianness to the native endianness
    7.68 + */
    7.69 +/*@{*/
    7.70  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
    7.71  #define SDL_SwapLE16(X)	(X)
    7.72  #define SDL_SwapLE32(X)	(X)
    7.73 @@ -184,6 +198,7 @@
    7.74  #define SDL_SwapBE32(X)	(X)
    7.75  #define SDL_SwapBE64(X)	(X)
    7.76  #endif
    7.77 +/*@}*/
    7.78  
    7.79  /* Ends C function definitions when using C++ */
    7.80  #ifdef __cplusplus
     8.1 --- a/include/SDL_error.h	Mon Sep 21 09:27:08 2009 +0000
     8.2 +++ b/include/SDL_error.h	Mon Sep 21 09:38:10 2009 +0000
     8.3 @@ -20,7 +20,10 @@
     8.4      slouken@libsdl.org
     8.5  */
     8.6  
     8.7 -/* Simple error message routines for SDL */
     8.8 +/**
     8.9 + *  @file SDL_error.h
    8.10 + *  Simple error message routines for SDL
    8.11 + */
    8.12  
    8.13  #ifndef _SDL_error_h
    8.14  #define _SDL_error_h
    8.15 @@ -33,12 +36,20 @@
    8.16  extern "C" {
    8.17  #endif
    8.18  
    8.19 -/* Public functions */
    8.20 +/** 
    8.21 + *  @name Public functions
    8.22 + */
    8.23 +/*@{*/
    8.24  extern DECLSPEC void SDLCALL SDL_SetError(const char *fmt, ...);
    8.25  extern DECLSPEC char * SDLCALL SDL_GetError(void);
    8.26  extern DECLSPEC void SDLCALL SDL_ClearError(void);
    8.27 +/*@}*/
    8.28  
    8.29 -/* Private error message function - used internally */
    8.30 +/**
    8.31 + *  @name Private functions
    8.32 + *  @internal Private error message function - used internally
    8.33 + */
    8.34 +/*@{*/
    8.35  #define SDL_OutOfMemory()	SDL_Error(SDL_ENOMEM)
    8.36  #define SDL_Unsupported()	SDL_Error(SDL_UNSUPPORTED)
    8.37  typedef enum {
    8.38 @@ -50,7 +61,7 @@
    8.39  	SDL_LASTERROR
    8.40  } SDL_errorcode;
    8.41  extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
    8.42 -
    8.43 +/*@}*/
    8.44  
    8.45  /* Ends C function definitions when using C++ */
    8.46  #ifdef __cplusplus
     9.1 --- a/include/SDL_events.h	Mon Sep 21 09:27:08 2009 +0000
     9.2 +++ b/include/SDL_events.h	Mon Sep 21 09:38:10 2009 +0000
     9.3 @@ -20,7 +20,10 @@
     9.4      slouken@libsdl.org
     9.5  */
     9.6  
     9.7 -/* Include file for SDL event handling */
     9.8 +/**
     9.9 + *  @file SDL_events.h
    9.10 + *  Include file for SDL event handling
    9.11 + */
    9.12  
    9.13  #ifndef _SDL_events_h
    9.14  #define _SDL_events_h
    9.15 @@ -39,45 +42,48 @@
    9.16  extern "C" {
    9.17  #endif
    9.18  
    9.19 -/* General keyboard/mouse state definitions */
    9.20 +/** @name General keyboard/mouse state definitions */
    9.21 +/*@{*/
    9.22  #define SDL_RELEASED	0
    9.23  #define SDL_PRESSED	1
    9.24 +/*@}*/
    9.25  
    9.26 -/* Event enumerations */
    9.27 +/** Event enumerations */
    9.28  typedef enum {
    9.29 -       SDL_NOEVENT = 0,			/* Unused (do not remove) */
    9.30 -       SDL_ACTIVEEVENT,			/* Application loses/gains visibility */
    9.31 -       SDL_KEYDOWN,			/* Keys pressed */
    9.32 -       SDL_KEYUP,			/* Keys released */
    9.33 -       SDL_MOUSEMOTION,			/* Mouse moved */
    9.34 -       SDL_MOUSEBUTTONDOWN,		/* Mouse button pressed */
    9.35 -       SDL_MOUSEBUTTONUP,		/* Mouse button released */
    9.36 -       SDL_JOYAXISMOTION,		/* Joystick axis motion */
    9.37 -       SDL_JOYBALLMOTION,		/* Joystick trackball motion */
    9.38 -       SDL_JOYHATMOTION,		/* Joystick hat position change */
    9.39 -       SDL_JOYBUTTONDOWN,		/* Joystick button pressed */
    9.40 -       SDL_JOYBUTTONUP,			/* Joystick button released */
    9.41 -       SDL_QUIT,			/* User-requested quit */
    9.42 -       SDL_SYSWMEVENT,			/* System specific event */
    9.43 -       SDL_EVENT_RESERVEDA,		/* Reserved for future use.. */
    9.44 -       SDL_EVENT_RESERVEDB,		/* Reserved for future use.. */
    9.45 -       SDL_VIDEORESIZE,			/* User resized video mode */
    9.46 -       SDL_VIDEOEXPOSE,			/* Screen needs to be redrawn */
    9.47 -       SDL_EVENT_RESERVED2,		/* Reserved for future use.. */
    9.48 -       SDL_EVENT_RESERVED3,		/* Reserved for future use.. */
    9.49 -       SDL_EVENT_RESERVED4,		/* Reserved for future use.. */
    9.50 -       SDL_EVENT_RESERVED5,		/* Reserved for future use.. */
    9.51 -       SDL_EVENT_RESERVED6,		/* Reserved for future use.. */
    9.52 -       SDL_EVENT_RESERVED7,		/* Reserved for future use.. */
    9.53 -       /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
    9.54 +       SDL_NOEVENT = 0,			/**< Unused (do not remove) */
    9.55 +       SDL_ACTIVEEVENT,			/**< Application loses/gains visibility */
    9.56 +       SDL_KEYDOWN,			/**< Keys pressed */
    9.57 +       SDL_KEYUP,			/**< Keys released */
    9.58 +       SDL_MOUSEMOTION,			/**< Mouse moved */
    9.59 +       SDL_MOUSEBUTTONDOWN,		/**< Mouse button pressed */
    9.60 +       SDL_MOUSEBUTTONUP,		/**< Mouse button released */
    9.61 +       SDL_JOYAXISMOTION,		/**< Joystick axis motion */
    9.62 +       SDL_JOYBALLMOTION,		/**< Joystick trackball motion */
    9.63 +       SDL_JOYHATMOTION,		/**< Joystick hat position change */
    9.64 +       SDL_JOYBUTTONDOWN,		/**< Joystick button pressed */
    9.65 +       SDL_JOYBUTTONUP,			/**< Joystick button released */
    9.66 +       SDL_QUIT,			/**< User-requested quit */
    9.67 +       SDL_SYSWMEVENT,			/**< System specific event */
    9.68 +       SDL_EVENT_RESERVEDA,		/**< Reserved for future use.. */
    9.69 +       SDL_EVENT_RESERVEDB,		/**< Reserved for future use.. */
    9.70 +       SDL_VIDEORESIZE,			/**< User resized video mode */
    9.71 +       SDL_VIDEOEXPOSE,			/**< Screen needs to be redrawn */
    9.72 +       SDL_EVENT_RESERVED2,		/**< Reserved for future use.. */
    9.73 +       SDL_EVENT_RESERVED3,		/**< Reserved for future use.. */
    9.74 +       SDL_EVENT_RESERVED4,		/**< Reserved for future use.. */
    9.75 +       SDL_EVENT_RESERVED5,		/**< Reserved for future use.. */
    9.76 +       SDL_EVENT_RESERVED6,		/**< Reserved for future use.. */
    9.77 +       SDL_EVENT_RESERVED7,		/**< Reserved for future use.. */
    9.78 +       /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
    9.79         SDL_USEREVENT = 24,
    9.80 -       /* This last event is only for bounding internal arrays
    9.81 -	  It is the number of bits in the event mask datatype -- Uint32
    9.82 +       /** This last event is only for bounding internal arrays
    9.83 +	*  It is the number of bits in the event mask datatype -- Uint32
    9.84          */
    9.85         SDL_NUMEVENTS = 32
    9.86  } SDL_EventType;
    9.87  
    9.88 -/* Predefined event masks */
    9.89 +/** @name Predefined event masks */
    9.90 +/*@{*/
    9.91  #define SDL_EVENTMASK(X)	(1<<(X))
    9.92  typedef enum {
    9.93  	SDL_ACTIVEEVENTMASK	= SDL_EVENTMASK(SDL_ACTIVEEVENT),
    9.94 @@ -107,108 +113,109 @@
    9.95  	SDL_SYSWMEVENTMASK	= SDL_EVENTMASK(SDL_SYSWMEVENT)
    9.96  } SDL_EventMask ;
    9.97  #define SDL_ALLEVENTS		0xFFFFFFFF
    9.98 +/*@}*/
    9.99  
   9.100 -/* Application visibility event structure */
   9.101 +/** Application visibility event structure */
   9.102  typedef struct SDL_ActiveEvent {
   9.103 -	Uint8 type;	/* SDL_ACTIVEEVENT */
   9.104 -	Uint8 gain;	/* Whether given states were gained or lost (1/0) */
   9.105 -	Uint8 state;	/* A mask of the focus states */
   9.106 +	Uint8 type;	/**< SDL_ACTIVEEVENT */
   9.107 +	Uint8 gain;	/**< Whether given states were gained or lost (1/0) */
   9.108 +	Uint8 state;	/**< A mask of the focus states */
   9.109  } SDL_ActiveEvent;
   9.110  
   9.111 -/* Keyboard event structure */
   9.112 +/** Keyboard event structure */
   9.113  typedef struct SDL_KeyboardEvent {
   9.114 -	Uint8 type;	/* SDL_KEYDOWN or SDL_KEYUP */
   9.115 -	Uint8 which;	/* The keyboard device index */
   9.116 -	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
   9.117 +	Uint8 type;	/**< SDL_KEYDOWN or SDL_KEYUP */
   9.118 +	Uint8 which;	/**< The keyboard device index */
   9.119 +	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
   9.120  	SDL_keysym keysym;
   9.121  } SDL_KeyboardEvent;
   9.122  
   9.123 -/* Mouse motion event structure */
   9.124 +/** Mouse motion event structure */
   9.125  typedef struct SDL_MouseMotionEvent {
   9.126 -	Uint8 type;	/* SDL_MOUSEMOTION */
   9.127 -	Uint8 which;	/* The mouse device index */
   9.128 -	Uint8 state;	/* The current button state */
   9.129 -	Uint16 x, y;	/* The X/Y coordinates of the mouse */
   9.130 -	Sint16 xrel;	/* The relative motion in the X direction */
   9.131 -	Sint16 yrel;	/* The relative motion in the Y direction */
   9.132 +	Uint8 type;	/**< SDL_MOUSEMOTION */
   9.133 +	Uint8 which;	/**< The mouse device index */
   9.134 +	Uint8 state;	/**< The current button state */
   9.135 +	Uint16 x, y;	/**< The X/Y coordinates of the mouse */
   9.136 +	Sint16 xrel;	/**< The relative motion in the X direction */
   9.137 +	Sint16 yrel;	/**< The relative motion in the Y direction */
   9.138  } SDL_MouseMotionEvent;
   9.139  
   9.140 -/* Mouse button event structure */
   9.141 +/** Mouse button event structure */
   9.142  typedef struct SDL_MouseButtonEvent {
   9.143 -	Uint8 type;	/* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
   9.144 -	Uint8 which;	/* The mouse device index */
   9.145 -	Uint8 button;	/* The mouse button index */
   9.146 -	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
   9.147 -	Uint16 x, y;	/* The X/Y coordinates of the mouse at press time */
   9.148 +	Uint8 type;	/**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
   9.149 +	Uint8 which;	/**< The mouse device index */
   9.150 +	Uint8 button;	/**< The mouse button index */
   9.151 +	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
   9.152 +	Uint16 x, y;	/**< The X/Y coordinates of the mouse at press time */
   9.153  } SDL_MouseButtonEvent;
   9.154  
   9.155 -/* Joystick axis motion event structure */
   9.156 +/** Joystick axis motion event structure */
   9.157  typedef struct SDL_JoyAxisEvent {
   9.158 -	Uint8 type;	/* SDL_JOYAXISMOTION */
   9.159 -	Uint8 which;	/* The joystick device index */
   9.160 -	Uint8 axis;	/* The joystick axis index */
   9.161 -	Sint16 value;	/* The axis value (range: -32768 to 32767) */
   9.162 +	Uint8 type;	/**< SDL_JOYAXISMOTION */
   9.163 +	Uint8 which;	/**< The joystick device index */
   9.164 +	Uint8 axis;	/**< The joystick axis index */
   9.165 +	Sint16 value;	/**< The axis value (range: -32768 to 32767) */
   9.166  } SDL_JoyAxisEvent;
   9.167  
   9.168 -/* Joystick trackball motion event structure */
   9.169 +/** Joystick trackball motion event structure */
   9.170  typedef struct SDL_JoyBallEvent {
   9.171 -	Uint8 type;	/* SDL_JOYBALLMOTION */
   9.172 -	Uint8 which;	/* The joystick device index */
   9.173 -	Uint8 ball;	/* The joystick trackball index */
   9.174 -	Sint16 xrel;	/* The relative motion in the X direction */
   9.175 -	Sint16 yrel;	/* The relative motion in the Y direction */
   9.176 +	Uint8 type;	/**< SDL_JOYBALLMOTION */
   9.177 +	Uint8 which;	/**< The joystick device index */
   9.178 +	Uint8 ball;	/**< The joystick trackball index */
   9.179 +	Sint16 xrel;	/**< The relative motion in the X direction */
   9.180 +	Sint16 yrel;	/**< The relative motion in the Y direction */
   9.181  } SDL_JoyBallEvent;
   9.182  
   9.183 -/* Joystick hat position change event structure */
   9.184 +/** Joystick hat position change event structure */
   9.185  typedef struct SDL_JoyHatEvent {
   9.186 -	Uint8 type;	/* SDL_JOYHATMOTION */
   9.187 -	Uint8 which;	/* The joystick device index */
   9.188 -	Uint8 hat;	/* The joystick hat index */
   9.189 -	Uint8 value;	/* The hat position value:
   9.190 -			    SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
   9.191 -			    SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
   9.192 -			    SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
   9.193 -			   Note that zero means the POV is centered.
   9.194 -			*/
   9.195 +	Uint8 type;	/**< SDL_JOYHATMOTION */
   9.196 +	Uint8 which;	/**< The joystick device index */
   9.197 +	Uint8 hat;	/**< The joystick hat index */
   9.198 +	Uint8 value;	/**< The hat position value:
   9.199 +			 *   SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
   9.200 +			 *   SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
   9.201 +			 *   SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
   9.202 +			 *  Note that zero means the POV is centered.
   9.203 +			 */
   9.204  } SDL_JoyHatEvent;
   9.205  
   9.206 -/* Joystick button event structure */
   9.207 +/** Joystick button event structure */
   9.208  typedef struct SDL_JoyButtonEvent {
   9.209 -	Uint8 type;	/* SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
   9.210 -	Uint8 which;	/* The joystick device index */
   9.211 -	Uint8 button;	/* The joystick button index */
   9.212 -	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
   9.213 +	Uint8 type;	/**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
   9.214 +	Uint8 which;	/**< The joystick device index */
   9.215 +	Uint8 button;	/**< The joystick button index */
   9.216 +	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
   9.217  } SDL_JoyButtonEvent;
   9.218  
   9.219 -/* The "window resized" event
   9.220 -   When you get this event, you are responsible for setting a new video
   9.221 -   mode with the new width and height.
   9.222 +/** The "window resized" event
   9.223 + *  When you get this event, you are responsible for setting a new video
   9.224 + *  mode with the new width and height.
   9.225   */
   9.226  typedef struct SDL_ResizeEvent {
   9.227 -	Uint8 type;	/* SDL_VIDEORESIZE */
   9.228 -	int w;		/* New width */
   9.229 -	int h;		/* New height */
   9.230 +	Uint8 type;	/**< SDL_VIDEORESIZE */
   9.231 +	int w;		/**< New width */
   9.232 +	int h;		/**< New height */
   9.233  } SDL_ResizeEvent;
   9.234  
   9.235 -/* The "screen redraw" event */
   9.236 +/** The "screen redraw" event */
   9.237  typedef struct SDL_ExposeEvent {
   9.238 -	Uint8 type;	/* SDL_VIDEOEXPOSE */
   9.239 +	Uint8 type;	/**< SDL_VIDEOEXPOSE */
   9.240  } SDL_ExposeEvent;
   9.241  
   9.242 -/* The "quit requested" event */
   9.243 +/** The "quit requested" event */
   9.244  typedef struct SDL_QuitEvent {
   9.245 -	Uint8 type;	/* SDL_QUIT */
   9.246 +	Uint8 type;	/**< SDL_QUIT */
   9.247  } SDL_QuitEvent;
   9.248  
   9.249 -/* A user-defined event type */
   9.250 +/** A user-defined event type */
   9.251  typedef struct SDL_UserEvent {
   9.252 -	Uint8 type;	/* SDL_USEREVENT through SDL_NUMEVENTS-1 */
   9.253 -	int code;	/* User defined event code */
   9.254 -	void *data1;	/* User defined data pointer */
   9.255 -	void *data2;	/* User defined data pointer */
   9.256 +	Uint8 type;	/**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
   9.257 +	int code;	/**< User defined event code */
   9.258 +	void *data1;	/**< User defined data pointer */
   9.259 +	void *data2;	/**< User defined data pointer */
   9.260  } SDL_UserEvent;
   9.261  
   9.262 -/* If you want to use this event, you should include SDL_syswm.h */
   9.263 +/** If you want to use this event, you should include SDL_syswm.h */
   9.264  struct SDL_SysWMmsg;
   9.265  typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   9.266  typedef struct SDL_SysWMEvent {
   9.267 @@ -216,7 +223,7 @@
   9.268  	SDL_SysWMmsg *msg;
   9.269  } SDL_SysWMEvent;
   9.270  
   9.271 -/* General event structure */
   9.272 +/** General event structure */
   9.273  typedef union SDL_Event {
   9.274  	Uint8 type;
   9.275  	SDL_ActiveEvent active;
   9.276 @@ -237,97 +244,109 @@
   9.277  
   9.278  /* Function prototypes */
   9.279  
   9.280 -/* Pumps the event loop, gathering events from the input devices.
   9.281 -   This function updates the event queue and internal input device state.
   9.282 -   This should only be run in the thread that sets the video mode.
   9.283 -*/
   9.284 +/** Pumps the event loop, gathering events from the input devices.
   9.285 + *  This function updates the event queue and internal input device state.
   9.286 + *  This should only be run in the thread that sets the video mode.
   9.287 + */
   9.288  extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   9.289  
   9.290 -/* Checks the event queue for messages and optionally returns them.
   9.291 -   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   9.292 -   the back of the event queue.
   9.293 -   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   9.294 -   of the event queue, matching 'mask', will be returned and will not
   9.295 -   be removed from the queue.
   9.296 -   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   9.297 -   of the event queue, matching 'mask', will be returned and will be
   9.298 -   removed from the queue.
   9.299 -   This function returns the number of events actually stored, or -1
   9.300 -   if there was an error.  This function is thread-safe.
   9.301 -*/
   9.302  typedef enum {
   9.303  	SDL_ADDEVENT,
   9.304  	SDL_PEEKEVENT,
   9.305  	SDL_GETEVENT
   9.306  } SDL_eventaction;
   9.307 -/* */
   9.308 +
   9.309 +/**
   9.310 + *  Checks the event queue for messages and optionally returns them.
   9.311 + *
   9.312 + *  If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   9.313 + *  the back of the event queue.
   9.314 + *  If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   9.315 + *  of the event queue, matching 'mask', will be returned and will not
   9.316 + *  be removed from the queue.
   9.317 + *  If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   9.318 + *  of the event queue, matching 'mask', will be returned and will be
   9.319 + *  removed from the queue.
   9.320 + *
   9.321 + *  @return
   9.322 + *  This function returns the number of events actually stored, or -1
   9.323 + *  if there was an error.
   9.324 + *
   9.325 + *  This function is thread-safe.
   9.326 + */
   9.327  extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
   9.328  				SDL_eventaction action, Uint32 mask);
   9.329  
   9.330 -/* Polls for currently pending events, and returns 1 if there are any pending
   9.331 -   events, or 0 if there are none available.  If 'event' is not NULL, the next
   9.332 -   event is removed from the queue and stored in that area.
   9.333 +/** Polls for currently pending events, and returns 1 if there are any pending
   9.334 + *  events, or 0 if there are none available.  If 'event' is not NULL, the next
   9.335 + *  event is removed from the queue and stored in that area.
   9.336   */
   9.337  extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
   9.338  
   9.339 -/* Waits indefinitely for the next available event, returning 1, or 0 if there
   9.340 -   was an error while waiting for events.  If 'event' is not NULL, the next
   9.341 -   event is removed from the queue and stored in that area.
   9.342 +/** Waits indefinitely for the next available event, returning 1, or 0 if there
   9.343 + *  was an error while waiting for events.  If 'event' is not NULL, the next
   9.344 + *  event is removed from the queue and stored in that area.
   9.345   */
   9.346  extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
   9.347  
   9.348 -/* Add an event to the event queue.
   9.349 -   This function returns 0 on success, or -1 if the event queue was full
   9.350 -   or there was some other error.
   9.351 +/** Add an event to the event queue.
   9.352 + *  This function returns 0 on success, or -1 if the event queue was full
   9.353 + *  or there was some other error.
   9.354   */
   9.355  extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
   9.356  
   9.357 -/*
   9.358 -  This function sets up a filter to process all events before they
   9.359 -  change internal state and are posted to the internal event queue.
   9.360 -
   9.361 -  The filter is protypted as:
   9.362 -*/
   9.363 +/** @name Event Filtering */
   9.364 +/*@{*/
   9.365  typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
   9.366 -/*
   9.367 -  If the filter returns 1, then the event will be added to the internal queue.
   9.368 -  If it returns 0, then the event will be dropped from the queue, but the 
   9.369 -  internal state will still be updated.  This allows selective filtering of
   9.370 -  dynamically arriving events.
   9.371 -
   9.372 -  WARNING:  Be very careful of what you do in the event filter function, as 
   9.373 -            it may run in a different thread!
   9.374 -
   9.375 -  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   9.376 -  event filter is only called when the window manager desires to close the
   9.377 -  application window.  If the event filter returns 1, then the window will
   9.378 -  be closed, otherwise the window will remain open if possible.
   9.379 -  If the quit event is generated by an interrupt signal, it will bypass the
   9.380 -  internal queue and be delivered to the application at the next event poll.
   9.381 -*/
   9.382 +/**
   9.383 + *  This function sets up a filter to process all events before they
   9.384 + *  change internal state and are posted to the internal event queue.
   9.385 + *
   9.386 + *  The filter is protypted as:
   9.387 + *      @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode
   9.388 + *
   9.389 + * If the filter returns 1, then the event will be added to the internal queue.
   9.390 + * If it returns 0, then the event will be dropped from the queue, but the 
   9.391 + * internal state will still be updated.  This allows selective filtering of
   9.392 + * dynamically arriving events.
   9.393 + *
   9.394 + * @warning  Be very careful of what you do in the event filter function, as 
   9.395 + *           it may run in a different thread!
   9.396 + *
   9.397 + * There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   9.398 + * event filter is only called when the window manager desires to close the
   9.399 + * application window.  If the event filter returns 1, then the window will
   9.400 + * be closed, otherwise the window will remain open if possible.
   9.401 + * If the quit event is generated by an interrupt signal, it will bypass the
   9.402 + * internal queue and be delivered to the application at the next event poll.
   9.403 + */
   9.404  extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
   9.405  
   9.406 -/*
   9.407 -  Return the current event filter - can be used to "chain" filters.
   9.408 -  If there is no event filter set, this function returns NULL.
   9.409 -*/
   9.410 +/**
   9.411 + *  Return the current event filter - can be used to "chain" filters.
   9.412 + *  If there is no event filter set, this function returns NULL.
   9.413 + */
   9.414  extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
   9.415 +/*@}*/
   9.416  
   9.417 -/*
   9.418 -  This function allows you to set the state of processing certain events.
   9.419 -  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   9.420 -  from the event queue and will not event be filtered.
   9.421 -  If 'state' is set to SDL_ENABLE, that event will be processed normally.
   9.422 -  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   9.423 -  current processing state of the specified event.
   9.424 -*/
   9.425 +/** @name Event State */
   9.426 +/*@{*/
   9.427  #define SDL_QUERY	-1
   9.428  #define SDL_IGNORE	 0
   9.429  #define SDL_DISABLE	 0
   9.430  #define SDL_ENABLE	 1
   9.431 +/*@}*/
   9.432 +
   9.433 +/**
   9.434 +* This function allows you to set the state of processing certain events.
   9.435 +* If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   9.436 +* from the event queue and will not event be filtered.
   9.437 +* If 'state' is set to SDL_ENABLE, that event will be processed normally.
   9.438 +* If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   9.439 +* current processing state of the specified event.
   9.440 +*/
   9.441  extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
   9.442  
   9.443 -
   9.444  /* Ends C function definitions when using C++ */
   9.445  #ifdef __cplusplus
   9.446  }
    10.1 --- a/include/SDL_getenv.h	Mon Sep 21 09:27:08 2009 +0000
    10.2 +++ b/include/SDL_getenv.h	Mon Sep 21 09:38:10 2009 +0000
    10.3 @@ -20,5 +20,9 @@
    10.4      slouken@libsdl.org
    10.5  */
    10.6  
    10.7 +/** @file SDL_getenv.h
    10.8 + *  @deprecated Use SDL_stdinc.h instead
    10.9 + */
   10.10 +
   10.11  /* DEPRECATED */
   10.12  #include "SDL_stdinc.h"
    11.1 --- a/include/SDL_joystick.h	Mon Sep 21 09:27:08 2009 +0000
    11.2 +++ b/include/SDL_joystick.h	Mon Sep 21 09:38:10 2009 +0000
    11.3 @@ -20,7 +20,9 @@
    11.4      slouken@libsdl.org
    11.5  */
    11.6  
    11.7 -/* Include file for SDL joystick event handling */
    11.8 +/** @file SDL_joystick.h
    11.9 + *  Include file for SDL joystick event handling
   11.10 + */
   11.11  
   11.12  #ifndef _SDL_joystick_h
   11.13  #define _SDL_joystick_h
   11.14 @@ -34,97 +36,108 @@
   11.15  extern "C" {
   11.16  #endif
   11.17  
   11.18 -/* In order to use these functions, SDL_Init() must have been called
   11.19 -   with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
   11.20 -   for joysticks, and load appropriate drivers.
   11.21 -*/
   11.22 +/** @file SDL_joystick.h
   11.23 + *  @note In order to use these functions, SDL_Init() must have been called
   11.24 + *        with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
   11.25 + *        for joysticks, and load appropriate drivers.
   11.26 + */
   11.27  
   11.28 -/* The joystick structure used to identify an SDL joystick */
   11.29 +/** The joystick structure used to identify an SDL joystick */
   11.30  struct _SDL_Joystick;
   11.31  typedef struct _SDL_Joystick SDL_Joystick;
   11.32  
   11.33 -
   11.34  /* Function prototypes */
   11.35 -/*
   11.36 +/**
   11.37   * Count the number of joysticks attached to the system
   11.38   */
   11.39  extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
   11.40  
   11.41 -/*
   11.42 +/**
   11.43   * Get the implementation dependent name of a joystick.
   11.44 + *
   11.45   * This can be called before any joysticks are opened.
   11.46   * If no name can be found, this function returns NULL.
   11.47   */
   11.48  extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index);
   11.49  
   11.50 -/*
   11.51 - * Open a joystick for use - the index passed as an argument refers to
   11.52 +/**
   11.53 + * Open a joystick for use.
   11.54 + *
   11.55 + * @param[in] device_index
   11.56 + * The index passed as an argument refers to
   11.57   * the N'th joystick on the system.  This index is the value which will
   11.58   * identify this joystick in future joystick events.
   11.59   *
   11.60 - * This function returns a joystick identifier, or NULL if an error occurred.
   11.61 + * @return This function returns a joystick identifier, or NULL if an error occurred.
   11.62   */
   11.63  extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index);
   11.64  
   11.65 -/*
   11.66 +/**
   11.67   * Returns 1 if the joystick has been opened, or 0 if it has not.
   11.68   */
   11.69  extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
   11.70  
   11.71 -/*
   11.72 +/**
   11.73   * Get the device index of an opened joystick.
   11.74   */
   11.75  extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick);
   11.76  
   11.77 -/*
   11.78 +/**
   11.79   * Get the number of general axis controls on a joystick
   11.80   */
   11.81  extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
   11.82  
   11.83 -/*
   11.84 +/**
   11.85   * Get the number of trackballs on a joystick
   11.86 + *
   11.87   * Joystick trackballs have only relative motion events associated
   11.88   * with them and their state cannot be polled.
   11.89   */
   11.90  extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
   11.91  
   11.92 -/*
   11.93 +/**
   11.94   * Get the number of POV hats on a joystick
   11.95   */
   11.96  extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
   11.97  
   11.98 -/*
   11.99 +/**
  11.100   * Get the number of buttons on a joystick
  11.101   */
  11.102  extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
  11.103  
  11.104 -/*
  11.105 +/**
  11.106   * Update the current state of the open joysticks.
  11.107 + *
  11.108   * This is called automatically by the event loop if any joystick
  11.109   * events are enabled.
  11.110   */
  11.111  extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
  11.112  
  11.113 -/*
  11.114 +/**
  11.115   * Enable/disable joystick event polling.
  11.116 + *
  11.117   * If joystick events are disabled, you must call SDL_JoystickUpdate()
  11.118   * yourself and check the state of the joystick when you want joystick
  11.119   * information.
  11.120 - * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
  11.121 + *
  11.122 + * @param[in] state The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
  11.123   */
  11.124  extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
  11.125  
  11.126 -/*
  11.127 +/**
  11.128   * Get the current state of an axis control on a joystick
  11.129 - * The state is a value ranging from -32768 to 32767.
  11.130 - * The axis indices start at index 0.
  11.131 + *
  11.132 + * @param[in] axis The axis indices start at index 0.
  11.133 + *
  11.134 + * @return The state is a value ranging from -32768 to 32767.
  11.135   */
  11.136  extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis);
  11.137  
  11.138 -/*
  11.139 - * Get the current state of a POV hat on a joystick
  11.140 - * The return value is one of the following positions:
  11.141 +/**
  11.142 + *  @name Hat Positions
  11.143 + *  The return value of SDL_JoystickGetHat() is one of the following positions:
  11.144   */
  11.145 +/*@{*/
  11.146  #define SDL_HAT_CENTERED	0x00
  11.147  #define SDL_HAT_UP		0x01
  11.148  #define SDL_HAT_RIGHT		0x02
  11.149 @@ -134,25 +147,32 @@
  11.150  #define SDL_HAT_RIGHTDOWN	(SDL_HAT_RIGHT|SDL_HAT_DOWN)
  11.151  #define SDL_HAT_LEFTUP		(SDL_HAT_LEFT|SDL_HAT_UP)
  11.152  #define SDL_HAT_LEFTDOWN	(SDL_HAT_LEFT|SDL_HAT_DOWN)
  11.153 -/*
  11.154 - * The hat indices start at index 0.
  11.155 +/*@}*/
  11.156 +
  11.157 +/** 
  11.158 + *  Get the current state of a POV hat on a joystick
  11.159 + *
  11.160 + *  @param[in] hat The hat indices start at index 0.
  11.161   */
  11.162  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat);
  11.163  
  11.164 -/*
  11.165 +/**
  11.166   * Get the ball axis change since the last poll
  11.167 - * This returns 0, or -1 if you passed it invalid parameters.
  11.168 - * The ball indices start at index 0.
  11.169 + *
  11.170 + * @param[in] ball The ball indices start at index 0.
  11.171 + *
  11.172 + * @return This returns 0, or -1 if you passed it invalid parameters.
  11.173   */
  11.174  extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
  11.175  
  11.176 -/*
  11.177 +/**
  11.178   * Get the current state of a button on a joystick
  11.179 - * The button indices start at index 0.
  11.180 + *
  11.181 + * @param[in] button The button indices start at index 0.
  11.182   */
  11.183  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button);
  11.184  
  11.185 -/*
  11.186 +/**
  11.187   * Close a joystick previously opened with SDL_JoystickOpen()
  11.188   */
  11.189  extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
    12.1 --- a/include/SDL_keyboard.h	Mon Sep 21 09:27:08 2009 +0000
    12.2 +++ b/include/SDL_keyboard.h	Mon Sep 21 09:38:10 2009 +0000
    12.3 @@ -20,7 +20,9 @@
    12.4      slouken@libsdl.org
    12.5  */
    12.6  
    12.7 -/* Include file for SDL keyboard event handling */
    12.8 +/** @file SDL_keyboard.h
    12.9 + *  Include file for SDL keyboard event handling
   12.10 + */
   12.11  
   12.12  #ifndef _SDL_keyboard_h
   12.13  #define _SDL_keyboard_h
   12.14 @@ -35,78 +37,90 @@
   12.15  extern "C" {
   12.16  #endif
   12.17  
   12.18 -/* Keysym structure
   12.19 -   - The scancode is hardware dependent, and should not be used by general
   12.20 -     applications.  If no hardware scancode is available, it will be 0.
   12.21 -
   12.22 -   - The 'unicode' translated character is only available when character
   12.23 -     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
   12.24 -     this is a UNICODE character corresponding to the keypress.  If the
   12.25 -     high 9 bits of the character are 0, then this maps to the equivalent
   12.26 -     ASCII character:
   12.27 -	char ch;
   12.28 -	if ( (keysym.unicode & 0xFF80) == 0 ) {
   12.29 -		ch = keysym.unicode & 0x7F;
   12.30 -	} else {
   12.31 -		An international character..
   12.32 -	}
   12.33 +/** Keysym structure
   12.34 + *
   12.35 + *  - The scancode is hardware dependent, and should not be used by general
   12.36 + *    applications.  If no hardware scancode is available, it will be 0.
   12.37 + *
   12.38 + *  - The 'unicode' translated character is only available when character
   12.39 + *    translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
   12.40 + *    this is a UNICODE character corresponding to the keypress.  If the
   12.41 + *    high 9 bits of the character are 0, then this maps to the equivalent
   12.42 + *    ASCII character:
   12.43 + *      @code
   12.44 + *	char ch;
   12.45 + *	if ( (keysym.unicode & 0xFF80) == 0 ) {
   12.46 + *		ch = keysym.unicode & 0x7F;
   12.47 + *	} else {
   12.48 + *		An international character..
   12.49 + *	}
   12.50 + *      @endcode
   12.51   */
   12.52  typedef struct SDL_keysym {
   12.53 -	Uint8 scancode;			/* hardware specific scancode */
   12.54 -	SDLKey sym;			/* SDL virtual keysym */
   12.55 -	SDLMod mod;			/* current key modifiers */
   12.56 -	Uint16 unicode;			/* translated character */
   12.57 +	Uint8 scancode;			/**< hardware specific scancode */
   12.58 +	SDLKey sym;			/**< SDL virtual keysym */
   12.59 +	SDLMod mod;			/**< current key modifiers */
   12.60 +	Uint16 unicode;			/**< translated character */
   12.61  } SDL_keysym;
   12.62  
   12.63 -/* This is the mask which refers to all hotkey bindings */
   12.64 +/** This is the mask which refers to all hotkey bindings */
   12.65  #define SDL_ALL_HOTKEYS		0xFFFFFFFF
   12.66  
   12.67  /* Function prototypes */
   12.68 -/*
   12.69 +/**
   12.70   * Enable/Disable UNICODE translation of keyboard input.
   12.71 + *
   12.72   * This translation has some overhead, so translation defaults off.
   12.73 + *
   12.74 + * @param[in] enable
   12.75   * If 'enable' is 1, translation is enabled.
   12.76   * If 'enable' is 0, translation is disabled.
   12.77   * If 'enable' is -1, the translation state is not changed.
   12.78 - * It returns the previous state of keyboard translation.
   12.79 + *
   12.80 + * @return It returns the previous state of keyboard translation.
   12.81   */
   12.82  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
   12.83  
   12.84 -/*
   12.85 - * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
   12.86 - * 'delay' is the initial delay in ms between the time when a key is
   12.87 - * pressed, and keyboard repeat begins.
   12.88 - * 'interval' is the time in ms between keyboard repeat events.
   12.89 - */
   12.90  #define SDL_DEFAULT_REPEAT_DELAY	500
   12.91  #define SDL_DEFAULT_REPEAT_INTERVAL	30
   12.92 -/*
   12.93 - * If 'delay' is set to 0, keyboard repeat is disabled.
   12.94 +/**
   12.95 + * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
   12.96 + *
   12.97 + *  @param[in] delay
   12.98 + *  'delay' is the initial delay in ms between the time when a key is
   12.99 + *  pressed, and keyboard repeat begins.
  12.100 + *
  12.101 + *  @param[in] interval
  12.102 + *  'interval' is the time in ms between keyboard repeat events.
  12.103 + *
  12.104 + *  If 'delay' is set to 0, keyboard repeat is disabled.
  12.105   */
  12.106  extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
  12.107  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
  12.108  
  12.109 -/*
  12.110 +/**
  12.111   * Get a snapshot of the current state of the keyboard.
  12.112   * Returns an array of keystates, indexed by the SDLK_* syms.
  12.113 - * Used:
  12.114 + * Usage:
  12.115 + *	@code
  12.116   * 	Uint8 *keystate = SDL_GetKeyState(NULL);
  12.117 - *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
  12.118 + *	if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
  12.119 + *	@endcode
  12.120   */
  12.121  extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
  12.122  
  12.123 -/*
  12.124 +/**
  12.125   * Get the current key modifier state
  12.126   */
  12.127  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
  12.128  
  12.129 -/*
  12.130 - * Set the current key modifier state
  12.131 +/**
  12.132 + * Set the current key modifier state.
  12.133   * This does not change the keyboard state, only the key modifier flags.
  12.134   */
  12.135  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
  12.136  
  12.137 -/*
  12.138 +/**
  12.139   * Get the name of an SDL virtual keysym
  12.140   */
  12.141  extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);
    13.1 --- a/include/SDL_keysym.h	Mon Sep 21 09:27:08 2009 +0000
    13.2 +++ b/include/SDL_keysym.h	Mon Sep 21 09:38:10 2009 +0000
    13.3 @@ -23,14 +23,16 @@
    13.4  #ifndef _SDL_keysym_h
    13.5  #define _SDL_keysym_h
    13.6  
    13.7 -/* What we really want is a mapping of every raw key on the keyboard.
    13.8 -   To support international keyboards, we use the range 0xA1 - 0xFF
    13.9 -   as international virtual keycodes.  We'll follow in the footsteps of X11...
   13.10 -   The names of the keys
   13.11 +/** What we really want is a mapping of every raw key on the keyboard.
   13.12 + *  To support international keyboards, we use the range 0xA1 - 0xFF
   13.13 + *  as international virtual keycodes.  We'll follow in the footsteps of X11...
   13.14 + *  @brief The names of the keys
   13.15   */
   13.16 - 
   13.17  typedef enum {
   13.18 -	/* The keyboard syms have been cleverly chosen to map to ASCII */
   13.19 +        /** @name ASCII mapped keysyms
   13.20 +         *  The keyboard syms have been cleverly chosen to map to ASCII
   13.21 +         */
   13.22 +        /*@{*/
   13.23  	SDLK_UNKNOWN		= 0,
   13.24  	SDLK_FIRST		= 0,
   13.25  	SDLK_BACKSPACE		= 8,
   13.26 @@ -108,8 +110,10 @@
   13.27  	SDLK_z			= 122,
   13.28  	SDLK_DELETE		= 127,
   13.29  	/* End of ASCII mapped keysyms */
   13.30 +        /*@}*/
   13.31  
   13.32 -	/* International keyboard syms */
   13.33 +	/** @name International keyboard syms */
   13.34 +        /*@{*/
   13.35  	SDLK_WORLD_0		= 160,		/* 0xA0 */
   13.36  	SDLK_WORLD_1		= 161,
   13.37  	SDLK_WORLD_2		= 162,
   13.38 @@ -206,8 +210,10 @@
   13.39  	SDLK_WORLD_93		= 253,
   13.40  	SDLK_WORLD_94		= 254,
   13.41  	SDLK_WORLD_95		= 255,		/* 0xFF */
   13.42 +        /*@}*/
   13.43  
   13.44 -	/* Numeric keypad */
   13.45 +	/** @name Numeric keypad */
   13.46 +        /*@{*/
   13.47  	SDLK_KP0		= 256,
   13.48  	SDLK_KP1		= 257,
   13.49  	SDLK_KP2		= 258,
   13.50 @@ -225,8 +231,10 @@
   13.51  	SDLK_KP_PLUS		= 270,
   13.52  	SDLK_KP_ENTER		= 271,
   13.53  	SDLK_KP_EQUALS		= 272,
   13.54 +        /*@}*/
   13.55  
   13.56 -	/* Arrows + Home/End pad */
   13.57 +	/** @name Arrows + Home/End pad */
   13.58 +        /*@{*/
   13.59  	SDLK_UP			= 273,
   13.60  	SDLK_DOWN		= 274,
   13.61  	SDLK_RIGHT		= 275,
   13.62 @@ -236,8 +244,10 @@
   13.63  	SDLK_END		= 279,
   13.64  	SDLK_PAGEUP		= 280,
   13.65  	SDLK_PAGEDOWN		= 281,
   13.66 +        /*@}*/
   13.67  
   13.68 -	/* Function keys */
   13.69 +	/** @name Function keys */
   13.70 +        /*@{*/
   13.71  	SDLK_F1			= 282,
   13.72  	SDLK_F2			= 283,
   13.73  	SDLK_F3			= 284,
   13.74 @@ -253,8 +263,10 @@
   13.75  	SDLK_F13		= 294,
   13.76  	SDLK_F14		= 295,
   13.77  	SDLK_F15		= 296,
   13.78 +        /*@}*/
   13.79  
   13.80 -	/* Key state modifier keys */
   13.81 +	/** @name Key state modifier keys */
   13.82 +        /*@{*/
   13.83  	SDLK_NUMLOCK		= 300,
   13.84  	SDLK_CAPSLOCK		= 301,
   13.85  	SDLK_SCROLLOCK		= 302,
   13.86 @@ -266,27 +278,30 @@
   13.87  	SDLK_LALT		= 308,
   13.88  	SDLK_RMETA		= 309,
   13.89  	SDLK_LMETA		= 310,
   13.90 -	SDLK_LSUPER		= 311,		/* Left "Windows" key */
   13.91 -	SDLK_RSUPER		= 312,		/* Right "Windows" key */
   13.92 -	SDLK_MODE		= 313,		/* "Alt Gr" key */
   13.93 -	SDLK_COMPOSE		= 314,		/* Multi-key compose key */
   13.94 +	SDLK_LSUPER		= 311,		/**< Left "Windows" key */
   13.95 +	SDLK_RSUPER		= 312,		/**< Right "Windows" key */
   13.96 +	SDLK_MODE		= 313,		/**< "Alt Gr" key */
   13.97 +	SDLK_COMPOSE		= 314,		/**< Multi-key compose key */
   13.98 +        /*@}*/
   13.99  
  13.100 -	/* Miscellaneous function keys */
  13.101 +	/** @name Miscellaneous function keys */
  13.102 +        /*@{*/
  13.103  	SDLK_HELP		= 315,
  13.104  	SDLK_PRINT		= 316,
  13.105  	SDLK_SYSREQ		= 317,
  13.106  	SDLK_BREAK		= 318,
  13.107  	SDLK_MENU		= 319,
  13.108 -	SDLK_POWER		= 320,		/* Power Macintosh power key */
  13.109 -	SDLK_EURO		= 321,		/* Some european keyboards */
  13.110 -	SDLK_UNDO		= 322,		/* Atari keyboard has Undo */
  13.111 +	SDLK_POWER		= 320,		/**< Power Macintosh power key */
  13.112 +	SDLK_EURO		= 321,		/**< Some european keyboards */
  13.113 +	SDLK_UNDO		= 322,		/**< Atari keyboard has Undo */
  13.114 +        /*@}*/
  13.115  
  13.116  	/* Add any other keys here */
  13.117  
  13.118  	SDLK_LAST
  13.119  } SDLKey;
  13.120  
  13.121 -/* Enumeration of valid key mods (possibly OR'd together) */
  13.122 +/** Enumeration of valid key mods (possibly OR'd together) */
  13.123  typedef enum {
  13.124  	KMOD_NONE  = 0x0000,
  13.125  	KMOD_LSHIFT= 0x0001,
    14.1 --- a/include/SDL_loadso.h	Mon Sep 21 09:27:08 2009 +0000
    14.2 +++ b/include/SDL_loadso.h	Mon Sep 21 09:38:10 2009 +0000
    14.3 @@ -20,22 +20,24 @@
    14.4      slouken@libsdl.org
    14.5  */
    14.6  
    14.7 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    14.8 -/* System dependent library loading routines                           */
    14.9 +/** @file SDL_loadso.h
   14.10 + *  System dependent library loading routines
   14.11 + */
   14.12  
   14.13 -/* Some things to keep in mind:                                        
   14.14 -   - These functions only work on C function names.  Other languages may
   14.15 -     have name mangling and intrinsic language support that varies from
   14.16 -     compiler to compiler.
   14.17 -   - Make sure you declare your function pointers with the same calling
   14.18 -     convention as the actual library function.  Your code will crash
   14.19 -     mysteriously if you do not do this.
   14.20 -   - Avoid namespace collisions.  If you load a symbol from the library,
   14.21 -     it is not defined whether or not it goes into the global symbol
   14.22 -     namespace for the application.  If it does and it conflicts with
   14.23 -     symbols in your code or other shared libraries, you will not get
   14.24 -     the results you expect. :)
   14.25 -*/
   14.26 +/** @file SDL_loadso.h
   14.27 + *  Some things to keep in mind:                                        
   14.28 + *  - These functions only work on C function names.  Other languages may
   14.29 + *    have name mangling and intrinsic language support that varies from
   14.30 + *    compiler to compiler.
   14.31 + *  - Make sure you declare your function pointers with the same calling
   14.32 + *    convention as the actual library function.  Your code will crash
   14.33 + *    mysteriously if you do not do this.
   14.34 + *  - Avoid namespace collisions.  If you load a symbol from the library,
   14.35 + *    it is not defined whether or not it goes into the global symbol
   14.36 + *    namespace for the application.  If it does and it conflicts with
   14.37 + *    symbols in your code or other shared libraries, you will not get
   14.38 + *    the results you expect. :)
   14.39 + */
   14.40  
   14.41  
   14.42  #ifndef _SDL_loadso_h
   14.43 @@ -50,19 +52,21 @@
   14.44  extern "C" {
   14.45  #endif
   14.46  
   14.47 -/* This function dynamically loads a shared object and returns a pointer
   14.48 +/**
   14.49 + * This function dynamically loads a shared object and returns a pointer
   14.50   * to the object handle (or NULL if there was an error).
   14.51   * The 'sofile' parameter is a system dependent name of the object file.
   14.52   */
   14.53  extern DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile);
   14.54  
   14.55 -/* Given an object handle, this function looks up the address of the
   14.56 +/**
   14.57 + * Given an object handle, this function looks up the address of the
   14.58   * named function in the shared object and returns it.  This address
   14.59   * is no longer valid after calling SDL_UnloadObject().
   14.60   */
   14.61  extern DECLSPEC void * SDLCALL SDL_LoadFunction(void *handle, const char *name);
   14.62  
   14.63 -/* Unload a shared object from memory */
   14.64 +/** Unload a shared object from memory */
   14.65  extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
   14.66  
   14.67  /* Ends C function definitions when using C++ */
    15.1 --- a/include/SDL_main.h	Mon Sep 21 09:27:08 2009 +0000
    15.2 +++ b/include/SDL_main.h	Mon Sep 21 09:38:10 2009 +0000
    15.3 @@ -25,7 +25,9 @@
    15.4  
    15.5  #include "SDL_stdinc.h"
    15.6  
    15.7 -/* Redefine main() on Win32 and MacOS so that it is called by winmain.c */
    15.8 +/** @file SDL_main.h
    15.9 + *  Redefine main() on Win32 and MacOS so that it is called by winmain.c
   15.10 + */
   15.11  
   15.12  #if defined(__WIN32__) || \
   15.13      (defined(__MWERKS__) && !defined(__BEOS__)) || \
   15.14 @@ -38,22 +40,25 @@
   15.15  #define C_LINKAGE
   15.16  #endif /* __cplusplus */
   15.17  
   15.18 -/* The application's main() function must be called with C linkage,
   15.19 -   and should be declared like this:
   15.20 -#ifdef __cplusplus
   15.21 -extern "C"
   15.22 -#endif
   15.23 -	int main(int argc, char *argv[])
   15.24 -	{
   15.25 -	}
   15.26 +/** The application's main() function must be called with C linkage,
   15.27 + *  and should be declared like this:
   15.28 + *      @code
   15.29 + *      #ifdef __cplusplus
   15.30 + *      extern "C"
   15.31 + *      #endif
   15.32 + *	int main(int argc, char *argv[])
   15.33 + *	{
   15.34 + *	}
   15.35 + *      @endcode
   15.36   */
   15.37  #define main	SDL_main
   15.38  
   15.39 -/* The prototype for the application's main() function */
   15.40 +/** The prototype for the application's main() function */
   15.41  extern C_LINKAGE int SDL_main(int argc, char *argv[]);
   15.42  
   15.43  
   15.44 -/* From the SDL library code -- needed for registering the app on Win32 */
   15.45 +/** @name From the SDL library code -- needed for registering the app on Win32 */
   15.46 +/*@{*/
   15.47  #ifdef __WIN32__
   15.48  
   15.49  #include "begin_code.h"
   15.50 @@ -61,19 +66,21 @@
   15.51  extern "C" {
   15.52  #endif
   15.53  
   15.54 -/* This should be called from your WinMain() function, if any */
   15.55 +/** This should be called from your WinMain() function, if any */
   15.56  extern DECLSPEC void SDLCALL SDL_SetModuleHandle(void *hInst);
   15.57 -/* This can also be called, but is no longer necessary */
   15.58 +/** This can also be called, but is no longer necessary */
   15.59  extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
   15.60 -/* This can also be called, but is no longer necessary (SDL_Quit calls it) */
   15.61 +/** This can also be called, but is no longer necessary (SDL_Quit calls it) */
   15.62  extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
   15.63  #ifdef __cplusplus
   15.64  }
   15.65  #endif
   15.66  #include "close_code.h"
   15.67  #endif
   15.68 +/*@}*/
   15.69  
   15.70 -/* From the SDL library code -- needed for registering QuickDraw on MacOS */
   15.71 +/** @name From the SDL library code -- needed for registering QuickDraw on MacOS */
   15.72 +/*@{*/
   15.73  #if defined(__MACOS__)
   15.74  
   15.75  #include "begin_code.h"
   15.76 @@ -81,10 +88,10 @@
   15.77  extern "C" {
   15.78  #endif
   15.79  
   15.80 -/* Forward declaration so we don't need to include QuickDraw.h */
   15.81 +/** Forward declaration so we don't need to include QuickDraw.h */
   15.82  struct QDGlobals;
   15.83  
   15.84 -/* This should be called from your main() function, if any */
   15.85 +/** This should be called from your main() function, if any */
   15.86  extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
   15.87  
   15.88  #ifdef __cplusplus
   15.89 @@ -92,6 +99,7 @@
   15.90  #endif
   15.91  #include "close_code.h"
   15.92  #endif
   15.93 +/*@}*/
   15.94  
   15.95  #endif /* Need to redefine main()? */
   15.96  
    16.1 --- a/include/SDL_mouse.h	Mon Sep 21 09:27:08 2009 +0000
    16.2 +++ b/include/SDL_mouse.h	Mon Sep 21 09:38:10 2009 +0000
    16.3 @@ -20,7 +20,9 @@
    16.4      slouken@libsdl.org
    16.5  */
    16.6  
    16.7 -/* Include file for SDL mouse event handling */
    16.8 +/** @file SDL_mouse.h
    16.9 + *  Include file for SDL mouse event handling
   16.10 + */
   16.11  
   16.12  #ifndef _SDL_mouse_h
   16.13  #define _SDL_mouse_h
   16.14 @@ -35,18 +37,18 @@
   16.15  extern "C" {
   16.16  #endif
   16.17  
   16.18 -typedef struct WMcursor WMcursor;	/* Implementation dependent */
   16.19 +typedef struct WMcursor WMcursor;	/**< Implementation dependent */
   16.20  typedef struct SDL_Cursor {
   16.21 -	SDL_Rect area;			/* The area of the mouse cursor */
   16.22 -	Sint16 hot_x, hot_y;		/* The "tip" of the cursor */
   16.23 -	Uint8 *data;			/* B/W cursor data */
   16.24 -	Uint8 *mask;			/* B/W cursor mask */
   16.25 -	Uint8 *save[2];			/* Place to save cursor area */
   16.26 -	WMcursor *wm_cursor;		/* Window-manager cursor */
   16.27 +	SDL_Rect area;			/**< The area of the mouse cursor */
   16.28 +	Sint16 hot_x, hot_y;		/**< The "tip" of the cursor */
   16.29 +	Uint8 *data;			/**< B/W cursor data */
   16.30 +	Uint8 *mask;			/**< B/W cursor mask */
   16.31 +	Uint8 *save[2];			/**< Place to save cursor area */
   16.32 +	WMcursor *wm_cursor;		/**< Window-manager cursor */
   16.33  } SDL_Cursor;
   16.34  
   16.35  /* Function prototypes */
   16.36 -/*
   16.37 +/**
   16.38   * Retrieve the current state of the mouse.
   16.39   * The current button state is returned as a button bitmask, which can
   16.40   * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
   16.41 @@ -54,7 +56,7 @@
   16.42   */
   16.43  extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
   16.44  
   16.45 -/*
   16.46 +/**
   16.47   * Retrieve the current state of the mouse.
   16.48   * The current button state is returned as a button bitmask, which can
   16.49   * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
   16.50 @@ -62,12 +64,12 @@
   16.51   */
   16.52  extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
   16.53  
   16.54 -/*
   16.55 +/**
   16.56   * Set the position of the mouse cursor (generates a mouse motion event)
   16.57   */
   16.58  extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
   16.59  
   16.60 -/*
   16.61 +/**
   16.62   * Create a cursor using the specified data and mask (in MSB format).
   16.63   * The cursor width must be a multiple of 8 bits.
   16.64   *
   16.65 @@ -83,24 +85,24 @@
   16.66  extern DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor
   16.67  		(Uint8 *data, Uint8 *mask, int w, int h, int hot_x, int hot_y);
   16.68  
   16.69 -/*
   16.70 +/**
   16.71   * Set the currently active cursor to the specified one.
   16.72   * If the cursor is currently visible, the change will be immediately 
   16.73   * represented on the display.
   16.74   */
   16.75  extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
   16.76  
   16.77 -/*
   16.78 +/**
   16.79   * Returns the currently active cursor.
   16.80   */
   16.81  extern DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
   16.82  
   16.83 -/*
   16.84 +/**
   16.85   * Deallocates a cursor created with SDL_CreateCursor().
   16.86   */
   16.87  extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
   16.88  
   16.89 -/*
   16.90 +/**
   16.91   * Toggle whether or not the cursor is shown on the screen.
   16.92   * The cursor start off displayed, but can be turned off.
   16.93   * SDL_ShowCursor() returns 1 if the cursor was being displayed
   16.94 @@ -109,12 +111,13 @@
   16.95   */
   16.96  extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
   16.97  
   16.98 -/* Used as a mask when testing buttons in buttonstate
   16.99 -   Button 1:	Left mouse button
  16.100 -   Button 2:	Middle mouse button
  16.101 -   Button 3:	Right mouse button
  16.102 -   Button 4:	Mouse wheel up	 (may also be a real button)
  16.103 -   Button 5:	Mouse wheel down (may also be a real button)
  16.104 +/*@{*/
  16.105 +/** Used as a mask when testing buttons in buttonstate
  16.106 + *  Button 1:	Left mouse button
  16.107 + *  Button 2:	Middle mouse button
  16.108 + *  Button 3:	Right mouse button
  16.109 + *  Button 4:	Mouse wheel up	 (may also be a real button)
  16.110 + *  Button 5:	Mouse wheel down (may also be a real button)
  16.111   */
  16.112  #define SDL_BUTTON(X)		(1 << ((X)-1))
  16.113  #define SDL_BUTTON_LEFT		1
  16.114 @@ -129,7 +132,7 @@
  16.115  #define SDL_BUTTON_RMASK	SDL_BUTTON(SDL_BUTTON_RIGHT)
  16.116  #define SDL_BUTTON_X1MASK	SDL_BUTTON(SDL_BUTTON_X1)
  16.117  #define SDL_BUTTON_X2MASK	SDL_BUTTON(SDL_BUTTON_X2)
  16.118 -
  16.119 +/*@}*/
  16.120  
  16.121  /* Ends C function definitions when using C++ */
  16.122  #ifdef __cplusplus
    17.1 --- a/include/SDL_mutex.h	Mon Sep 21 09:27:08 2009 +0000
    17.2 +++ b/include/SDL_mutex.h	Mon Sep 21 09:38:10 2009 +0000
    17.3 @@ -23,10 +23,11 @@
    17.4  #ifndef _SDL_mutex_h
    17.5  #define _SDL_mutex_h
    17.6  
    17.7 -/* Functions to provide thread synchronization primitives
    17.8 -
    17.9 -	These are independent of the other SDL routines.
   17.10 -*/
   17.11 +/** @file SDL_mutex.h
   17.12 + *  Functions to provide thread synchronization primitives
   17.13 + *
   17.14 + *  @note These are independent of the other SDL routines.
   17.15 + */
   17.16  
   17.17  #include "SDL_stdinc.h"
   17.18  #include "SDL_error.h"
   17.19 @@ -37,122 +38,135 @@
   17.20  extern "C" {
   17.21  #endif
   17.22  
   17.23 -/* Synchronization functions which can time out return this value
   17.24 -   if they time out.
   17.25 -*/
   17.26 +/** Synchronization functions which can time out return this value
   17.27 + *  if they time out.
   17.28 + */
   17.29  #define SDL_MUTEX_TIMEDOUT	1
   17.30  
   17.31 -/* This is the timeout value which corresponds to never time out */
   17.32 +/** This is the timeout value which corresponds to never time out */
   17.33  #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
   17.34  
   17.35  
   17.36  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   17.37 -/* Mutex functions                                               */
   17.38 +/** @name Mutex functions                                        */ /*@{*/
   17.39  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   17.40  
   17.41 -/* The SDL mutex structure, defined in SDL_mutex.c */
   17.42 +/** The SDL mutex structure, defined in SDL_mutex.c */
   17.43  struct SDL_mutex;
   17.44  typedef struct SDL_mutex SDL_mutex;
   17.45  
   17.46 -/* Create a mutex, initialized unlocked */
   17.47 +/** Create a mutex, initialized unlocked */
   17.48  extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
   17.49  
   17.50 -/* Lock the mutex  (Returns 0, or -1 on error) */
   17.51  #define SDL_LockMutex(m)	SDL_mutexP(m)
   17.52 +/** Lock the mutex
   17.53 + *  @return 0, or -1 on error
   17.54 + */
   17.55  extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
   17.56  
   17.57 -/* Unlock the mutex  (Returns 0, or -1 on error)
   17.58 -   It is an error to unlock a mutex that has not been locked by
   17.59 -   the current thread, and doing so results in undefined behavior.
   17.60 +#define SDL_UnlockMutex(m)	SDL_mutexV(m)
   17.61 +/** Unlock the mutex
   17.62 + *  @return 0, or -1 on error
   17.63 + *
   17.64 + *  It is an error to unlock a mutex that has not been locked by
   17.65 + *  the current thread, and doing so results in undefined behavior.
   17.66   */
   17.67 -#define SDL_UnlockMutex(m)	SDL_mutexV(m)
   17.68  extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
   17.69  
   17.70 -/* Destroy a mutex */
   17.71 +/** Destroy a mutex */
   17.72  extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
   17.73  
   17.74 +/*@}*/
   17.75  
   17.76  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   17.77 -/* Semaphore functions                                           */
   17.78 +/** @name Semaphore functions                                    */ /*@{*/
   17.79  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   17.80  
   17.81 -/* The SDL semaphore structure, defined in SDL_sem.c */
   17.82 +/** The SDL semaphore structure, defined in SDL_sem.c */
   17.83  struct SDL_semaphore;
   17.84  typedef struct SDL_semaphore SDL_sem;
   17.85  
   17.86 -/* Create a semaphore, initialized with value, returns NULL on failure. */
   17.87 +/** Create a semaphore, initialized with value, returns NULL on failure. */
   17.88  extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
   17.89  
   17.90 -/* Destroy a semaphore */
   17.91 +/** Destroy a semaphore */
   17.92  extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
   17.93  
   17.94 -/* This function suspends the calling thread until the semaphore pointed 
   17.95 +/**
   17.96 + * This function suspends the calling thread until the semaphore pointed 
   17.97   * to by sem has a positive count. It then atomically decreases the semaphore
   17.98   * count.
   17.99   */
  17.100  extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
  17.101  
  17.102 -/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
  17.103 -   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
  17.104 -*/
  17.105 +/** Non-blocking variant of SDL_SemWait().
  17.106 + *  @return 0 if the wait succeeds,
  17.107 + *  SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
  17.108 + */
  17.109  extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
  17.110  
  17.111 -/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
  17.112 -   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
  17.113 -   the allotted time, and -1 on error.
  17.114 -   On some platforms this function is implemented by looping with a delay
  17.115 -   of 1 ms, and so should be avoided if possible.
  17.116 -*/
  17.117 +/** Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
  17.118 + *  the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
  17.119 + *  the allotted time, and -1 on error.
  17.120 + *
  17.121 + *  On some platforms this function is implemented by looping with a delay
  17.122 + *  of 1 ms, and so should be avoided if possible.
  17.123 + */
  17.124  extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
  17.125  
  17.126 -/* Atomically increases the semaphore's count (not blocking), returns 0,
  17.127 -   or -1 on error.
  17.128 +/** Atomically increases the semaphore's count (not blocking).
  17.129 + *  @return 0, or -1 on error.
  17.130   */
  17.131  extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
  17.132  
  17.133 -/* Returns the current count of the semaphore */
  17.134 +/** Returns the current count of the semaphore */
  17.135  extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
  17.136  
  17.137 +/*@}*/
  17.138  
  17.139  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  17.140 -/* Condition variable functions                                  */
  17.141 +/** @name Condition_variable_functions                           */ /*@{*/
  17.142  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  17.143  
  17.144 -/* The SDL condition variable structure, defined in SDL_cond.c */
  17.145 +/*@{*/
  17.146 +/** The SDL condition variable structure, defined in SDL_cond.c */
  17.147  struct SDL_cond;
  17.148  typedef struct SDL_cond SDL_cond;
  17.149 +/*@}*/
  17.150  
  17.151 -/* Create a condition variable */
  17.152 +/** Create a condition variable */
  17.153  extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
  17.154  
  17.155 -/* Destroy a condition variable */
  17.156 +/** Destroy a condition variable */
  17.157  extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
  17.158  
  17.159 -/* Restart one of the threads that are waiting on the condition variable,
  17.160 -   returns 0 or -1 on error.
  17.161 +/** Restart one of the threads that are waiting on the condition variable,
  17.162 + *  @return 0 or -1 on error.
  17.163   */
  17.164  extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
  17.165  
  17.166 -/* Restart all threads that are waiting on the condition variable,
  17.167 -   returns 0 or -1 on error.
  17.168 +/** Restart all threads that are waiting on the condition variable,
  17.169 + *  @return 0 or -1 on error.
  17.170   */
  17.171  extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
  17.172  
  17.173 -/* Wait on the condition variable, unlocking the provided mutex.
  17.174 -   The mutex must be locked before entering this function!
  17.175 -   The mutex is re-locked once the condition variable is signaled.
  17.176 -   Returns 0 when it is signaled, or -1 on error.
  17.177 +/** Wait on the condition variable, unlocking the provided mutex.
  17.178 + *  The mutex must be locked before entering this function!
  17.179 + *  The mutex is re-locked once the condition variable is signaled.
  17.180 + *  @return 0 when it is signaled, or -1 on error.
  17.181   */
  17.182  extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
  17.183  
  17.184 -/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
  17.185 -   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
  17.186 -   signaled in the allotted time, and -1 on error.
  17.187 -   On some platforms this function is implemented by looping with a delay
  17.188 -   of 1 ms, and so should be avoided if possible.
  17.189 -*/
  17.190 +/** Waits for at most 'ms' milliseconds, and returns 0 if the condition
  17.191 + *  variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
  17.192 + *  signaled in the allotted time, and -1 on error.
  17.193 + *  On some platforms this function is implemented by looping with a delay
  17.194 + *  of 1 ms, and so should be avoided if possible.
  17.195 + */
  17.196  extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
  17.197  
  17.198 +/*@}*/
  17.199 +
  17.200  /* Ends C function definitions when using C++ */
  17.201  #ifdef __cplusplus
  17.202  }
  17.203 @@ -160,3 +174,4 @@
  17.204  #include "close_code.h"
  17.205  
  17.206  #endif /* _SDL_mutex_h */
  17.207 +
    18.1 --- a/include/SDL_opengl.h	Mon Sep 21 09:27:08 2009 +0000
    18.2 +++ b/include/SDL_opengl.h	Mon Sep 21 09:38:10 2009 +0000
    18.3 @@ -20,7 +20,9 @@
    18.4      slouken@libsdl.org
    18.5  */
    18.6  
    18.7 -/* This is a simple file to encapsulate the OpenGL API headers */
    18.8 +/** @file SDL_opengl.h
    18.9 + *  This is a simple file to encapsulate the OpenGL API headers
   18.10 + */
   18.11  
   18.12  #include "SDL_config.h"
   18.13  
   18.14 @@ -48,10 +50,12 @@
   18.15  #undef __glext_h_
   18.16  #endif
   18.17  
   18.18 -/* This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
   18.19 -   It is included here because glext.h is not available on some systems.
   18.20 -   If you don't want this version included, simply define "NO_SDL_GLEXT"
   18.21 +/** @name GLext.h
   18.22 + *  This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
   18.23 + *  It is included here because glext.h is not available on some systems.
   18.24 + *  If you don't want this version included, simply define "NO_SDL_GLEXT"
   18.25   */
   18.26 +/*@{*/
   18.27  #ifndef NO_SDL_GLEXT
   18.28  #if !defined(__glext_h_) && !defined(GL_GLEXT_LEGACY)
   18.29  #define __glext_h_
   18.30 @@ -6549,3 +6553,4 @@
   18.31  
   18.32  #endif
   18.33  #endif /* NO_SDL_GLEXT */
   18.34 +/*@}*/
   18.35 \ No newline at end of file
    19.1 --- a/include/SDL_platform.h	Mon Sep 21 09:27:08 2009 +0000
    19.2 +++ b/include/SDL_platform.h	Mon Sep 21 09:38:10 2009 +0000
    19.3 @@ -20,7 +20,9 @@
    19.4      slouken@libsdl.org
    19.5  */
    19.6  
    19.7 -/* Try to get a standard set of platform defines */
    19.8 +/** @file SDL_platform.h
    19.9 + *  Try to get a standard set of platform defines
   19.10 + */
   19.11  
   19.12  #ifndef _SDL_platform_h
   19.13  #define _SDL_platform_h
    20.1 --- a/include/SDL_quit.h	Mon Sep 21 09:27:08 2009 +0000
    20.2 +++ b/include/SDL_quit.h	Mon Sep 21 09:38:10 2009 +0000
    20.3 @@ -20,7 +20,9 @@
    20.4      slouken@libsdl.org
    20.5  */
    20.6  
    20.7 -/* Include file for SDL quit event handling */
    20.8 +/** @file SDL_quit.h
    20.9 + *  Include file for SDL quit event handling
   20.10 + */
   20.11  
   20.12  #ifndef _SDL_quit_h
   20.13  #define _SDL_quit_h
   20.14 @@ -28,22 +30,25 @@
   20.15  #include "SDL_stdinc.h"
   20.16  #include "SDL_error.h"
   20.17  
   20.18 -/* 
   20.19 -  An SDL_QUITEVENT is generated when the user tries to close the application
   20.20 -  window.  If it is ignored or filtered out, the window will remain open.
   20.21 -  If it is not ignored or filtered, it is queued normally and the window
   20.22 -  is allowed to close.  When the window is closed, screen updates will 
   20.23 -  complete, but have no effect.
   20.24 +/** @file SDL_quit.h
   20.25 + *  An SDL_QUITEVENT is generated when the user tries to close the application
   20.26 + *  window.  If it is ignored or filtered out, the window will remain open.
   20.27 + *  If it is not ignored or filtered, it is queued normally and the window
   20.28 + *  is allowed to close.  When the window is closed, screen updates will 
   20.29 + *  complete, but have no effect.
   20.30 + *
   20.31 + *  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
   20.32 + *  and SIGTERM (system termination request), if handlers do not already
   20.33 + *  exist, that generate SDL_QUITEVENT events as well.  There is no way
   20.34 + *  to determine the cause of an SDL_QUITEVENT, but setting a signal
   20.35 + *  handler in your application will override the default generation of
   20.36 + *  quit events for that signal.
   20.37 + */
   20.38  
   20.39 -  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
   20.40 -  and SIGTERM (system termination request), if handlers do not already
   20.41 -  exist, that generate SDL_QUITEVENT events as well.  There is no way
   20.42 -  to determine the cause of an SDL_QUITEVENT, but setting a signal
   20.43 -  handler in your application will override the default generation of
   20.44 -  quit events for that signal.
   20.45 -*/
   20.46 +/** @file SDL_quit.h
   20.47 + *  There are no functions directly affecting the quit event 
   20.48 + */
   20.49  
   20.50 -/* There are no functions directly affecting the quit event */
   20.51  #define SDL_QuitRequested() \
   20.52          (SDL_PumpEvents(), SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUITMASK))
   20.53  
    21.1 --- a/include/SDL_rwops.h	Mon Sep 21 09:27:08 2009 +0000
    21.2 +++ b/include/SDL_rwops.h	Mon Sep 21 09:38:10 2009 +0000
    21.3 @@ -20,9 +20,10 @@
    21.4      slouken@libsdl.org
    21.5  */
    21.6  
    21.7 -/* This file provides a general interface for SDL to read and write
    21.8 -   data sources.  It can easily be extended to files, memory, etc.
    21.9 -*/
   21.10 +/** @file SDL_rwops.h
   21.11 + *  This file provides a general interface for SDL to read and write
   21.12 + *  data sources.  It can easily be extended to files, memory, etc.
   21.13 + */
   21.14  
   21.15  #ifndef _SDL_rwops_h
   21.16  #define _SDL_rwops_h
   21.17 @@ -36,28 +37,28 @@
   21.18  extern "C" {
   21.19  #endif
   21.20  
   21.21 -/* This is the read/write operation structure -- very basic */
   21.22 +/** This is the read/write operation structure -- very basic */
   21.23  
   21.24  typedef struct SDL_RWops {
   21.25 -	/* Seek to 'offset' relative to whence, one of stdio's whence values:
   21.26 -		SEEK_SET, SEEK_CUR, SEEK_END
   21.27 -	   Returns the final offset in the data source.
   21.28 +	/** Seek to 'offset' relative to whence, one of stdio's whence values:
   21.29 +	 *	SEEK_SET, SEEK_CUR, SEEK_END
   21.30 +	 *  Returns the final offset in the data source.
   21.31  	 */
   21.32  	int (SDLCALL *seek)(struct SDL_RWops *context, int offset, int whence);
   21.33  
   21.34 -	/* Read up to 'maxnum' objects each of size 'size' from the data
   21.35 -	   source to the area pointed at by 'ptr'.
   21.36 -	   Returns the number of objects read, or -1 if the read failed.
   21.37 +	/** Read up to 'maxnum' objects each of size 'size' from the data
   21.38 +	 *  source to the area pointed at by 'ptr'.
   21.39 +	 *  Returns the number of objects read, or -1 if the read failed.
   21.40  	 */
   21.41  	int (SDLCALL *read)(struct SDL_RWops *context, void *ptr, int size, int maxnum);
   21.42  
   21.43 -	/* Write exactly 'num' objects each of size 'objsize' from the area
   21.44 -	   pointed at by 'ptr' to data source.
   21.45 -	   Returns 'num', or -1 if the write failed.
   21.46 +	/** Write exactly 'num' objects each of size 'objsize' from the area
   21.47 +	 *  pointed at by 'ptr' to data source.
   21.48 +	 *  Returns 'num', or -1 if the write failed.
   21.49  	 */
   21.50  	int (SDLCALL *write)(struct SDL_RWops *context, const void *ptr, int size, int num);
   21.51  
   21.52 -	/* Close and free an allocated SDL_FSops structure */
   21.53 +	/** Close and free an allocated SDL_FSops structure */
   21.54  	int (SDLCALL *close)(struct SDL_RWops *context);
   21.55  
   21.56  	Uint32 type;
   21.57 @@ -92,7 +93,8 @@
   21.58  } SDL_RWops;
   21.59  
   21.60  
   21.61 -/* Functions to create SDL_RWops structures from various data sources */
   21.62 +/** @name Functions to create SDL_RWops structures from various data sources */
   21.63 +/*@{*/
   21.64  
   21.65  extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromFile(const char *file, const char *mode);
   21.66  
   21.67 @@ -106,34 +108,43 @@
   21.68  extern DECLSPEC SDL_RWops * SDLCALL SDL_AllocRW(void);
   21.69  extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops *area);
   21.70  
   21.71 -#define RW_SEEK_SET	0	/* Seek from the beginning of data */
   21.72 -#define RW_SEEK_CUR	1	/* Seek relative to current read point */
   21.73 -#define RW_SEEK_END	2	/* Seek relative to the end of data */
   21.74 +/*@}*/
   21.75  
   21.76 -/* Macros to easily read and write from an SDL_RWops structure */
   21.77 +/** @name Seek Reference Points */
   21.78 +/*@{*/
   21.79 +#define RW_SEEK_SET	0	/**< Seek from the beginning of data */
   21.80 +#define RW_SEEK_CUR	1	/**< Seek relative to current read point */
   21.81 +#define RW_SEEK_END	2	/**< Seek relative to the end of data */
   21.82 +/*@}*/
   21.83 +
   21.84 +/** @name Macros to easily read and write from an SDL_RWops structure */
   21.85 +/*@{*/
   21.86  #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
   21.87  #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
   21.88  #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
   21.89  #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
   21.90  #define SDL_RWclose(ctx)		(ctx)->close(ctx)
   21.91 +/*@}*/
   21.92  
   21.93 -
   21.94 -/* Read an item of the specified endianness and return in native format */
   21.95 +/** @name Read an item of the specified endianness and return in native format */
   21.96 +/*@{*/
   21.97  extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops *src);
   21.98  extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops *src);
   21.99  extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops *src);
  21.100  extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops *src);
  21.101  extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops *src);
  21.102  extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops *src);
  21.103 +/*@}*/
  21.104  
  21.105 -/* Write an item of native format to the specified endianness */
  21.106 +/** @name Write an item of native format to the specified endianness */
  21.107 +/*@{*/
  21.108  extern DECLSPEC int SDLCALL SDL_WriteLE16(SDL_RWops *dst, Uint16 value);
  21.109  extern DECLSPEC int SDLCALL SDL_WriteBE16(SDL_RWops *dst, Uint16 value);
  21.110  extern DECLSPEC int SDLCALL SDL_WriteLE32(SDL_RWops *dst, Uint32 value);
  21.111  extern DECLSPEC int SDLCALL SDL_WriteBE32(SDL_RWops *dst, Uint32 value);
  21.112  extern DECLSPEC int SDLCALL SDL_WriteLE64(SDL_RWops *dst, Uint64 value);
  21.113  extern DECLSPEC int SDLCALL SDL_WriteBE64(SDL_RWops *dst, Uint64 value);
  21.114 -
  21.115 +/*@}*/
  21.116  
  21.117  /* Ends C function definitions when using C++ */
  21.118  #ifdef __cplusplus
    22.1 --- a/include/SDL_stdinc.h	Mon Sep 21 09:27:08 2009 +0000
    22.2 +++ b/include/SDL_stdinc.h	Mon Sep 21 09:38:10 2009 +0000
    22.3 @@ -20,7 +20,9 @@
    22.4      slouken@libsdl.org
    22.5  */
    22.6  
    22.7 -/* This is a general header that includes C language support */
    22.8 +/** @file SDL_stdinc.h
    22.9 + *  This is a general header that includes C language support
   22.10 + */
   22.11  
   22.12  #ifndef _SDL_stdinc_h
   22.13  #define _SDL_stdinc_h
   22.14 @@ -72,11 +74,12 @@
   22.15  # include <iconv.h>
   22.16  #endif
   22.17  
   22.18 -/* The number of elements in an array */
   22.19 +/** The number of elements in an array */
   22.20  #define SDL_arraysize(array)	(sizeof(array)/sizeof(array[0]))
   22.21  #define SDL_TABLESIZE(table)	SDL_arraysize(table)
   22.22  
   22.23 -/* Basic data types */
   22.24 +/** @name Basic data types */
   22.25 +/*@{*/
   22.26  typedef enum SDL_bool {
   22.27  	SDL_FALSE = 0,
   22.28  	SDL_TRUE  = 1
   22.29 @@ -102,7 +105,10 @@
   22.30  } Uint64, Sint64;
   22.31  #endif
   22.32  
   22.33 -/* Make sure the types really have the right sizes */
   22.34 +/*@}*/
   22.35 +
   22.36 +/** @name Make sure the types really have the right sizes */
   22.37 +/*@{*/
   22.38  #define SDL_COMPILE_TIME_ASSERT(name, x)               \
   22.39         typedef int SDL_dummy_ ## name[(x) * 2 - 1]
   22.40  
   22.41 @@ -114,12 +120,14 @@
   22.42  SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4);
   22.43  SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8);
   22.44  SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
   22.45 +/*@}*/
   22.46  
   22.47 -/* Check to make sure enums are the size of ints, for structure packing.
   22.48 -   For both Watcom C/C++ and Borland C/C++ the compiler option that makes
   22.49 -   enums having the size of an int must be enabled.
   22.50 -   This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
   22.51 -*/
   22.52 +/** @name Enum Size Check
   22.53 + *  Check to make sure enums are the size of ints, for structure packing.
   22.54 + *  For both Watcom C/C++ and Borland C/C++ the compiler option that makes
   22.55 + *  enums having the size of an int must be enabled.
   22.56 + *  This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
   22.57 + */
   22.58  /* Enable enums always int in CodeWarrior (for MPW use "-enum int") */
   22.59  #ifdef __MWERKS__
   22.60  #pragma enumsalwaysint on
   22.61 @@ -132,7 +140,7 @@
   22.62  #ifndef __NDS__
   22.63  SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
   22.64  #endif
   22.65 -
   22.66 +/*@}*/
   22.67  
   22.68  #include "begin_code.h"
   22.69  /* Set up for C function definitions, even when using C++ */
   22.70 @@ -565,11 +573,15 @@
   22.71  extern DECLSPEC int SDLCALL SDL_vsnprintf(char *text, size_t maxlen, const char *fmt, va_list ap);
   22.72  #endif
   22.73  
   22.74 -/* The SDL implementation of iconv() returns these error codes */
   22.75 +/** @name SDL_ICONV Error Codes
   22.76 + *  The SDL implementation of iconv() returns these error codes 
   22.77 + */
   22.78 +/*@{*/
   22.79  #define SDL_ICONV_ERROR		(size_t)-1
   22.80  #define SDL_ICONV_E2BIG		(size_t)-2
   22.81  #define SDL_ICONV_EILSEQ	(size_t)-3
   22.82  #define SDL_ICONV_EINVAL	(size_t)-4
   22.83 +/*@}*/
   22.84  
   22.85  #ifdef HAVE_ICONV
   22.86  #define SDL_iconv_t     iconv_t
   22.87 @@ -581,9 +593,9 @@
   22.88  extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
   22.89  #endif
   22.90  extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
   22.91 -/* This function converts a string between encodings in one pass, returning a
   22.92 -   string that must be freed with SDL_free() or NULL on error.
   22.93 -*/
   22.94 +/** This function converts a string between encodings in one pass, returning a
   22.95 + *  string that must be freed with SDL_free() or NULL on error.
   22.96 + */
   22.97  extern DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, const char *inbuf, size_t inbytesleft);
   22.98  #define SDL_iconv_utf8_locale(S)	SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
   22.99  #define SDL_iconv_utf8_ucs2(S)		(Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1)
    23.1 --- a/include/SDL_syswm.h	Mon Sep 21 09:27:08 2009 +0000
    23.2 +++ b/include/SDL_syswm.h	Mon Sep 21 09:38:10 2009 +0000
    23.3 @@ -20,7 +20,9 @@
    23.4      slouken@libsdl.org
    23.5  */
    23.6  
    23.7 -/* Include file for SDL custom system window manager hooks */
    23.8 +/** @file SDL_syswm.h
    23.9 + *  Include file for SDL custom system window manager hooks
   23.10 + */
   23.11  
   23.12  #ifndef _SDL_syswm_h
   23.13  #define _SDL_syswm_h
   23.14 @@ -35,11 +37,12 @@
   23.15  extern "C" {
   23.16  #endif
   23.17  
   23.18 -/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
   23.19 -   which contains window-manager specific information and arrives whenever
   23.20 -   an unhandled window event occurs.  This event is ignored by default, but
   23.21 -   you can enable it with SDL_EventState()
   23.22 -*/
   23.23 +/** @file SDL_syswm.h
   23.24 + *  Your application has access to a special type of event 'SDL_SYSWMEVENT',
   23.25 + *  which contains window-manager specific information and arrives whenever
   23.26 + *  an unhandled window event occurs.  This event is ignored by default, but
   23.27 + *  you can enable it with SDL_EventState()
   23.28 + */
   23.29  #ifdef SDL_PROTOTYPES_ONLY
   23.30  struct SDL_SysWMinfo;
   23.31  typedef struct SDL_SysWMinfo SDL_SysWMinfo;
   23.32 @@ -60,12 +63,12 @@
   23.33  #undef Cursor
   23.34  #endif
   23.35  
   23.36 -/* These are the various supported subsystems under UNIX */
   23.37 +/** These are the various supported subsystems under UNIX */
   23.38  typedef enum {
   23.39  	SDL_SYSWM_X11
   23.40  } SDL_SYSWM_TYPE;
   23.41  
   23.42 -/* The UNIX custom event structure */
   23.43 +/** The UNIX custom event structure */
   23.44  struct SDL_SysWMmsg {
   23.45  	SDL_version version;
   23.46  	SDL_SYSWM_TYPE subsystem;
   23.47 @@ -74,32 +77,38 @@
   23.48  	} event;
   23.49  };
   23.50  
   23.51 -/* The UNIX custom window manager information structure.
   23.52 -   When this structure is returned, it holds information about which
   23.53 -   low level system it is using, and will be one of SDL_SYSWM_TYPE.
   23.54 +/** The UNIX custom window manager information structure.
   23.55 + *  When this structure is returned, it holds information about which
   23.56 + *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
   23.57   */
   23.58  typedef struct SDL_SysWMinfo {
   23.59  	SDL_version version;
   23.60  	SDL_SYSWM_TYPE subsystem;
   23.61  	union {
   23.62  	    struct {
   23.63 -	    	Display *display;	/* The X11 display */
   23.64 -	    	Window window;		/* The X11 display window */
   23.65 -		/* These locking functions should be called around
   23.66 -                   any X11 functions using the display variable, 
   23.67 -                   but not the gfxdisplay variable.
   23.68 -                   They lock the event thread, so should not be
   23.69 -		   called around event functions or from event filters.
   23.70 +	    	Display *display;	/**< The X11 display */
   23.71 +	    	Window window;		/**< The X11 display window */
   23.72 +		/** These locking functions should be called around
   23.73 +                 *  any X11 functions using the display variable, 
   23.74 +                 *  but not the gfxdisplay variable.
   23.75 +                 *  They lock the event thread, so should not be
   23.76 +		 *  called around event functions or from event filters.
   23.77  		 */
   23.78 +                /*@{*/
   23.79  		void (*lock_func)(void);
   23.80  		void (*unlock_func)(void);
   23.81 +                /*@}*/
   23.82  
   23.83 -		/* Introduced in SDL 1.0.2 */
   23.84 -	    	Window fswindow;	/* The X11 fullscreen window */
   23.85 -	    	Window wmwindow;	/* The X11 managed input window */
   23.86 +		/** @name Introduced in SDL 1.0.2 */
   23.87 +                /*@{*/
   23.88 +	    	Window fswindow;	/**< The X11 fullscreen window */
   23.89 +	    	Window wmwindow;	/**< The X11 managed input window */
   23.90 +                /*@}*/
   23.91  
   23.92 -		/* Introduced in SDL 1.2.12 */
   23.93 -		Display *gfxdisplay;	/* The X11 display to which rendering is done */
   23.94 +		/** @name Introduced in SDL 1.2.12 */
   23.95 +                /*@{*/
   23.96 +		Display *gfxdisplay;	/**< The X11 display to which rendering is done */
   23.97 +                /*@}*/
   23.98  	    } x11;
   23.99  	} info;
  23.100  } SDL_SysWMinfo;
  23.101 @@ -107,13 +116,13 @@
  23.102  #elif defined(SDL_VIDEO_DRIVER_NANOX)
  23.103  #include <microwin/nano-X.h>
  23.104  
  23.105 -/* The generic custom event structure */
  23.106 +/** The generic custom event structure */
  23.107  struct SDL_SysWMmsg {
  23.108  	SDL_version version;
  23.109  	int data;
  23.110  };
  23.111  
  23.112 -/* The windows custom window manager information structure */
  23.113 +/** The windows custom window manager information structure */
  23.114  typedef struct SDL_SysWMinfo {
  23.115  	SDL_version version ;
  23.116  	GR_WINDOW_ID window ;	/* The display window */
  23.117 @@ -123,50 +132,50 @@
  23.118  #define WIN32_LEAN_AND_MEAN
  23.119  #include <windows.h>
  23.120  
  23.121 -/* The windows custom event structure */
  23.122 +/** The windows custom event structure */
  23.123  struct SDL_SysWMmsg {
  23.124  	SDL_version version;
  23.125 -	HWND hwnd;			/* The window for the message */
  23.126 -	UINT msg;			/* The type of message */
  23.127 -	WPARAM wParam;			/* WORD message parameter */
  23.128 -	LPARAM lParam;			/* LONG message parameter */
  23.129 +	HWND hwnd;			/**< The window for the message */
  23.130 +	UINT msg;			/**< The type of message */
  23.131 +	WPARAM wParam;			/**< WORD message parameter */
  23.132 +	LPARAM lParam;			/**< LONG message parameter */
  23.133  };
  23.134  
  23.135 -/* The windows custom window manager information structure */
  23.136 +/** The windows custom window manager information structure */
  23.137  typedef struct SDL_SysWMinfo {
  23.138  	SDL_version version;
  23.139 -	HWND window;			/* The Win32 display window */
  23.140 -	HGLRC hglrc;			/* The OpenGL context, if any */
  23.141 +	HWND window;			/**< The Win32 display window */
  23.142 +	HGLRC hglrc;			/**< The OpenGL context, if any */
  23.143  } SDL_SysWMinfo;
  23.144  
  23.145  #elif defined(SDL_VIDEO_DRIVER_RISCOS)
  23.146  
  23.147 -/* RISC OS custom event structure */
  23.148 +/** RISC OS custom event structure */
  23.149  struct SDL_SysWMmsg {
  23.150  	SDL_version version;
  23.151 -	int eventCode;		/* The window for the message */
  23.152 +	int eventCode;		/**< The window for the message */
  23.153  	int pollBlock[64];
  23.154  };
  23.155  
  23.156 -/* The RISC OS custom window manager information structure */
  23.157 +/** The RISC OS custom window manager information structure */
  23.158  typedef struct SDL_SysWMinfo {
  23.159  	SDL_version version;
  23.160 -	int wimpVersion;    /* Wimp version running under */
  23.161 -	int taskHandle;     /* The RISC OS task handle */
  23.162 -	int window;		/* The RISC OS display window */
  23.163 +	int wimpVersion;    /**< Wimp version running under */
  23.164 +	int taskHandle;     /**< The RISC OS task handle */
  23.165 +	int window;		/**< The RISC OS display window */
  23.166  } SDL_SysWMinfo;
  23.167  
  23.168  #elif defined(SDL_VIDEO_DRIVER_PHOTON)
  23.169  #include <sys/neutrino.h>
  23.170  #include <Ph.h>
  23.171  
  23.172 -/* The QNX custom event structure */
  23.173 +/** The QNX custom event structure */
  23.174  struct SDL_SysWMmsg {
  23.175  	SDL_version version;
  23.176  	int data;
  23.177  };
  23.178  
  23.179 -/* The QNX custom window manager information structure */
  23.180 +/** The QNX custom window manager information structure */
  23.181  typedef struct SDL_SysWMinfo {
  23.182  	SDL_version version;
  23.183  	int data;
  23.184 @@ -174,13 +183,13 @@
  23.185  
  23.186  #else
  23.187  
  23.188 -/* The generic custom event structure */
  23.189 +/** The generic custom event structure */
  23.190  struct SDL_SysWMmsg {
  23.191  	SDL_version version;
  23.192  	int data;
  23.193  };
  23.194  
  23.195 -/* The generic custom window manager information structure */
  23.196 +/** The generic custom window manager information structure */
  23.197  typedef struct SDL_SysWMinfo {
  23.198  	SDL_version version;
  23.199  	int data;
  23.200 @@ -191,16 +200,18 @@
  23.201  #endif /* SDL_PROTOTYPES_ONLY */
  23.202  
  23.203  /* Function prototypes */
  23.204 -/*
  23.205 +/**
  23.206   * This function gives you custom hooks into the window manager information.
  23.207   * It fills the structure pointed to by 'info' with custom information and
  23.208   * returns 1 if the function is implemented.  If it's not implemented, or
  23.209   * the version member of the 'info' structure is invalid, it returns 0. 
  23.210   *
  23.211   * You typically use this function like this:
  23.212 + * @code
  23.213   * SDL_SysWMInfo info;
  23.214   * SDL_VERSION(&info.version);
  23.215   * if ( SDL_GetWMInfo(&info) ) { ... }
  23.216 + * @endcode
  23.217   */
  23.218  extern DECLSPEC int SDLCALL SDL_GetWMInfo(SDL_SysWMinfo *info);
  23.219  
    24.1 --- a/include/SDL_thread.h	Mon Sep 21 09:27:08 2009 +0000
    24.2 +++ b/include/SDL_thread.h	Mon Sep 21 09:38:10 2009 +0000
    24.3 @@ -23,10 +23,11 @@
    24.4  #ifndef _SDL_thread_h
    24.5  #define _SDL_thread_h
    24.6  
    24.7 -/* Header for the SDL thread management routines 
    24.8 -
    24.9 -	These are independent of the other SDL routines.
   24.10 -*/
   24.11 +/** @file SDL_thread.h
   24.12 + *  Header for the SDL thread management routines 
   24.13 + *
   24.14 + *  @note These are independent of the other SDL routines.
   24.15 + */
   24.16  
   24.17  #include "SDL_stdinc.h"
   24.18  #include "SDL_error.h"
   24.19 @@ -40,25 +41,25 @@
   24.20  extern "C" {
   24.21  #endif
   24.22  
   24.23 -/* The SDL thread structure, defined in SDL_thread.c */
   24.24 +/** The SDL thread structure, defined in SDL_thread.c */
   24.25  struct SDL_Thread;
   24.26  typedef struct SDL_Thread SDL_Thread;
   24.27  
   24.28 -/* Create a thread */
   24.29 +/** Create a thread */
   24.30  #if ((defined(__WIN32__) && !defined(HAVE_LIBC)) || defined(__OS2__)) &&  !defined(__SYMBIAN32__)
   24.31 -/*
   24.32 -   We compile SDL into a DLL on OS/2. This means, that it's the DLL which
   24.33 -   creates a new thread for the calling process with the SDL_CreateThread()
   24.34 -   API. There is a problem with this, that only the RTL of the SDL.DLL will
   24.35 -   be initialized for those threads, and not the RTL of the calling application!
   24.36 -   To solve this, we make a little hack here.
   24.37 -   We'll always use the caller's _beginthread() and _endthread() APIs to
   24.38 -   start a new thread. This way, if it's the SDL.DLL which uses this API,
   24.39 -   then the RTL of SDL.DLL will be used to create the new thread, and if it's
   24.40 -   the application, then the RTL of the application will be used.
   24.41 -   So, in short:
   24.42 -   Always use the _beginthread() and _endthread() of the calling runtime library!
   24.43 -*/
   24.44 +/**
   24.45 + *  We compile SDL into a DLL on OS/2. This means, that it's the DLL which
   24.46 + *  creates a new thread for the calling process with the SDL_CreateThread()
   24.47 + *  API. There is a problem with this, that only the RTL of the SDL.DLL will
   24.48 + *  be initialized for those threads, and not the RTL of the calling application!
   24.49 + *  To solve this, we make a little hack here.
   24.50 + *  We'll always use the caller's _beginthread() and _endthread() APIs to
   24.51 + *  start a new thread. This way, if it's the SDL.DLL which uses this API,
   24.52 + *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
   24.53 + *  the application, then the RTL of the application will be used.
   24.54 + *  So, in short:
   24.55 + *  Always use the _beginthread() and _endthread() of the calling runtime library!
   24.56 + */
   24.57  #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
   24.58  #ifndef _WIN32_WCE
   24.59  #include <process.h> /* This has _beginthread() and _endthread() defined! */
   24.60 @@ -92,21 +93,21 @@
   24.61  extern DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(int (SDLCALL *fn)(void *), void *data);
   24.62  #endif
   24.63  
   24.64 -/* Get the 32-bit thread identifier for the current thread */
   24.65 +/** Get the 32-bit thread identifier for the current thread */
   24.66  extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
   24.67  
   24.68 -/* Get the 32-bit thread identifier for the specified thread,
   24.69 -   equivalent to SDL_ThreadID() if the specified thread is NULL.
   24.70 +/** Get the 32-bit thread identifier for the specified thread,
   24.71 + *  equivalent to SDL_ThreadID() if the specified thread is NULL.
   24.72   */
   24.73  extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread *thread);
   24.74  
   24.75 -/* Wait for a thread to finish.
   24.76 -   The return code for the thread function is placed in the area
   24.77 -   pointed to by 'status', if 'status' is not NULL.
   24.78 +/** Wait for a thread to finish.
   24.79 + *  The return code for the thread function is placed in the area
   24.80 + *  pointed to by 'status', if 'status' is not NULL.
   24.81   */
   24.82  extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status);
   24.83  
   24.84 -/* Forcefully kill a thread without worrying about its state */
   24.85 +/** Forcefully kill a thread without worrying about its state */
   24.86  extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread *thread);
   24.87  
   24.88  
    25.1 --- a/include/SDL_timer.h	Mon Sep 21 09:27:08 2009 +0000
    25.2 +++ b/include/SDL_timer.h	Mon Sep 21 09:38:10 2009 +0000
    25.3 @@ -23,7 +23,9 @@
    25.4  #ifndef _SDL_timer_h
    25.5  #define _SDL_timer_h
    25.6  
    25.7 -/* Header for the SDL time management routines */
    25.8 +/** @file SDL_timer.h
    25.9 + *  Header for the SDL time management routines
   25.10 + */
   25.11  
   25.12  #include "SDL_stdinc.h"
   25.13  #include "SDL_error.h"
   25.14 @@ -34,24 +36,26 @@
   25.15  extern "C" {
   25.16  #endif
   25.17  
   25.18 -/* This is the OS scheduler timeslice, in milliseconds */
   25.19 +/** This is the OS scheduler timeslice, in milliseconds */
   25.20  #define SDL_TIMESLICE		10
   25.21  
   25.22 -/* This is the maximum resolution of the SDL timer on all platforms */
   25.23 -#define TIMER_RESOLUTION	10	/* Experimentally determined */
   25.24 +/** This is the maximum resolution of the SDL timer on all platforms */
   25.25 +#define TIMER_RESOLUTION	10	/**< Experimentally determined */
   25.26  
   25.27 -/* Get the number of milliseconds since the SDL library initialization.
   25.28 +/**
   25.29 + * Get the number of milliseconds since the SDL library initialization.
   25.30   * Note that this value wraps if the program runs for more than ~49 days.
   25.31   */ 
   25.32  extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
   25.33  
   25.34 -/* Wait a specified number of milliseconds before returning */
   25.35 +/** Wait a specified number of milliseconds before returning */
   25.36  extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
   25.37  
   25.38 -/* Function prototype for the timer callback function */
   25.39 +/** Function prototype for the timer callback function */
   25.40  typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
   25.41  
   25.42 -/* Set a callback to run after the specified number of milliseconds has
   25.43 +/**
   25.44 + * Set a callback to run after the specified number of milliseconds has
   25.45   * elapsed. The callback function is passed the current timer interval
   25.46   * and returns the next timer interval.  If the returned value is the 
   25.47   * same as the one passed in, the periodic alarm continues, otherwise a
   25.48 @@ -68,7 +72,7 @@
   25.49   * later on an unloaded system.  If you wanted to set a flag signaling
   25.50   * a frame update at 30 frames per second (every 33 ms), you might set a 
   25.51   * timer for 30 ms:
   25.52 - *   SDL_SetTimer((33/10)*10, flag_update);
   25.53 + *   @code SDL_SetTimer((33/10)*10, flag_update); @endcode
   25.54   *
   25.55   * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
   25.56   *
   25.57 @@ -81,11 +85,14 @@
   25.58   */
   25.59  extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback callback);
   25.60  
   25.61 -/* New timer API, supports multiple timers
   25.62 +/** @name New timer API
   25.63 + * New timer API, supports multiple timers
   25.64   * Written by Stephane Peter <megastep@lokigames.com>
   25.65   */
   25.66 +/*@{*/
   25.67  
   25.68 -/* Function prototype for the new timer callback function.
   25.69 +/**
   25.70 + * Function prototype for the new timer callback function.
   25.71   * The callback function is passed the current timer interval and returns
   25.72   * the next timer interval.  If the returned value is the same as the one
   25.73   * passed in, the periodic alarm continues, otherwise a new alarm is
   25.74 @@ -93,19 +100,22 @@
   25.75   */
   25.76  typedef Uint32 (SDLCALL *SDL_NewTimerCallback)(Uint32 interval, void *param);
   25.77  
   25.78 -/* Definition of the timer ID type */
   25.79 +/** Definition of the timer ID type */
   25.80  typedef struct _SDL_TimerID *SDL_TimerID;
   25.81  
   25.82 -/* Add a new timer to the pool of timers already running.
   25.83 -   Returns a timer ID, or NULL when an error occurs.
   25.84 +/** Add a new timer to the pool of timers already running.
   25.85 + *  Returns a timer ID, or NULL when an error occurs.
   25.86   */
   25.87  extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_NewTimerCallback callback, void *param);
   25.88  
   25.89 -/* Remove one of the multiple timers knowing its ID.
   25.90 +/**
   25.91 + * Remove one of the multiple timers knowing its ID.
   25.92   * Returns a boolean value indicating success.
   25.93   */
   25.94  extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
   25.95  
   25.96 +/*@}*/
   25.97 +
   25.98  /* Ends C function definitions when using C++ */
   25.99  #ifdef __cplusplus
  25.100  }
    26.1 --- a/include/SDL_types.h	Mon Sep 21 09:27:08 2009 +0000
    26.2 +++ b/include/SDL_types.h	Mon Sep 21 09:38:10 2009 +0000
    26.3 @@ -20,5 +20,9 @@
    26.4      slouken@libsdl.org
    26.5  */
    26.6  
    26.7 +/** @file SDL_types.h
    26.8 + *  @deprecated Use SDL_stdinc.h instead.
    26.9 + */
   26.10 +
   26.11  /* DEPRECATED */
   26.12  #include "SDL_stdinc.h"
    27.1 --- a/include/SDL_version.h	Mon Sep 21 09:27:08 2009 +0000
    27.2 +++ b/include/SDL_version.h	Mon Sep 21 09:38:10 2009 +0000
    27.3 @@ -20,7 +20,9 @@
    27.4      slouken@libsdl.org
    27.5  */
    27.6  
    27.7 -/* This header defines the current SDL version */
    27.8 +/** @file SDL_version.h
    27.9 + *  This header defines the current SDL version
   27.10 + */
   27.11  
   27.12  #ifndef _SDL_version_h
   27.13  #define _SDL_version_h
   27.14 @@ -33,11 +35,14 @@
   27.15  extern "C" {
   27.16  #endif
   27.17  
   27.18 -/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
   27.19 -*/
   27.20 +/** @name Version Number
   27.21 + *  Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
   27.22 + */
   27.23 +/*@{*/
   27.24  #define SDL_MAJOR_VERSION	1
   27.25  #define SDL_MINOR_VERSION	2
   27.26  #define SDL_PATCHLEVEL		14
   27.27 +/*@}*/
   27.28  
   27.29  typedef struct SDL_version {
   27.30  	Uint8 major;
   27.31 @@ -45,7 +50,8 @@
   27.32  	Uint8 patch;
   27.33  } SDL_version;
   27.34  
   27.35 -/* This macro can be used to fill a version structure with the compile-time
   27.36 +/**
   27.37 + * This macro can be used to fill a version structure with the compile-time
   27.38   * version of the SDL library.
   27.39   */
   27.40  #define SDL_VERSION(X)							\
   27.41 @@ -55,24 +61,24 @@
   27.42  	(X)->patch = SDL_PATCHLEVEL;					\
   27.43  }
   27.44  
   27.45 -/* This macro turns the version numbers into a numeric value:
   27.46 -   (1,2,3) -> (1203)
   27.47 -   This assumes that there will never be more than 100 patchlevels
   27.48 -*/
   27.49 +/** This macro turns the version numbers into a numeric value:
   27.50 + *  (1,2,3) -> (1203)
   27.51 + *  This assumes that there will never be more than 100 patchlevels
   27.52 + */
   27.53  #define SDL_VERSIONNUM(X, Y, Z)						\
   27.54  	((X)*1000 + (Y)*100 + (Z))
   27.55  
   27.56 -/* This is the version number macro for the current SDL version */
   27.57 +/** This is the version number macro for the current SDL version */
   27.58  #define SDL_COMPILEDVERSION \
   27.59  	SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL)
   27.60  
   27.61 -/* This macro will evaluate to true if compiled with SDL at least X.Y.Z */
   27.62 +/** This macro will evaluate to true if compiled with SDL at least X.Y.Z */
   27.63  #define SDL_VERSION_ATLEAST(X, Y, Z) \
   27.64  	(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
   27.65  
   27.66 -/* This function gets the version of the dynamically linked SDL library.
   27.67 -   it should NOT be used to fill a version structure, instead you should
   27.68 -   use the SDL_Version() macro.
   27.69 +/** This function gets the version of the dynamically linked SDL library.
   27.70 + *  it should NOT be used to fill a version structure, instead you should
   27.71 + *  use the SDL_Version() macro.
   27.72   */
   27.73  extern DECLSPEC const SDL_version * SDLCALL SDL_Linked_Version(void);
   27.74  
    28.1 --- a/include/SDL_video.h	Mon Sep 21 09:27:08 2009 +0000
    28.2 +++ b/include/SDL_video.h	Mon Sep 21 09:38:10 2009 +0000
    28.3 @@ -20,7 +20,9 @@
    28.4      slouken@libsdl.org
    28.5  */
    28.6  
    28.7 -/* Header file for access to the SDL raw framebuffer window */
    28.8 +/** @file SDL_video.h
    28.9 + *  Header file for access to the SDL raw framebuffer window
   28.10 + */
   28.11  
   28.12  #ifndef _SDL_video_h
   28.13  #define _SDL_video_h
   28.14 @@ -35,11 +37,16 @@
   28.15  extern "C" {
   28.16  #endif
   28.17  
   28.18 -/* Transparency definitions: These define alpha as the opacity of a surface */
   28.19 +/** @name Transparency definitions
   28.20 + *  These define alpha as the opacity of a surface
   28.21 + */
   28.22 +/*@{*/
   28.23  #define SDL_ALPHA_OPAQUE 255
   28.24  #define SDL_ALPHA_TRANSPARENT 0
   28.25 +/*@}*/
   28.26  
   28.27 -/* Useful data types */
   28.28 +/** @name Useful data types */
   28.29 +/*@{*/
   28.30  typedef struct SDL_Rect {
   28.31  	Sint16 x, y;
   28.32  	Uint16 w, h;
   28.33 @@ -57,8 +64,9 @@
   28.34  	int       ncolors;
   28.35  	SDL_Color *colors;
   28.36  } SDL_Palette;
   28.37 +/*@}*/
   28.38  
   28.39 -/* Everything in the pixel format structure is read-only */
   28.40 +/** Everything in the pixel format structure is read-only */
   28.41  typedef struct SDL_PixelFormat {
   28.42  	SDL_Palette *palette;
   28.43  	Uint8  BitsPerPixel;
   28.44 @@ -76,128 +84,149 @@
   28.45  	Uint32 Bmask;
   28.46  	Uint32 Amask;
   28.47  
   28.48 -	/* RGB color key information */
   28.49 +	/** RGB color key information */
   28.50  	Uint32 colorkey;
   28.51 -	/* Alpha value information (per-surface alpha) */
   28.52 +	/** Alpha value information (per-surface alpha) */
   28.53  	Uint8  alpha;
   28.54  } SDL_PixelFormat;
   28.55  
   28.56 -/* This structure should be treated as read-only, except for 'pixels',
   28.57 -   which, if not NULL, contains the raw pixel data for the surface.
   28.58 -*/
   28.59 +/** This structure should be treated as read-only, except for 'pixels',
   28.60 + *  which, if not NULL, contains the raw pixel data for the surface.
   28.61 + */
   28.62  typedef struct SDL_Surface {
   28.63 -	Uint32 flags;				/* Read-only */
   28.64 -	SDL_PixelFormat *format;		/* Read-only */
   28.65 -	int w, h;				/* Read-only */
   28.66 -	Uint16 pitch;				/* Read-only */
   28.67 -	void *pixels;				/* Read-write */
   28.68 -	int offset;				/* Private */
   28.69 +	Uint32 flags;				/**< Read-only */
   28.70 +	SDL_PixelFormat *format;		/**< Read-only */
   28.71 +	int w, h;				/**< Read-only */
   28.72 +	Uint16 pitch;				/**< Read-only */
   28.73 +	void *pixels;				/**< Read-write */
   28.74 +	int offset;				/**< Private */
   28.75  
   28.76 -	/* Hardware-specific surface info */
   28.77 +	/** Hardware-specific surface info */
   28.78  	struct private_hwdata *hwdata;
   28.79  
   28.80 -	/* clipping information */
   28.81 -	SDL_Rect clip_rect;			/* Read-only */
   28.82 -	Uint32 unused1;				/* for binary compatibility */
   28.83 +	/** clipping information */
   28.84 +	SDL_Rect clip_rect;			/**< Read-only */
   28.85 +	Uint32 unused1;				/**< for binary compatibility */
   28.86  
   28.87 -	/* Allow recursive locks */
   28.88 -	Uint32 locked;				/* Private */
   28.89 +	/** Allow recursive locks */
   28.90 +	Uint32 locked;				/**< Private */
   28.91  
   28.92 -	/* info for fast blit mapping to other surfaces */
   28.93 -	struct SDL_BlitMap *map;		/* Private */
   28.94 +	/** info for fast blit mapping to other surfaces */
   28.95 +	struct SDL_BlitMap *map;		/**< Private */
   28.96  
   28.97 -	/* format version, bumped at every change to invalidate blit maps */
   28.98 -	unsigned int format_version;		/* Private */
   28.99 +	/** format version, bumped at every change to invalidate blit maps */
  28.100 +	unsigned int format_version;		/**< Private */
  28.101  
  28.102 -	/* Reference count -- used when freeing surface */
  28.103 -	int refcount;				/* Read-mostly */
  28.104 +	/** Reference count -- used when freeing surface */
  28.105 +	int refcount;				/**< Read-mostly */
  28.106  } SDL_Surface;
  28.107  
  28.108 -/* These are the currently supported flags for the SDL_surface */
  28.109 -/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
  28.110 -#define SDL_SWSURFACE	0x00000000	/* Surface is in system memory */
  28.111 -#define SDL_HWSURFACE	0x00000001	/* Surface is in video memory */
  28.112 -#define SDL_ASYNCBLIT	0x00000004	/* Use asynchronous blits if possible */
  28.113 -/* Available for SDL_SetVideoMode() */
  28.114 -#define SDL_ANYFORMAT	0x10000000	/* Allow any video depth/pixel-format */
  28.115 -#define SDL_HWPALETTE	0x20000000	/* Surface has exclusive palette */
  28.116 -#define SDL_DOUBLEBUF	0x40000000	/* Set up double-buffered video mode */
  28.117 -#define SDL_FULLSCREEN	0x80000000	/* Surface is a full screen display */
  28.118 -#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
  28.119 -#define SDL_OPENGLBLIT	0x0000000A	/* Create an OpenGL rendering context and use it for blitting */
  28.120 -#define SDL_RESIZABLE	0x00000010	/* This video mode may be resized */
  28.121 -#define SDL_NOFRAME	0x00000020	/* No window caption or edge frame */
  28.122 -/* Used internally (read-only) */
  28.123 -#define SDL_HWACCEL	0x00000100	/* Blit uses hardware acceleration */
  28.124 -#define SDL_SRCCOLORKEY	0x00001000	/* Blit uses a source color key */
  28.125 -#define SDL_RLEACCELOK	0x00002000	/* Private flag */
  28.126 -#define SDL_RLEACCEL	0x00004000	/* Surface is RLE encoded */
  28.127 -#define SDL_SRCALPHA	0x00010000	/* Blit uses source alpha blending */
  28.128 -#define SDL_PREALLOC	0x01000000	/* Surface uses preallocated memory */
  28.129 +/** @name SDL_Surface Flags
  28.130 + *  These are the currently supported flags for the SDL_surface
  28.131 + */
  28.132 +/*@{*/
  28.133  
  28.134 -/* Evaluates to true if the surface needs to be locked before access */
  28.135 +/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
  28.136 +/*@{*/
  28.137 +#define SDL_SWSURFACE	0x00000000	/**< Surface is in system memory */
  28.138 +#define SDL_HWSURFACE	0x00000001	/**< Surface is in video memory */
  28.139 +#define SDL_ASYNCBLIT	0x00000004	/**< Use asynchronous blits if possible */
  28.140 +/*@}*/
  28.141 +
  28.142 +/** Available for SDL_SetVideoMode() */
  28.143 +/*@{*/
  28.144 +#define SDL_ANYFORMAT	0x10000000	/**< Allow any video depth/pixel-format */
  28.145 +#define SDL_HWPALETTE	0x20000000	/**< Surface has exclusive palette */
  28.146 +#define SDL_DOUBLEBUF	0x40000000	/**< Set up double-buffered video mode */
  28.147 +#define SDL_FULLSCREEN	0x80000000	/**< Surface is a full screen display */
  28.148 +#define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
  28.149 +#define SDL_OPENGLBLIT	0x0000000A	/**< Create an OpenGL rendering context and use it for blitting */
  28.150 +#define SDL_RESIZABLE	0x00000010	/**< This video mode may be resized */
  28.151 +#define SDL_NOFRAME	0x00000020	/**< No window caption or edge frame */
  28.152 +/*@}*/
  28.153 +
  28.154 +/** Used internally (read-only) */
  28.155 +/*@{*/
  28.156 +#define SDL_HWACCEL	0x00000100	/**< Blit uses hardware acceleration */
  28.157 +#define SDL_SRCCOLORKEY	0x00001000	/**< Blit uses a source color key */
  28.158 +#define SDL_RLEACCELOK	0x00002000	/**< Private flag */
  28.159 +#define SDL_RLEACCEL	0x00004000	/**< Surface is RLE encoded */
  28.160 +#define SDL_SRCALPHA	0x00010000	/**< Blit uses source alpha blending */
  28.161 +#define SDL_PREALLOC	0x01000000	/**< Surface uses preallocated memory */
  28.162 +/*@}*/
  28.163 +
  28.164 +/*@}*/
  28.165 +
  28.166 +/** Evaluates to true if the surface needs to be locked before access */
  28.167  #define SDL_MUSTLOCK(surface)	\
  28.168    (surface->offset ||		\
  28.169    ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
  28.170  
  28.171 -/* typedef for private surface blitting functions */
  28.172 +/** typedef for private surface blitting functions */
  28.173  typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
  28.174  			struct SDL_Surface *dst, SDL_Rect *dstrect);
  28.175  
  28.176  
  28.177 -/* Useful for determining the video hardware capabilities */
  28.178 +/** Useful for determining the video hardware capabilities */
  28.179  typedef struct SDL_VideoInfo {
  28.180 -	Uint32 hw_available :1;	/* Flag: Can you create hardware surfaces? */
  28.181 -	Uint32 wm_available :1;	/* Flag: Can you talk to a window manager? */
  28.182 +	Uint32 hw_available :1;	/**< Flag: Can you create hardware surfaces? */
  28.183 +	Uint32 wm_available :1;	/**< Flag: Can you talk to a window manager? */
  28.184  	Uint32 UnusedBits1  :6;
  28.185  	Uint32 UnusedBits2  :1;
  28.186 -	Uint32 blit_hw      :1;	/* Flag: Accelerated blits HW --> HW */
  28.187 -	Uint32 blit_hw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
  28.188 -	Uint32 blit_hw_A    :1;	/* Flag: Accelerated blits with Alpha */
  28.189 -	Uint32 blit_sw      :1;	/* Flag: Accelerated blits SW --> HW */
  28.190 -	Uint32 blit_sw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
  28.191 -	Uint32 blit_sw_A    :1;	/* Flag: Accelerated blits with Alpha */
  28.192 -	Uint32 blit_fill    :1;	/* Flag: Accelerated color fill */
  28.193 +	Uint32 blit_hw      :1;	/**< Flag: Accelerated blits HW --> HW */
  28.194 +	Uint32 blit_hw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
  28.195 +	Uint32 blit_hw_A    :1;	/**< Flag: Accelerated blits with Alpha */
  28.196 +	Uint32 blit_sw      :1;	/**< Flag: Accelerated blits SW --> HW */
  28.197 +	Uint32 blit_sw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
  28.198 +	Uint32 blit_sw_A    :1;	/**< Flag: Accelerated blits with Alpha */
  28.199 +	Uint32 blit_fill    :1;	/**< Flag: Accelerated color fill */
  28.200  	Uint32 UnusedBits3  :16;
  28.201 -	Uint32 video_mem;	/* The total amount of video memory (in K) */
  28.202 -	SDL_PixelFormat *vfmt;	/* Value: The format of the video surface */
  28.203 -	int    current_w;	/* Value: The current video mode width */
  28.204 -	int    current_h;	/* Value: The current video mode height */
  28.205 +	Uint32 video_mem;	/**< The total amount of video memory (in K) */
  28.206 +	SDL_PixelFormat *vfmt;	/**< Value: The format of the video surface */
  28.207 +	int    current_w;	/**< Value: The current video mode width */
  28.208 +	int    current_h;	/**< Value: The current video mode height */
  28.209  } SDL_VideoInfo;
  28.210  
  28.211  
  28.212 -/* The most common video overlay formats.
  28.213 -   For an explanation of these pixel formats, see:
  28.214 -	http://www.webartz.com/fourcc/indexyuv.htm
  28.215 +/** @name Overlay Formats
  28.216 + *  The most common video overlay formats.
  28.217 + *  For an explanation of these pixel formats, see:
  28.218 + *	http://www.webartz.com/fourcc/indexyuv.htm
  28.219 + *
  28.220 + *  For information on the relationship between color spaces, see:
  28.221 + *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
  28.222 + */
  28.223 +/*@{*/
  28.224 +#define SDL_YV12_OVERLAY  0x32315659	/**< Planar mode: Y + V + U  (3 planes) */
  28.225 +#define SDL_IYUV_OVERLAY  0x56555949	/**< Planar mode: Y + U + V  (3 planes) */
  28.226 +#define SDL_YUY2_OVERLAY  0x32595559	/**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
  28.227 +#define SDL_UYVY_OVERLAY  0x59565955	/**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
  28.228 +#define SDL_YVYU_OVERLAY  0x55595659	/**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
  28.229 +/*@}*/
  28.230  
  28.231 -   For information on the relationship between color spaces, see:
  28.232 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
  28.233 - */
  28.234 -#define SDL_YV12_OVERLAY  0x32315659	/* Planar mode: Y + V + U  (3 planes) */
  28.235 -#define SDL_IYUV_OVERLAY  0x56555949	/* Planar mode: Y + U + V  (3 planes) */
  28.236 -#define SDL_YUY2_OVERLAY  0x32595559	/* Packed mode: Y0+U0+Y1+V0 (1 plane) */
  28.237 -#define SDL_UYVY_OVERLAY  0x59565955	/* Packed mode: U0+Y0+V0+Y1 (1 plane) */
  28.238 -#define SDL_YVYU_OVERLAY  0x55595659	/* Packed mode: Y0+V0+Y1+U0 (1 plane) */
  28.239 +/** The YUV hardware video overlay */
  28.240 +typedef struct SDL_Overlay {
  28.241 +	Uint32 format;				/**< Read-only */
  28.242 +	int w, h;				/**< Read-only */
  28.243 +	int planes;				/**< Read-only */
  28.244 +	Uint16 *pitches;			/**< Read-only */
  28.245 +	Uint8 **pixels;				/**< Read-write */
  28.246  
  28.247 -/* The YUV hardware video overlay */
  28.248 -typedef struct SDL_Overlay {
  28.249 -	Uint32 format;				/* Read-only */
  28.250 -	int w, h;				/* Read-only */
  28.251 -	int planes;				/* Read-only */
  28.252 -	Uint16 *pitches;			/* Read-only */
  28.253 -	Uint8 **pixels;				/* Read-write */
  28.254 -
  28.255 -	/* Hardware-specific surface info */
  28.256 +	/** @name Hardware-specific surface info */
  28.257 +        /*@{*/
  28.258  	struct private_yuvhwfuncs *hwfuncs;
  28.259  	struct private_yuvhwdata *hwdata;
  28.260 +        /*@{*/
  28.261  
  28.262 -	/* Special flags */
  28.263 -	Uint32 hw_overlay :1;	/* Flag: This overlay hardware accelerated? */
  28.264 +	/** @name Special flags */
  28.265 +        /*@{*/
  28.266 +	Uint32 hw_overlay :1;	/**< Flag: This overlay hardware accelerated? */
  28.267  	Uint32 UnusedBits :31;
  28.268 +        /*@}*/
  28.269  } SDL_Overlay;
  28.270  
  28.271  
  28.272 -/* Public enumeration for setting the OpenGL window attributes. */
  28.273 +/** Public enumeration for setting the OpenGL window attributes. */
  28.274  typedef enum {
  28.275      SDL_GL_RED_SIZE,
  28.276      SDL_GL_GREEN_SIZE,
  28.277 @@ -218,17 +247,23 @@
  28.278      SDL_GL_SWAP_CONTROL
  28.279  } SDL_GLattr;
  28.280  
  28.281 -/* flags for SDL_SetPalette() */
  28.282 +/** @name flags for SDL_SetPalette() */
  28.283 +/*@{*/
  28.284  #define SDL_LOGPAL 0x01
  28.285  #define SDL_PHYSPAL 0x02
  28.286 +/*@}*/
  28.287  
  28.288  /* Function prototypes */
  28.289  
  28.290 -/* These functions are used internally, and should not be used unless you
  28.291 +/**
  28.292 + * @name Video Init and Quit
  28.293 + * These functions are used internally, and should not be used unless you
  28.294   * have a specific need to specify the video driver you want to use.
  28.295   * You should normally use SDL_Init() or SDL_InitSubSystem().
  28.296 - *
  28.297 - * SDL_VideoInit() initializes the video subsystem -- sets up a connection
  28.298 + */
  28.299 +/*@{*/
  28.300 +/**
  28.301 + * Initializes the video subsystem. Sets up a connection
  28.302   * to the window manager, etc, and determines the current video mode and
  28.303   * pixel format, but does not initialize a window or graphics mode.
  28.304   * Note that event handling is activated by this routine.
  28.305 @@ -239,14 +274,16 @@
  28.306   */
  28.307  extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
  28.308  extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
  28.309 +/*@}*/
  28.310  
  28.311 -/* This function fills the given character buffer with the name of the
  28.312 +/**
  28.313 + * This function fills the given character buffer with the name of the
  28.314   * video driver, and returns a pointer to it if the video driver has
  28.315   * been initialized.  It returns NULL if no driver has been initialized.
  28.316   */
  28.317  extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
  28.318  
  28.319 -/*
  28.320 +/**
  28.321   * This function returns a pointer to the current display surface.
  28.322   * If SDL is doing format conversion on the display surface, this
  28.323   * function returns the publicly visible surface, not the real video
  28.324 @@ -254,7 +291,7 @@
  28.325   */
  28.326  extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
  28.327  
  28.328 -/*
  28.329 +/**
  28.330   * This function returns a read-only pointer to information about the
  28.331   * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
  28.332   * member of the returned structure will contain the pixel format of the
  28.333 @@ -262,7 +299,7 @@
  28.334   */
  28.335  extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
  28.336  
  28.337 -/* 
  28.338 +/**
  28.339   * Check to see if a particular video mode is supported.
  28.340   * It returns 0 if the requested mode is not supported under any bit depth,
  28.341   * or returns the bits-per-pixel of the closest available mode with the
  28.342 @@ -275,7 +312,7 @@
  28.343   */
  28.344  extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
  28.345  
  28.346 -/*
  28.347 +/**
  28.348   * Return a pointer to an array of available screen dimensions for the
  28.349   * given format and video flags, sorted largest to smallest.  Returns 
  28.350   * NULL if there are no dimensions available for a particular format, 
  28.351 @@ -286,7 +323,7 @@
  28.352   */
  28.353  extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
  28.354  
  28.355 -/*
  28.356 +/**
  28.357   * Set up a video mode with the specified width, height and bits-per-pixel.
  28.358   *
  28.359   * If 'bpp' is 0, it is treated as the current display bits per pixel.
  28.360 @@ -347,18 +384,24 @@
  28.361  extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
  28.362  			(int width, int height, int bpp, Uint32 flags);
  28.363  
  28.364 -/*
  28.365 +/** @name SDL_Update Functions
  28.366 + * These functions should not be called while 'screen' is locked.
  28.367 + */
  28.368 +/*@{*/
  28.369 +/**
  28.370   * Makes sure the given list of rectangles is updated on the given screen.
  28.371 - * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
  28.372 - * screen.
  28.373 - * These functions should not be called while 'screen' is locked.
  28.374   */
  28.375  extern DECLSPEC void SDLCALL SDL_UpdateRects
  28.376  		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
  28.377 +/**
  28.378 + * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
  28.379 + * screen.
  28.380 + */
  28.381  extern DECLSPEC void SDLCALL SDL_UpdateRect
  28.382  		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
  28.383 +/*@}*/
  28.384  
  28.385 -/*
  28.386 +/**
  28.387   * On hardware that supports double-buffering, this function sets up a flip
  28.388   * and returns.  The hardware will wait for vertical retrace, and then swap
  28.389   * video buffers before the next video surface blit or lock will return.
  28.390 @@ -370,7 +413,7 @@
  28.391   */
  28.392  extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
  28.393  
  28.394 -/*
  28.395 +/**
  28.396   * Set the gamma correction for each of the color channels.
  28.397   * The gamma values range (approximately) between 0.1 and 10.0
  28.398   * 
  28.399 @@ -380,7 +423,7 @@
  28.400   */
  28.401  extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
  28.402  
  28.403 -/*
  28.404 +/**
  28.405   * Set the gamma translation table for the red, green, and blue channels
  28.406   * of the video hardware.  Each table is an array of 256 16-bit quantities,
  28.407   * representing a mapping between the input and output for that channel.
  28.408 @@ -394,7 +437,7 @@
  28.409   */
  28.410  extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
  28.411  
  28.412 -/*
  28.413 +/**
  28.414   * Retrieve the current values of the gamma translation tables.
  28.415   * 
  28.416   * You must pass in valid pointers to arrays of 256 16-bit quantities.
  28.417 @@ -405,7 +448,7 @@
  28.418   */
  28.419  extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
  28.420  
  28.421 -/*
  28.422 +/**
  28.423   * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
  28.424   * is not a palettized surface, this function does nothing, returning 0.
  28.425   * If all of the colors were set as passed to SDL_SetColors(), it will
  28.426 @@ -423,7 +466,7 @@
  28.427  extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
  28.428  			SDL_Color *colors, int firstcolor, int ncolors);
  28.429  
  28.430 -/*
  28.431 +/**
  28.432   * Sets a portion of the colormap for a given 8-bit surface.
  28.433   * 'flags' is one or both of:
  28.434   * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
  28.435 @@ -443,35 +486,37 @@
  28.436  				   SDL_Color *colors, int firstcolor,
  28.437  				   int ncolors);
  28.438  
  28.439 -/*
  28.440 +/**
  28.441   * Maps an RGB triple to an opaque pixel value for a given pixel format
  28.442   */
  28.443  extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
  28.444  (const SDL_PixelFormat * const format,
  28.445   const Uint8 r, const Uint8 g, const Uint8 b);
  28.446  
  28.447 -/*
  28.448 +/**
  28.449   * Maps an RGBA quadruple to a pixel value for a given pixel format
  28.450   */
  28.451  extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
  28.452  (const SDL_PixelFormat * const format,
  28.453   const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
  28.454  
  28.455 -/*
  28.456 +/**
  28.457   * Maps a pixel value into the RGB components for a given pixel format
  28.458   */
  28.459  extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
  28.460  				const SDL_PixelFormat * const fmt,
  28.461  				Uint8 *r, Uint8 *g, Uint8 *b);
  28.462  
  28.463 -/*
  28.464 +/**
  28.465   * Maps a pixel value into the RGBA components for a given pixel format
  28.466   */
  28.467  extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
  28.468  				const SDL_PixelFormat * const fmt,
  28.469  				Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
  28.470  
  28.471 -/*
  28.472 +/** @sa SDL_CreateRGBSurface */
  28.473 +#define SDL_AllocSurface    SDL_CreateRGBSurface
  28.474 +/**
  28.475   * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
  28.476   * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
  28.477   * If the depth is greater than 8 bits, the pixel format is set using the
  28.478 @@ -505,16 +550,16 @@
  28.479   * reason the surface could not be placed in video memory, it will not have
  28.480   * the SDL_HWSURFACE flag set, and will be created in system memory instead.
  28.481   */
  28.482 -#define SDL_AllocSurface    SDL_CreateRGBSurface
  28.483  extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
  28.484  			(Uint32 flags, int width, int height, int depth, 
  28.485  			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  28.486 +/** @sa SDL_CreateRGBSurface */
  28.487  extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
  28.488  			int width, int height, int depth, int pitch,
  28.489  			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  28.490  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
  28.491  
  28.492 -/*
  28.493 +/**
  28.494   * SDL_LockSurface() sets up a surface for directly accessing the pixels.
  28.495   * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
  28.496   * to and read from 'surface->pixels', using the pixel format stored in 
  28.497 @@ -535,7 +580,7 @@
  28.498  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
  28.499  extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  28.500  
  28.501 -/*
  28.502 +/**
  28.503   * Load a surface from a seekable SDL data source (memory or file.)
  28.504   * If 'freesrc' is non-zero, the source will be closed after being read.
  28.505   * Returns the new surface, or NULL if there was an error.
  28.506 @@ -543,10 +588,10 @@
  28.507   */
  28.508  extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
  28.509  
  28.510 -/* Convenience macro -- load a surface from a file */
  28.511 +/** Convenience macro -- load a surface from a file */
  28.512  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
  28.513  
  28.514 -/*
  28.515 +/**
  28.516   * Save a surface to a seekable SDL data source (memory or file.)
  28.517   * If 'freedst' is non-zero, the source will be closed after being written.
  28.518   * Returns 0 if successful or -1 if there was an error.
  28.519 @@ -554,11 +599,11 @@
  28.520  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
  28.521  		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
  28.522  
  28.523 -/* Convenience macro -- save a surface to a file */
  28.524 +/** Convenience macro -- save a surface to a file */
  28.525  #define SDL_SaveBMP(surface, file) \
  28.526  		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
  28.527  
  28.528 -/*
  28.529 +/**
  28.530   * Sets the color key (transparent pixel) in a blittable surface.
  28.531   * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
  28.532   * 'key' will be the transparent pixel in the source image of a blit.
  28.533 @@ -570,7 +615,7 @@
  28.534  extern DECLSPEC int SDLCALL SDL_SetColorKey
  28.535  			(SDL_Surface *surface, Uint32 flag, Uint32 key);
  28.536  
  28.537 -/*
  28.538 +/**
  28.539   * This function sets the alpha value for the entire surface, as opposed to
  28.540   * using the alpha component of each pixel. This value measures the range
  28.541   * of transparency of the surface, 0 being completely transparent to 255
  28.542 @@ -587,7 +632,7 @@
  28.543   */
  28.544  extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
  28.545  
  28.546 -/*
  28.547 +/**
  28.548   * Sets the clipping rectangle for the destination surface in a blit.
  28.549   *
  28.550   * If the clip rectangle is NULL, clipping will be disabled.
  28.551 @@ -601,14 +646,14 @@
  28.552   */
  28.553  extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
  28.554  
  28.555 -/*
  28.556 +/**
  28.557   * Gets the clipping rectangle for the destination surface in a blit.
  28.558   * 'rect' must be a pointer to a valid rectangle which will be filled
  28.559   * with the correct values.
  28.560   */
  28.561  extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
  28.562  
  28.563 -/*
  28.564 +/**
  28.565   * Creates a new surface of the specified format, and then copies and maps 
  28.566   * the given surface to it so the blit of the converted surface will be as 
  28.567   * fast as possible.  If this function fails, it returns NULL.
  28.568 @@ -623,7 +668,7 @@
  28.569  extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
  28.570  			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
  28.571  
  28.572 -/*
  28.573 +/**
  28.574   * This performs a fast blit from the source surface to the destination
  28.575   * surface.  It assumes that the source and destination rectangles are
  28.576   * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
  28.577 @@ -679,35 +724,38 @@
  28.578   * If either of the surfaces were in video memory, and the blit returns -2,
  28.579   * the video memory was lost, so it should be reloaded with artwork and 
  28.580   * re-blitted:
  28.581 -	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  28.582 -		while ( SDL_LockSurface(image) < 0 )
  28.583 -			Sleep(10);
  28.584 -		-- Write image pixels to image->pixels --
  28.585 -		SDL_UnlockSurface(image);
  28.586 -	}
  28.587 + * @code
  28.588 + *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  28.589 + *		while ( SDL_LockSurface(image) < 0 )
  28.590 + *			Sleep(10);
  28.591 + *		-- Write image pixels to image->pixels --
  28.592 + *		SDL_UnlockSurface(image);
  28.593 + *	}
  28.594 + * @endcode
  28.595 + *
  28.596   * This happens under DirectX 5.0 when the system switches away from your
  28.597   * fullscreen application.  The lock will also fail until you have access
  28.598   * to the video memory again.
  28.599 + *
  28.600 + * You should call SDL_BlitSurface() unless you know exactly how SDL
  28.601 + * blitting works internally and how to use the other blit functions.
  28.602   */
  28.603 -/* You should call SDL_BlitSurface() unless you know exactly how SDL
  28.604 -   blitting works internally and how to use the other blit functions.
  28.605 -*/
  28.606  #define SDL_BlitSurface SDL_UpperBlit
  28.607  
  28.608 -/* This is the public blit function, SDL_BlitSurface(), and it performs
  28.609 -   rectangle validation and clipping before passing it to SDL_LowerBlit()
  28.610 -*/
  28.611 +/** This is the public blit function, SDL_BlitSurface(), and it performs
  28.612 + *  rectangle validation and clipping before passing it to SDL_LowerBlit()
  28.613 + */
  28.614  extern DECLSPEC int SDLCALL SDL_UpperBlit
  28.615  			(SDL_Surface *src, SDL_Rect *srcrect,
  28.616  			 SDL_Surface *dst, SDL_Rect *dstrect);
  28.617 -/* This is a semi-private blit function and it performs low-level surface
  28.618 -   blitting only.
  28.619 -*/
  28.620 +/** This is a semi-private blit function and it performs low-level surface
  28.621 + *  blitting only.
  28.622 + */
  28.623  extern DECLSPEC int SDLCALL SDL_LowerBlit
  28.624  			(SDL_Surface *src, SDL_Rect *srcrect,
  28.625  			 SDL_Surface *dst, SDL_Rect *dstrect);
  28.626  
  28.627 -/*
  28.628 +/**
  28.629   * This function performs a fast fill of the given rectangle with 'color'
  28.630   * The given rectangle is clipped to the destination surface clip area
  28.631   * and the final fill rectangle is saved in the passed in pointer.
  28.632 @@ -719,7 +767,7 @@
  28.633  extern DECLSPEC int SDLCALL SDL_FillRect
  28.634  		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
  28.635  
  28.636 -/* 
  28.637 +/**
  28.638   * This function takes a surface and copies it to a new surface of the
  28.639   * pixel format and colors of the video framebuffer, suitable for fast
  28.640   * blitting onto the display surface.  It calls SDL_ConvertSurface()
  28.641 @@ -732,7 +780,7 @@
  28.642   */
  28.643  extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
  28.644  
  28.645 -/* 
  28.646 +/**
  28.647   * This function takes a surface and copies it to a new surface of the
  28.648   * pixel format and colors of the video framebuffer (if possible),
  28.649   * suitable for fast alpha blitting onto the display surface.
  28.650 @@ -748,38 +796,39 @@
  28.651  
  28.652  
  28.653  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.654 -/* YUV video surface overlay functions                                       */
  28.655 +/** @name YUV video surface overlay functions                                */ /*@{*/
  28.656  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.657  
  28.658 -/* This function creates a video output overlay
  28.659 -   Calling the returned surface an overlay is something of a misnomer because
  28.660 -   the contents of the display surface underneath the area where the overlay
  28.661 -   is shown is undefined - it may be overwritten with the converted YUV data.
  28.662 -*/
  28.663 +/** This function creates a video output overlay
  28.664 + *  Calling the returned surface an overlay is something of a misnomer because
  28.665 + *  the contents of the display surface underneath the area where the overlay
  28.666 + *  is shown is undefined - it may be overwritten with the converted YUV data.
  28.667 + */
  28.668  extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
  28.669  				Uint32 format, SDL_Surface *display);
  28.670  
  28.671 -/* Lock an overlay for direct access, and unlock it when you are done */
  28.672 +/** Lock an overlay for direct access, and unlock it when you are done */
  28.673  extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
  28.674  extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
  28.675  
  28.676 -/* Blit a video overlay to the display surface.
  28.677 -   The contents of the video surface underneath the blit destination are
  28.678 -   not defined.  
  28.679 -   The width and height of the destination rectangle may be different from
  28.680 -   that of the overlay, but currently only 2x scaling is supported.
  28.681 -*/
  28.682 +/** Blit a video overlay to the display surface.
  28.683 + *  The contents of the video surface underneath the blit destination are
  28.684 + *  not defined.  
  28.685 + *  The width and height of the destination rectangle may be different from
  28.686 + *  that of the overlay, but currently only 2x scaling is supported.
  28.687 + */
  28.688  extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
  28.689  
  28.690 -/* Free a video overlay */
  28.691 +/** Free a video overlay */
  28.692  extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
  28.693  
  28.694 +/*@}*/
  28.695  
  28.696  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.697 -/* OpenGL support functions.                                                 */
  28.698 +/** @name OpenGL support functions.                                          */ /*@{*/
  28.699  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.700  
  28.701 -/*
  28.702 +/**
  28.703   * Dynamically load an OpenGL library, or the default one if path is NULL
  28.704   *
  28.705   * If you do this, you need to retrieve all of the GL functions used in
  28.706 @@ -787,17 +836,17 @@
  28.707   */
  28.708  extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
  28.709  
  28.710 -/*
  28.711 +/**
  28.712   * Get the address of a GL function
  28.713   */
  28.714  extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
  28.715  
  28.716 -/*
  28.717 +/**
  28.718   * Set an attribute of the OpenGL subsystem before intialization.
  28.719   */
  28.720  extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  28.721  
  28.722 -/*
  28.723 +/**
  28.724   * Get an attribute of the OpenGL subsystem from the windowing
  28.725   * interface, such as glX. This is of course different from getting
  28.726   * the values from SDL's internal OpenGL subsystem, which only
  28.727 @@ -808,30 +857,38 @@
  28.728   */
  28.729  extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
  28.730  
  28.731 -/*
  28.732 +/**
  28.733   * Swap the OpenGL buffers, if double-buffering is supported.
  28.734   */
  28.735  extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
  28.736  
  28.737 -/*
  28.738 +/** @name OpenGL Internal Functions
  28.739   * Internal functions that should not be called unless you have read
  28.740   * and understood the source code for these functions.
  28.741   */
  28.742 +/*@{*/
  28.743  extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
  28.744  extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
  28.745  extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
  28.746 +/*@}*/
  28.747 +
  28.748 +/*@}*/
  28.749  
  28.750  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.751 -/* These functions allow interaction with the window manager, if any.        */
  28.752 +/** @name Window Manager Functions                                           */
  28.753 +/** These functions allow interaction with the window manager, if any.       */ /*@{*/
  28.754  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  28.755  
  28.756 -/*
  28.757 - * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
  28.758 +/**
  28.759 + * Sets the title and icon text of the display window (UTF-8 encoded)
  28.760   */
  28.761  extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
  28.762 +/**
  28.763 + * Gets the title and icon text of the display window (UTF-8 encoded)
  28.764 + */
  28.765  extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
  28.766  
  28.767 -/*
  28.768 +/**
  28.769   * Sets the icon for the display window.
  28.770   * This function must be called before the first call to SDL_SetVideoMode().
  28.771   * It takes an icon surface, and a mask in MSB format.
  28.772 @@ -839,14 +896,14 @@
  28.773   */
  28.774  extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
  28.775  
  28.776 -/*
  28.777 +/**
  28.778   * This function iconifies the window, and returns 1 if it succeeded.
  28.779   * If the function succeeds, it generates an SDL_APPACTIVE loss event.
  28.780   * This function is a noop and returns 0 in non-windowed environments.
  28.781   */
  28.782  extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
  28.783  
  28.784 -/*
  28.785 +/**
  28.786   * Toggle fullscreen mode without changing the contents of the screen.
  28.787   * If the display surface does not require locking before accessing
  28.788   * the pixel information, then the memory pointers will not change.
  28.789 @@ -863,24 +920,25 @@
  28.790   */
  28.791  extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
  28.792  
  28.793 -/*
  28.794 - * This function allows you to set and query the input grab state of
  28.795 - * the application.  It returns the new input grab state.
  28.796 - */
  28.797  typedef enum {
  28.798  	SDL_GRAB_QUERY = -1,
  28.799  	SDL_GRAB_OFF = 0,
  28.800  	SDL_GRAB_ON = 1,
  28.801 -	SDL_GRAB_FULLSCREEN	/* Used internally */
  28.802 +	SDL_GRAB_FULLSCREEN	/**< Used internally */
  28.803  } SDL_GrabMode;
  28.804 -/*
  28.805 +/**
  28.806 + * This function allows you to set and query the input grab state of
  28.807 + * the application.  It returns the new input grab state.
  28.808 + *
  28.809   * Grabbing means that the mouse is confined to the application window,
  28.810   * and nearly all keyboard input is passed directly to the application,
  28.811   * and not interpreted by a window manager, if any.
  28.812   */
  28.813  extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
  28.814  
  28.815 -/* Not in public API at the moment - do not use! */
  28.816 +/*@}*/
  28.817 +
  28.818 +/** @internal Not in public API at the moment - do not use! */
  28.819  extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
  28.820                                      SDL_Surface *dst, SDL_Rect *dstrect);
  28.821                      
    29.1 --- a/include/begin_code.h	Mon Sep 21 09:27:08 2009 +0000
    29.2 +++ b/include/begin_code.h	Mon Sep 21 09:38:10 2009 +0000
    29.3 @@ -20,18 +20,26 @@
    29.4      slouken@libsdl.org
    29.5  */
    29.6  
    29.7 -/* This file sets things up for C dynamic library function definitions,
    29.8 -   static inlined functions, and structures aligned at 4-byte alignment.
    29.9 -   If you don't like ugly C preprocessor code, don't look at this file. :)
   29.10 -*/
   29.11 +/** 
   29.12 + *  @file begin_code.h
   29.13 + *  This file sets things up for C dynamic library function definitions,
   29.14 + *  static inlined functions, and structures aligned at 4-byte alignment.
   29.15 + *  If you don't like ugly C preprocessor code, don't look at this file. :)
   29.16 + */
   29.17  
   29.18 -/* This shouldn't be nested -- included it around code only. */
   29.19 +/** 
   29.20 + *  @file begin_code.h
   29.21 + *  This shouldn't be nested -- included it around code only.
   29.22 + */
   29.23  #ifdef _begin_code_h
   29.24  #error Nested inclusion of begin_code.h
   29.25  #endif
   29.26  #define _begin_code_h
   29.27  
   29.28 -/* Some compilers use a special export keyword */
   29.29 +/** 
   29.30 + *  @def DECLSPEC
   29.31 + *  Some compilers use a special export keyword
   29.32 + */
   29.33  #ifndef DECLSPEC
   29.34  # if defined(__BEOS__) || defined(__HAIKU__)
   29.35  #  if defined(__GNUC__)
   29.36 @@ -77,7 +85,10 @@
   29.37  # endif
   29.38  #endif
   29.39  
   29.40 -/* By default SDL uses the C calling convention */
   29.41 +/** 
   29.42 + *  @def SDLCALL
   29.43 + *  By default SDL uses the C calling convention
   29.44 + */
   29.45  #ifndef SDLCALL
   29.46  # if defined(__WIN32__) && !defined(__GNUC__)
   29.47  #  define SDLCALL __cdecl
   29.48 @@ -107,10 +118,12 @@
   29.49  #endif /* !EKA2 */
   29.50  #endif /* __SYMBIAN32__ */
   29.51  
   29.52 -/* Force structure packing at 4 byte alignment.
   29.53 -   This is necessary if the header is included in code which has structure
   29.54 -   packing set to an alternate value, say for loading structures from disk.
   29.55 -   The packing is reset to the previous value in close_code.h
   29.56 +/**
   29.57 + *  @file begin_code.h
   29.58 + *  Force structure packing at 4 byte alignment.
   29.59 + *  This is necessary if the header is included in code which has structure
   29.60 + *  packing set to an alternate value, say for loading structures from disk.
   29.61 + *  The packing is reset to the previous value in close_code.h 
   29.62   */
   29.63  #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__)
   29.64  #ifdef _MSC_VER
   29.65 @@ -125,7 +138,10 @@
   29.66  #pragma enumsalwaysint on
   29.67  #endif /* Compiler needs structure packing set */
   29.68  
   29.69 -/* Set up compiler-specific options for inlining functions */
   29.70 +/**
   29.71 + *  @def SDL_INLINE_OKAY
   29.72 + *  Set up compiler-specific options for inlining functions
   29.73 + */
   29.74  #ifndef SDL_INLINE_OKAY
   29.75  #ifdef __GNUC__
   29.76  #define SDL_INLINE_OKAY
   29.77 @@ -150,15 +166,20 @@
   29.78  #endif /* GNU C */
   29.79  #endif /* SDL_INLINE_OKAY */
   29.80  
   29.81 -/* If inlining isn't supported, remove "__inline__", turning static
   29.82 -   inlined functions into static functions (resulting in code bloat
   29.83 -   in all files which include the offending header files)
   29.84 -*/
   29.85 +/**
   29.86 + *  @def __inline__
   29.87 + *  If inlining isn't supported, remove "__inline__", turning static
   29.88 + *  inlined functions into static functions (resulting in code bloat
   29.89 + *  in all files which include the offending header files)
   29.90 + */
   29.91  #ifndef SDL_INLINE_OKAY
   29.92  #define __inline__
   29.93  #endif
   29.94  
   29.95 -/* Apparently this is needed by several Windows compilers */
   29.96 +/**
   29.97 + *  @def NULL
   29.98 + *  Apparently this is needed by several Windows compilers
   29.99 + */
  29.100  #if !defined(__MACH__)
  29.101  #ifndef NULL
  29.102  #ifdef __cplusplus
    30.1 --- a/include/close_code.h	Mon Sep 21 09:27:08 2009 +0000
    30.2 +++ b/include/close_code.h	Mon Sep 21 09:38:10 2009 +0000
    30.3 @@ -20,13 +20,18 @@
    30.4      slouken@libsdl.org
    30.5  */
    30.6  
    30.7 -/* This file reverses the effects of begin_code.h and should be included
    30.8 -   after you finish any function and structure declarations in your headers
    30.9 -*/
   30.10 +/**
   30.11 + *  @file close_code.h
   30.12 + *  This file reverses the effects of begin_code.h and should be included
   30.13 + *  after you finish any function and structure declarations in your headers
   30.14 + */
   30.15  
   30.16  #undef _begin_code_h
   30.17  
   30.18 -/* Reset structure packing at previous byte alignment */
   30.19 +/**
   30.20 + *  @file close_code.h
   30.21 + *  Reset structure packing at previous byte alignment
   30.22 + */
   30.23  #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__WATCOMC__)  || defined(__BORLANDC__)
   30.24  #ifdef __BORLANDC__
   30.25  #pragma nopackwarning
    31.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    31.2 +++ b/include/doxyfile	Mon Sep 21 09:38:10 2009 +0000
    31.3 @@ -0,0 +1,946 @@
    31.4 +# Doxyfile 1.2.16
    31.5 +
    31.6 +# This file describes the settings to be used by the documentation system
    31.7 +# doxygen (www.doxygen.org) for a project
    31.8 +#
    31.9 +# All text after a hash (#) is considered a comment and will be ignored
   31.10 +# The format is:
   31.11 +#       TAG = value [value, ...]
   31.12 +# For lists items can also be appended using:
   31.13 +#       TAG += value [value, ...]
   31.14 +# Values that contain spaces should be placed between quotes (" ")
   31.15 +
   31.16 +#---------------------------------------------------------------------------
   31.17 +# General configuration options
   31.18 +#---------------------------------------------------------------------------
   31.19 +
   31.20 +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
   31.21 +# by quotes) that should identify the project.
   31.22 +
   31.23 +PROJECT_NAME           = SDL
   31.24 +
   31.25 +# The PROJECT_NUMBER tag can be used to enter a project or revision number.
   31.26 +# This could be handy for archiving the generated documentation or
   31.27 +# if some version control system is used.
   31.28 +
   31.29 +PROJECT_NUMBER         = 1.2.14
   31.30 +
   31.31 +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
   31.32 +# base path where the generated documentation will be put.
   31.33 +# If a relative path is entered, it will be relative to the location
   31.34 +# where doxygen was started. If left blank the current directory will be used.
   31.35 +
   31.36 +OUTPUT_DIRECTORY       = docs
   31.37 +
   31.38 +# The OUTPUT_LANGUAGE tag is used to specify the language in which all
   31.39 +# documentation generated by doxygen is written. Doxygen will use this
   31.40 +# information to generate all constant output in the proper language.
   31.41 +# The default language is English, other supported languages are:
   31.42 +# Brazilian, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch,
   31.43 +# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean,
   31.44 +# Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovene,
   31.45 +# Spanish, Swedish and Ukrainian.
   31.46 +
   31.47 +OUTPUT_LANGUAGE        = English
   31.48 +
   31.49 +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
   31.50 +# documentation are documented, even if no documentation was available.
   31.51 +# Private class members and static file members will be hidden unless
   31.52 +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
   31.53 +
   31.54 +EXTRACT_ALL            = NO
   31.55 +
   31.56 +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
   31.57 +# will be included in the documentation.
   31.58 +
   31.59 +EXTRACT_PRIVATE        = NO
   31.60 +
   31.61 +# If the EXTRACT_STATIC tag is set to YES all static members of a file
   31.62 +# will be included in the documentation.
   31.63 +
   31.64 +EXTRACT_STATIC         = NO
   31.65 +
   31.66 +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
   31.67 +# defined locally in source files will be included in the documentation.
   31.68 +# If set to NO only classes defined in header files are included.
   31.69 +
   31.70 +EXTRACT_LOCAL_CLASSES  = NO
   31.71 +
   31.72 +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
   31.73 +# undocumented members of documented classes, files or namespaces.
   31.74 +# If set to NO (the default) these members will be included in the
   31.75 +# various overviews, but no documentation section is generated.
   31.76 +# This option has no effect if EXTRACT_ALL is enabled.
   31.77 +
   31.78 +HIDE_UNDOC_MEMBERS     = NO
   31.79 +
   31.80 +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
   31.81 +# undocumented classes that are normally visible in the class hierarchy.
   31.82 +# If set to NO (the default) these class will be included in the various
   31.83 +# overviews. This option has no effect if EXTRACT_ALL is enabled.
   31.84 +
   31.85 +HIDE_UNDOC_CLASSES     = NO
   31.86 +
   31.87 +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
   31.88 +# include brief member descriptions after the members that are listed in
   31.89 +# the file and class documentation (similar to JavaDoc).
   31.90 +# Set to NO to disable this.
   31.91 +
   31.92 +BRIEF_MEMBER_DESC      = YES
   31.93 +
   31.94 +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
   31.95 +# the brief description of a member or function before the detailed description.
   31.96 +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
   31.97 +# brief descriptions will be completely suppressed.
   31.98 +
   31.99 +REPEAT_BRIEF           = YES
  31.100 +
  31.101 +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
  31.102 +# Doxygen will generate a detailed section even if there is only a brief
  31.103 +# description.
  31.104 +
  31.105 +ALWAYS_DETAILED_SEC    = NO
  31.106 +
  31.107 +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
  31.108 +# members of a class in the documentation of that class as if those members were
  31.109 +# ordinary class members. Constructors, destructors and assignment operators of
  31.110 +# the base classes will not be shown.
  31.111 +
  31.112 +INLINE_INHERITED_MEMB  = NO
  31.113 +
  31.114 +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
  31.115 +# path before files name in the file list and in the header files. If set
  31.116 +# to NO the shortest path that makes the file name unique will be used.
  31.117 +
  31.118 +FULL_PATH_NAMES        = NO
  31.119 +
  31.120 +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
  31.121 +# can be used to strip a user defined part of the path. Stripping is
  31.122 +# only done if one of the specified strings matches the left-hand part of
  31.123 +# the path. It is allowed to use relative paths in the argument list.
  31.124 +
  31.125 +STRIP_FROM_PATH        =
  31.126 +
  31.127 +# The INTERNAL_DOCS tag determines if documentation
  31.128 +# that is typed after a \internal command is included. If the tag is set
  31.129 +# to NO (the default) then the documentation will be excluded.
  31.130 +# Set it to YES to include the internal documentation.
  31.131 +
  31.132 +INTERNAL_DOCS          = NO
  31.133 +
  31.134 +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
  31.135 +# doxygen to hide any special comment blocks from generated source code
  31.136 +# fragments. Normal C and C++ comments will always remain visible.
  31.137 +
  31.138 +STRIP_CODE_COMMENTS    = YES
  31.139 +
  31.140 +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
  31.141 +# file names in lower case letters. If set to YES upper case letters are also
  31.142 +# allowed. This is useful if you have classes or files whose names only differ
  31.143 +# in case and if your file system supports case sensitive file names. Windows
  31.144 +# users are adviced to set this option to NO.
  31.145 +
  31.146 +CASE_SENSE_NAMES       = YES
  31.147 +
  31.148 +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
  31.149 +# (but less readable) file names. This can be useful is your file systems
  31.150 +# doesn't support long names like on DOS, Mac, or CD-ROM.
  31.151 +
  31.152 +SHORT_NAMES            = NO
  31.153 +
  31.154 +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
  31.155 +# will show members with their full class and namespace scopes in the
  31.156 +# documentation. If set to YES the scope will be hidden.
  31.157 +
  31.158 +HIDE_SCOPE_NAMES       = NO
  31.159 +
  31.160 +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
  31.161 +# will generate a verbatim copy of the header file for each class for
  31.162 +# which an include is specified. Set to NO to disable this.
  31.163 +
  31.164 +VERBATIM_HEADERS       = YES
  31.165 +
  31.166 +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
  31.167 +# will put list of the files that are included by a file in the documentation
  31.168 +# of that file.
  31.169 +
  31.170 +SHOW_INCLUDE_FILES     = YES
  31.171 +
  31.172 +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
  31.173 +# will interpret the first line (until the first dot) of a JavaDoc-style
  31.174 +# comment as the brief description. If set to NO, the JavaDoc
  31.175 +# comments  will behave just like the Qt-style comments (thus requiring an
  31.176 +# explict @brief command for a brief description.
  31.177 +
  31.178 +JAVADOC_AUTOBRIEF      = NO
  31.179 +
  31.180 +# If the DETAILS_AT_TOP tag is set to YES then Doxygen
  31.181 +# will output the detailed description near the top, like JavaDoc.
  31.182 +# If set to NO, the detailed description appears after the member
  31.183 +# documentation.
  31.184 +
  31.185 +DETAILS_AT_TOP         = NO
  31.186 +
  31.187 +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
  31.188 +# member inherits the documentation from any documented member that it
  31.189 +# reimplements.
  31.190 +
  31.191 +INHERIT_DOCS           = YES
  31.192 +
  31.193 +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
  31.194 +# is inserted in the documentation for inline members.
  31.195 +
  31.196 +INLINE_INFO            = YES
  31.197 +
  31.198 +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
  31.199 +# will sort the (detailed) documentation of file and class members
  31.200 +# alphabetically by member name. If set to NO the members will appear in
  31.201 +# declaration order.
  31.202 +
  31.203 +SORT_MEMBER_DOCS       = YES
  31.204 +
  31.205 +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
  31.206 +# tag is set to YES, then doxygen will reuse the documentation of the first
  31.207 +# member in the group (if any) for the other members of the group. By default
  31.208 +# all members of a group must be documented explicitly.
  31.209 +
  31.210 +DISTRIBUTE_GROUP_DOC   = NO
  31.211 +
  31.212 +# The TAB_SIZE tag can be used to set the number of spaces in a tab.
  31.213 +# Doxygen uses this value to replace tabs by spaces in code fragments.
  31.214 +
  31.215 +TAB_SIZE               = 4
  31.216 +
  31.217 +# The GENERATE_TODOLIST tag can be used to enable (YES) or
  31.218 +# disable (NO) the todo list. This list is created by putting \todo
  31.219 +# commands in the documentation.
  31.220 +
  31.221 +GENERATE_TODOLIST      = YES
  31.222 +
  31.223 +# The GENERATE_TESTLIST tag can be used to enable (YES) or
  31.224 +# disable (NO) the test list. This list is created by putting \test
  31.225 +# commands in the documentation.
  31.226 +
  31.227 +GENERATE_TESTLIST      = YES
  31.228 +
  31.229 +# The GENERATE_BUGLIST tag can be used to enable (YES) or
  31.230 +# disable (NO) the bug list. This list is created by putting \bug
  31.231 +# commands in the documentation.
  31.232 +
  31.233 +GENERATE_BUGLIST       = YES
  31.234 +
  31.235 +# This tag can be used to specify a number of aliases that acts
  31.236 +# as commands in the documentation. An alias has the form "name=value".
  31.237 +# For example adding "sideeffect=\par Side Effects:\n" will allow you to
  31.238 +# put the command \sideeffect (or @sideeffect) in the documentation, which
  31.239 +# will result in a user defined paragraph with heading "Side Effects:".
  31.240 +# You can put \n's in the value part of an alias to insert newlines.
  31.241 +
  31.242 +ALIASES                =
  31.243 +
  31.244 +# The ENABLED_SECTIONS tag can be used to enable conditional
  31.245 +# documentation sections, marked by \if sectionname ... \endif.
  31.246 +
  31.247 +ENABLED_SECTIONS       =
  31.248 +
  31.249 +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
  31.250 +# the initial value of a variable or define consist of for it to appear in
  31.251 +# the documentation. If the initializer consists of more lines than specified
  31.252 +# here it will be hidden. Use a value of 0 to hide initializers completely.
  31.253 +# The appearance of the initializer of individual variables and defines in the
  31.254 +# documentation can be controlled using \showinitializer or \hideinitializer
  31.255 +# command in the documentation regardless of this setting.
  31.256 +
  31.257 +MAX_INITIALIZER_LINES  = 30
  31.258 +
  31.259 +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
  31.260 +# only. Doxygen will then generate output that is more tailored for C.
  31.261 +# For instance some of the names that are used will be different. The list
  31.262 +# of all members will be omitted, etc.
  31.263 +
  31.264 +OPTIMIZE_OUTPUT_FOR_C  = YES
  31.265 +
  31.266 +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
  31.267 +# only. Doxygen will then generate output that is more tailored for Java.
  31.268 +# For instance namespaces will be presented as packages, qualified scopes
  31.269 +# will look different, etc.
  31.270 +
  31.271 +OPTIMIZE_OUTPUT_JAVA   = NO
  31.272 +
  31.273 +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
  31.274 +# at the bottom of the documentation of classes and structs. If set to YES the
  31.275 +# list will mention the files that were used to generate the documentation.
  31.276 +
  31.277 +SHOW_USED_FILES        = YES
  31.278 +
  31.279 +#---------------------------------------------------------------------------
  31.280 +# configuration options related to warning and progress messages
  31.281 +#---------------------------------------------------------------------------
  31.282 +
  31.283 +# The QUIET tag can be used to turn on/off the messages that are generated
  31.284 +# by doxygen. Possible values are YES and NO. If left blank NO is used.
  31.285 +
  31.286 +QUIET                  = NO
  31.287 +
  31.288 +# The WARNINGS tag can be used to turn on/off the warning messages that are
  31.289 +# generated by doxygen. Possible values are YES and NO. If left blank
  31.290 +# NO is used.
  31.291 +
  31.292 +WARNINGS               = YES
  31.293 +
  31.294 +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
  31.295 +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
  31.296 +# automatically be disabled.
  31.297 +
  31.298 +WARN_IF_UNDOCUMENTED   = YES
  31.299 +
  31.300 +# The WARN_FORMAT tag determines the format of the warning messages that
  31.301 +# doxygen can produce. The string should contain the $file, $line, and $text
  31.302 +# tags, which will be replaced by the file and line number from which the
  31.303 +# warning originated and the warning text.
  31.304 +
  31.305 +WARN_FORMAT            = "$file:$line: $text"
  31.306 +
  31.307 +# The WARN_LOGFILE tag can be used to specify a file to which warning
  31.308 +# and error messages should be written. If left blank the output is written
  31.309 +# to stderr.
  31.310 +
  31.311 +WARN_LOGFILE           =
  31.312 +
  31.313 +#---------------------------------------------------------------------------
  31.314 +# configuration options related to the input files
  31.315 +#---------------------------------------------------------------------------
  31.316 +
  31.317 +# The INPUT tag can be used to specify the files and/or directories that contain
  31.318 +# documented source files. You may enter file names like "myfile.cpp" or
  31.319 +# directories like "/usr/src/myproject". Separate the files or directories
  31.320 +# with spaces.
  31.321 +
  31.322 +INPUT                  = include
  31.323 +
  31.324 +# If the value of the INPUT tag contains directories, you can use the
  31.325 +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
  31.326 +# and *.h) to filter out the source-files in the directories. If left
  31.327 +# blank the following patterns are tested:
  31.328 +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
  31.329 +# *.h++ *.idl *.odl
  31.330 +
  31.331 +FILE_PATTERNS          = *.h
  31.332 +
  31.333 +# The RECURSIVE tag can be used to turn specify whether or not subdirectories
  31.334 +# should be searched for input files as well. Possible values are YES and NO.
  31.335 +# If left blank NO is used.
  31.336 +
  31.337 +RECURSIVE              = NO
  31.338 +
  31.339 +# The EXCLUDE tag can be used to specify files and/or directories that should
  31.340 +# excluded from the INPUT source files. This way you can easily exclude a
  31.341 +# subdirectory from a directory tree whose root is specified with the INPUT tag.
  31.342 +
  31.343 +EXCLUDE                =
  31.344 +
  31.345 +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
  31.346 +# that are symbolic links (a Unix filesystem feature) are excluded from the input.
  31.347 +
  31.348 +EXCLUDE_SYMLINKS       = NO
  31.349 +
  31.350 +# If the value of the INPUT tag contains directories, you can use the
  31.351 +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
  31.352 +# certain files from those directories.
  31.353 +
  31.354 +EXCLUDE_PATTERNS       =
  31.355 +
  31.356 +# The EXAMPLE_PATH tag can be used to specify one or more files or
  31.357 +# directories that contain example code fragments that are included (see
  31.358 +# the \include command).
  31.359 +
  31.360 +EXAMPLE_PATH           =
  31.361 +
  31.362 +# If the value of the EXAMPLE_PATH tag contains directories, you can use the
  31.363 +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
  31.364 +# and *.h) to filter out the source-files in the directories. If left
  31.365 +# blank all files are included.
  31.366 +
  31.367 +EXAMPLE_PATTERNS       =
  31.368 +
  31.369 +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
  31.370 +# searched for input files to be used with the \include or \dontinclude
  31.371 +# commands irrespective of the value of the RECURSIVE tag.
  31.372 +# Possible values are YES and NO. If left blank NO is used.
  31.373 +
  31.374 +EXAMPLE_RECURSIVE      = NO
  31.375 +
  31.376 +# The IMAGE_PATH tag can be used to specify one or more files or
  31.377 +# directories that contain image that are included in the documentation (see
  31.378 +# the \image command).
  31.379 +
  31.380 +IMAGE_PATH             =
  31.381 +
  31.382 +# The INPUT_FILTER tag can be used to specify a program that doxygen should
  31.383 +# invoke to filter for each input file. Doxygen will invoke the filter program
  31.384 +# by executing (via popen()) the command <filter> <input-file>, where <filter>
  31.385 +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
  31.386 +# input file. Doxygen will then use the output that the filter program writes
  31.387 +# to standard output.
  31.388 +
  31.389 +INPUT_FILTER           =
  31.390 +
  31.391 +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
  31.392 +# INPUT_FILTER) will be used to filter the input files when producing source
  31.393 +# files to browse.
  31.394 +
  31.395 +FILTER_SOURCE_FILES    = NO
  31.396 +
  31.397 +#---------------------------------------------------------------------------
  31.398 +# configuration options related to source browsing
  31.399 +#---------------------------------------------------------------------------
  31.400 +
  31.401 +# If the SOURCE_BROWSER tag is set to YES then a list of source files will
  31.402 +# be generated. Documented entities will be cross-referenced with these sources.
  31.403 +
  31.404 +SOURCE_BROWSER         = NO
  31.405 +
  31.406 +# Setting the INLINE_SOURCES tag to YES will include the body
  31.407 +# of functions and classes directly in the documentation.
  31.408 +
  31.409 +INLINE_SOURCES         = NO
  31.410 +
  31.411 +# If the REFERENCED_BY_RELATION tag is set to YES (the default)
  31.412 +# then for each documented function all documented
  31.413 +# functions referencing it will be listed.
  31.414 +
  31.415 +REFERENCED_BY_RELATION = YES
  31.416 +
  31.417 +# If the REFERENCES_RELATION tag is set to YES (the default)
  31.418 +# then for each documented function all documented entities
  31.419 +# called/used by that function will be listed.
  31.420 +
  31.421 +REFERENCES_RELATION    = YES
  31.422 +
  31.423 +#---------------------------------------------------------------------------
  31.424 +# configuration options related to the alphabetical class index
  31.425 +#---------------------------------------------------------------------------
  31.426 +
  31.427 +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
  31.428 +# of all compounds will be generated. Enable this if the project
  31.429 +# contains a lot of classes, structs, unions or interfaces.
  31.430 +
  31.431 +ALPHABETICAL_INDEX     = NO
  31.432 +
  31.433 +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
  31.434 +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
  31.435 +# in which this list will be split (can be a number in the range [1..20])
  31.436 +
  31.437 +COLS_IN_ALPHA_INDEX    = 5
  31.438 +
  31.439 +# In case all classes in a project start with a common prefix, all
  31.440 +# classes will be put under the same header in the alphabetical index.
  31.441 +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
  31.442 +# should be ignored while generating the index headers.
  31.443 +
  31.444 +IGNORE_PREFIX          =
  31.445 +
  31.446 +#---------------------------------------------------------------------------
  31.447 +# configuration options related to the HTML output
  31.448 +#---------------------------------------------------------------------------
  31.449 +
  31.450 +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
  31.451 +# generate HTML output.
  31.452 +
  31.453 +GENERATE_HTML          = YES
  31.454 +
  31.455 +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
  31.456 +# If a relative path is entered the value of OUTPUT_DIRECTORY will be
  31.457 +# put in front of it. If left blank `html' will be used as the default path.
  31.458 +
  31.459 +HTML_OUTPUT            = html
  31.460 +
  31.461 +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
  31.462 +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
  31.463 +# doxygen will generate files with .html extension.
  31.464 +
  31.465 +HTML_FILE_EXTENSION    = .html
  31.466 +
  31.467 +# The HTML_HEADER tag can be used to specify a personal HTML header for
  31.468 +# each generated HTML page. If it is left blank doxygen will generate a
  31.469 +# standard header.
  31.470 +
  31.471 +HTML_HEADER            =
  31.472 +
  31.473 +# The HTML_FOOTER tag can be used to specify a personal HTML footer for
  31.474 +# each generated HTML page. If it is left blank doxygen will generate a
  31.475 +# standard footer.
  31.476 +
  31.477 +HTML_FOOTER            =
  31.478 +
  31.479 +# The HTML_STYLESHEET tag can be used to specify a user defined cascading
  31.480 +# style sheet that is used by each HTML page. It can be used to
  31.481 +# fine-tune the look of the HTML output. If the tag is left blank doxygen
  31.482 +# will generate a default style sheet
  31.483 +
  31.484 +HTML_STYLESHEET        =
  31.485 +
  31.486 +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
  31.487 +# files or namespaces will be aligned in HTML using tables. If set to
  31.488 +# NO a bullet list will be used.
  31.489 +
  31.490 +HTML_ALIGN_MEMBERS     = YES
  31.491 +
  31.492 +# If the GENERATE_HTMLHELP tag is set to YES, additional index files
  31.493 +# will be generated that can be used as input for tools like the
  31.494 +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
  31.495 +# of the generated HTML documentation.
  31.496 +
  31.497 +GENERATE_HTMLHELP      = NO
  31.498 +
  31.499 +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
  31.500 +# controls if a separate .chi index file is generated (YES) or that
  31.501 +# it should be included in the master .chm file (NO).
  31.502 +
  31.503 +GENERATE_CHI           = NO
  31.504 +
  31.505 +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
  31.506 +# controls whether a binary table of contents is generated (YES) or a
  31.507 +# normal table of contents (NO) in the .chm file.
  31.508 +
  31.509 +BINARY_TOC             = NO
  31.510 +
  31.511 +# The TOC_EXPAND flag can be set to YES to add extra items for group members
  31.512 +# to the contents of the Html help documentation and to the tree view.
  31.513 +
  31.514 +TOC_EXPAND             = NO
  31.515 +
  31.516 +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
  31.517 +# top of each HTML page. The value NO (the default) enables the index and
  31.518 +# the value YES disables it.
  31.519 +
  31.520 +DISABLE_INDEX          = NO
  31.521 +
  31.522 +# This tag can be used to set the number of enum values (range [1..20])
  31.523 +# that doxygen will group on one line in the generated HTML documentation.
  31.524 +
  31.525 +ENUM_VALUES_PER_LINE   = 4
  31.526 +
  31.527 +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
  31.528 +# generated containing a tree-like index structure (just like the one that
  31.529 +# is generated for HTML Help). For this to work a browser that supports
  31.530 +# JavaScript and frames is required (for instance Mozilla, Netscape 4.0+,
  31.531 +# or Internet explorer 4.0+). Note that for large projects the tree generation
  31.532 +# can take a very long time. In such cases it is better to disable this feature.
  31.533 +# Windows users are probably better off using the HTML help feature.
  31.534 +
  31.535 +GENERATE_TREEVIEW      = NO
  31.536 +
  31.537 +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
  31.538 +# used to set the initial width (in pixels) of the frame in which the tree
  31.539 +# is shown.
  31.540 +
  31.541 +TREEVIEW_WIDTH         = 250
  31.542 +
  31.543 +#---------------------------------------------------------------------------
  31.544 +# configuration options related to the LaTeX output
  31.545 +#---------------------------------------------------------------------------
  31.546 +
  31.547 +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
  31.548 +# generate Latex output.
  31.549 +
  31.550 +GENERATE_LATEX         = NO
  31.551 +
  31.552 +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
  31.553 +# If a relative path is entered the value of OUTPUT_DIRECTORY will be
  31.554 +# put in front of it. If left blank `latex' will be used as the default path.
  31.555 +
  31.556 +LATEX_OUTPUT           = latex
  31.557 +
  31.558 +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be invoked. If left blank `latex' will be used as the default command name.
  31.559 +
  31.560 +LATEX_CMD_NAME         = latex
  31.561 +
  31.562 +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
  31.563 +# generate index for LaTeX. If left blank `makeindex' will be used as the
  31.564 +# default command name.
  31.565 +
  31.566 +MAKEINDEX_CMD_NAME     = makeindex
  31.567 +
  31.568 +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
  31.569 +# LaTeX documents. This may be useful for small projects and may help to
  31.570 +# save some trees in general.
  31.571 +
  31.572 +COMPACT_LATEX          = NO
  31.573 +
  31.574 +# The PAPER_TYPE tag can be used to set the paper type that is used
  31.575 +# by the printer. Possible values are: a4, a4wide, letter, legal and
  31.576 +# executive. If left blank a4wide will be used.
  31.577 +
  31.578 +PAPER_TYPE             = a4wide
  31.579 +
  31.580 +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
  31.581 +# packages that should be included in the LaTeX output.
  31.582 +
  31.583 +EXTRA_PACKAGES         =
  31.584 +
  31.585 +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
  31.586 +# the generated latex document. The header should contain everything until
  31.587 +# the first chapter. If it is left blank doxygen will generate a
  31.588 +# standard header. Notice: only use this tag if you know what you are doing!
  31.589 +
  31.590 +LATEX_HEADER           =
  31.591 +
  31.592 +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
  31.593 +# is prepared for conversion to pdf (using ps2pdf). The pdf file will
  31.594 +# contain links (just like the HTML output) instead of page references
  31.595 +# This makes the output suitable for online browsing using a pdf viewer.
  31.596 +
  31.597 +PDF_HYPERLINKS         = NO
  31.598 +
  31.599 +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
  31.600 +# plain latex in the generated Makefile. Set this option to YES to get a
  31.601 +# higher quality PDF documentation.
  31.602 +
  31.603 +USE_PDFLATEX           = NO
  31.604 +
  31.605 +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
  31.606 +# command to the generated LaTeX files. This will instruct LaTeX to keep
  31.607 +# running if errors occur, instead of asking the user for help.
  31.608 +# This option is also used when generating formulas in HTML.
  31.609 +
  31.610 +LATEX_BATCHMODE        = NO
  31.611 +
  31.612 +#---------------------------------------------------------------------------
  31.613 +# configuration options related to the RTF output
  31.614 +#---------------------------------------------------------------------------
  31.615 +
  31.616 +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
  31.617 +# The RTF output is optimised for Word 97 and may not look very pretty with
  31.618 +# other RTF readers or editors.
  31.619 +
  31.620 +GENERATE_RTF           = YES
  31.621 +
  31.622 +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
  31.623 +# If a relative path is entered the value of OUTPUT_DIRECTORY will be
  31.624 +# put in front of it. If left blank `rtf' will be used as the default path.
  31.625 +
  31.626 +RTF_OUTPUT             = rtf
  31.627 +
  31.628 +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
  31.629 +# RTF documents. This may be useful for small projects and may help to
  31.630 +# save some trees in general.
  31.631 +
  31.632 +COMPACT_RTF            = NO
  31.633 +
  31.634 +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
  31.635 +# will contain hyperlink fields. The RTF file will
  31.636 +# contain links (just like the HTML output) instead of page references.
  31.637 +# This makes the output suitable for online browsing using WORD or other
  31.638 +# programs which support those fields.
  31.639 +# Note: wordpad (write) and others do not support links.
  31.640 +
  31.641 +RTF_HYPERLINKS         = NO
  31.642 +
  31.643 +# Load stylesheet definitions from file. Syntax is similar to doxygen's
  31.644 +# config file, i.e. a series of assigments. You only have to provide
  31.645 +# replacements, missing definitions are set to their default value.
  31.646 +
  31.647 +RTF_STYLESHEET_FILE    =
  31.648 +
  31.649 +# Set optional variables used in the generation of an rtf document.
  31.650 +# Syntax is similar to doxygen's config file.
  31.651 +
  31.652 +RTF_EXTENSIONS_FILE    =
  31.653 +
  31.654 +#---------------------------------------------------------------------------
  31.655 +# configuration options related to the man page output
  31.656 +#---------------------------------------------------------------------------
  31.657 +
  31.658 +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
  31.659 +# generate man pages
  31.660 +
  31.661 +GENERATE_MAN           = YES
  31.662 +
  31.663 +# The MAN_OUTPUT tag is used to specify where the man pages will be put.
  31.664 +# If a relative path is entered the value of OUTPUT_DIRECTORY will be
  31.665 +# put in front of it. If left blank `man' will be used as the default path.
  31.666 +
  31.667 +MAN_OUTPUT             = man
  31.668 +
  31.669 +# The MAN_EXTENSION tag determines the extension that is added to
  31.670 +# the generated man pages (default is the subroutine's section .3)
  31.671 +
  31.672 +MAN_EXTENSION          = .3
  31.673 +
  31.674 +# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
  31.675 +# then it will generate one additional man file for each entity
  31.676 +# documented in the real man page(s). These additional files
  31.677 +# only source the real man page, but without them the man command
  31.678 +# would be unable to find the correct page. The default is NO.
  31.679 +
  31.680 +MAN_LINKS              = YES
  31.681 +
  31.682 +#---------------------------------------------------------------------------
  31.683 +# configuration options related to the XML output
  31.684 +#---------------------------------------------------------------------------
  31.685 +
  31.686 +# If the GENERATE_XML tag is set to YES Doxygen will
  31.687 +# generate an XML file that captures the structure of
  31.688 +# the code including all documentation. Note that this
  31.689 +# feature is still experimental and incomplete at the
  31.690 +# moment.
  31.691 +
  31.692 +GENERATE_XML           = NO
  31.693 +
  31.694 +#---------------------------------------------------------------------------
  31.695 +# configuration options for the AutoGen Definitions output
  31.696 +#---------------------------------------------------------------------------
  31.697 +
  31.698 +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
  31.699 +# generate an AutoGen Definitions (see autogen.sf.net) file
  31.700 +# that captures the structure of the code including all
  31.701 +# documentation. Note that this feature is still experimental
  31.702 +# and incomplete at the moment.
  31.703 +
  31.704 +GENERATE_AUTOGEN_DEF   = NO
  31.705 +
  31.706 +#---------------------------------------------------------------------------
  31.707 +# Configuration options related to the preprocessor
  31.708 +#---------------------------------------------------------------------------
  31.709 +
  31.710 +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
  31.711 +# evaluate all C-preprocessor directives found in the sources and include
  31.712 +# files.
  31.713 +
  31.714 +ENABLE_PREPROCESSING   = YES
  31.715 +
  31.716 +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
  31.717 +# names in the source code. If set to NO (the default) only conditional
  31.718 +# compilation will be performed. Macro expansion can be done in a controlled
  31.719 +# way by setting EXPAND_ONLY_PREDEF to YES.
  31.720 +
  31.721 +MACRO_EXPANSION        = YES
  31.722 +
  31.723 +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
  31.724 +# then the macro expansion is limited to the macros specified with the
  31.725 +# PREDEFINED and EXPAND_AS_PREDEFINED tags.
  31.726 +
  31.727 +EXPAND_ONLY_PREDEF     = YES
  31.728 +
  31.729 +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
  31.730 +# in the INCLUDE_PATH (see below) will be search if a #include is found.
  31.731 +
  31.732 +SEARCH_INCLUDES        = YES
  31.733 +
  31.734 +# The INCLUDE_PATH tag can be used to specify one or more directories that
  31.735 +# contain include files that are not input files but should be processed by
  31.736 +# the preprocessor.
  31.737 +
  31.738 +INCLUDE_PATH           =
  31.739 +
  31.740 +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
  31.741 +# patterns (like *.h and *.hpp) to filter out the header-files in the
  31.742 +# directories. If left blank, the patterns specified with FILE_PATTERNS will
  31.743 +# be used.
  31.744 +
  31.745 +INCLUDE_FILE_PATTERNS  =
  31.746 +
  31.747 +# The PREDEFINED tag can be used to specify one or more macro names that
  31.748 +# are defined before the preprocessor is started (similar to the -D option of
  31.749 +# gcc). The argument of the tag is a list of macros of the form: name
  31.750 +# or name=definition (no spaces). If the definition and the = are
  31.751 +# omitted =1 is assumed.
  31.752 +
  31.753 +PREDEFINED             = DOXYGEN_SHOULD_IGNORE_THIS=1 SDLCALL= SNDDECLSPEC=
  31.754 +
  31.755 +# If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then
  31.756 +# this tag can be used to specify a list of macro names that should be expanded.
  31.757 +# The macro definition that is found in the sources will be used.
  31.758 +# Use the PREDEFINED tag if you want to use a different macro definition.
  31.759 +
  31.760 +EXPAND_AS_DEFINED      =
  31.761 +
  31.762 +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
  31.763 +# doxygen's preprocessor will remove all function-like macros that are alone
  31.764 +# on a line and do not end with a semicolon. Such function macros are typically
  31.765 +# used for boiler-plate code, and will confuse the parser if not removed.
  31.766 +
  31.767 +SKIP_FUNCTION_MACROS   = YES
  31.768 +
  31.769 +#---------------------------------------------------------------------------
  31.770 +# Configuration::addtions related to external references
  31.771 +#---------------------------------------------------------------------------
  31.772 +
  31.773 +# The TAGFILES tag can be used to specify one or more tagfiles.
  31.774 +
  31.775 +TAGFILES               =
  31.776 +
  31.777 +# When a file name is specified after GENERATE_TAGFILE, doxygen will create
  31.778 +# a tag file that is based on the input files it reads.
  31.779 +
  31.780 +GENERATE_TAGFILE       =
  31.781 +
  31.782 +# If the ALLEXTERNALS tag is set to YES all external classes will be listed
  31.783 +# in the class index. If set to NO only the inherited external classes
  31.784 +# will be listed.
  31.785 +
  31.786 +ALLEXTERNALS           = NO
  31.787 +
  31.788 +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
  31.789 +# in the modules index. If set to NO, only the current project's groups will
  31.790 +# be listed.
  31.791 +
  31.792 +EXTERNAL_GROUPS        = YES
  31.793 +
  31.794 +# The PERL_PATH should be the absolute path and name of the perl script
  31.795 +# interpreter (i.e. the result of `which perl').
  31.796 +
  31.797 +PERL_PATH              = /usr/bin/perl
  31.798 +
  31.799 +#---------------------------------------------------------------------------
  31.800 +# Configuration options related to the dot tool
  31.801 +#---------------------------------------------------------------------------
  31.802 +
  31.803 +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
  31.804 +# generate a inheritance diagram (in Html, RTF and LaTeX) for classes with base or
  31.805 +# super classes. Setting the tag to NO turns the diagrams off. Note that this
  31.806 +# option is superceded by the HAVE_DOT option below. This is only a fallback. It is
  31.807 +# recommended to install and use dot, since it yields more powerful graphs.
  31.808 +
  31.809 +CLASS_DIAGRAMS         = NO
  31.810 +
  31.811 +# If set to YES, the inheritance and collaboration graphs will hide
  31.812 +# inheritance and usage relations if the target is undocumented
  31.813 +# or is not a class.
  31.814 +
  31.815 +HIDE_UNDOC_RELATIONS   = YES
  31.816 +
  31.817 +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
  31.818 +# available from the path. This tool is part of Graphviz, a graph visualization
  31.819 +# toolkit from AT&T and Lucent Bell Labs. The other options in this section
  31.820 +# have no effect if this option is set to NO (the default)
  31.821 +
  31.822 +HAVE_DOT               = NO
  31.823 +
  31.824 +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
  31.825 +# will generate a graph for each documented class showing the direct and
  31.826 +# indirect inheritance relations. Setting this tag to YES will force the
  31.827 +# the CLASS_DIAGRAMS tag to NO.
  31.828 +
  31.829 +CLASS_GRAPH            = NO
  31.830 +
  31.831 +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
  31.832 +# will generate a graph for each documented class showing the direct and
  31.833 +# indirect implementation dependencies (inheritance, containment, and
  31.834 +# class references variables) of the class with other documented classes.
  31.835 +
  31.836 +COLLABORATION_GRAPH    = NO
  31.837 +
  31.838 +# If set to YES, the inheritance and collaboration graphs will show the
  31.839 +# relations between templates and their instances.
  31.840 +
  31.841 +TEMPLATE_RELATIONS     = NO
  31.842 +
  31.843 +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
  31.844 +# tags are set to YES then doxygen will generate a graph for each documented
  31.845 +# file showing the direct and indirect include dependencies of the file with
  31.846 +# other documented files.
  31.847 +
  31.848 +INCLUDE_GRAPH          = NO
  31.849 +
  31.850 +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
  31.851 +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
  31.852 +# documented header file showing the documented files that directly or
  31.853 +# indirectly include this file.
  31.854 +
  31.855 +INCLUDED_BY_GRAPH      = YES
  31.856 +
  31.857 +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
  31.858 +# will graphical hierarchy of all classes instead of a textual one.
  31.859 +
  31.860 +GRAPHICAL_HIERARCHY    = YES
  31.861 +
  31.862 +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
  31.863 +# generated by dot. Possible values are png, jpg, or gif
  31.864 +# If left blank png will be used.
  31.865 +
  31.866 +DOT_IMAGE_FORMAT       = png
  31.867 +
  31.868 +# The tag DOT_PATH can be used to specify the path where the dot tool can be
  31.869 +# found. If left blank, it is assumed the dot tool can be found on the path.
  31.870 +
  31.871 +DOT_PATH               =
  31.872 +
  31.873 +# The DOTFILE_DIRS tag can be used to specify one or more directories that
  31.874 +# contain dot files that are included in the documentation (see the
  31.875 +# \dotfile command).
  31.876 +
  31.877 +DOTFILE_DIRS           =
  31.878 +
  31.879 +# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
  31.880 +# (in pixels) of the graphs generated by dot. If a graph becomes larger than
  31.881 +# this value, doxygen will try to truncate the graph, so that it fits within
  31.882 +# the specified constraint. Beware that most browsers cannot cope with very
  31.883 +# large images.
  31.884 +
  31.885 +MAX_DOT_GRAPH_WIDTH    = 1024
  31.886 +
  31.887 +# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
  31.888 +# (in pixels) of the graphs generated by dot. If a graph becomes larger than
  31.889 +# this value, doxygen will try to truncate the graph, so that it fits within
  31.890 +# the specified constraint. Beware that most browsers cannot cope with very
  31.891 +# large images.
  31.892 +
  31.893 +MAX_DOT_GRAPH_HEIGHT   = 1024
  31.894 +
  31.895 +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
  31.896 +# generate a legend page explaining the meaning of the various boxes and
  31.897 +# arrows in the dot generated graphs.
  31.898 +
  31.899 +GENERATE_LEGEND        = YES
  31.900 +
  31.901 +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
  31.902 +# remove the intermedate dot files that are used to generate
  31.903 +# the various graphs.
  31.904 +
  31.905 +DOT_CLEANUP            = YES
  31.906 +
  31.907 +#---------------------------------------------------------------------------
  31.908 +# Configuration::addtions related to the search engine
  31.909 +#---------------------------------------------------------------------------
  31.910 +
  31.911 +# The SEARCHENGINE tag specifies whether or not a search engine should be
  31.912 +# used. If set to NO the values of all tags below this one will be ignored.
  31.913 +
  31.914 +SEARCHENGINE           = NO
  31.915 +
  31.916 +# The CGI_NAME tag should be the name of the CGI script that
  31.917 +# starts the search engine (doxysearch) with the correct parameters.
  31.918 +# A script with this name will be generated by doxygen.
  31.919 +
  31.920 +CGI_NAME               = search.cgi
  31.921 +
  31.922 +# The CGI_URL tag should be the absolute URL to the directory where the
  31.923 +# cgi binaries are located. See the documentation of your http daemon for
  31.924 +# details.
  31.925 +
  31.926 +CGI_URL                =
  31.927 +
  31.928 +# The DOC_URL tag should be the absolute URL to the directory where the
  31.929 +# documentation is located. If left blank the absolute path to the
  31.930 +# documentation, with file:// prepended to it, will be used.
  31.931 +
  31.932 +DOC_URL                =
  31.933 +
  31.934 +# The DOC_ABSPATH tag should be the absolute path to the directory where the
  31.935 +# documentation is located. If left blank the directory on the local machine
  31.936 +# will be used.
  31.937 +
  31.938 +DOC_ABSPATH            =
  31.939 +
  31.940 +# The BIN_ABSPATH tag must point to the directory where the doxysearch binary
  31.941 +# is installed.
  31.942 +
  31.943 +BIN_ABSPATH            = /usr/local/bin/
  31.944 +
  31.945 +# The EXT_DOC_PATHS tag can be used to specify one or more paths to
  31.946 +# documentation generated for other projects. This allows doxysearch to search
  31.947 +# the documentation for these projects as well.
  31.948 +
  31.949 +EXT_DOC_PATHS          =