Sync SDL3 wiki -> headers

include/SDL3/SDL_assert.h

@@ -129,8 +129,8 @@ typedef enum
  * Information about an assertion failure.
  *
  * This structure is filled in with information about a triggered assertion,
- * used by the assertion handler, then added to the assertion report.
+ * used by the assertion handler, then added to the assertion report. This is
- * This is returned as a linked list from SDL_GetAssertionReport().
+ * returned as a linked list from SDL_GetAssertionReport().
  *
  * \since This struct is available since SDL 3.0.0.
  */

include/SDL3/SDL_audio.h

@@ -149,9 +149,9 @@ typedef Uint32 SDL_AudioDeviceID;
 /**
  * Format specifier for audio data.
  *
- * \sa SDL_AudioFormat
- *
  * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_AudioFormat
  */
 typedef struct SDL_AudioSpec
 {
@@ -168,19 +168,19 @@ typedef struct SDL_AudioSpec
  *
  * SDL_AudioStream is an audio conversion interface.
  *
- * - It can handle resampling data in chunks without generating
+ * - It can handle resampling data in chunks without generating artifacts,
- *   artifacts, when it doesn't have the complete buffer available.
+ *   when it doesn't have the complete buffer available.
  * - It can handle incoming data in any variable size.
  * - It can handle input/output format changes on the fly.
  * - You push data as you have it, and pull it when you need it
- * - It can also function as a basic audio data queue even if you
+ * - It can also function as a basic audio data queue even if you just have
- *   just have sound that needs to pass from one place to another.
+ *   sound that needs to pass from one place to another.
- * - You can hook callbacks up to them when more data is added or
+ * - You can hook callbacks up to them when more data is added or requested,
- *   requested, to manage data on-the-fly.
+ *   to manage data on-the-fly.
  *
- * Audio streams are the core of the SDL3 audio interface. You create
+ * Audio streams are the core of the SDL3 audio interface. You create one or
- * one or more of them, bind them to an opened audio device, and feed
+ * more of them, bind them to an opened audio device, and feed data to them
- * data to them (or for recording, consume data from them).
+ * (or for recording, consume data from them).
  *
  * \since This struct is available since SDL 3.0.0.
  *

include/SDL3/SDL_blendmode.h

@@ -37,11 +37,12 @@ extern "C" {
 /**
  * An enumeration of blend modes used in drawing operations.
  *
- * Note that additional values may be obtained from SDL_ComposeCustomBlendMode.
+ * Note that additional values may be obtained from
- *
+ * SDL_ComposeCustomBlendMode.
- * \sa SDL_ComposeCustomBlendMode
  *
  * \since This enum is available since SDL 3.0.0.
+ *
+ * \sa SDL_ComposeCustomBlendMode
  */
 typedef enum SDL_BlendMode
 {
@@ -66,7 +67,8 @@ typedef enum SDL_BlendMode
 } SDL_BlendMode;
 
 /**
- * The blend operation used when combining source and destination pixel components.
+ * The blend operation used when combining source and destination pixel
+ * components.
  *
  * \since This enum is available since SDL 3.0.0.
  */
@@ -82,10 +84,10 @@ typedef enum SDL_BlendOperation
 /**
  * The normalized factor used to multiply pixel components.
  *
- * The blend factors are multiplied with the pixels from a drawing
+ * The blend factors are multiplied with the pixels from a drawing operation
- * operation (src) and the pixels from the render target (dst) before
+ * (src) and the pixels from the render target (dst) before the blend
- * the blend operation. The comma-separated factors listed above are always
+ * operation. The comma-separated factors listed above are always applied in
- * applied in the component order red, green, blue, and alpha.
+ * the component order red, green, blue, and alpha.
  *
  * \since This enum is available since SDL 3.0.0.
  */

include/SDL3/SDL_camera.h

@@ -59,12 +59,13 @@ typedef struct SDL_Camera SDL_Camera;
 /**
  * The details of an output format for a camera device.
  *
- * Cameras often support multiple formats; each one will be encapsulated in this struct.
+ * Cameras often support multiple formats; each one will be encapsulated in
+ * this struct.
+ *
+ * \since This struct is available since SDL 3.0.0.
  *
  * \sa SDL_GetCameraDeviceSupportedFormats
  * \sa SDL_GetCameraFormat
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_CameraSpec
 {
@@ -78,9 +79,9 @@ typedef struct SDL_CameraSpec
 /**
  * The position of camera in relation to system device.
  *
- * \sa SDL_GetCameraDevicePosition
- *
  * \since This enum is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetCameraDevicePosition
  */
 typedef enum SDL_CameraPosition
 {

include/SDL3/SDL_dialog.h

@@ -34,7 +34,8 @@ extern "C" {
 /**
  * An entry for filters for file dialogs.
  *
- * `name` is a user-readable label for the filter (for example, "Office document").
+ * `name` is a user-readable label for the filter (for example, "Office
+ * document").
  *
  * `pattern` is a semicolon-separated list of file extensions (for example,
  * "doc;docx"). File extensions may only contain alphanumeric characters,

include/SDL3/SDL_events.h

@@ -303,11 +303,12 @@ typedef struct SDL_KeyboardEvent
 } SDL_KeyboardEvent;
 
 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE 64
+
 /**
  * Keyboard text editing event structure (event.edit.*)
  *
- *  The `text` is owned by SDL and should be copied if the application
+ * The `text` is owned by SDL and should be copied if the application wants to
- *  wants to hold onto it beyond the scope of handling this event.
+ * hold onto it beyond the scope of handling this event.
  */
 typedef struct SDL_TextEditingEvent
 {
@@ -323,8 +324,8 @@ typedef struct SDL_TextEditingEvent
 /**
  * Keyboard text input event structure (event.text.*)
  *
- *  The `text` is owned by SDL and should be copied if the application
+ * The `text` is owned by SDL and should be copied if the application wants to
- *  wants to hold onto it beyond the scope of handling this event.
+ * hold onto it beyond the scope of handling this event.
  */
 typedef struct SDL_TextInputEvent
 {
@@ -416,7 +417,7 @@ typedef struct SDL_JoyAxisEvent
 } SDL_JoyAxisEvent;
 
 /**
- *  \brief Joystick trackball motion event structure (event.jball.*)
+ * Joystick trackball motion event structure (event.jball.*)
  */
 typedef struct SDL_JoyBallEvent
 {
@@ -616,6 +617,7 @@ typedef struct SDL_TouchFingerEvent
 
 
 #define SDL_DROPEVENT_DATA_SIZE 64
+
 /**
  * Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
  */
@@ -635,7 +637,8 @@ typedef struct SDL_PenTipEvent
 } SDL_PenTipEvent;
 
 /**
- *  Pressure-sensitive pen motion / pressure / angle event structure (event.pmotion.*)
+ * Pressure-sensitive pen motion / pressure / angle event structure
+ * (event.pmotion.*)
  */
 typedef struct SDL_PenMotionEvent
 {
@@ -671,10 +674,11 @@ typedef struct SDL_PenButtonEvent
 } SDL_PenButtonEvent;
 
 /**
- * An event used to drop text or request a file open by the system (event.drop.*)
+ * An event used to drop text or request a file open by the system
+ * (event.drop.*)
  *
- * The `data` is owned by SDL and should be copied if the application
+ * The `data` is owned by SDL and should be copied if the application wants to
- * wants to hold onto it beyond the scope of handling this event. Do not free it!
+ * hold onto it beyond the scope of handling this event. Do not free it!
  */
 typedef struct SDL_DropEvent
 {
@@ -689,7 +693,8 @@ typedef struct SDL_DropEvent
 } SDL_DropEvent;
 
 /**
- * An event triggered when the clipboard contents have changed (event.clipboard.*)
+ * An event triggered when the clipboard contents have changed
+ * (event.clipboard.*)
  */
 typedef struct SDL_ClipboardEvent
 {
@@ -726,9 +731,9 @@ typedef struct SDL_QuitEvent
  *
  * This event is unique; it is never created by SDL, but only by the
  * application. The event can be pushed onto the event queue using
- * SDL_PushEvent(). The contents of the structure members are completely
+ * SDL_PushEvent(). The contents of the structure members are completely up to
- * up to the programmer; the only requirement is that '''type''' is a value
+ * the programmer; the only requirement is that '''type''' is a value obtained
- * obtained from SDL_RegisterEvents().
+ * from SDL_RegisterEvents().
  */
 typedef struct SDL_UserEvent
 {

include/SDL3/SDL_filesystem.h

@@ -142,9 +142,9 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
 /**
  * The type of the OS-provided default folder for a specific purpose.
  *
- * Note that the Trash folder isn't included here, because trashing files usually
+ * Note that the Trash folder isn't included here, because trashing files
- * involves extra OS-specific functionality to remember the file's original
+ * usually involves extra OS-specific functionality to remember the file's
- * location.
+ * original location.
  *
  * The folders supported per platform are:
  *

include/SDL3/SDL_gamepad.h

@@ -78,22 +78,23 @@ typedef enum SDL_GamepadType
 /**
  * The list of buttons available on a gamepad
  *
- *  For controllers that use a diamond pattern for the face buttons,
+ * For controllers that use a diamond pattern for the face buttons, the
- *  the south/east/west/north buttons below correspond to the locations
+ * south/east/west/north buttons below correspond to the locations in the
- *  in the diamond pattern. For Xbox controllers, this would be A/B/X/Y,
+ * diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo
- *  for Nintendo Switch controllers, this would be B/A/Y/X, for
+ * Switch controllers, this would be B/A/Y/X, for PlayStation controllers this
- *  PlayStation controllers this would be Cross/Circle/Square/Triangle.
+ * would be Cross/Circle/Square/Triangle.
  *
- *  For controllers that don't use a diamond pattern for the face buttons,
+ * For controllers that don't use a diamond pattern for the face buttons, the
- *  the south/east/west/north buttons indicate the buttons labeled A, B,
+ * south/east/west/north buttons indicate the buttons labeled A, B, C, D, or
- *  C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are
+ * 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary,
- *  the primary, secondary, etc. buttons.
+ * secondary, etc. buttons.
  *
- *  The activate action is often the south button and the cancel action
+ * The activate action is often the south button and the cancel action is
- *  is often the east button, but in some regions this is reversed, so
+ * often the east button, but in some regions this is reversed, so your game
- *  your game should allow remapping actions based on user preferences.
+ * should allow remapping actions based on user preferences.
  *
- *  You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
+ * You can query the labels for the face buttons using
+ * SDL_GetGamepadButtonLabel()
  */
 typedef enum SDL_GamepadButton
 {
@@ -130,9 +131,11 @@ typedef enum SDL_GamepadButton
 /**
  * The set of gamepad button labels
  *
- *  This isn't a complete set, just the face buttons to make it easy to show button prompts.
+ * This isn't a complete set, just the face buttons to make it easy to show
+ * button prompts.
  *
- *  For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
+ * For a complete set, you should look at the button and gamepad type and have
+ * a set of symbols that work well with your art style.
  */
 typedef enum SDL_GamepadButtonLabel
 {
@@ -150,12 +153,13 @@ typedef enum SDL_GamepadButtonLabel
 /**
  * The list of axes available on a gamepad
  *
- *  Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX,
+ * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
- *  and are centered within ~8000 of zero, though advanced UI will allow users to set
+ * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
- *  or autodetect the dead zone, which varies between gamepads.
+ * advanced UI will allow users to set or autodetect the dead zone, which
+ * varies between gamepads.
  *
- *  Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX
+ * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
- *  (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
+ * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
  * same range that will be reported by the lower-level SDL_GetJoystickAxis().
  */
 typedef enum SDL_GamepadAxis

include/SDL3/SDL_guid.h

@@ -38,19 +38,19 @@ extern "C" {
 #endif
 
 /**
- * An SDL_GUID is a 128-bit identifier for an input device that
+ * An SDL_GUID is a 128-bit identifier for an input device that identifies
- *   identifies that device across runs of SDL programs on the same
+ * that device across runs of SDL programs on the same platform.
- *   platform.  If the device is detached and then re-attached to a
- *   different port, or if the base system is rebooted, the device
- *   should still report the same GUID.
  *
- * GUIDs are as precise as possible but are not guaranteed to
+ * If the device is detached and then re-attached to a different port, or if
- *   distinguish physically distinct but equivalent devices.  For
+ * the base system is rebooted, the device should still report the same GUID.
- *   example, two game controllers from the same vendor with the same
- *   product ID and revision may have the same GUID.
  *
- * GUIDs may be platform-dependent (i.e., the same device may report
+ * GUIDs are as precise as possible but are not guaranteed to distinguish
- *   different GUIDs on different operating systems).
+ * physically distinct but equivalent devices. For example, two game
+ * controllers from the same vendor with the same product ID and revision may
+ * have the same GUID.
+ *
+ * GUIDs may be platform-dependent (i.e., the same device may report different
+ * GUIDs on different operating systems).
  */
 typedef struct SDL_GUID {
     Uint8 data[16];

include/SDL3/SDL_haptic.h

@@ -359,8 +359,8 @@ typedef struct SDL_Haptic SDL_Haptic;
 /**
  * Use this value to play an effect on the steering wheel axis.
  *
- * This provides better compatibility across platforms and devices as SDL
+ * This provides better compatibility across platforms and devices as SDL will
- * will guess the correct axis.
+ * guess the correct axis.
  *
  * \sa SDL_HapticDirection
  */
@@ -385,8 +385,8 @@ typedef struct SDL_Haptic SDL_Haptic;
 /**
  * Structure that represents a haptic direction.
  *
- *  This is the direction where the force comes from,
+ * This is the direction where the force comes from, instead of the direction
- *  instead of the direction in which the force is exerted.
+ * in which the force is exerted.
  *
  * Directions can be specified by:
  *
@@ -394,8 +394,8 @@ typedef struct SDL_Haptic SDL_Haptic;
  * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
  * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
  *
- *  Cardinal directions of the haptic device are relative to the positioning
+ * Cardinal directions of the haptic device are relative to the positioning of
- *  of the device.  North is considered to be away from the user.
+ * the device. North is considered to be away from the user.
  *
  * The following diagram represents the cardinal directions:
  *
@@ -426,31 +426,31 @@ typedef struct SDL_Haptic SDL_Haptic;
  *                 ---ooO-(_)-Ooo---
  * ```
  *
- *  If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
+ * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree
- *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
+ * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first
- *  the first `dir` parameter.  The cardinal directions would be:
+ * `dir` parameter. The cardinal directions would be:
  *
  * - North: 0 (0 degrees)
  * - East: 9000 (90 degrees)
  * - South: 18000 (180 degrees)
  * - West: 27000 (270 degrees)
  *
- *  If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
+ * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X
- *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
+ * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first
- *  the first three `dir` parameters.  The cardinal directions would be:
+ * three `dir` parameters. The cardinal directions would be:
  *
  * - North: 0,-1, 0
  * - East: 1, 0, 0
  * - South: 0, 1, 0
  * - West: -1, 0, 0
  *
- *  The Z axis represents the height of the effect if supported, otherwise
+ * The Z axis represents the height of the effect if supported, otherwise it's
- *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
+ * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can
- *  can use any multiple you want, only the direction matters.
+ * use any multiple you want, only the direction matters.
  *
- *  If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
+ * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The
- *  The first two `dir` parameters are used.  The `dir` parameters are as
+ * first two `dir` parameters are used. The `dir` parameters are as follows
- *  follows (all values are in hundredths of degrees):
+ * (all values are in hundredths of degrees):
  *
  * - Degrees from (1, 0) rotated towards (0, 1).
  * - Degrees towards (0, 0, 1) (device needs at least 3 axes).
@@ -495,8 +495,8 @@ typedef struct SDL_HapticDirection
  *
  * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
  *
- *  A constant effect applies a constant force in the specified direction
+ * A constant effect applies a constant force in the specified direction to
- *  to the joystick.
+ * the joystick.
  *
  * \sa SDL_HAPTIC_CONSTANT
  * \sa SDL_HapticEffect
@@ -536,12 +536,12 @@ typedef struct SDL_HapticConstant
  * - SDL_HAPTIC_SAWTOOTHUP
  * - SDL_HAPTIC_SAWTOOTHDOWN
  *
- *  A periodic effect consists in a wave-shaped effect that repeats itself
+ * A periodic effect consists in a wave-shaped effect that repeats itself over
- *  over time.  The type determines the shape of the wave and the parameters
+ * time. The type determines the shape of the wave and the parameters
  * determine the dimensions of the wave.
  *
- *  Phase is given by hundredth of a degree meaning that giving the phase a value
+ * Phase is given by hundredth of a degree meaning that giving the phase a
- *  of 9000 will displace it 25% of its period.  Here are sample values:
+ * value of 9000 will displace it 25% of its period. Here are sample values:
  *
  * - 0: No phase displacement.
  * - 9000: Displaced 25% of its period.
@@ -626,11 +626,11 @@ typedef struct SDL_HapticPeriodic
  *
  * Direction is handled by condition internals instead of a direction member.
  * The condition effect specific members have three parameters. The first
- *  refers to the X axis, the second refers to the Y axis and the third
+ * refers to the X axis, the second refers to the Y axis and the third refers
- *  refers to the Z axis.  The right terms refer to the positive side of the
+ * to the Z axis. The right terms refer to the positive side of the axis and
- *  axis and the left terms refer to the negative side of the axis.  Please
+ * the left terms refer to the negative side of the axis. Please refer to the
- *  refer to the SDL_HapticDirection diagram for which side is positive and
+ * SDL_HapticDirection diagram for which side is positive and which is
- *  which is negative.
+ * negative.
  *
  * \sa SDL_HapticDirection
  * \sa SDL_HAPTIC_SPRING
@@ -668,10 +668,10 @@ typedef struct SDL_HapticCondition
  *
  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
  *
- *  The ramp effect starts at start strength and ends at end strength.
+ * The ramp effect starts at start strength and ends at end strength. It
- *  It augments in linear fashion.  If you use attack and fade with a ramp
+ * augments in linear fashion. If you use attack and fade with a ramp the
- *  the effects get added to the ramp effect making the effect become
+ * effects get added to the ramp effect making the effect become quadratic
- *  quadratic instead of linear.
+ * instead of linear.
  *
  * \sa SDL_HAPTIC_RAMP
  * \sa SDL_HapticEffect
@@ -732,8 +732,8 @@ typedef struct SDL_HapticLeftRight
  * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
  *
  * A custom force feedback effect is much like a periodic effect, where the
- *  application can define its exact shape.  You will have to allocate the
+ * application can define its exact shape. You will have to allocate the data
- *  data yourself.  Data should consist of channels * samples Uint16 samples.
+ * yourself. Data should consist of channels * samples Uint16 samples.
  *
  * If channels is one, the effect is rotated using the defined direction.
  * Otherwise it uses the samples in data for the different axes.
@@ -771,19 +771,19 @@ typedef struct SDL_HapticCustom
 /**
  * The generic template for any haptic effect.
  *
- *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
+ * All values max at 32767 (0x7FFF). Signed values also can be negative. Time
- *  Time values unless specified otherwise are in milliseconds.
+ * values unless specified otherwise are in milliseconds.
  *
- *  You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767
+ * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
- *  value.  Neither delay, interval, attack_length nor fade_length support
+ * Neither delay, interval, attack_length nor fade_length support
  * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
  *
  * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
  * SDL_HAPTIC_INFINITY.
  *
  * Button triggers may not be supported on all devices, it is advised to not
- *  use them if possible.  Buttons start at index 1 instead of index 0 like
+ * use them if possible. Buttons start at index 1 instead of index 0 like the
- *  the joystick.
+ * joystick.
  *
  * If both attack_length and fade_level are 0, the envelope is not used,
  * otherwise both values are used.

include/SDL3/SDL_hidapi.h

@@ -109,6 +109,7 @@ typedef enum SDL_hid_bus_type {
 } SDL_hid_bus_type;
 
 /** hidapi info structure */
+
 /**
  * Information about a connected HID device
  */

include/SDL3/SDL_init.h

@@ -42,8 +42,8 @@ extern "C" {
 /**
  * Initialization flags for SDL_Init and/or SDL_InitSubSystem
  *
- * These are the flags which may be passed to SDL_Init().  You should
+ * These are the flags which may be passed to SDL_Init(). You should specify
- * specify the subsystems which you will be using in your application.
+ * the subsystems which you will be using in your application.
  *
  * \sa SDL_Init
  * \sa SDL_Quit

include/SDL3/SDL_iostream.h

@@ -56,11 +56,10 @@ typedef enum SDL_IOStatus
 /**
  * The function pointers that drive an SDL_IOStream.
  *
- * Applications can provide this struct to SDL_OpenIO() to
+ * Applications can provide this struct to SDL_OpenIO() to create their own
- * create their own implementation of SDL_IOStream. This is
+ * implementation of SDL_IOStream. This is not necessarily required, as SDL
- * not necessarily required, as SDL already offers several
+ * already offers several common types of I/O streams, via functions like
- * common types of I/O streams, via functions like SDL_IOFromFile()
+ * SDL_IOFromFile() and SDL_IOFromMem().
- * and SDL_IOFromMem().
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -120,10 +119,10 @@ typedef struct SDL_IOStreamInterface
 /**
  * The read/write operation structure.
  *
- * This operates as an opaque handle. There are several APIs to create
+ * This operates as an opaque handle. There are several APIs to create various
- * various types of I/O streams, or an app can supply an
+ * types of I/O streams, or an app can supply an SDL_IOStreamInterface to
- * SDL_IOStreamInterface to SDL_OpenIO() to provide their own stream
+ * SDL_OpenIO() to provide their own stream implementation behind this
- * implementation behind this struct's abstract interface.
+ * struct's abstract interface.
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -323,8 +322,8 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
  *
  * You must free the returned pointer with SDL_CloseIO().
  *
- * This function makes a copy of `iface` and the caller does not need to
+ * This function makes a copy of `iface` and the caller does not need to keep
- * keep this data around after this call.
+ * this data around after this call.
  *
  * \param iface The function pointers that implement this SDL_IOStream.
  * \param userdata The app-controlled pointer that is passed to iface's

include/SDL3/SDL_joystick.h

@@ -356,8 +356,10 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickTyp
 /**
  * The structure that defines an extended virtual joystick description
  *
- * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_AttachVirtualJoystickEx()
+ * The caller must zero the structure and then initialize the version with
- *  All other elements of this structure are optional and can be left 0.
+ * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to
+ * SDL_AttachVirtualJoystickEx() All other elements of this structure are
+ * optional and can be left 0.
  *
  * \sa SDL_AttachVirtualJoystickEx
  */

include/SDL3/SDL_keyboard.h

@@ -44,7 +44,8 @@ typedef Uint32 SDL_KeyboardID;
 /**
  * The SDL keysym structure, used in key events.
  *
- *  If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event.
+ * If you are looking for translated character input, see the
+ * ::SDL_EVENT_TEXT_INPUT event.
  */
 typedef struct SDL_Keysym
 {

include/SDL3/SDL_locale.h

@@ -42,10 +42,10 @@ extern "C" {
 /**
  * A struct to provide locale data.
  *
- * Locale data is split into a spoken language, like English, and an
+ * Locale data is split into a spoken language, like English, and an optional
- * optional country, like Canada. The language will be in ISO-639 format
+ * country, like Canada. The language will be in ISO-639 format (so English
- * (so English would be "en"), and the country, if not NULL, will be an
+ * would be "en"), and the country, if not NULL, will be an ISO-3166 country
- * ISO-3166 country code (so Canada would be "CA").
+ * code (so Canada would be "CA").
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_log.h

@@ -56,10 +56,9 @@ extern "C" {
 /**
  * The predefined log categories
  *
- *  By default the application category is enabled at the INFO level,
+ * By default the application category is enabled at the INFO level, the
- *  the assert category is enabled at the WARN level, test is enabled
+ * assert category is enabled at the WARN level, test is enabled at the
- *  at the VERBOSE level and all other categories are enabled at the
+ * VERBOSE level and all other categories are enabled at the ERROR level.
- *  ERROR level.
  */
 typedef enum SDL_LogCategory
 {

include/SDL3/SDL_messagebox.h

@@ -33,7 +33,9 @@ extern "C" {
 #endif
 
 /**
- * SDL_MessageBox flags. If supported will display warning icon, etc.
+ * SDL_MessageBox flags.
+ *
+ * If supported will display warning icon, etc.
  */
 typedef enum SDL_MessageBoxFlags
 {

include/SDL3/SDL_mutex.h

@@ -116,8 +116,8 @@ extern "C" {
 #endif
 
 /**
- *  Synchronization functions which can time out return this value
+ * Synchronization functions which can time out return this value if they time
- *  if they time out.
+ * out.
  */
 #define SDL_MUTEX_TIMEDOUT  1
 

include/SDL3/SDL_pen.h

@@ -66,11 +66,12 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio
 /**
  * Pen axis indices
  *
- * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and SDL_PenButtonEvent.
+ * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and
- * The axis indices form a contiguous range of ints from 0 to SDL_PEN_AXIS_LAST, inclusive.
+ * SDL_PenButtonEvent. The axis indices form a contiguous range of ints from 0
- * All "axis[]" entries are either normalised to  0..1 or report a (positive or negative)
+ * to SDL_PEN_AXIS_LAST, inclusive. All "axis[]" entries are either normalised
- * angle in degrees, with 0.0 representing the centre.
+ * to 0..1 or report a (positive or negative) angle in degrees, with 0.0
- * Not all pens/backends support all axes: unsupported entries are always "0.0f".
+ * representing the centre. Not all pens/backends support all axes:
+ * unsupported entries are always "0.0f".
  *
  * To convert angles for tilt and rotation into vector representation, use
  * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
@@ -122,7 +123,8 @@ typedef enum SDL_PenAxis
 /**
  * Pen types
  *
- * Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
+ * Some pens identify as a particular type of drawing device (e.g., an
+ * airbrush or a pencil).
  *
  * \since This enum is available since SDL 3.0.0
  */
@@ -221,10 +223,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
  * \returns A string that contains the name of the pen, intended for human
  *          consumption. The string might or might not be localised, depending
  *          on platform settings. It is not guaranteed to be unique; use
- *          SDL_GetPenGUID() for (best-effort) unique identifiers. The
+ *          SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
- *          pointer is managed by the SDL pen subsystem and must not be
+ *          is managed by the SDL pen subsystem and must not be deallocated.
- *          deallocated. The pointer remains valid until SDL is shut down.
+ *          The pointer remains valid until SDL is shut down. Returns NULL on
- *          Returns NULL on error (cf. SDL_GetError())
+ *          error (cf. SDL_GetError())
  *
  * \since This function is available since SDL 3.0.0
  */
@@ -258,10 +260,10 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL
  * \param instance_id The pen to query.
  * \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
  *          Note that the pen type does not dictate whether the pen tip is
- *          SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a
+ *          SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen
- *          pen is being used for drawing or in eraser mode, check either the
+ *          is being used for drawing or in eraser mode, check either the pen
- *          pen tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK
+ *          tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK in the
- *          in the pen state.
+ *          pen state.
  *
  * \since This function is available since SDL 3.0.0
  */

include/SDL3/SDL_pixels.h

@@ -457,7 +457,8 @@ typedef enum SDL_ColorType
 } SDL_ColorType;
 
 /**
- * The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
+ * The color range, as described by
+ * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
  */
 typedef enum SDL_ColorRange
 {
@@ -467,7 +468,8 @@ typedef enum SDL_ColorRange
 } SDL_ColorRange;
 
 /**
- * The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
+ * The color primaries, as described by
+ * https://www.itu.int/rec/T-REC-H.273-201612-S/en
  */
 typedef enum SDL_ColorPrimaries
 {
@@ -488,7 +490,8 @@ typedef enum SDL_ColorPrimaries
 } SDL_ColorPrimaries;
 
 /**
- * The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
+ * The transfer characteristics, as described by
+ * https://www.itu.int/rec/T-REC-H.273-201612-S/en
  */
 typedef enum SDL_TransferCharacteristics
 {
@@ -514,7 +517,8 @@ typedef enum SDL_TransferCharacteristics
 } SDL_TransferCharacteristics;
 
 /**
- * The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
+ * The matrix coefficients, as described by
+ * https://www.itu.int/rec/T-REC-H.273-201612-S/en
  */
 typedef enum SDL_MatrixCoefficients
 {
@@ -663,9 +667,10 @@ typedef enum SDL_Colorspace
 /**
  * A structure that represents a color as RGBA components.
  *
- * The bits of this structure can be directly reinterpreted as an integer-packed
+ * The bits of this structure can be directly reinterpreted as an
- * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
+ * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format
- * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
+ * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and
+ * SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -712,9 +717,8 @@ typedef struct SDL_Palette
 /**
  * Details about the format of a pixel.
  *
- * Generally this is used with SDL_Surface, and covers many
+ * Generally this is used with SDL_Surface, and covers many possible
- * possible configurations, including paletted data and various
+ * configurations, including paletted data and various bit patterns.
- * bit patterns.
  *
  * \since This struct is available since SDL 3.0.0.
  */

include/SDL3/SDL_rect.h

@@ -40,10 +40,10 @@ extern "C" {
 /**
  * The structure that defines a point (using integers).
  *
+ * \since This struct is available since SDL 3.0.0.
+ *
  * \sa SDL_GetRectEnclosingPoints
  * \sa SDL_PointInRect
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_Point
 {
@@ -54,10 +54,10 @@ typedef struct SDL_Point
 /**
  * The structure that defines a point (using floating point values).
  *
+ * \since This struct is available since SDL 3.0.0.
+ *
  * \sa SDL_GetRectEnclosingPointsFloat
  * \sa SDL_PointInRectFloat
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_FPoint
 {
@@ -69,6 +69,8 @@ typedef struct SDL_FPoint
 /**
  * A rectangle, with the origin at the upper left (using integers).
  *
+ * \since This struct is available since SDL 3.0.0.
+ *
  * \sa SDL_RectEmpty
  * \sa SDL_RectsEqual
  * \sa SDL_HasRectIntersection
@@ -76,8 +78,6 @@ typedef struct SDL_FPoint
  * \sa SDL_GetRectAndLineIntersection
  * \sa SDL_GetRectUnion
  * \sa SDL_GetRectEnclosingPoints
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_Rect
 {
@@ -87,7 +87,10 @@ typedef struct SDL_Rect
 
 
 /**
- * A rectangle, with the origin at the upper left (using floating point values).
+ * A rectangle, with the origin at the upper left (using floating point
+ * values).
+ *
+ * \since This struct is available since SDL 3.0.0.
  *
  * \sa SDL_RectEmptyFloat
  * \sa SDL_RectsEqualFloat
@@ -98,8 +101,6 @@ typedef struct SDL_Rect
  * \sa SDL_GetRectUnionFloat
  * \sa SDL_GetRectEnclosingPointsFloat
  * \sa SDL_PointInRectFloat
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_FRect
 {

include/SDL3/SDL_sensor.h

@@ -81,16 +81,16 @@ typedef enum
 /**
  * Accelerometer sensor.
  *
- * The accelerometer returns the current acceleration in SI meters per
+ * The accelerometer returns the current acceleration in SI meters per second
- * second squared. This measurement includes the force of gravity, so
+ * squared. This measurement includes the force of gravity, so a device at
- * a device at rest will have an value of SDL_STANDARD_GRAVITY away
+ * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
- * from the center of the earth, which is a positive Y value.
+ * earth, which is a positive Y value.
  *
- * values[0]: Acceleration on the x axis
+ * values[0]: Acceleration on the x axis values[1]: Acceleration on the y axis
- * values[1]: Acceleration on the y axis
  * values[2]: Acceleration on the z axis
  *
- * For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:
+ * For phones and tablets held in natural orientation and game controllers
+ * held in front of you, the axes are defined as follows:
  *
  * - -X ... +X : left ... right
  * - -Y ... +Y : bottom ... top
@@ -98,7 +98,7 @@ typedef enum
  *
  * The axis data is not changed when the device is rotated.
  *
- * \sa SDL_GetCurrentDisplayOrientation()
+ * \sa SDL_GetCurrentDisplayOrientation
  */
 #define SDL_STANDARD_GRAVITY    9.80665f
 

include/SDL3/SDL_stdinc.h

@@ -146,30 +146,35 @@ typedef int SDL_bool;
 #define SDL_MAX_SINT8   ((Sint8)0x7F)           /* 127 */
 #define SDL_MIN_SINT8   ((Sint8)(~0x7F))        /* -128 */
 typedef int8_t Sint8;
+
 /**
  * An unsigned 8-bit integer type.
  */
 #define SDL_MAX_UINT8   ((Uint8)0xFF)           /* 255 */
 #define SDL_MIN_UINT8   ((Uint8)0x00)           /* 0 */
 typedef uint8_t Uint8;
+
 /**
  * A signed 16-bit integer type.
  */
 #define SDL_MAX_SINT16  ((Sint16)0x7FFF)        /* 32767 */
 #define SDL_MIN_SINT16  ((Sint16)(~0x7FFF))     /* -32768 */
 typedef int16_t Sint16;
+
 /**
  * An unsigned 16-bit integer type.
  */
 #define SDL_MAX_UINT16  ((Uint16)0xFFFF)        /* 65535 */
 #define SDL_MIN_UINT16  ((Uint16)0x0000)        /* 0 */
 typedef uint16_t Uint16;
+
 /**
  * A signed 32-bit integer type.
  */
 #define SDL_MAX_SINT32  ((Sint32)0x7FFFFFFF)    /* 2147483647 */
 #define SDL_MIN_SINT32  ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
 typedef int32_t Sint32;
+
 /**
  * An unsigned 32-bit integer type.
  */
@@ -183,6 +188,7 @@ typedef uint32_t Uint32;
 #define SDL_MAX_SINT64  ((Sint64)0x7FFFFFFFFFFFFFFFll)      /* 9223372036854775807 */
 #define SDL_MIN_SINT64  ((Sint64)(~0x7FFFFFFFFFFFFFFFll))   /* -9223372036854775808 */
 typedef int64_t Sint64;
+
 /**
  * An unsigned 64-bit integer type.
  */
@@ -191,10 +197,12 @@ typedef int64_t Sint64;
 typedef uint64_t Uint64;
 
 /**
- * SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970).
+ * SDL times are signed, 64-bit integers representing nanoseconds since the
+ * Unix epoch (Jan 1, 1970).
  *
- * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() and SDL_SECONDS_TO_NS(),
+ * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS()
- * and between Windows FILETIME values with SDL_TimeToWindows() and SDL_TimeFromWindows().
+ * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
+ * SDL_TimeToWindows() and SDL_TimeFromWindows().
  */
 #define SDL_MAX_TIME SDL_MAX_SINT64
 #define SDL_MIN_TIME SDL_MIN_SINT64

include/SDL3/SDL_surface.h

@@ -89,21 +89,17 @@ typedef enum SDL_FlipMode
 /**
  * A collection of pixels used in software blitting.
  *
- * Pixels are arranged in memory in rows, with the top row first.
+ * Pixels are arranged in memory in rows, with the top row first. Each row
- * Each row occupies an amount of memory given by the pitch (sometimes
+ * occupies an amount of memory given by the pitch (sometimes known as the row
- * known as the row stride in non-SDL APIs).
+ * stride in non-SDL APIs).
  *
- * Within each row, pixels are arranged from left to right until the
+ * Within each row, pixels are arranged from left to right until the width is
- * width is reached.
+ * reached. Each pixel occupies a number of bits appropriate for its format,
- * Each pixel occupies a number of bits appropriate for its format, with
+ * with most formats representing each pixel as one or more whole bytes (in
- * most formats representing each pixel as one or more whole bytes
+ * some indexed formats, instead multiple pixels are packed into each byte),
- * (in some indexed formats, instead multiple pixels are packed into
+ * and a byte order given by the format. After encoding all pixels, any
- * each byte), and a byte order given by the format.
+ * remaining bytes to reach the pitch are used as padding to reach a desired
- * After encoding all pixels, any remaining bytes to reach the pitch are
+ * alignment, and have undefined contents.
- * used as padding to reach a desired alignment, and have undefined contents.
- *
- * \note  This structure should be treated as read-only, except for \c pixels,
- *        which, if not NULL, contains the raw pixel data for the surface.
  */
 typedef struct SDL_Surface
 {

include/SDL3/SDL_system.h

@@ -337,9 +337,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
 
 /**
-   See the official Android developer guide for more information:
+ * See the official Android developer guide for more information:
-   http://developer.android.com/guide/topics/data/data-storage.html
+ * http://developer.android.com/guide/topics/data/data-storage.html
-*/
+ */
 #define SDL_ANDROID_EXTERNAL_STORAGE_READ   0x01
 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE  0x02
 

include/SDL3/SDL_thread.h

@@ -58,12 +58,11 @@ typedef Uint32 SDL_TLSID;
 /**
  * The SDL thread priority.
  *
- *  SDL will make system changes as necessary in order to apply the thread priority.
+ * SDL will make system changes as necessary in order to apply the thread
- *  Code which attempts to control thread state related to priority should be aware
+ * priority. Code which attempts to control thread state related to priority
- *  that calling SDL_SetThreadPriority may alter such state.
+ * should be aware that calling SDL_SetThreadPriority may alter such state.
- *  SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior.
+ * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this
- *
+ * behavior.
- *  \note On many systems you require special privileges to set high or time critical priority.
  */
 typedef enum SDL_ThreadPriority {
     SDL_THREAD_PRIORITY_LOW,

include/SDL3/SDL_time.h

@@ -38,7 +38,8 @@ extern "C" {
 #endif
 
 /**
- * A structure holding a calendar date and time broken down into its components.
+ * A structure holding a calendar date and time broken down into its
+ * components.
  */
 typedef struct SDL_DateTime
 {

include/SDL3/SDL_version.h

@@ -41,15 +41,14 @@ extern "C" {
  * Information about the version of SDL in use.
  *
  * Represents the library's version as three levels: major revision
- * (increments with massive changes, additions, and enhancements),
+ * (increments with massive changes, additions, and enhancements), minor
- * minor revision (increments with backwards-compatible changes to the
+ * revision (increments with backwards-compatible changes to the major
- * major revision), and patchlevel (increments with fixes to the minor
+ * revision), and patchlevel (increments with fixes to the minor revision).
- * revision).
+ *
+ * \since This struct is available since SDL 3.0.0.
  *
  * \sa SDL_VERSION
  * \sa SDL_GetVersion
- *
- * \since This struct is available since SDL 3.0.0.
  */
 typedef struct SDL_Version
 {
@@ -70,15 +69,15 @@ typedef struct SDL_Version
  * library you compiled against. This is determined by what header the
  * compiler uses. Note that if you dynamically linked the library, you might
  * have a slightly newer or older version at runtime. That version can be
- * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
+ * determined with SDL_GetVersion(), which, unlike SDL_VERSION(), is not a
- * is not a macro.
+ * macro.
  *
  * \param x A pointer to an SDL_Version struct to initialize.
  *
+ * \since This macro is available since SDL 3.0.0.
+ *
  * \sa SDL_Version
  * \sa SDL_GetVersion
- *
- * \since This macro is available since SDL 3.0.0.
  */
 #define SDL_VERSION(x)                \
 {                                     \

include/SDL3/SDL_video.h

@@ -76,13 +76,13 @@ typedef enum SDL_SystemTheme
 /**
  * The structure that defines a display mode.
  *
- * \sa SDL_GetFullscreenDisplayModes()
- * \sa SDL_GetDesktopDisplayMode()
- * \sa SDL_GetCurrentDisplayMode()
- * \sa SDL_SetWindowFullscreenMode()
- * \sa SDL_GetWindowFullscreenMode()
- *
  * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetFullscreenDisplayModes
+ * \sa SDL_GetDesktopDisplayMode
+ * \sa SDL_GetCurrentDisplayMode
+ * \sa SDL_SetWindowFullscreenMode
+ * \sa SDL_GetWindowFullscreenMode
  */
 typedef struct SDL_DisplayMode
 {
@@ -207,9 +207,17 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);
 /**
  * An enumeration of OpenGL configuration attributes.
  *
- * While you can set most OpenGL attributes normally, the attributes listed above must be known before SDL creates the window that will be used with the OpenGL context. These attributes are set and read with SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
+ * While you can set most OpenGL attributes normally, the attributes listed
+ * above must be known before SDL creates the window that will be used with
+ * the OpenGL context. These attributes are set and read with
+ * SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
  *
- * In some cases, these attributes are minimum requests; the GL does not promise to give you exactly what you asked for. It's possible to ask for a 16-bit depth buffer and get a 24-bit one instead, for example, or to ask for no stencil buffer and still have one available. Context creation should fail if the GL can't provide your requested attributes at a minimum, but you should check to see exactly what you got.
+ * In some cases, these attributes are minimum requests; the GL does not
+ * promise to give you exactly what you asked for. It's possible to ask for a
+ * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask
+ * for no stencil buffer and still have one available. Context creation should
+ * fail if the GL can't provide your requested attributes at a minimum, but
+ * you should check to see exactly what you got.
  *
  * \since This enum is available since SDL 3.0.0.
  */
@@ -271,7 +279,8 @@ typedef enum SDL_GLcontextFlag
 } SDL_GLcontextFlag;
 
 /**
- * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR attribute.
+ * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR
+ * attribute.
  *
  * \since This enum is available since SDL 3.0.0.
  */