Sync SDL3 wiki -> header

include/SDL3/SDL_audio.h

@@ -989,32 +989,34 @@ extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
 /**
  * A callback that fires when data passes through an SDL_AudioStream.
  *
- * Apps can (optionally) register a callback with an audio stream that
- * is called when data is added with SDL_PutAudioStreamData, or requested
- * with SDL_GetAudioStreamData.
+ * Apps can (optionally) register a callback with an audio stream that is
+ * called when data is added with SDL_PutAudioStreamData, or requested with
+ * SDL_GetAudioStreamData.
  *
- * Two values are offered here: one is the amount of additional data needed
- * to satisfy the immediate request (which might be zero if the stream
- * already has enough data queued) and the other is the total amount
- * being requested. In a Get call triggering a Put callback, these
- * values can be different. In a Put call triggering a Get callback,
- * these values are always the same.
+ * Two values are offered here: one is the amount of additional data needed to
+ * satisfy the immediate request (which might be zero if the stream already
+ * has enough data queued) and the other is the total amount being requested.
+ * In a Get call triggering a Put callback, these values can be different. In
+ * a Put call triggering a Get callback, these values are always the same.
  *
- * Byte counts might be slightly overestimated due to buffering or
- * resampling, and may change from call to call.
+ * Byte counts might be slightly overestimated due to buffering or resampling,
+ * and may change from call to call.
  *
- * This callback is not required to do anything. Generally this is useful
- * for adding/reading data on demand, and the app will often put/get data as
- * appropriate, but the system goes on with the data currently available
- * to it if this callback does nothing.
+ * This callback is not required to do anything. Generally this is useful for
+ * adding/reading data on demand, and the app will often put/get data as
+ * appropriate, but the system goes on with the data currently available to it
+ * if this callback does nothing.
  *
  * \param stream The SDL audio stream associated with this callback.
- * \param additional_amount The amount of data, in bytes, that is needed right now.
- * \param total_amount The total amount of data requested, in bytes, that is requested or available.
- * \param userdata An opaque pointer provided by the app for their personal use.
- *
- * \threadsafety This callbacks may run from any thread, so if you need
- *               to protect shared data, you should use SDL_LockAudioStream to
+ * \param additional_amount The amount of data, in bytes, that is needed right
+ *                          now.
+ * \param total_amount The total amount of data requested, in bytes, that is
+ *                     requested or available.
+ * \param userdata An opaque pointer provided by the app for their personal
+ *                 use.
+ *
+ * \threadsafety This callbacks may run from any thread, so if you need to
+ *               protect shared data, you should use SDL_LockAudioStream to
  *               serialize access; this lock will be held before your callback
  *               is called, so your callback does not need to manage the lock
  *               explicitly.
@@ -1202,21 +1204,21 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDevi
  * device, which can cause audio playback problems.
  *
  * The postmix callback _must_ be able to handle any audio data format
- * specified in `spec`, which can change between callbacks if the audio
- * device changed. However, this only covers frequency and channel count;
- * data is always provided here in SDL_AUDIO_F32 format.
+ * specified in `spec`, which can change between callbacks if the audio device
+ * changed. However, this only covers frequency and channel count; data is
+ * always provided here in SDL_AUDIO_F32 format.
  *
  * \param userdata a pointer provided by the app through
- *        SDL_SetAudioDevicePostmixCallback, for its own use.
+ *                 SDL_SetAudioDevicePostmixCallback, for its own use.
  * \param spec the current format of audio that is to be submitted to the
- *        audio device.
- * \param buffer the buffer of audio samples to be submitted. The callback
- *        can inspect and/or modify this data.
+ *             audio device.
+ * \param buffer the buffer of audio samples to be submitted. The callback can
+ *               inspect and/or modify this data.
  * \param buflen the size of `buffer` in bytes.
  *
- * \threadsafety This will run from a background thread owned by SDL.
- *               The application is responsible for locking resources the
- *               callback touches that need to be protected.
+ * \threadsafety This will run from a background thread owned by SDL. The
+ *               application is responsible for locking resources the callback
+ *               touches that need to be protected.
  *
  * \since This datatype is available since SDL 3.0.0.
  *

include/SDL3/SDL_camera.h

@@ -38,11 +38,13 @@ extern "C" {
 #endif
 
 /**
- * This is a unique ID for a camera device for the time it is connected to the system,
- * and is never reused for the lifetime of the application. If the device is
- * disconnected and reconnected, it will get a new ID.
+ * This is a unique ID for a camera device for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
  *
- * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
+ * If the device is disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 1 and increments from there. The value 0 is an
+ * invalid ID.
  *
  * \sa SDL_GetCameraDevices
  */

include/SDL3/SDL_clipboard.h

@@ -134,18 +134,19 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
  * Callback function that will be called when data for the specified mime-type
  * is requested by the OS.
  *
- * The callback function is called with NULL as the mime_type when the clipboard
- * is cleared or new data is set. The clipboard is automatically cleared in SDL_Quit().
+ * The callback function is called with NULL as the mime_type when the
+ * clipboard is cleared or new data is set. The clipboard is automatically
+ * cleared in SDL_Quit().
  *
- * \param userdata  A pointer to provided user data
+ * \param userdata A pointer to provided user data
  * \param mime_type The requested mime-type
- * \param size      A pointer filled in with the length of the returned data
- * \returns a pointer to the data for the provided mime-type. Returning NULL or
- *          setting length to 0 will cause no data to be sent to the "receiver". It is
- *          up to the receiver to handle this. Essentially returning no data is more or
- *          less undefined behavior and may cause breakage in receiving applications.
- *          The returned data will not be freed so it needs to be retained and dealt
- *          with internally.
+ * \param size A pointer filled in with the length of the returned data
+ * \returns a pointer to the data for the provided mime-type. Returning NULL
+ *          or setting length to 0 will cause no data to be sent to the
+ *          "receiver". It is up to the receiver to handle this. Essentially
+ *          returning no data is more or less undefined behavior and may cause
+ *          breakage in receiving applications. The returned data will not be
+ *          freed so it needs to be retained and dealt with internally.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -154,7 +155,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
 typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size);
 
 /**
- * Callback function that will be called when the clipboard is cleared, or new data is set.
+ * Callback function that will be called when the clipboard is cleared, or new
+ * data is set.
  *
  * \param userdata A pointer to provided user data
  *

include/SDL3/SDL_dialog.h

@@ -58,12 +58,11 @@ typedef struct SDL_DialogFileFilter
  *
  * The specific usage is described in each function.
  *
- * If filelist is...
- * - `NULL`, an error occured. Details can be obtained with SDL_GetError().
- * - A pointer to `NULL`, the user either didn't choose any file or canceled
- *   the dialog.
- * - A pointer to non-`NULL`, the user chose one or more files. The argument is
- *   a null-terminated list of pointers to C strings, each containing a path.
+ * If filelist is... - `NULL`, an error occured. Details can be obtained with
+ * SDL_GetError(). - A pointer to `NULL`, the user either didn't choose any
+ * file or canceled the dialog. - A pointer to non-`NULL`, the user chose one
+ * or more files. The argument is a null-terminated list of pointers to C
+ * strings, each containing a path.
  *
  * The filelist argument does not need to be freed; it will automatically be
  * freed when the callback returns.

include/SDL3/SDL_events.h

@@ -1100,11 +1100,11 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
 /**
  * A function pointer used for callbacks that watch the event queue.
  *
- * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
- *        or SDL_AddEventWatch, etc
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
+ *                 SDL_AddEventWatch, etc
  * \param event the event that triggered the callback
- * \returns 1 to permit event to be added to the queue, and 0 to disallow
- *          it. When used with SDL_AddEventWatch, the return value is ignored.
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow it.
+ *          When used with SDL_AddEventWatch, the return value is ignored.
  *
  * \threadsafety SDL may call this callback at any time from any thread; the
  *               application is responsible for locking resources the callback

include/SDL3/SDL_haptic.h

@@ -851,9 +851,13 @@ typedef union SDL_HapticEffect
 } SDL_HapticEffect;
 
 /**
- * This is a unique ID for a haptic device for the time it is connected to the system, and is never reused for the lifetime of the application. If the haptic device is disconnected and reconnected, it will get a new ID.
+ * This is a unique ID for a haptic device for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
  *
- * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
+ * If the haptic device is disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 1 and increments from there. The value 0 is an
+ * invalid ID.
  */
 typedef Uint32 SDL_HapticID;
 

include/SDL3/SDL_joystick.h

@@ -76,11 +76,13 @@ typedef struct SDL_Joystick SDL_Joystick;
 typedef SDL_GUID SDL_JoystickGUID;
 
 /**
- * This is a unique ID for a joystick for the time it is connected to the system,
- * and is never reused for the lifetime of the application. If the joystick is
- * disconnected and reconnected, it will get a new ID.
+ * This is a unique ID for a joystick for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
  *
- * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
+ * If the joystick is disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 1 and increments from there. The value 0 is an
+ * invalid ID.
  */
 typedef Uint32 SDL_JoystickID;
 

include/SDL3/SDL_keycode.h

@@ -32,18 +32,18 @@
 #include <SDL3/SDL_scancode.h>
 
 /**
- *  The SDL virtual key representation.
+ * The SDL virtual key representation.
  *
- *  Values of this type are used to represent keyboard keys using the current
- *  layout of the keyboard.  These values include Unicode values representing
- *  the unmodified character that would be generated by pressing the key, or
- *  an `SDLK_*` constant for those keys that do not generate characters.
+ * Values of this type are used to represent keyboard keys using the current
+ * layout of the keyboard. These values include Unicode values representing
+ * the unmodified character that would be generated by pressing the key, or an
+ * `SDLK_*` constant for those keys that do not generate characters.
  *
- *  A special exception is the number keys at the top of the keyboard which
- *  map to SDLK_0...SDLK_9 on AZERTY layouts.
+ * A special exception is the number keys at the top of the keyboard which map
+ * to SDLK_0...SDLK_9 on AZERTY layouts.
  *
- *  The list of `SDLK_*` values are in SDL_KeyCode, which is an enum, while
- *  SDL_Keycode is an integer.
+ * The list of `SDLK_*` values are in SDL_KeyCode, which is an enum, while
+ * SDL_Keycode is an integer.
  *
  * \since This datatype is available since SDL 3.0.0.
  *

include/SDL3/SDL_main.h

@@ -366,7 +366,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate);
 
 
 /**
- *  The prototype for the application's main() function
+ * The prototype for the application's main() function
  */
 typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
 extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]);

include/SDL3/SDL_metal.h

@@ -37,9 +37,7 @@ extern "C" {
 #endif
 
 /**
- *  A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
- *
- *  \note This can be cast directly to an NSView or UIView.
+ * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
  */
 typedef void *SDL_MetalView;
 

include/SDL3/SDL_sensor.h

@@ -52,10 +52,11 @@ struct SDL_Sensor;
 typedef struct SDL_Sensor SDL_Sensor;
 
 /**
- * This is a unique ID for a sensor for the time it is connected to the system,
- * and is never reused for the lifetime of the application.
+ * This is a unique ID for a sensor for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
  *
- * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
+ * The ID value starts at 1 and increments from there. The value 0 is an
+ * invalid ID.
  */
 typedef Uint32 SDL_SensorID;
 

include/SDL3/SDL_timer.h

@@ -127,14 +127,16 @@ extern DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns);
 /**
  * Function prototype for the timer callback function.
  *
- * The callback function is passed the current timer interval and returns
- * the next timer interval, in milliseconds. If the returned value is the same as the one
- * passed in, the periodic alarm continues, otherwise a new alarm is
+ * The callback function is passed the current timer interval and returns the
+ * next timer interval, in milliseconds. If the returned value is the same as
+ * the one passed in, the periodic alarm continues, otherwise a new alarm is
  * scheduled. If the callback returns 0, the periodic alarm is cancelled.
  *
  * \param interval the current callback time interval.
- * \param param an arbitrary pointer provided by the app through SDL_AddTimer, for its own use.
- * \returns the new callback time interval, or 0 to disable further runs of the callback.
+ * \param param an arbitrary pointer provided by the app through SDL_AddTimer,
+ *              for its own use.
+ * \returns the new callback time interval, or 0 to disable further runs of
+ *          the callback.
  *
  * \threadsafety SDL may call this callback at any time from a background
  *               thread; the application is responsible for locking resources

include/SDL3/SDL_video.h

@@ -121,10 +121,10 @@ typedef struct SDL_Window SDL_Window;
 /**
  * The flags on a window.
  *
- * These cover a lot of true/false, or on/off, window state. Some of it
- * is immutable after being set through SDL_CreateWindow(), some of it can
- * be changed on existing windows by the app, and some of it might be altered
- * by the user or system outside of the app's control.
+ * These cover a lot of true/false, or on/off, window state. Some of it is
+ * immutable after being set through SDL_CreateWindow(), some of it can be
+ * changed on existing windows by the app, and some of it might be altered by
+ * the user or system outside of the app's control.
  *
  * \sa SDL_GetWindowFlags
  */
@@ -185,12 +185,12 @@ typedef enum SDL_FlashOperation
 } SDL_FlashOperation;
 
 /**
- *  An opaque handle to an OpenGL context.
+ * An opaque handle to an OpenGL context.
  */
 typedef void *SDL_GLContext;
 
 /**
- *  Opaque EGL types.
+ * Opaque EGL types.
  */
 typedef void *SDL_EGLDisplay;
 typedef void *SDL_EGLConfig;
@@ -199,7 +199,7 @@ typedef intptr_t SDL_EGLAttrib;
 typedef int SDL_EGLint;
 
 /**
- *  EGL attribute initialization callback types.
+ * EGL attribute initialization callback types.
  */
 typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void);
 typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);