From 85bbc6028ad36e2c1daa8fac60ae07562077b17e Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Tue, 27 Aug 2024 17:33:28 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
---
include/SDL3/SDL_audio.h | 129 ++++++++--------
include/SDL3/SDL_camera.h | 12 +-
include/SDL3/SDL_clipboard.h | 16 +-
include/SDL3/SDL_events.h | 13 +-
include/SDL3/SDL_filesystem.h | 24 +--
include/SDL3/SDL_gamepad.h | 40 ++---
include/SDL3/SDL_haptic.h | 58 ++++----
include/SDL3/SDL_hints.h | 16 +-
include/SDL3/SDL_init.h | 16 +-
include/SDL3/SDL_iostream.h | 8 +-
include/SDL3/SDL_joystick.h | 65 ++++-----
include/SDL3/SDL_keyboard.h | 28 ++--
include/SDL3/SDL_log.h | 4 +-
include/SDL3/SDL_main.h | 9 +-
include/SDL3/SDL_messagebox.h | 8 +-
include/SDL3/SDL_misc.h | 4 +-
include/SDL3/SDL_mouse.h | 24 +--
include/SDL3/SDL_mutex.h | 25 ++--
include/SDL3/SDL_pixels.h | 8 +-
include/SDL3/SDL_properties.h | 40 ++---
include/SDL3/SDL_rect.h | 8 +-
include/SDL3/SDL_render.h | 268 +++++++++++++++++-----------------
include/SDL3/SDL_sensor.h | 4 +-
include/SDL3/SDL_stdinc.h | 4 +-
include/SDL3/SDL_storage.h | 32 ++--
include/SDL3/SDL_surface.h | 140 +++++++++---------
include/SDL3/SDL_system.h | 40 ++---
include/SDL3/SDL_thread.h | 8 +-
include/SDL3/SDL_time.h | 29 ++--
include/SDL3/SDL_timer.h | 4 +-
include/SDL3/SDL_video.h | 223 ++++++++++++++--------------
include/SDL3/SDL_vulkan.h | 8 +-
32 files changed, 658 insertions(+), 657 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index f74374105d76b..8b3e61bbba855 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -532,8 +532,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI
* \param spec on return, will be filled with device details.
* \param sample_frames pointer to store device buffer size, in sample frames.
* Can be NULL.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -659,8 +659,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
* created through SDL_OpenAudioDevice() can be.
*
* \param dev a device opened by SDL_OpenAudioDevice().
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -687,8 +687,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev)
* created through SDL_OpenAudioDevice() can be.
*
* \param dev a device opened by SDL_OpenAudioDevice().
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -767,8 +767,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid
*
* \param devid the audio device on which to change gain.
* \param gain the gain. 1.0f is no change, 0.0f is silence.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -824,8 +824,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* \param devid an audio device to bind a stream to.
* \param streams an array of audio streams to bind.
* \param num_streams number streams listed in the `streams` array.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -845,8 +845,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi
*
* \param devid an audio device to bind a stream to.
* \param stream an audio stream to bind to a device.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -953,8 +953,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
* \param stream the SDL_AudioStream to query.
* \param src_spec where to store the input audio format; ignored if NULL.
* \param dst_spec where to store the output audio format; ignored if NULL.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -983,8 +983,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s
* changed.
* \param dst_spec the new format of the audio output; if NULL, it is not
* changed.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -1027,8 +1027,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
* \param stream the stream the frequency ratio is being changed.
* \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -1074,8 +1074,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream
*
* \param stream the stream on which the gain is being changed.
* \param gain the gain. 1.0f is no change, 0.0f is silence.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -1171,8 +1171,8 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt
* \param stream the SDL_AudioStream to change.
* \param chmap the new channel map, NULL to reset to default.
* \param count The number of channels in the map.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running. Don't change the
@@ -1218,8 +1218,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio
* \param stream the SDL_AudioStream to change.
* \param chmap the new channel map, NULL to reset to default.
* \param count The number of channels in the map.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running. Don't change the
@@ -1246,8 +1246,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi
* \param stream the stream the audio data is being added to.
* \param buf a pointer to the audio data to add.
* \param len the number of bytes to write to the stream.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
@@ -1277,8 +1277,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str
* \param stream the stream the audio is being requested from.
* \param buf a buffer to fill with audio data.
* \param len the maximum number of bytes to fill.
- * \returns the number of bytes read from the stream or -1
- * on failure; call SDL_GetError() for more information.
+ * \returns the number of bytes read from the stream or -1 on failure; call
+ * SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
@@ -1306,7 +1306,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream,
* clamped.
*
* \param stream the audio stream to query.
- * \returns the number of converted/resampled bytes available or -1 on failure; call SDL_GetError() for more information.
+ * \returns the number of converted/resampled bytes available or -1 on
+ * failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1338,8 +1339,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str
* clamped.
*
* \param stream the audio stream to query.
- * \returns the number of bytes queued or -1 on failure;
- * call SDL_GetError() for more information.
+ * \returns the number of bytes queued or -1 on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1360,8 +1361,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream
* input, so the complete output becomes available.
*
* \param stream the audio stream to flush.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1378,8 +1379,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea
* stream until more is added.
*
* \param stream the audio stream to clear.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1405,8 +1406,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea
* loading, etc.
*
* \param stream the audio stream associated with the audio device to pause.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1425,8 +1426,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream
* to progress again, and audio can be generated.
*
* \param stream the audio stream associated with the audio device to resume.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1453,8 +1454,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream
* all the same attributes (recursive locks are allowed, etc).
*
* \param stream the audio stream to lock.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1471,8 +1472,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream
* This unlocks an audio stream after a call to SDL_LockAudioStream.
*
* \param stream the audio stream to unlock.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety You should only call this from the same thread that
* previously called SDL_LockAudioStream.
@@ -1560,9 +1561,8 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information. This only fails if `stream`
- * is NULL.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1610,9 +1610,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information. This only fails if `stream`
- * is NULL.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1789,8 +1788,8 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
* \param devid the ID of an opened audio device.
* \param callback a callback function to be called. Can be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1859,13 +1858,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice
* function.
* \param audio_len a pointer filled with the length of the audio data buffer
* in bytes.
- * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to an
- * allocated buffer containing the audio data, and `audio_len` is
+ * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to
+ * an allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes.
*
- * This function returns SDL_FALSE if the .WAV file cannot be opened, uses
- * an unknown data format, or is corrupt; call SDL_GetError() for
- * more information.
+ * This function returns SDL_FALSE if the .WAV file cannot be opened,
+ * uses an unknown data format, or is corrupt; call SDL_GetError()
+ * for more information.
*
* When the application is done with the data returned in
* `audio_buf`, it should call SDL_free() to dispose of it.
@@ -1895,13 +1894,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool
* function.
* \param audio_len a pointer filled with the length of the audio data buffer
* in bytes.
- * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to an
- * allocated buffer containing the audio data, and `audio_len` is
+ * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to
+ * an allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes.
*
- * This function returns SDL_FALSE if the .WAV file cannot be opened, uses
- * an unknown data format, or is corrupt; call SDL_GetError() for
- * more information.
+ * This function returns SDL_FALSE if the .WAV file cannot be opened,
+ * uses an unknown data format, or is corrupt; call SDL_GetError()
+ * for more information.
*
* When the application is done with the data returned in
* `audio_buf`, it should call SDL_free() to dispose of it.
@@ -1942,8 +1941,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec
* \param len the length of the audio buffer in bytes.
* \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
* audio volume.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1972,8 +1971,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src,
* which should be freed with SDL_free(). On error, it will be
* NULL.
* \param dst_len will be filled with the len of dst_data.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 7282e7f82d149..3d4c57e9b8352 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -366,15 +366,15 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera
* be converting to this format behind the scenes.
*
* If the system is waiting for the user to approve access to the camera, as
- * some platforms require, this will return SDL_FALSE, but this isn't necessarily a
- * fatal error; you should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED
- * (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
- * occasionally until it returns non-zero.
+ * some platforms require, this will return SDL_FALSE, but this isn't
+ * necessarily a fatal error; you should either wait for an
+ * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
+ * or poll SDL_IsCameraApproved() occasionally until it returns non-zero.
*
* \param camera opened camera device.
* \param spec the SDL_CameraSpec to be initialized by this function.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index 0e5230e677c24..4d4ae3220be57 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -46,8 +46,8 @@ extern "C" {
* Put UTF-8 text into the clipboard.
*
* \param text the text to store in the clipboard.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -89,8 +89,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
* Put UTF-8 text into the primary selection.
*
* \param text the text to store in the primary selection.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -185,8 +185,8 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
* \param userdata an opaque pointer that will be forwarded to the callbacks.
* \param mime_types a list of mime-types that are being offered.
* \param num_mime_types the number of mime-types in the mime_types list.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -199,8 +199,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallb
/**
* Clear the clipboard data.
*
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \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 6d845fb83f4bc..1d94fc7d327a1 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -1039,8 +1039,8 @@ typedef enum SDL_EventAction
* SDL_EVENT_FIRST is a safe choice.
* \param maxType maximum value of the event type to be considered;
* SDL_EVENT_LAST is a safe choice.
- * \returns the number of events actually stored or -1 on
- * failure; call SDL_GetError() for more information.
+ * \returns the number of events actually stored or -1 on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1254,8 +1254,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint
* its own custom event types.
*
* \param event the SDL_Event to be added to the queue.
- * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on failure; call SDL_GetError() for more information. A
- * common reason for error is the event queue being full.
+ * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on
+ * failure; call SDL_GetError() for more information. A common reason
+ * for error is the event queue being full.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1371,8 +1372,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
*
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index abf9875bb397c..5faa244b8906b 100644
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@@ -266,8 +266,8 @@ typedef Uint32 SDL_GlobFlags;
* Create a directory.
*
* \param path the path of the directory to create.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -289,8 +289,8 @@ typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char
* \param path the path of the directory to enumerate.
* \param callback a function that is called for each entry in the directory.
* \param userdata a pointer that is passed to `callback`.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -300,8 +300,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SD
* Remove a file or an empty directory.
*
* \param path the path of the directory to enumerate.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -312,8 +312,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path);
*
* \param oldpath the old path.
* \param newpath the new path.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -324,8 +324,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const c
*
* \param oldpath the old path.
* \param newpath the new path.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -337,8 +337,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha
* \param path the path to query.
* \param info a pointer filled in with information about the path, or NULL to
* check for the existence of a file.
- * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist,
- * or another failure; call SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or
+ * another failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 22e315fbe9bc0..3d2d726d77417 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -379,8 +379,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file)
*
* This will generate gamepad events as needed if device mappings change.
*
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -442,8 +442,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
* \param instance_id the joystick instance ID.
* \param mapping the mapping to use for this device, or NULL to clear the
* mapping.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -813,8 +813,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *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.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1257,8 +1257,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga
* \param y filled with y position, normalized 0 to 1, with the origin in the
* upper left.
* \param pressure filled with pressure value.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1287,8 +1287,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad,
* \param gamepad the gamepad to update.
* \param type the type of sensor to enable/disable.
* \param enabled whether data reporting should be enabled.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1331,8 +1331,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game
* \param type the type of sensor to query.
* \param data a pointer filled with the current sensor state.
* \param num_values the number of values to write to data.
- * \returns SDL_TRUE on success or SDL_FALSE on failure; call
- * SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
*
* \since
(Patch may be truncated, please check the link at the top of this post.)