Sync wiki -> headers.

include/SDL3/SDL_audio.h

@@ -407,8 +407,8 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
  * Open a specific audio device.
  *
  * Passing in a `device` name of NULL requests the most reasonable default.
- * The `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
- * some drivers allow arbitrary and driver-specific strings, such as a
+ * The `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(),
+ * but some drivers allow arbitrary and driver-specific strings, such as a
  * hostname/IP address for a remote audio server, or a filename in the
  * diskaudio driver.
  *
@@ -545,13 +545,13 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice
 /**
  * Use this function to play audio on a specified device.
  *
- * Newly-opened audio devices start in the paused state, so you must
- * call this function after opening the specified audio
- * device to start playing sound. This allows you to safely initialize data
- * for your callback function after opening the audio device. Silence will be
- * written to the audio device while paused, and the audio callback is
- * guaranteed to not be called. Pausing one device does not prevent other
- * unpaused devices from running their callbacks.
+ * Newly-opened audio devices start in the paused state, so you must call this
+ * function after opening the specified audio device to start playing sound.
+ * This allows you to safely initialize data for your callback function after
+ * opening the audio device. Silence will be written to the audio device while
+ * paused, and the audio callback is guaranteed to not be called. Pausing one
+ * device does not prevent other unpaused devices from running their
+ * callbacks.
  *
  * \param dev a device opened by SDL_OpenAudioDevice()
  *
@@ -567,11 +567,10 @@ extern DECLSPEC void SDLCALL SDL_PlayAudioDevice(SDL_AudioDeviceID dev);
 /**
  * Use this function to pause audio playback on a specified device.
  *
- * This function pauses the audio callback processing for a given
- * device.  Silence will be written to the audio device while paused, and
- * the audio callback is guaranteed to not be called.
- * Pausing one device does not prevent other unpaused devices from running
- * their callbacks.
+ * This function pauses the audio callback processing for a given device.
+ * Silence will be written to the audio device while paused, and the audio
+ * callback is guaranteed to not be called. Pausing one device does not
+ * prevent other unpaused devices from running their callbacks.
  *
  * If you just need to protect a few variables from race conditions vs your
  * callback, you shouldn't pause the audio device, as it will lead to dropouts
@@ -1119,15 +1118,16 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
  * \param src_format The format of the source audio
  * \param src_channels The number of channels of the source audio
  * \param src_rate The sampling rate of the source audio
- * \param src_len  The len of src_data
+ * \param src_len The len of src_data
  * \param src_data The audio data to be converted
  * \param dst_format The format of the desired audio output
  * \param dst_channels The number of channels of the desired audio output
  * \param dst_rate The sampling rate of the desired audio output
- * \param dst_len  Will be filled with the len of dst_data
- * \param dst_data Will be filled with a pointer to converted audio data, which should be freed with SDL_free().
- *
- * \returns 0 on success or a negative error code on failure. On error, *dst_data will be NULL and so not allocated.
+ * \param dst_len Will be filled with the len of dst_data
+ * \param dst_data Will be filled with a pointer to converted audio data,
+ *                 which should be freed with SDL_free().
+ * \returns 0 on success or a negative error code on failure. On error,
+ *          *dst_data will be NULL and so not allocated.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_events.h

@@ -879,8 +879,8 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
  * As this function may implicitly call SDL_PumpEvents(), you can only call
  * this function in the thread that initialized the video subsystem.
  *
- * The timeout is not guaranteed, the actual wait time could be longer
- * due to system scheduling.
+ * The timeout is not guaranteed, the actual wait time could be longer due to
+ * system scheduling.
  *
  * \param event the SDL_Event structure to be filled in with the next event
  *              from the queue, or NULL

include/SDL3/SDL_gamepad.h

@@ -160,11 +160,11 @@ typedef struct SDL_GamepadBinding
  *
  * The mapping string has the format "GUID,name,mapping", where GUID is the
  * string value from SDL_GetJoystickGUIDString(), name is the human readable
- * string for the device and mappings are gamepad mappings to joystick
- * ones. Under Windows there is a reserved GUID of "xinput" that covers all
- * XInput devices. The mapping format for joystick is: {| |bX |a joystick
- * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
- * |} Buttons can be used as a gamepad axes and vice versa.
+ * string for the device and mappings are gamepad mappings to joystick ones.
+ * Under Windows there is a reserved GUID of "xinput" that covers all XInput
+ * devices. The mapping format for joystick is: {| |bX |a joystick button,
+ * index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick |}
+ * Buttons can be used as a gamepad axes and vice versa.
  *
  * This string shows an example of a valid mapping for a gamepad:
  *
@@ -262,10 +262,9 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID gui
  *
  * Details about mappings are discussed with SDL_AddGamepadMapping().
  *
- * \param gamepad the gamepad you want to get the current
- *                       mapping for
- * \returns a string that has the gamepad's mapping or NULL if no mapping
- *          is available; call SDL_GetError() for more information.
+ * \param gamepad the gamepad you want to get the current mapping for
+ * \returns a string that has the gamepad's mapping or NULL if no mapping is
+ *          available; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -278,7 +277,9 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
  * Get a list of currently connected gamepads.
  *
  * \param count a pointer filled in with the number of gamepads returned
- * \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
+ * \returns a 0 terminated array of joystick instance IDs which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -370,8 +371,8 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joystick
  * available this function returns 0.
  *
  * \param instance_id the joystick instance ID
- * \returns the USB vendor ID of the selected gamepad. If called on an
- *          invalid index, this function returns zero
+ * \returns the USB vendor ID of the selected gamepad. If called on an invalid
+ *          index, this function returns zero
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -446,10 +447,12 @@ extern DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID insta
 extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id);
 
 /**
- * Get the SDL_Gamepad associated with a joystick instance ID, if it has been opened.
+ * Get the SDL_Gamepad associated with a joystick instance ID, if it has been
+ * opened.
  *
  * \param instance_id the joystick instance ID of the gamepad
- * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
+ * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
+ *          opened yet; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -471,13 +474,13 @@ extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int player_in
 /**
  * Get the implementation-dependent name for an opened gamepad.
  *
- * This is the same name as returned by SDL_GetGamepadNameForIndex(), but
- * it takes a gamepad identifier instead of the (unstable) device index.
+ * This is the same name as returned by SDL_GetGamepadNameForIndex(), but it
+ * takes a gamepad identifier instead of the (unstable) device index.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                       SDL_OpenGamepad()
- * \returns the implementation dependent name for the gamepad, or NULL
- *          if there is no name or the identifier passed is invalid.
+ *                SDL_OpenGamepad()
+ * \returns the implementation dependent name for the gamepad, or NULL if
+ *          there is no name or the identifier passed is invalid.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -489,13 +492,13 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
 /**
  * Get the implementation-dependent path for an opened gamepad.
  *
- * This is the same path as returned by SDL_GetGamepadNameForIndex(), but
- * it takes a gamepad identifier instead of the (unstable) device index.
+ * This is the same path as returned by SDL_GetGamepadNameForIndex(), but it
+ * takes a gamepad identifier instead of the (unstable) device index.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                       SDL_OpenGamepad()
- * \returns the implementation dependent path for the gamepad, or NULL
- *          if there is no path or the identifier passed is invalid.
+ *                SDL_OpenGamepad()
+ * \returns the implementation dependent path for the gamepad, or NULL if
+ *          there is no path or the identifier passed is invalid.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -506,8 +509,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
 /**
  * Get the type of this currently opened gamepad
  *
- * This is the same name as returned by SDL_GetGamepadInstanceType(), but
- * it takes a gamepad identifier instead of the (unstable) device index.
+ * This is the same name as returned by SDL_GetGamepadInstanceType(), but it
+ * takes a gamepad identifier instead of the (unstable) device index.
  *
  * \param gamepad the gamepad object to query.
  * \returns the gamepad type.
@@ -532,8 +535,8 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
  * Set the player index of an opened gamepad.
  *
  * \param gamepad the gamepad object to adjust.
- * \param player_index Player index to assign to this gamepad, or -1 to
- *                     clear the player index and turn off player LEDs.
+ * \param player_index Player index to assign to this gamepad, or -1 to clear
+ *                     the player index and turn off player LEDs.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -590,8 +593,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepa
 /**
  * Get the serial number of an opened gamepad, if available.
  *
- * Returns the serial number of the gamepad, or NULL if it is not
- * available.
+ * Returns the serial number of the gamepad, or NULL if it is not available.
  *
  * \param gamepad the gamepad object to query.
  * \return the serial number, or NULL if unavailable.
@@ -604,7 +606,7 @@ extern DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
  * Check if a gamepad has been opened and is currently connected.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                       SDL_OpenGamepad()
+ *                SDL_OpenGamepad()
  * \returns SDL_TRUE if the gamepad has been opened and is currently
  *          connected, or SDL_FALSE if not.
  *
@@ -619,17 +621,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
  * Get the underlying joystick from a gamepad
  *
  * This function will give you a SDL_Joystick object, which allows you to use
- * the SDL_Joystick functions with a SDL_Gamepad object. This would be
- * useful for getting a joystick's position at any given time, even if it
- * hasn't moved (moving it would produce an event, which would have the axis'
- * value).
+ * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful
+ * for getting a joystick's position at any given time, even if it hasn't
+ * moved (moving it would produce an event, which would have the axis' value).
  *
- * The pointer returned is owned by the SDL_Gamepad. You should not
- * call SDL_CloseJoystick() on it, for example, since doing so will likely
- * cause SDL to crash.
+ * The pointer returned is owned by the SDL_Gamepad. You should not call
+ * SDL_CloseJoystick() on it, for example, since doing so will likely cause
+ * SDL to crash.
  *
- * \param gamepad the gamepad object that you want to get a
- *                       joystick from
+ * \param gamepad the gamepad object that you want to get a joystick from
  * \returns an SDL_Joystick object; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -639,9 +639,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepa
 /**
  * Set the state of gamepad event processing.
  *
- * If gamepad events are disabled, you must call SDL_UpdateGamepads()
- * yourself and check the state of the gamepad when you want gamepad
- * information.
+ * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
+ * and check the state of the gamepad when you want gamepad information.
  *
  * \param enabled whether to process gamepad events or not
  *
@@ -654,11 +653,11 @@ extern DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled);
 /**
  * Query the state of gamepad event processing.
  *
- * If gamepad events are disabled, you must call SDL_UpdateGamepads()
- * yourself and check the state of the gamepad when you want gamepad
- * information.
+ * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
+ * and check the state of the gamepad when you want gamepad information.
  *
- * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE
+ *          otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -681,18 +680,18 @@ extern DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
 /**
  * Convert a string into SDL_GamepadAxis enum.
  *
- * This function is called internally to translate SDL_Gamepad mapping
- * strings for the underlying joystick device into the consistent
- * SDL_Gamepad mapping. You do not normally need to call this function
- * unless you are parsing SDL_Gamepad mappings in your own code.
+ * This function is called internally to translate SDL_Gamepad mapping strings
+ * for the underlying joystick device into the consistent SDL_Gamepad mapping.
+ * You do not normally need to call this function unless you are parsing
+ * SDL_Gamepad mappings in your own code.
  *
  * Note specially that "righttrigger" and "lefttrigger" map to
  * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
  * respectively.
  *
  * \param str string representing a SDL_Gamepad axis
- * \returns the SDL_GamepadAxis enum corresponding to the input string,
- *          or `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
+ * \returns the SDL_GamepadAxis enum corresponding to the input string, or
+ *          `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -721,8 +720,8 @@ extern DECLSPEC const char* SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis
  *
  * \param gamepad a gamepad
  * \param axis an axis enum value (one of the SDL_GamepadAxis values)
- * \returns a SDL_GamepadBinding describing the bind. On failure
- *          (like the given Controller axis doesn't exist on the device), its
+ * \returns a SDL_GamepadBinding describing the bind. On failure (like the
+ *          given Controller axis doesn't exist on the device), its
  *          `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
  *
  * \since This function is available since SDL 3.0.0.
@@ -767,14 +766,14 @@ extern DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_Game
 /**
  * Convert a string into an SDL_GamepadButton enum.
  *
- * This function is called internally to translate SDL_Gamepad mapping
- * strings for the underlying joystick device into the consistent
- * SDL_Gamepad mapping. You do not normally need to call this function
- * unless you are parsing SDL_Gamepad mappings in your own code.
+ * This function is called internally to translate SDL_Gamepad mapping strings
+ * for the underlying joystick device into the consistent SDL_Gamepad mapping.
+ * You do not normally need to call this function unless you are parsing
+ * SDL_Gamepad mappings in your own code.
  *
  * \param str string representing a SDL_Gamepad axis
- * \returns the SDL_GamepadButton enum corresponding to the input
- *          string, or `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
+ * \returns the SDL_GamepadButton enum corresponding to the input string, or
+ *          `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -801,9 +800,9 @@ extern DECLSPEC const char* SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadBut
  *
  * \param gamepad a gamepad
  * \param button an button enum value (an SDL_GamepadButton value)
- * \returns a SDL_GamepadBinding describing the bind. On failure
- *          (like the given Controller button doesn't exist on the device),
- *          its `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
+ * \returns a SDL_GamepadBinding describing the bind. On failure (like the
+ *          given Controller button doesn't exist on the device), its
+ *          `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -814,8 +813,8 @@ extern DECLSPEC SDL_GamepadBinding SDLCALL SDL_GetGamepadBindForButton(SDL_Gamep
 /**
  * Query whether a gamepad has a given button.
  *
- * This merely reports whether the gamepad's mapping defined this button,
- * as that is all the information SDL has about the physical device.
+ * This merely reports whether the gamepad's mapping defined this button, as
+ * that is all the information SDL has about the physical device.
  *
  * \param gamepad a gamepad
  * \param button a button enum value (an SDL_GamepadButton value)
@@ -896,8 +895,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SD
 extern DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type);
 
 /**
- * Get the data rate (number of events per second) of a gamepad
- * sensor.
+ * Get the data rate (number of events per second) of a gamepad sensor.
  *
  * \param gamepad The gamepad to query
  * \param type The type of sensor to query
@@ -949,10 +947,9 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
  * Each call to this function cancels any previous trigger rumble effect, and
  * calling it with 0 intensity stops any rumbling.
  *
- * Note that this is rumbling of the _triggers_ and not the gamepad as
- * a whole. This is currently only supported on Xbox One gamepads. If you
- * want the (more common) whole-gamepad rumble, use
- * SDL_RumbleGamepad() instead.
+ * Note that this is rumbling of the _triggers_ and not the gamepad as a
+ * whole. This is currently only supported on Xbox One gamepads. If you want
+ * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.
  *
  * \param gamepad The gamepad to vibrate
  * \param left_rumble The intensity of the left trigger rumble motor, from 0
@@ -972,8 +969,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint
  * Query whether a gamepad has an LED.
  *
  * \param gamepad The gamepad to query
- * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a
- *          modifiable LED
+ * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a modifiable
+ *          LED
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1024,8 +1021,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, U
  * \param gamepad The gamepad to affect
  * \param data The data to send to the gamepad
  * \param size The size of the data to send to the gamepad
- * \returns 0, or -1 if this gamepad or driver doesn't support effect
- *          packets
+ * \returns 0, or -1 if this gamepad or driver doesn't support effect packets
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1034,7 +1030,8 @@ extern DECLSPEC int SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const vo
 /**
  * Close a gamepad previously opened with SDL_OpenGamepad().
  *
- * \param gamepad a gamepad identifier previously returned by SDL_OpenGamepad()
+ * \param gamepad a gamepad identifier previously returned by
+ *                SDL_OpenGamepad()
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1057,8 +1054,7 @@ extern DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
 extern DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
 
 /**
- * Return the sfSymbolsName for a given axis on a gamepad on Apple
- * platforms.
+ * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
  *
  * \param gamepad the gamepad to query
  * \param axis an axis on the gamepad

include/SDL3/SDL_init.h

@@ -91,8 +91,8 @@ typedef enum
  * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
  *   events subsystem
  * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
- * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically
- *   initializes the joystick subsystem
+ * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically initializes the
+ *   joystick subsystem
  * - `SDL_INIT_EVENTS`: events subsystem
  * - `SDL_INIT_EVERYTHING`: all of the above subsystems
  *

include/SDL3/SDL_joystick.h

@@ -121,9 +121,9 @@ typedef enum
 /**
  * Locking for atomic access to the joystick API
  *
- * The SDL joystick functions are thread-safe, however you can lock the joysticks
- * while processing to guarantee that the joystick list won't change and joystick
- * and gamepad events will not be delivered.
+ * The SDL joystick functions are thread-safe, however you can lock the
+ * joysticks while processing to guarantee that the joystick list won't change
+ * and joystick and gamepad events will not be delivered.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -140,7 +140,9 @@ extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_
  * Get a list of currently connected joysticks.
  *
  * \param count a pointer filled in with the number of joysticks returned
- * \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
+ * \returns a 0 terminated array of joystick instance IDs which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -286,7 +288,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_i
  * Get the SDL_Joystick associated with an instance ID, if it has been opened.
  *
  * \param instance_id the instance ID to get the SDL_Joystick for
- * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
+ * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
+ *          opened yet; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -306,7 +309,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
 /**
  * Attach a new virtual joystick.
  *
- * \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
+ * \returns the joystick instance ID, or 0 if an error occurred; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -357,7 +361,8 @@ typedef struct SDL_VirtualJoystickDesc
 /**
  * Attach a new virtual joystick with extended properties.
  *
- * \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
+ * \returns the joystick instance ID, or 0 if an error occurred; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -366,7 +371,8 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
 /**
  * Detach a virtual joystick.
  *
- * \param instance_id the joystick instance ID, previously returned from SDL_AttachVirtualJoystick()
+ * \param instance_id the joystick instance ID, previously returned from
+ *                    SDL_AttachVirtualJoystick()
  * \returns 0 on success, or -1 if an error occurred.
  *
  * \since This function is available since SDL 3.0.0.
@@ -729,7 +735,8 @@ extern DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled);
  * yourself and check the state of the joystick when you want joystick
  * information.
  *
- * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE
+ *          otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_keyboard.h

@@ -247,9 +247,9 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
  * Start accepting Unicode text input events.
  *
  * This function will start accepting Unicode text input events in the focused
- * SDL window, and start emitting SDL_TextInputEvent (SDL_EVENT_TEXT_INPUT) and
- * SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this function in
- * pair with SDL_StopTextInput().
+ * SDL window, and start emitting SDL_TextInputEvent (SDL_EVENT_TEXT_INPUT)
+ * and SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this
+ * function in pair with SDL_StopTextInput().
  *
  * On some platforms using this function activates the screen keyboard.
  *

include/SDL3/SDL_locale.h

@@ -79,8 +79,8 @@ typedef struct SDL_Locale
  * This might be a "slow" call that has to query the operating system. It's
  * best to ask for this once and save the results. However, this list can
  * change, usually because the user has changed a system preference outside of
- * your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if
- * possible, and you can call this function again to get an updated copy of
+ * your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case,
+ * if possible, and you can call this function again to get an updated copy of
  * preferred locales.
  *
  * \return array of locales, terminated with a locale with a NULL language

include/SDL3/SDL_main.h

@@ -173,22 +173,24 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
 
 /**
  * Initializes and launches an SDL application, by doing platform-specific
- * initialization before calling your mainFunction and cleanups after it returns,
- * if that is needed for a specific platform, otherwise it just calls mainFunction.
- * You can use this if you want to use your own main() implementation
- * without using SDL_main (like when using SDL_MAIN_HANDLED).
- * When using this, you do *not* need SDL_SetMainReady().
+ * initialization before calling your mainFunction and cleanups after it
+ * returns, if that is needed for a specific platform, otherwise it just calls
+ * mainFunction.
  *
- * \param argc The argc parameter from the application's main() function,
- *             or 0 if the platform's main-equivalent has no argc
- * \param argv The argv parameter from the application's main() function,
- *             or NULL  if the platform's main-equivalent has no argv
- * \param mainFunction Your SDL app's C-style main(), an SDL_main_func.
- *                     NOT the function you're calling this from!
- *                     Its name doesn't matter, but its signature must be
- *                     like int my_main(int argc, char* argv[])
- * \param reserved should be NULL (reserved for future use, will probably
- *                 be platform-specific then)
+ * You can use this if you want to use your own main() implementation without
+ * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do
+ * *not* need SDL_SetMainReady().
+ *
+ * \param argc The argc parameter from the application's main() function, or 0
+ *             if the platform's main-equivalent has no argc
+ * \param argv The argv parameter from the application's main() function, or
+ *             NULL if the platform's main-equivalent has no argv
+ * \param mainFunction Your SDL app's C-style main(), an SDL_main_func. NOT
+ *                     the function you're calling this from! Its name doesn't
+ *                     matter, but its signature must be like int my_main(int
+ *                     argc, char* argv[])
+ * \param reserved should be NULL (reserved for future use, will probably be
+ *                 platform-specific then)
  * \return the return value from mainFunction: 0 on success, -1 on failure;
  *         SDL_GetError() might have more information on the failure
  *

include/SDL3/SDL_mouse.h

@@ -389,8 +389,8 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 /**
  * Get the default cursor.
  *
- * You do not have to call SDL_DestroyCursor() on the return value,
- * but it is safe to do so.
+ * You do not have to call SDL_DestroyCursor() on the return value, but it is
+ * safe to do so.
  *
  * \returns the default cursor on success or NULL on failure.
  *

include/SDL3/SDL_mutex.h

@@ -481,9 +481,9 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
  * `cond`. Once the condition variable is signaled, the mutex is re-locked and
  * the function returns.
  *
- * The mutex must be locked before calling this function. Locking the
- * mutex recursively (more than once) is not supported and leads to
- * undefined behavior.
+ * The mutex must be locked before calling this function. Locking the mutex
+ * recursively (more than once) is not supported and leads to undefined
+ * behavior.
  *
  * This function is the equivalent of calling SDL_CondWaitTimeout() with a
  * time length of `SDL_MUTEX_MAXWAIT`.
@@ -512,14 +512,14 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex);
  * signaled or the time elapsed, the mutex is re-locked and the function
  * returns.
  *
- * The mutex must be locked before calling this function. Locking the
- * mutex recursively (more than once) is not supported and leads to
- * undefined behavior.
+ * The mutex must be locked before calling this function. Locking the mutex
+ * recursively (more than once) is not supported and leads to undefined
+ * behavior.
  *
  * \param cond the condition variable to wait on
  * \param mutex the mutex used to coordinate thread access
- * \param timeoutMS the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
- *           to wait indefinitely
+ * \param timeoutMS the maximum time to wait, in milliseconds, or
+ *                  `SDL_MUTEX_MAXWAIT` to wait indefinitely
  * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
  *          the condition is not signaled in the allotted time, or a negative
  *          error code on failure; call SDL_GetError() for more information.

include/SDL3/SDL_power.h

@@ -64,12 +64,12 @@ typedef enum
  * It's possible a platform can only report battery percentage or time left
  * but not both.
  *
- * \param seconds seconds of battery life left, you can pass a NULL here if you
- *             don't care, will return -1 if we can't determine a value, or
- *             we're not running on a battery
- * \param percent percentage of battery life left, between 0 and 100, you can pass
- *            a NULL here if you don't care, will return -1 if we can't
- *            determine a value, or we're not running on a battery
+ * \param seconds seconds of battery life left, you can pass a NULL here if
+ *                you don't care, will return -1 if we can't determine a
+ *                value, or we're not running on a battery
+ * \param percent percentage of battery life left, between 0 and 100, you can
+ *                pass a NULL here if you don't care, will return -1 if we
+ *                can't determine a value, or we're not running on a battery
  * \returns an SDL_PowerState enum representing the current battery state.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_render.h

@@ -217,12 +217,11 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
 /**
  * Create a 2D rendering context for a window.
  *
- * If you want a specific renderer, you can specify its name here. A list
- * of available renderers can be obtained by calling SDL_GetRenderDriver
- * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If
- * you don't need a specific renderer, specify NULL and SDL will attempt
- * to chooes the best option for you, based on what is available on the
- * user's system.
+ * If you want a specific renderer, you can specify its name here. A list of
+ * available renderers can be obtained by calling SDL_GetRenderDriver multiple
+ * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't
+ * need a specific renderer, specify NULL and SDL will attempt to chooes the
+ * best option for you, based on what is available on the user's system.
  *
  * \param window the window where rendering is displayed
  * \param name the name of the rendering driver to initialize, or NULL to
@@ -1377,9 +1376,9 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer,
  * Update the screen with any rendering performed since the previous call.
  *
  * SDL's rendering functions operate on a backbuffer; that is, calling a
- * rendering function such as SDL_RenderLine() does not directly put a
- * line on the screen, but rather updates the backbuffer. As such, you compose
- * your entire scene and *present* the composed backbuffer to the screen as a
+ * rendering function such as SDL_RenderLine() does not directly put a line on
+ * the screen, but rather updates the backbuffer. As such, you compose your
+ * entire scene and *present* the composed backbuffer to the screen as a
  * complete picture.
  *
  * Therefore, when using SDL's rendering API, one does all drawing intended
@@ -1394,12 +1393,12 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer,
  *
  * \param renderer the rendering context
  *
- * \since This function is available since SDL 3.0.0.
+ * \threadsafety You may only call this function on the main thread. If this
+ *               happens to work on a background thread on any given platform
+ *               or backend, it's purely by luck and you should not rely on it
+ *               to work next time.
  *
- * \threadsafety You may only call this function on the main thread. If
- *               this happens to work on a background thread on any given
- *               platform or backend, it's purely by luck and you should
- *               not rely on it to work next time.
+ * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_RenderClear
  * \sa SDL_RenderLine
@@ -1580,7 +1579,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync
  * Get VSync of the given renderer.
  *
  * \param renderer The renderer to toggle
- * \param vsync an int filled with 1 for on, 0 for off. All other values are reserved
+ * \param vsync an int filled with 1 for on, 0 for off. All other values are
+ *              reserved
  * \returns a 0 int on success, or non-zero on failure
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_rwops.h

@@ -319,10 +319,11 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(void);
  * call the **close** method on those SDL_RWops pointers when you are done
  * with them.
  *
- * Only use SDL_DestroyRW() on pointers returned by SDL_CreateRW(). The pointer is
- * invalid as soon as this function returns. Any extra memory allocated during
- * creation of the SDL_RWops is not freed by SDL_DestroyRW(); the programmer must
- * be responsible for managing that memory in their **close** method.
+ * Only use SDL_DestroyRW() on pointers returned by SDL_CreateRW(). The
+ * pointer is invalid as soon as this function returns. Any extra memory
+ * allocated during creation of the SDL_RWops is not freed by SDL_DestroyRW();
+ * the programmer must be responsible for managing that memory in their
+ * **close** method.
  *
  * \param area the SDL_RWops structure to be freed
  *
@@ -371,7 +372,8 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
  * \param context a pointer to an SDL_RWops structure
  * \param offset an offset in bytes, relative to **whence** location; can be
  *               negative
- * \param whence any of `SDL_RW_SEEK_SET`, `SDL_RW_SEEK_CUR`, `SDL_RW_SEEK_END`
+ * \param whence any of `SDL_RW_SEEK_SET`, `SDL_RW_SEEK_CUR`,
+ *               `SDL_RW_SEEK_END`
  * \returns the final offset in the data stream after the seek or -1 on error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -417,24 +419,25 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
  * Read from a data source.
  *
  * This function reads up `size` bytes from the data source to the area
- * pointed at by `ptr`. This function may read less bytes than requested.
- * It will return zero when the data stream is completely read, or
- * -1 on error. For streams that support non-blocking
- * operation, if nothing was read because it would require blocking,
- * this function returns -2 to distinguish that this is not an error or
- * end-of-file, and the caller can try again later.
+ * pointed at by `ptr`. This function may read less bytes than requested. It
+ * will return zero when the data stream is completely read, or -1 on error.
+ * For streams that support non-blocking operation, if nothing was read
+ * because it would require blocking, this function returns -2 to distinguish
+ * that this is not an error or end-of-file, and the caller can try again
+ * later.
  *
  * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
  * `read` method appropriately, to simplify application development.
  *
- * It is an error to specify a negative `size`, but this parameter is
- * signed so you definitely cannot overflow the return value on a
- * successful run with enormous amounts of data.
+ * It is an error to specify a negative `size`, but this parameter is signed
+ * so you definitely cannot overflow the return value on a successful run with
+ * enormous amounts of data.
  *
  * \param context a pointer to an SDL_RWops structure
  * \param ptr a pointer to a buffer to read data into
  * \param size the number of bytes to read from the data source.
- * \returns the number of bytes read, 0 at end of file, -1 on error, and -2 for data not ready with a non-blocking context.
+ * \returns the number of bytes read, 0 at end of file, -1 on error, and -2
+ *          for data not ready with a non-blocking context.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -450,25 +453,23 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWread(SDL_RWops *context, void *ptr, Sint64
 /**
  * Write to an SDL_RWops data stream.
  *
- * This function writes exactly `size` bytes from the area pointed at by
- * `ptr` to the stream. If this fails for any reason, it'll return less
- * than `size` to demonstrate how far the write progressed. On success,
- * it returns `num`.
+ * This function writes exactly `size` bytes from the area pointed at by `ptr`
+ * to the stream. If this fails for any reason, it'll return less than `size`
+ * to demonstrate how far the write progressed. On success, it returns `num`.
  *
- * On error, this function still attempts to write as much as possible,
- * so it might return a positive value less than the requested write
- * size. If the function failed to write anything and there was an
- * actual error, it will return -1. For streams that support non-blocking
- * operation, if nothing was written because it would require blocking,
- * this function returns -2 to distinguish that this is not an error and
- * the caller can try again later.
+ * On error, this function still attempts to write as much as possible, so it
+ * might return a positive value less than the requested write size. If the
+ * function failed to write anything and there was an actual error, it will
+ * return -1. For streams that support non-blocking operation, if nothing was
+ * written because it would require blocking, this function returns -2 to
+ * distinguish that this is not an error and the caller can try again later.
  *
  * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
  * `write` method appropriately, to simplify application development.
  *
- * It is an error to specify a negative `size`, but this parameter is
- * signed so you definitely cannot overflow the return value on a
- * successful run with enormous amounts of data.
+ * It is an error to specify a negative `size`, but this parameter is signed
+ * so you definitely cannot overflow the return value on a successful run with
+ * enormous amounts of data.
  *
  * \param context a pointer to an SDL_RWops structure
  * \param ptr a pointer to a buffer containing data to write

include/SDL3/SDL_sensor.h

@@ -132,7 +132,9 @@ typedef enum
  * Get a list of currently connected sensors.
  *
  * \param count a pointer filled in with the number of sensors returned
- * \returns a 0 terminated array of sensor instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
+ * \returns a 0 terminated array of sensor instance IDs which should be freed
+ *          with SDL_free(), or NULL on error; call SDL_GetError() for more
+ *          details.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -152,7 +154,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID insta
  * Get the type of a sensor.
  *
  * \param instance_id the sensor instance ID
- * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is not valid
+ * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is
+ *          not valid
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -162,7 +165,8 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorID in
  * Get the platform dependent type of a sensor.
  *
  * \param instance_id the sensor instance ID
- * \returns the sensor platform dependent type, or -1 if `instance_id` is not valid
+ * \returns the sensor platform dependent type, or -1 if `instance_id` is not
+ *          valid
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_stdinc.h

@@ -424,9 +424,11 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
 /**
  * Allocate memory aligned to a specific value
  *
- * If `alignment` is less than the size of `void *`, then it will be increased to match that.
+ * If `alignment` is less than the size of `void *`, then it will be increased
+ * to match that.
  *
- * The returned memory address will be a multiple of the alignment value, and the amount of memory allocated will be a multiple of the alignment value.
+ * The returned memory address will be a multiple of the alignment value, and
+ * the amount of memory allocated will be a multiple of the alignment value.
  *
  * The memory returned by this function must be freed with SDL_aligned_free()
  *

include/SDL3/SDL_surface.h

@@ -224,8 +224,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
 /**
  * Load a BMP image from a seekable SDL data stream.
  *
- * The new surface should be freed with SDL_DestroySurface(). Not doing so will
- * result in a memory leak.
+ * The new surface should be freed with SDL_DestroySurface(). Not doing so
+ * will result in a memory leak.
  *
  * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile.
  * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap
@@ -652,8 +652,8 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height,
  * information, no blending takes place.
  *
  * If there is a clip rectangle set on the destination (set via
- * SDL_SetSurfaceClipRect()), then this function will fill based on the intersection
- * of the clip rectangle and `rect`.
+ * SDL_SetSurfaceClipRect()), then this function will fill based on the
+ * intersection of the clip rectangle and `rect`.
  *
  * \param dst the SDL_Surface structure that is the drawing target
  * \param rect the SDL_Rect structure representing the rectangle to fill, or
@@ -678,8 +678,8 @@ extern DECLSPEC int SDLCALL SDL_FillSurfaceRect
  * information, no blending takes place.
  *
  * If there is a clip rectangle set on the destination (set via
- * SDL_SetSurfaceClipRect()), then this function will fill based on the intersection
- * of the clip rectangle and `rect`.
+ * SDL_SetSurfaceClipRect()), then this function will fill based on the
+ * intersection of the clip rectangle and `rect`.
  *
  * \param dst the SDL_Surface structure that is the drawing target
  * \param rects an array of SDL_Rects representing the rectangles to fill.
@@ -696,56 +696,57 @@ extern DECLSPEC int SDLCALL SDL_FillSurfaceRects
     (SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color);
 
 /**
- *  Performs a fast blit from the source surface to the destination surface.
- *
- *  This assumes that the source and destination rectangles are
- *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
- *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
- *  in \c srcrect and \c dstrect after all clipping is performed.
- *
- *  The blit function should not be called on a locked surface.
- *
- *  The blit semantics for surfaces with and without blending and colorkey
- *  are defined as follows:
- *  \verbatim
-    RGBA->RGB:
-      Source surface blend mode set to SDL_BLENDMODE_BLEND:
-        alpha-blend (using the source alpha-channel and per-surface alpha)
-        SDL_SRCCOLORKEY ignored.
-      Source surface blend mode set to SDL_BLENDMODE_NONE:
-        copy RGB.
-        if SDL_SRCCOLORKEY set, only copy the pixels matching the
-        RGB values of the source color key, ignoring alpha in the
-        comparison.
-
-    RGB->RGBA:
-      Source surface blend mode set to SDL_BLENDMODE_BLEND:
-        alpha-blend (using the source per-surface alpha)
-      Source surface blend mode set to SDL_BLENDMODE_NONE:
-        copy RGB, set destination alpha to source per-surface alpha value.
-      both:
-        if SDL_SRCCOLORKEY set, only copy the pixels matching the
-        source color key.
-
-    RGBA->RGBA:
-      Source surface blend mode set to SDL_BLENDMODE_BLEND:
-        alpha-blend (using the source alpha-channel and per-surface alpha)
-        SDL_SRCCOLORKEY ignored.
-      Source surface blend mode set to SDL_BLENDMODE_NONE:
-        copy all of RGBA to the destination.
-        if SDL_SRCCOLORKEY set, only copy the pixels matching the
-        RGB values of the source color key, ignoring alpha in the
-        comparison.
-
-    RGB->RGB:
-      Source surface blend mode set to SDL_BLENDMODE_BLEND:
-        alpha-blend (using the source per-surface alpha)
-      Source surface blend mode set to SDL_BLENDMODE_NONE:
-        copy RGB.
-      both:
-        if SDL_SRCCOLORKEY set, only copy the pixels matching the
-        source color key.
-    \endverbatim
+ * Performs a fast blit from the source surface to the destination surface.
+ *
+ * This assumes that the source and destination rectangles are the same size.
+ * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
+ * `dst`) is copied. The final blit rectangles are saved in `srcrect` and
+ * `dstrect` after all clipping is performed.
+ *
+ * The blit function should not be called on a locked surface.
+ *
+ * The blit semantics for surfaces with and without blending and colorkey are
+ * defined as follows:
+ *
+ * ```c
+ *    RGBA->RGB:
+ *      Source surface blend mode set to SDL_BLENDMODE_BLEND:
+ *       alpha-blend (using the source alpha-channel and per-surface alpha)
+ *       SDL_SRCCOLORKEY ignored.
+ *     Source surface blend mode set to SDL_BLENDMODE_NONE:
+ *       copy RGB.
+ *       if SDL_SRCCOLORKEY set, only copy the pixels matching the
+ *       RGB values of the source color key, ignoring alpha in the
+ *       comparison.
+ *
+ *   RGB->RGBA:
+ *     Source surface blend mode set to SDL_BLENDMODE_BLEND:
+ *       alpha-blend (using the source per-surface alpha)
+ *     Source surface blend mode set to SDL_BLENDMODE_NONE:
+ *       copy RGB, set destination alpha to source per-surface alpha value.
+ *     both:
+ *       if SDL_SRCCOLORKEY set, only copy the pixels matching the
+ *       source color key.
+ *
+ *   RGBA->RGBA:
+ *     Source surface blend mode set to SDL_BLENDMODE_BLEND:
+ *       alpha-blend (using the source alpha-channel and per-surface alpha)
+ *       SDL_SRCCOLORKEY ignored.
+ *     Source surface blend mode set to SDL_BLENDMODE_NONE:
+ *       copy all of RGBA to the destination.
+ *       if SDL_SRCCOLORKEY set, only copy the pixels matching the
+ *       RGB values of the source color key, ignoring alpha in the
+ *       comparison.
+ *
+ *   RGB->RGB:
+ *     Source surface blend mode set to SDL_BLENDMODE_BLEND:
+ *       alpha-blend (using the source per-surface alpha)
+ *     Source surface blend mode set to SDL_BLENDMODE_NONE:
+ *       copy RGB.
+ *     both:
+ *       if SDL_SRCCOLORKEY set, only copy the pixels matching the
+ *       source color key.
+ * ```
  *
  * \param src the SDL_Surface structure to be copied from
  * \param srcrect the SDL_Rect structure representing the rectangle to be

include/SDL3/SDL_video.h

@@ -339,7 +339,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetDisplayName(int displayIndex);
 extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rect);
 
 /**
- * Get the usable desktop area represented by a display, in screen coordinates.
+ * Get the usable desktop area represented by a display, in screen
+ * coordinates.
  *
  * The primary display (`displayIndex` zero) is always located at 0,0.
  *
@@ -385,7 +386,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
  * SDL_Vulkan_GetDrawableSize(), SDL_Metal_GetDrawableSize(), or
  * SDL_GetRendererOutputSize(), and compare the two values to get an actual
  * scaling value between the two. We will be rethinking how high-dpi details
- * should be managed in SDL3 to make things more consistent, reliable, and clear.
+ * should be managed in SDL3 to make things more consistent, reliable, and
+ * clear.
  *
  * \param displayIndex the index of the display from which DPI information
  *                     should be queried
@@ -659,13 +661,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
  * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
  * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
  *
- * The window size in pixels may differ from its size in screen coordinates if
- * the window is on a high density display (one with an OS scaling factor).
- * Use SDL_GetWindowSize() to query the client area's size in screen coordinates,
- * and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize() to query the
- * drawable size in pixels. Note that the drawable size can vary after the window
- * is created and should be queried again when the window is resized or moved
- * between displays.
+ *  The window size in pixels may differ from its size in screen coordinates
+ * if the window is on a high density display (one with an OS scaling factor).
+ * Use SDL_GetWindowSize() to query the client area's size in screen
+ * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize()
+ * to query the drawable size in pixels. Note that the drawable size can vary
+ * after the window is created and should be queried again when the window is
+ * resized or moved between displays.
  *
  * If the window is set fullscreen, the width and height parameters `w` and
  * `h` will not be used. However, invalid size parameters (e.g. too large) may
@@ -844,8 +846,10 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *
  * Set the position of a window, in screen coordinates.
  *
  * \param window the window to reposition
- * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
- * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
+ * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
+ *          `SDL_WINDOWPOS_UNDEFINED`
+ * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
+ *          `SDL_WINDOWPOS_UNDEFINED`
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -916,8 +920,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h)
 extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h);
 
 /**
- * Get the size of a window's borders (decorations) around the client area,
- * in screen coordinates.
+ * Get the size of a window's borders (decorations) around the client area, in
+ * screen coordinates.
  *
  * Note: If this function fails (returns -1), the size values will be
  * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
@@ -1938,12 +1942,12 @@ extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
  * If the system can't determine the swap interval, or there isn't a valid
  * current context, this function will set *interval to 0 as a safe default.
  *
- * \param interval Output interval value. 0 if there is no vertical retrace synchronization, 1 if the buffer
- *          swap is synchronized with the vertical retrace, and -1 if late
- *          swaps happen immediately instead of waiting for the next retrace
- *
- * \returns 0 on success or -1 error.
- *          call SDL_GetError() for more information.
+ * \param interval Output interval value. 0 if there is no vertical retrace
+ *                 synchronization, 1 if the buffer swap is synchronized with
+ *                 the vertical retrace, and -1 if late swaps happen
+ *                 immediately instead of waiting for the next retrace
+ * \returns 0 on success or -1 error. call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1962,7 +1966,6 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval);
  * extra.
  *
  * \param window the window to change
- *
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_vulkan.h

@@ -111,11 +111,13 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
  * This should be called after either calling SDL_Vulkan_LoadLibrary() or
  * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
  *
- * The actual type of the returned function pointer is PFN_vkGetInstanceProcAddr,
- * but that isn't available because the Vulkan headers are not included here. You
- * should cast the return value of this function to that type, e.g.
+ * The actual type of the returned function pointer is
+ * PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan
+ * headers are not included here. You should cast the return value of this
+ * function to that type, e.g.
  *
- *  `vkGetInstanceProcAddr = (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
+ * `vkGetInstanceProcAddr =
+ * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
  *
  * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
  *