From 197340ea1cad956fc15fc2cadd04b37a60702d9c Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 25 Jan 2023 12:58:29 -0500
Subject: [PATCH] Sync wiki -> headers.
---
include/SDL3/SDL_audio.h | 38 ++++-----
include/SDL3/SDL_events.h | 4 +-
include/SDL3/SDL_gamepad.h | 154 ++++++++++++++++++------------------
include/SDL3/SDL_init.h | 4 +-
include/SDL3/SDL_joystick.h | 25 +++---
include/SDL3/SDL_keyboard.h | 6 +-
include/SDL3/SDL_locale.h | 4 +-
include/SDL3/SDL_main.h | 32 ++++----
include/SDL3/SDL_mouse.h | 4 +-
include/SDL3/SDL_mutex.h | 16 ++--
include/SDL3/SDL_power.h | 12 +--
include/SDL3/SDL_render.h | 30 +++----
include/SDL3/SDL_rwops.h | 59 +++++++-------
include/SDL3/SDL_sensor.h | 10 ++-
include/SDL3/SDL_stdinc.h | 6 +-
include/SDL3/SDL_surface.h | 113 +++++++++++++-------------
include/SDL3/SDL_video.h | 43 +++++-----
include/SDL3/SDL_vulkan.h | 10 ++-
18 files changed, 294 insertions(+), 276 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 28500ea16f26..583befa51a01 100644
--- a/include/SDL3/SDL_audio.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 1e13f96f75ec..b719417fae72 100644
--- a/include/SDL3/SDL_events.h
+++ b/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
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index b03ebfbc79c3..f9e0a0244d25 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/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
diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h
index d4d149915ead..b10a14aa9681 100644
--- a/include/SDL3/SDL_init.h
+++ b/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
*
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 5026c62ed493..2891bf4ad94f 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h
index 0bc487c87563..eb6ab3fdece0 100644
--- a/include/SDL3/SDL_keyboard.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index eb46f016a455..61ea54a96b8a 100644
--- a/include/SDL3/SDL_locale.h
+++ b/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
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index c868a5882fa0..a20f2f846f38 100644
--- a/include/SDL3/SDL_main.h
+++ b/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'
(Patch may be truncated, please check the link at the top of this post.)