SDL: Sync SDL3 wiki -> header (073d2)

From 073d2378dcf6f282dfa8b68c381ed01aeb048bc5 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Thu, 11 Apr 2024 12:59:41 +0000
Subject: [PATCH] Sync SDL3 wiki -> header

---
 include/SDL3/SDL_audio.h     | 64 +++++++++++++++++++-----------------
 include/SDL3/SDL_camera.h    | 10 +++---
 include/SDL3/SDL_clipboard.h | 24 +++++++-------
 include/SDL3/SDL_dialog.h    | 11 +++----
 include/SDL3/SDL_events.h    |  8 ++---
 include/SDL3/SDL_haptic.h    |  8 +++--
 include/SDL3/SDL_joystick.h  | 10 +++---
 include/SDL3/SDL_keycode.h   | 18 +++++-----
 include/SDL3/SDL_main.h      |  2 +-
 include/SDL3/SDL_metal.h     |  4 +--
 include/SDL3/SDL_sensor.h    |  7 ++--
 include/SDL3/SDL_timer.h     | 12 ++++---
 include/SDL3/SDL_video.h     | 14 ++++----
 13 files changed, 102 insertions(+), 90 deletions(-)

diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index f2e1a3d097b2c..0d8cd510cb5b4 100644
--- a/include/SDL3/SDL_audio.h
+++ b/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.
  *
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index e9f705b147bb7..988b8e2beb1fa 100644
--- a/include/SDL3/SDL_camera.h
+++ b/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
  */
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index c1c8386c6e471..7bdbc7e90586c 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/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
  *
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
index c73cc79e0e61f..ab3875c91f8c1 100644
--- a/include/SDL3/SDL_dialog.h
+++ b/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.
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 7176d2ef4eecc..f728d5a4dba40 100644
--- a/include/SDL3/SDL_events.h
+++ b/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
diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h
index c70b421abd39a..67e324a4bdf46 100644
--- a/include/SDL3/SDL_haptic.h
+++ b/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;
 
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 9791c8283dee5..8aabe67c51688 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/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;
 
diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h
index 14da234a92a17..a43deaea13136 100644
--- a/include/SDL3/SDL_keycode.h
+++ b/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.
  *
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 7694e3eac5ced..e893fe1d607d1 100644
--- a/include/SDL3/SDL_main.h
+++ b/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[]);
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index e08ff36108382..18e2bba2c450c 100644
--- a/include/SDL3/SDL_metal.h
+++ b/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;
 
diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index dded4c36a5606..5eb6233658aa3 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/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;
 
diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h
index 2b03e089be8e8..d4cf4fd7db3f2 100644
--- a/include/SDL3/SDL_timer.h
+++ b/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
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 4610460b714f6..99a1a64ed3121 100644
--- a/include/SDL3/SDL_video.h
+++ b/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);