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
+ * Apps can (optionally) register a callback with an audio stream that is
- * is called when data is added with SDL_PutAudioStreamData, or requested
+ * called when data is added with SDL_PutAudioStreamData, or requested with
- * with SDL_GetAudioStreamData.
+ * SDL_GetAudioStreamData.
  *
- * Two values are offered here: one is the amount of additional data needed
+ * Two values are offered here: one is the amount of additional data needed to
- * to satisfy the immediate request (which might be zero if the stream
+ * satisfy the immediate request (which might be zero if the stream already
- * already has enough data queued) and the other is the total amount
+ * has enough data queued) and the other is the total amount being requested.
- * being requested. In a Get call triggering a Put callback, these
+ * In a Get call triggering a Put callback, these values can be different. In
- * values can be different. In a Put call triggering a Get callback,
+ * a Put call triggering a Get callback, these values are always the same.
- * these values are always the same.
  *
- * Byte counts might be slightly overestimated due to buffering or
+ * Byte counts might be slightly overestimated due to buffering or resampling,
- * resampling, and may change from call to call.
+ * and may change from call to call.
  *
- * This callback is not required to do anything. Generally this is useful
+ * This callback is not required to do anything. Generally this is useful for
- * for adding/reading data on demand, and the app will often put/get data as
+ * 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
+ * appropriate, but the system goes on with the data currently available to it
- * to it if this callback does nothing.
+ * 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 additional_amount The amount of data, in bytes, that is needed right
- * \param total_amount The total amount of data requested, in bytes, that is requested or available.
+ *                          now.
- * \param userdata An opaque pointer provided by the app for their personal use.
+ * \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
+ * \threadsafety This callbacks may run from any thread, so if you need to
- *               to protect shared data, you should use SDL_LockAudioStream 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
+ * specified in `spec`, which can change between callbacks if the audio device
- * device changed. However, this only covers frequency and channel count;
+ * changed. However, this only covers frequency and channel count; data is
- * data is always provided here in SDL_AUDIO_F32 format.
+ * always provided here in SDL_AUDIO_F32 format.
  *
  * \param userdata a pointer provided by the app through
  *                 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
+ * \param buffer the buffer of audio samples to be submitted. The callback can
- *        can inspect and/or modify this data.
+ *               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.
+ * \threadsafety This will run from a background thread owned by SDL. The
- *               The application is responsible for locking resources the
+ *               application is responsible for locking resources the callback
- *               callback touches that need to be protected.
+ *               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,
+ * This is a unique ID for a camera device for the time it is connected to the
- * and is never reused for the lifetime of the application. If the device is
+ * system, and is never reused for the lifetime of the application.
- * 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.
+ * 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
+ * The callback function is called with NULL as the mime_type when the
- * is cleared or new data is set. The clipboard is automatically cleared in SDL_Quit().
+ * 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 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
+ * \returns a pointer to the data for the provided mime-type. Returning NULL
- *          setting length to 0 will cause no data to be sent to the "receiver". It is
+ *          or setting length to 0 will cause no data to be sent to the
- *          up to the receiver to handle this. Essentially returning no data is more or
+ *          "receiver". It is up to the receiver to handle this. Essentially
- *          less undefined behavior and may cause breakage in receiving applications.
+ *          returning no data is more or less undefined behavior and may cause
- *          The returned data will not be freed so it needs to be retained and dealt
+ *          breakage in receiving applications. The returned data will not be
- *          with internally.
+ *          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...
+ * If filelist is... - `NULL`, an error occured. Details can be obtained with
- * - `NULL`, an error occured. Details can be obtained with SDL_GetError().
+ * SDL_GetError(). - A pointer to `NULL`, the user either didn't choose any
- * - A pointer to `NULL`, the user either didn't choose any file or canceled
+ * file or canceled the dialog. - A pointer to non-`NULL`, the user chose one
- *   the dialog.
+ * or more files. The argument is a null-terminated list of pointers to C
- * - A pointer to non-`NULL`, the user chose one or more files. The argument is
+ * strings, each containing a path.
- *   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()
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
- *        or SDL_AddEventWatch, etc
+ *                 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
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow it.
- *          it. When used with SDL_AddEventWatch, the return value is ignored.
+ *          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,
+ * This is a unique ID for a joystick for the time it is connected to the
- * and is never reused for the lifetime of the application. If the joystick is
+ * system, and is never reused for the lifetime of the application.
- * 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.
+ * 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

@@ -36,11 +36,11 @@
  *
  * 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
+ * the unmodified character that would be generated by pressing the key, or an
- *  an `SDLK_*` constant for those keys that do not generate characters.
+ * `SDLK_*` constant for those keys that do not generate characters.
  *
- *  A special exception is the number keys at the top of the keyboard which
+ * A special exception is the number keys at the top of the keyboard which map
- *  map to SDLK_0...SDLK_9 on AZERTY layouts.
+ * 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.

include/SDL3/SDL_metal.h

@@ -38,8 +38,6 @@ extern "C" {
 
 /**
  * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
- *
- *  \note This can be cast directly to an NSView or UIView.
  */
 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,
+ * This is a unique ID for a sensor for the time it is connected to the
- * and is never reused for the lifetime of the application.
+ * 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 callback function is passed the current timer interval and returns the
- * the next timer interval, in milliseconds. If the returned value is the same as the one
+ * next timer interval, in milliseconds. If the returned value is the same as
- * passed in, the periodic alarm continues, otherwise a new alarm is
+ * 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.
+ * \param param an arbitrary pointer provided by the app through SDL_AddTimer,
- * \returns the new callback time interval, or 0 to disable further runs of the callback.
+ *              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
+ * These cover a lot of true/false, or on/off, window state. Some of it is
- * is immutable after being set through SDL_CreateWindow(), some of it can
+ * immutable after being set through SDL_CreateWindow(), some of it can be
- * be changed on existing windows by the app, and some of it might be altered
+ * changed on existing windows by the app, and some of it might be altered by
- * by the user or system outside of the app's control.
+ * the user or system outside of the app's control.
  *
  * \sa SDL_GetWindowFlags
  */