Sync SDL3 wiki -> header

docs/README-strings.md

@@ -0,0 +1,59 @@
+# String policies in SDL3.
+
+## Encoding.
+
+Unless otherwise specified, all strings in SDL, across all platforms, are
+UTF-8 encoded and can represent the full range of [Unicode](https://unicode.org).
+
+
+## The SDL Get String Rule.
+
+Did you see 'SDL_GetStringRule' in the wiki or headers? Here are the details
+that aren't worth copying across dozens of functions' documentation.
+
+tl;dr: If an SDL function returns a `const char *` string, do not modify or
+free it, and if you need to save it, make a copy right away.
+
+In several cases, SDL wants to return a string to the app, and the question
+in any library that does this is: _who owns this thing?_
+
+The answer in almost all cases, is that SDL does, but not for long.
+
+The pointer is only guaranteed to be valid until the next time the event
+queue is updated, or SDL_Quit is called.
+
+The reason for this is memory safety.
+
+There are several strings that SDL provides that could be freed at
+any moment. For example, an app calls SDL_GetAudioDeviceName(), which returns
+a string that is part of the internal audio device structure. But, while this
+function is returning, the user yanks the USB audio device out of the
+computer, and SDL decides to deallocate the structure...and the string!
+Now the app is holding a pointer that didn't live long enough to be useful,
+and could crash if accessed.
+
+To avoid this, instead of calling SDL_free on a string as soon as it's done
+with it, SDL adds the pointer to a list. This list is freed at specific
+points: when the event queue is run (for ongoing cleanup) and when SDL_Quit
+is called (to catch things that are just hanging around). This allows the
+app to use a string without worrying about it becoming bogus in the middle
+of a printf() call. If the app needs it for longer, it should copy it.
+
+When does "the event queue run"? There are several points:
+
+- If the app calls SDL_PumpEvents() _from any thread_.
+- SDL_PumpEvents is also called by several other APIs internally:
+  SDL_PollEvent(), SDL_PeepEvents(), SDL_WaitEvent(),
+  SDL_WaitEventTimeout(), and maybe others.
+- If you are using [the main callbacks](main-functions#main-callbacks-in-sdl3),
+  the event queue can run immediately after any of the callback functions
+  return.
+
+Note that these are just guaranteed minimum lifespans; any given string
+might live much longer--some might even be static memory that is _never_
+deallocated--but this rule promises that the app has a safe window.
+
+Note that none of this applies if the return value is `char *` instead of
+`const char *`. Please see the specific function's documentation for how
+to handle those pointers.
+

include/SDL3/SDL_audio.h

@@ -400,7 +400,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
  * "coreaudio" or "wasapi". These never have Unicode characters, and are not
  * meant to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param index the index of the audio driver; the value ranges from 0 to
  *              SDL_GetNumAudioDrivers() - 1.
@@ -423,7 +424,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
  * "coreaudio" or "wasapi". These never have Unicode characters, and are not
  * meant to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the name of the current audio driver or NULL if no driver has been
  *          initialized.
@@ -448,11 +450,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
  * If this function returns NULL, to signify an error, `*count` will be set to
  * zero.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of devices returned, may be NULL.
- * \returns a 0 terminated array of device instance IDs or NULL on error; call SDL_GetError() for more
- *          information.
+ * \param count a pointer filled in with the number of devices returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of device instance IDs or NULL on error; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -477,11 +481,13 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice
  * If this function returns NULL, to signify an error, `*count` will be set to
  * zero.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of devices returned, may be NULL.
- * \returns a 0 terminated array of device instance IDs, or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \param count a pointer filled in with the number of devices returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of device instance IDs, or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -495,7 +501,8 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic
 /**
  * Get the human-readable name of a specific audio device.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param devid the instance ID of the device to query.
  * \returns the name of the audio device, or NULL on failure; call
@@ -555,7 +562,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
  * Audio devices usually have no remapping applied. This is represented by
  * returning NULL, and does not signify an error.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param devid the instance ID of the device to query.
  * \param count On output, set to number of channels in the map. Can be NULL.
@@ -634,8 +642,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDe
  *              default device.
  * \param spec the requested device configuration. Can be NULL to use
  *             reasonable defaults.
- * \returns the device ID on success or 0 on failure; call SDL_GetError() for more
- *          information.
+ * \returns the device ID on success or 0 on failure; call SDL_GetError() for
+ *          more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -739,8 +747,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
  * this function will always return -1.0f when used on physical devices.
  *
  * \param devid the audio device to query.
- * \returns the gain of the device or -1.0f on failure; call
- *          SDL_GetError() for more information.
+ * \returns the gain of the device or -1.0f on failure; call SDL_GetError()
+ *          for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -831,7 +839,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
  * \param streams an array of audio streams to unbind.
  * \param num_streams number streams listed in the `streams` array.
  * \returns 0 on success or a negative error code on failure; call
- *           SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -851,8 +859,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD
  *
  * \param devid an audio device to bind a stream to.
  * \param stream an audio stream to bind to a device.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more
- *          information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -992,7 +1000,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
  * \param dst_spec the new format of the audio output; if NULL, it is not
  *                 changed.
  * \returns 0 on success or a negative error code on failure; call
- *           SDL_GetError() for more information.
+ *          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.
@@ -1059,8 +1067,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
  * Audio streams default to a gain of 1.0f (no change in output).
  *
  * \param stream the SDL_AudioStream to query.
- * \returns the gain of the stream or -1.0f on failure; call
- *          SDL_GetError() for more information.
+ * \returns the gain of the stream or -1.0f 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.
@@ -1105,7 +1113,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
  * Audio streams default to no remapping applied. This is represented by
  * returning NULL, and does not signify an error.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param stream the SDL_AudioStream to query.
  * \param count On output, set to number of channels in the map. Can be NULL.
@@ -1130,7 +1139,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au
  * Audio streams default to no remapping applied. This is represented by
  * returning NULL, and does not signify an error.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param stream the SDL_AudioStream to query.
  * \param count On output, set to number of channels in the map. Can be NULL.
@@ -1289,8 +1299,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
  * \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 a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns the number of bytes read from the stream or a negative error code
+ *          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
@@ -1572,7 +1582,8 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
  * \param userdata an opaque pointer provided to the callback for its own
  *                 personal use.
  * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information. This only fails if `stream` is NULL.
+ *          SDL_GetError() for more information. This only fails if `stream`
+ *          is NULL.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1621,7 +1632,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s
  * \param userdata an opaque pointer provided to the callback for its own
  *                 personal use.
  * \returns 0 on success or a negative error code on failure; call
- *            SDL_GetError() for more information. This only fails if `stream` is NULL.
+ *          SDL_GetError() for more information. This only fails if `stream`
+ *          is NULL.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_camera.h

@@ -134,7 +134,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
  * "coremedia" or "android". These never have Unicode characters, and are not
  * meant to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param index the index of the camera driver; the value ranges from 0 to
  *              SDL_GetNumCameraDrivers() - 1.
@@ -156,7 +157,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
  * "coremedia" or "android". These never have Unicode characters, and are not
  * meant to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the name of the current camera driver or NULL if no driver has
  *          been initialized.
@@ -170,12 +172,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
 /**
  * Get a list of currently connected camera devices.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of cameras returned, may be
- *              NULL.
- * \returns a 0 terminated array of camera instance IDs or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \param count a pointer filled in with the number of cameras returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of camera instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -201,18 +204,20 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
  * If `count` is not NULL, it will be filled with the number of elements in
  * the returned array.
  *
- * Note that it's legal for a camera to supply an empty list. This is what will happen on
- * Emscripten builds, since that platform won't tell _anything_ about
- * available cameras until you've opened one, and won't even tell if there
- * _is_ a camera until the user has given you permission to check through a
- * scary warning popup.
+ * Note that it's legal for a camera to supply an empty list. This is what
+ * will happen on Emscripten builds, since that platform won't tell _anything_
+ * about available cameras until you've opened one, and won't even tell if
+ * there _is_ a camera until the user has given you permission to check
+ * through a scary warning popup.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param devid the camera device instance ID to query.
- * \param count a pointer filled in with the number of elements in the list, may be NULL.
- * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on failure; call
- *          SDL_GetError() for more information.
+ * \param count a pointer filled in with the number of elements in the list,
+ *              may be NULL.
+ * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -226,7 +231,8 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte
 /**
  * Get the human-readable device name for a camera.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the camera device instance ID.
  * \returns a human-readable device name or NULL on failure; call
@@ -293,8 +299,8 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI
  * \param instance_id the camera device instance ID.
  * \param spec the desired format for data the device will provide. Can be
  *             NULL.
- * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_clipboard.h

@@ -62,7 +62,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
  * This functions returns empty string if there was not enough memory left for
  * a copy of the clipboard's content.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the clipboard text on success or an empty string on failure; call
  *          SDL_GetError() for more information.
@@ -106,7 +107,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
  * This functions returns empty string if there was not enough memory left for
  * a copy of the primary selection's content.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the primary selection text on success or an empty string on
  *          failure; call SDL_GetError() for more information.
@@ -221,7 +223,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
  * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
  *          for more information.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ *          This returns temporary memory which will be automatically freed
+ *          later, and can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_error.h

@@ -96,8 +96,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_OutOfMemory(void);
  * Error strings are set per-thread, so an error set in a different thread
  * will not interfere with the current thread's operation.
  *
- * The returned value is a thread-local string which will remain valid until the current thread's error string is changed. The caller
- * should make a copy if the value is needed after the next SDL API call.
+ * The returned value is a thread-local string which will remain valid until
+ * the current thread's error string is changed. The caller should make a copy
+ * if the value is needed after the next SDL API call.
  *
  * \returns a message with information about the specific error that occurred,
  *          or an empty string if there hasn't been an error message set since

include/SDL3/SDL_events.h

@@ -350,7 +350,8 @@ typedef struct SDL_KeyboardEvent
  * will be inserted into the editing text. The length is the number of UTF-8
  * characters that will be replaced by new typing.
  *
- * The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * The text string is temporary memory which will be automatically freed
+ * later, and can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -368,7 +369,8 @@ typedef struct SDL_TextEditingEvent
 /**
  * Keyboard IME candidates event structure (event.edit_candidates.*)
  *
- * The candidates are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * The candidates are temporary memory which will be automatically freed
+ * later, and can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -387,7 +389,8 @@ typedef struct SDL_TextEditingCandidatesEvent
 /**
  * Keyboard text input event structure (event.text.*)
  *
- * The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * The text string is temporary memory which will be automatically freed
+ * later, and can be claimed with SDL_ClaimTemporaryMemory().
  *
  * This event will never be delivered unless text input is enabled by calling
  * SDL_StartTextInput(). Text input is disabled by default!
@@ -784,7 +787,9 @@ typedef struct SDL_PenButtonEvent
  * An event used to drop text or request a file open by the system
  * (event.drop.*)
  *
- * The source and data strings are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * The source and data strings are temporary memory which will be
+ * automatically freed later, and can be claimed with
+ * SDL_ClaimTemporaryMemory().
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -1409,7 +1414,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
 /**
  * Allocate temporary memory.
  *
- * You can use this to allocate memory that will be automatically freed later, after event processing is complete.
+ * You can use this to allocate memory that will be automatically freed later,
+ * after event processing is complete.
  *
  * \param size the amount of memory to allocate.
  * \returns a pointer to the memory allocated or NULL on failure; call
@@ -1427,13 +1433,20 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size);
 /**
  * Claim ownership of temporary memory.
  *
- * This function changes ownership of temporary memory allocated for events and functions that
- * return temporary memory. If this function succeeds, the memory will no longer be automatically freed by SDL, it must be freed using SDL_free() by the application.
+ * This function changes ownership of temporary memory allocated for events
+ * and functions that return temporary memory. If this function succeeds, the
+ * memory will no longer be automatically freed by SDL, it must be freed using
+ * SDL_free() by the application.
  *
- * If the memory isn't temporary, or it was allocated on a different thread, or if it is associated with an event currently in the event queue, this will return NULL, and the application does not have ownership of the memory.
+ * If the memory isn't temporary, or it was allocated on a different thread,
+ * or if it is associated with an event currently in the event queue, this
+ * will return NULL, and the application does not have ownership of the
+ * memory.
  *
  * \param mem a pointer allocated with SDL_AllocateTemporaryMemory().
- * \returns a pointer to the memory now owned by the application, which must be freed using SDL_free(), or NULL if the memory is not temporary or was allocated on a different thread.
+ * \returns a pointer to the memory now owned by the application, which must
+ *          be freed using SDL_free(), or NULL if the memory is not temporary
+ *          or was allocated on a different thread.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1447,17 +1460,22 @@ extern SDL_DECLSPEC void * SDLCALL SDL_ClaimTemporaryMemory(const void *mem);
 /**
  * Free temporary memory.
  *
- * This function frees temporary memory allocated for events and functions that
- * return temporary memory. This memory is local to the thread that creates
- * it and is automatically freed for the main thread when processing events.
- * For other threads you may call this function periodically to
- * free any temporary memory created by that thread.
+ * This function frees temporary memory allocated for events and functions
+ * that return temporary memory. This memory is local to the thread that
+ * creates it and is automatically freed for the main thread when processing
+ * events. For other threads you may call this function periodically to free
+ * any temporary memory created by that thread.
  *
- * You can free a specific pointer, to provide more fine grained control over memory management, or you can pass NULL to free all pending temporary allocations.
+ * You can free a specific pointer, to provide more fine grained control over
+ * memory management, or you can pass NULL to free all pending temporary
+ * allocations.
  *
- * All temporary memory is freed on the main thread in SDL_Quit() and for other threads when they call SDL_CleanupTLS(), which is automatically called at cleanup time for threads created using SDL_CreateThread().
+ * All temporary memory is freed on the main thread in SDL_Quit() and for
+ * other threads when they call SDL_CleanupTLS(), which is automatically
+ * called at cleanup time for threads created using SDL_CreateThread().
  *
- * \param mem a pointer allocated with SDL_AllocateTemporaryMemory(), or NULL to free all pending temporary allocations.
+ * \param mem a pointer allocated with SDL_AllocateTemporaryMemory(), or NULL
+ *            to free all pending temporary allocations.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_filesystem.h

@@ -68,7 +68,8 @@ extern "C" {
  * The returned path is guaranteed to end with a path separator ('\\' on
  * Windows, '/' on most other platforms).
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns an absolute path in UTF-8 encoding to the application data
  *          directory. NULL will be returned on error or when the platform
@@ -123,7 +124,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
  * The returned path is guaranteed to end with a path separator ('\\' on
  * Windows, '/' on most other platforms).
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param org the name of your organization.
  * \param app the name of your application.
@@ -223,7 +225,8 @@ typedef enum SDL_Folder
  * The returned path is guaranteed to end with a path separator ('\\' on
  * Windows, '/' on most other platforms).
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * If NULL is returned, the error may be obtained with SDL_GetError().
  *
@@ -354,7 +357,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
  * convenience, but if `count` is non-NULL, on return it will contain the
  * number of items in the array, not counting the NULL terminator.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param path the path of the directory to enumerate.
  * \param pattern the pattern that files in the directory must match. Can be

include/SDL3/SDL_gamepad.h

@@ -282,9 +282,9 @@ typedef struct SDL_GamepadBinding
  * existing gamepad.
  *
  * The mapping string has the format "GUID,name,mapping", where GUID is the
- * string value from SDL_GUIDToString(), 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
+ * string value from SDL_GUIDToString(), 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
@@ -389,7 +389,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
 /**
  * Get the current gamepad mappings.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of mappings returned, can
  *              be NULL.
@@ -403,7 +404,8 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
 /**
  * Get the gamepad mapping string for a given GUID.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param guid a structure containing the GUID for which a mapping is desired.
  * \returns a mapping string or NULL on failure; call SDL_GetError() for more
@@ -419,7 +421,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID g
 /**
  * Get the current mapping of a gamepad.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * Details about mappings are discussed with SDL_AddGamepadMapping().
  *
@@ -468,11 +471,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
 /**
  * Get a list of currently connected gamepads.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of gamepads returned, may be NULL.
- * \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for
- *          more information.
+ * \param count a pointer filled in with the number of gamepads returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -500,7 +505,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
  *
  * This can be called before any gamepads are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the joystick instance ID.
  * \returns the name of the selected gamepad. If no name can be found, this
@@ -518,7 +524,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID
  *
  * This can be called before any gamepads are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the joystick instance ID.
  * \returns the path of the selected gamepad. If no path can be found, this
@@ -651,7 +658,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
  *
  * This can be called before any gamepads are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the joystick instance ID.
  * \returns the mapping string. Returns NULL if no mapping is available.
@@ -750,7 +758,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
 /**
  * Get the implementation-dependent name for an opened gamepad.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param gamepad a gamepad identifier previously returned by
  *                SDL_OpenGamepad().
@@ -766,7 +775,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad
 /**
  * Get the implementation-dependent path for an opened gamepad.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param gamepad a gamepad identifier previously returned by
  *                SDL_OpenGamepad().
@@ -893,7 +903,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga
  *
  * Returns the serial number of the gamepad, or NULL if it is not available.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param gamepad the gamepad object to query.
  * \returns the serial number, or NULL if unavailable.
@@ -972,7 +983,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
  * SDL to crash.
  *
  * \param gamepad the gamepad object that you want to get a joystick from.
- * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() for more information.
+ * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1053,7 +1065,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
 /**
  * Convert from an SDL_GamepadType enum to a string.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param type an enum value for a given SDL_GamepadType.
  * \returns a string for the given type, or NULL if an invalid type is
@@ -1091,7 +1104,8 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
 /**
  * Convert from an SDL_GamepadAxis enum to a string.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param axis an enum value for a given SDL_GamepadAxis.
  * \returns a string for the given axis, or NULL if an invalid axis is
@@ -1166,7 +1180,8 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
 /**
  * Convert from an SDL_GamepadButton enum to a string.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param button an enum value for a given SDL_GamepadButton.
  * \returns a string for the given button, or NULL if an invalid button is
@@ -1454,7 +1469,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
  * Return the sfSymbolsName for a given button on a gamepad on Apple
  * platforms.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param gamepad the gamepad to query.
  * \param button a button on the gamepad.
@@ -1469,7 +1485,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt
 /**
  * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param gamepad the gamepad to query.
  * \param axis an axis on the gamepad.

include/SDL3/SDL_guid.h

@@ -66,7 +66,8 @@ typedef struct SDL_GUID {
 /**
  * Get an ASCII string representation for a given SDL_GUID.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param guid the SDL_GUID you wish to convert to string.
  * \returns the string representation of the GUID or NULL on failure; call

include/SDL3/SDL_haptic.h

@@ -931,12 +931,13 @@ typedef Uint32 SDL_HapticID;
 /**
  * Get a list of currently connected haptic devices.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of haptic devices
  *              returned, may be NULL.
- * \returns a 0 terminated array of haptic device instance IDs or NULL on failure; call SDL_GetError() for
- *          more information.
+ * \returns a 0 terminated array of haptic device instance IDs or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -949,7 +950,8 @@ extern SDL_DECLSPEC const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
  *
  * This can be called before any haptic devices are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the haptic device instance ID.
  * \returns the name of the selected haptic device. If no name can be found,
@@ -1014,7 +1016,8 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
 /**
  * Get the implementation dependent name of a haptic device.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
  * \returns the name of the selected haptic device. If no name can be found,

include/SDL3/SDL_hidapi.h

@@ -263,8 +263,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
  * \param serial_number the Serial Number of the device to open (Optionally
  *                      NULL).
  * \returns a pointer to a SDL_hid_device object on success or NULL on
- *          failure; call
- *          SDL_GetError() for more information.
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -278,8 +277,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
  *
  * \param path the path name of the device to open.
  * \returns a pointer to a SDL_hid_device object on success or NULL on
- *          failure; call
- *          SDL_GetError() for more information.
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -326,9 +324,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
  *               number.
  * \param milliseconds timeout in milliseconds or -1 for blocking wait.
  * \returns the actual number of bytes read and -1 on on failure; call
- *          SDL_GetError() for more information. If no packet was
- *          available to be read within the timeout period, this function
- *          returns 0.
+ *          SDL_GetError() for more information. If no packet was available to
+ *          be read within the timeout period, this function returns 0.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -347,9 +344,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
  *               reports, make sure to read an extra byte for the report
  *               number.
  * \returns the actual number of bytes read and -1 on failure; call
- *            SDL_GetError() for more information. If no packet was
- *          available to be read and the handle is in non-blocking mode, this
- *          function returns 0.
+ *          SDL_GetError() for more information. If no packet was available to
+ *          be read and the handle is in non-blocking mode, this function
+ *          returns 0.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -393,7 +390,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
  * \param length the length in bytes of the data to send, including the report
  *               number.
  * \returns the actual number of bytes written and -1 on failure; call
- *            SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -415,8 +412,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
  * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
- *          still in the first byte), or -1 on on failure; call
- *                    SDL_GetError() for more information.
+ *          still in the first byte), or -1 on on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -438,8 +435,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
  * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
- *          still in the first byte), or -1 on on failure; call
- *          SDL_GetError() for more information.
+ *          still in the first byte), or -1 on on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -514,9 +511,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
  *
  * \param dev a device handle returned from SDL_hid_open().
  * \returns a pointer to the SDL_hid_device_info for this hid_device or NULL
- *          on failure; call SDL_GetError() for more information.
- *          This struct is valid until the device is closed with
- *          SDL_hid_close().
+ *          on failure; call SDL_GetError() for more information. This struct
+ *          is valid until the device is closed with SDL_hid_close().
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_hints.h

@@ -3883,7 +3883,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
 /**
  * Get the value of a hint.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param name the hint to query.
  * \returns the string value of a hint or NULL if the hint isn't set.

include/SDL3/SDL_iostream.h

@@ -224,8 +224,8 @@ typedef struct SDL_IOStream SDL_IOStream;
  * \param file a UTF-8 string representing the filename to open.
  * \param mode an ASCII string representing the mode to be used for opening
  *             the file.
- * \returns a pointer to the SDL_IOStream structure that is created or NULL
- *          on failure; call SDL_GetError() for more information.
+ * \returns a pointer to the SDL_IOStream structure that is created or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -258,8 +258,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons
  *
  * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
  * \param size the buffer size, in bytes.
- * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
- *          call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -291,8 +291,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size)
  *
  * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
  * \param size the buffer size, in bytes.
- * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
- *          call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -319,8 +319,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s
  * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
  *   multiples of this size, defaulting to 1024.
  *
- * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
- *          call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -488,7 +488,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
  * \param context a pointer to an SDL_IOStream 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, or 0 on end of file or other failure; call SDL_GetError() for more information.
+ * \returns the number of bytes read, or 0 on end of file or other failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -576,7 +577,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
  * \param datasize if not NULL, will store the number of bytes read.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
- * \returns the data or NULL on failure; call SDL_GetError() for more information.
+ * \returns the data or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -595,7 +597,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da
  *
  * \param file the path to read all available data from.
  * \param datasize if not NULL, will store the number of bytes read.
- * \returns the data or NULL on failure; call SDL_GetError() for more information.
+ * \returns the data or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_joystick.h

@@ -37,9 +37,9 @@
  * controller. For XInput controllers this returns the XInput user index. Many
  * joysticks will not be able to supply this information.
  *
- * SDL_GUID is used as a stable 128-bit identifier for a joystick
- * device that does not change over time. It identifies class of the device (a
- * X360 wired controller for example). This identifier is platform dependent.
+ * SDL_GUID is used as a stable 128-bit identifier for a joystick device that
+ * does not change over time. It identifies class of the device (a X360 wired
+ * controller for example). This identifier is platform dependent.
  *
  * In order to use these functions, SDL_Init() must have been called with the
  * SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks,
@@ -201,11 +201,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
 /**
  * Get a list of currently connected joysticks.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of joysticks returned, may be NULL.
- * \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for
- *          more information.
+ * \param count a pointer filled in with the number of joysticks returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -219,7 +221,8 @@ extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
  *
  * This can be called before any joysticks are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the joystick instance ID.
  * \returns the name of the selected joystick. If no name can be found, this
@@ -237,7 +240,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID
  *
  * This can be called before any joysticks are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the joystick instance ID.
  * \returns the path of the selected joystick. If no path can be found, this
@@ -356,8 +360,8 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti
  * for use.
  *
  * \param instance_id the joystick instance ID.
- * \returns a joystick identifier or NULL on failure; call
- *          SDL_GetError() for more information.
+ * \returns a joystick identifier or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -462,8 +466,8 @@ typedef struct SDL_VirtualJoystickDesc
  * Attach a new virtual joystick.
  *
  * \param desc joystick description.
- * \returns the joystick instance ID, or 0 on failure; call
- *          SDL_GetError() for more information.
+ * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -658,7 +662,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
 /**
  * Get the implementation dependent name of a joystick.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the name of the selected joystick. If no name can be found, this
@@ -673,7 +678,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst
 /**
  * Get the implementation dependent path of a joystick.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the path of the selected joystick. If no path can be found, this
@@ -792,7 +798,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
  *
  * Returns the serial number of the joystick, or NULL if it is not available.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the serial number of the selected joystick, or NULL if
@@ -814,20 +821,6 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
  */
 extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joystick);
 
-/**
- * Convert a GUID string into a SDL_GUID structure.
- *
- * Performs no error checking. If this function is given a string containing
- * an invalid GUID, the function will silently succeed, but the GUID generated
- * will not be useful.
- *
- * \param pchGUID string containing an ASCII representation of a GUID.
- * \returns a SDL_GUID structure.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_GUIDToString
- */
 extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GUIDFromString(const char *pchGUID);
 
 /**

include/SDL3/SDL_keyboard.h

@@ -73,11 +73,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
  * power buttons, etc. You should wait for input from a device before you
  * consider it actively in use.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of keyboards returned, may be NULL.
- * \returns a 0 terminated array of keyboards instance IDs or NULL on failure; call SDL_GetError() for
- *          more information.
+ * \param count a pointer filled in with the number of keyboards returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of keyboards instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -91,7 +93,8 @@ extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
  *
  * This function returns "" if the keyboard doesn't have a name.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the keyboard instance ID.
  * \returns the name of the selected keyboard or NULL on failure; call
@@ -281,7 +284,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const
 /**
  * Get a human-readable name for a scancode.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * **Warning**: The returned name is by design not stable across platforms,
  * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
@@ -327,7 +331,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
  *
  * If the key doesn't have a name, this function returns an empty string ("").
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param key the desired SDL_Keycode to query.
  * \returns a UTF-8 encoded string of the key name.

include/SDL3/SDL_loadso.h

@@ -56,7 +56,8 @@ extern "C" {
  * Dynamically load a shared object.
  *
  * \param sofile a system-dependent name of the object file.
- * \returns an opaque pointer to the object handle or NULL on failure; call SDL_GetError() for more information.
+ * \returns an opaque pointer to the object handle or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -82,8 +83,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile);
  *
  * \param handle a valid shared object handle returned by SDL_LoadObject().
  * \param name the name of the function to look up.
- * \returns a pointer to the function or NULL on failure; call
- *          SDL_GetError() for more information.
+ * \returns a pointer to the function or NULL on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_locale.h

@@ -94,12 +94,13 @@ typedef struct SDL_Locale
  * if possible, and you can call this function again to get an updated copy of
  * preferred locales.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of locales returned, may
  *              be NULL.
- * \returns a NULL terminated array of locale pointers, or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \returns a NULL terminated array of locale pointers, or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_mouse.h

@@ -135,11 +135,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
  * You should wait for input from a device before you consider it actively in
  * use.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
- * \param count a pointer filled in with the number of mice returned, may be NULL.
- * \returns a 0 terminated array of mouse instance IDs or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \param count a pointer filled in with the number of mice returned, may be
+ *              NULL.
+ * \returns a 0 terminated array of mouse instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -153,7 +155,8 @@ extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
  *
  * This function returns "" if the mouse doesn't have a name.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the mouse instance ID.
  * \returns the name of the selected mouse, or NULL on failure; call
@@ -483,7 +486,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
  * 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 failuree; call SDL_GetError() for more information.
+ * \returns the default cursor on success or NULL on failuree; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_pen.h

@@ -224,7 +224,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
 /**
  * Retrieves a human-readable description for a SDL_PenID.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the pen to query.
  * \returns a string that contains the name of the pen, intended for human

include/SDL3/SDL_properties.h

@@ -378,7 +378,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props
 /**
  * Get a string property from a group of properties.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param props the properties to query.
  * \param name the name of the property to query.

include/SDL3/SDL_render.h

@@ -154,7 +154,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
  * "direct3d12" or "metal". These never have Unicode characters, and are not
  * meant to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param index the index of the rendering driver; the value ranges from 0 to
  *              SDL_GetNumRenderDrivers() - 1.
@@ -324,10 +325,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende
 /**
  * Get the name of a renderer.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param renderer the rendering context.
- * \returns the name of the selected renderer, or NULL on failure; call SDL_GetError() for more information.
+ * \returns the name of the selected renderer, or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1768,7 +1771,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD
  * \param rect a pointer to the destination rectangle, or NULL to outline the
  *             entire rendering target.
  * \returns 0 on success or a negative error code on failure; call
- *            SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1800,7 +1803,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD
  * \param rect a pointer to the destination rectangle, or NULL for the entire
  *             rendering target.
  * \returns 0 on success or a negative error code on failure; call
- *            SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1835,7 +1838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons
  * \param dstrect a pointer to the destination rectangle, or NULL for the
  *                entire rendering target.
  * \returns 0 on success or a negative error code on failure; call
- *            SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1886,7 +1889,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer,
  *                order.
  * \param num_indices number of indices.
  * \returns 0 on success or a negative error code on failure; call
- *            SDL_GetError() for more information.
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_sensor.h

@@ -146,9 +146,10 @@ typedef enum SDL_SensorType
 /**
  * Get a list of currently connected sensors.
  *
- * \param count a pointer filled in with the number of sensors returned, may be NULL.
- * \returns a 0 terminated array of sensor instance IDs or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \param count a pointer filled in with the number of sensors returned, may
+ *              be NULL.
+ * \returns a 0 terminated array of sensor instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -159,7 +160,8 @@ extern SDL_DECLSPEC const SDL_SensorID * SDLCALL SDL_GetSensors(int *count);
  *
  * This can be called before any sensors are opened.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param instance_id the sensor instance ID.
  * \returns the sensor name, or NULL if `instance_id` is not valid.
@@ -198,7 +200,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i
  * Open a sensor for use.
  *
  * \param instance_id the sensor instance ID.
- * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
+ * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -208,7 +211,8 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id
  * Return the SDL_Sensor associated with an instance ID.
  *
  * \param instance_id the sensor instance ID.
- * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
+ * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -228,10 +232,12 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
 /**
  * Get the implementation dependent name of a sensor.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param sensor the SDL_Sensor object.
- * \returns the sensor name or NULL on failure; call SDL_GetError() for more information.
+ * \returns the sensor name or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -262,7 +268,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
  * Get the instance ID of a sensor.
  *
  * \param sensor the SDL_Sensor object to inspect.
- * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for more information.
+ * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_storage.h

@@ -227,8 +227,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
  * \param storage a storage container to query.
  * \param path the relative path of the file to query.
  * \param length a pointer to be filled with the file's length.
- * \returns 0 if the file could be queried or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns 0 if the file could be queried or a negative error code on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -263,8 +263,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
  * \param path the relative path of the file to write.
  * \param source a client-provided buffer to write from.
  * \param length the length of the source buffer.
- * \returns 0 if the file was written or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns 0 if the file was written or a negative error code on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -383,7 +383,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
  * convenience, but if `count` is non-NULL, on return it will contain the
  * number of items in the array, not counting the NULL terminator.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param storage a storage container.
  * \param path the path of the directory to enumerate.

include/SDL3/SDL_surface.h

@@ -355,8 +355,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  * \param src the data stream for the surface.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
- * \returns a pointer to a new SDL_Surface structure or NULL on failure;
- *          call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -373,8 +373,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_
  * will result in a memory leak.
  *
  * \param file the BMP file to load.
- * \returns a pointer to a new SDL_Surface structure or NULL on failure;
- *          call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_system.h

@@ -162,7 +162,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
  *
  * \param threadID the Unix thread ID to change priority of.
  * \param priority the new, Unix-specific, priority value.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -280,7 +281,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled);
  * rationale being that the SDL headers can avoid including jni.h.
  *
  * \returns a pointer to Java native interface object (JNIEnv) to which the
- *          current thread is attached, or NULL on failure; call SDL_GetError() for more information.
+ *          current thread is attached, or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -304,7 +306,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
  * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
  *
  * \returns the jobject representing the instance of the Activity class of the
- *          Android application, or NULL on failure; call SDL_GetError() for more information.
+ *          Android application, or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -407,7 +410,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
  *
  * https://developer.android.com/reference/android/content/Context#getFilesDir()
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the path used for internal storage or NULL on failure; call
  *          SDL_GetError() for more information.
@@ -448,7 +452,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
  *
  * https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the path used for external storage for this application on success
  *          or NULL on failure; call SDL_GetError() for more information.
@@ -471,7 +476,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void)
  *
  * https://developer.android.com/reference/android/content/Context#getCacheDir()
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the path used for caches for this application on success or NULL
  *          on failure; call SDL_GetError() for more information.
@@ -625,7 +631,8 @@ typedef enum SDL_WinRT_DeviceFamily
  *
  * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param pathType the type of path to retrieve, one of SDL_WinRT_Path.
  * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
@@ -813,7 +820,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQue
  *
  * \param outUserHandle a pointer to be filled in with the default user
  *                      handle.
- * \returns 0 if success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 if success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_thread.h

@@ -330,7 +330,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S
 /**
  * Get the thread name as it was specified in SDL_CreateThread().
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param thread the thread to query.
  * \returns a pointer to a UTF-8 string that names the specified thread, or
@@ -520,7 +521,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL
 /**
  * Cleanup all TLS data for this thread.
  *
- * If you are creating your threads outside of SDL and then calling SDL functions, you should call this function before your thread exits, to properly clean up SDL memory.
+ * If you are creating your threads outside of SDL and then calling SDL
+ * functions, you should call this function before your thread exits, to
+ * properly clean up SDL memory.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_time.h

@@ -95,7 +95,8 @@ typedef enum SDL_TimeFormat
  *                   format, may be NULL.
  * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
  *                   format, may be NULL.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -106,7 +107,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
  * Jan 1, 1970 in Universal Coordinated Time (UTC).
  *
  * \param ticks the SDL_Time to hold the returned tick count.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -121,7 +123,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
  * \param localTime the resulting SDL_DateTime will be expressed in local time
  *                  if true, otherwise it will be in Universal Coordinated
  *                  Time (UTC).
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -135,7 +138,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
  *
  * \param dt the source SDL_DateTime.
  * \param ticks the resulting SDL_Time.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -177,7 +181,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
  *
  * \param year the year.
  * \param month the month [1-12].
- * \returns the number of days in the requested month or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns the number of days in the requested month or a negative error code
+ *          on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -189,7 +194,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
  * \param year the year component of the date.
  * \param month the month component of the date.
  * \param day the day component of the date.
- * \returns the day of year [0-365] if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns the day of year [0-365] if the date is valid or a negative error
+ *          code on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -201,7 +207,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
  * \param year the year component of the date.
  * \param month the month component of the date.
  * \param day the day component of the date.
- * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_touch.h

@@ -83,12 +83,13 @@ typedef struct SDL_Finger
  * Therefore the returned list might be empty, although devices are available.
  * After using all devices at least once the number will be correct.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of devices returned, may
  *              be NULL.
- * \returns a 0 terminated array of touch device IDs or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \returns a 0 terminated array of touch device IDs or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -97,11 +98,12 @@ extern SDL_DECLSPEC const SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count);
 /**
  * Get the touch device name as reported from the driver.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param touchID the touch device instance ID.
- * \returns touch device name, or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \returns touch device name, or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_video.h

@@ -349,7 +349,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
  * "x11" or "windows". These never have Unicode characters, and are not meant
  * to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param index the index of a video driver.
  * \returns the name of the video driver with the given **index**.
@@ -367,7 +368,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
  * "x11" or "windows". These never have Unicode characters, and are not meant
  * to be proper names.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \returns the name of the current video driver or NULL if no driver has been
  *          initialized.
@@ -391,12 +393,13 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
 /**
  * Get a list of currently connected displays.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of displays returned, may
  *              be NULL.
- * \returns a 0 terminated array of display instance IDs or NULL on failure; call SDL_GetError() for more
- *          information.
+ * \returns a 0 terminated array of display instance IDs or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -446,7 +449,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
 /**
  * Get the name of a display in UTF-8 encoding.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param displayID the instance ID of the display to query.
  * \returns the name of a display or NULL on failure; call SDL_GetError() for
@@ -555,12 +559,14 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
  * - refresh rate -> highest to lowest
  * - pixel density -> lowest to highest
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param displayID the instance ID of the display to query.
- * \param count a pointer filled in with the number of display modes returned, may be NULL.
- * \returns a NULL terminated array of display mode pointers or NULL on failure; call SDL_GetError() for
- *          more information.
+ * \param count a pointer filled in with the number of display modes returned,
+ *              may be NULL.
+ * \returns a NULL terminated array of display mode pointers or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -767,7 +773,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(
 /**
  * Get the raw ICC profile data for the screen the window is currently on.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param window the window to query.
  * \param size the size of the ICC profile.
@@ -793,11 +800,13 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window
 /**
  * Get a list of valid windows.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param count a pointer filled in with the number of windows returned, may
  *              be NULL.
- * \returns a NULL terminated array of SDL_Window pointers or NULL on failure; call SDL_GetError() for more information.
+ * \returns a NULL terminated array of SDL_Window pointers or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1306,7 +1315,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
 /**
  * Get the title of a window.
  *
- * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
+ * This returns temporary memory which will be automatically freed later, and
+ * can be claimed with SDL_ClaimTemporaryMemory().
  *
  * \param window the window to query.
  * \returns the title of the window in UTF-8 format or "" if there is no
@@ -2175,7 +2185,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
  *
  * \param modal_window the window that should be set modal.
  * \param parent_window the parent window for the modal window.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -2584,8 +2595,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value)
  * SDL_GLContext is opaque to the application.
  *
  * \param window the window to associate with the context.
- * \returns the OpenGL context associated with `window` or NULL on failure; call
- *          SDL_GetError() for more information.
+ * \returns the OpenGL context associated with `window` or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_vulkan.h

@@ -119,7 +119,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
  * `vkGetInstanceProcAddr =
  * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
  *
- * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on failure; call SDL_GetError() for more information.
+ * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -149,7 +150,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
  * You should not free the returned array; it is owned by SDL.
  *
  * \param count a pointer filled in with the number of extensions returned.
- * \returns an array of extension name strings on success, NULL on failure; call SDL_GetError() for more information.
+ * \returns an array of extension name strings on success, NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -173,7 +175,8 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension
  *                  allocator that creates the surface. Can be NULL.
  * \param surface a pointer to a VkSurfaceKHR handle to output the newly
  *                created surface.
- * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *