Sync SDL3 wiki -> header

[ci skip]

include/SDL3/SDL_assert.h

@@ -157,6 +157,7 @@ extern "C" {
 #endif
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * A macro that reports the current function being compiled.
  *
@@ -204,6 +205,7 @@ disable assertions.
 */
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * A macro for wrapping code in `do {} while (0);` without compiler warnings.
  *
@@ -211,7 +213,8 @@ disable assertions.
  * compiler complaints.
  *
  * the `do {} while (0);` trick is useful for wrapping code in a macro that
- * may or may not be a single statement, to avoid various C language accidents.
+ * may or may not be a single statement, to avoid various C language
+ * accidents.
  *
  * To use:
  *
@@ -311,6 +314,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
 
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * The macro used when an assertion triggers a breakpoint.
  *
@@ -342,9 +346,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * if (x) SDL_assert(y); else blah();
  * ```
  *
- * ... without the do/while, the "else" could attach to this macro's "if".
- * We try to handle just the minimum we need here in a macro...the loop,
- * the static vars, and break points. The heavy lifting is handled in
+ * ... without the do/while, the "else" could attach to this macro's "if". We
+ * try to handle just the minimum we need here in a macro...the loop, the
+ * static vars, and break points. The heavy lifting is handled in
  * SDL_ReportAssertion().
  *
  * \param condition the condition to assert.

include/SDL3/SDL_atomic.h

@@ -175,10 +175,10 @@ extern __inline void SDL_CompilerBarrier(void);
  * Insert a memory release barrier (function version).
  *
  * Please refer to SDL_MemoryBarrierRelease for details. This is a function
- * version, which might be useful if you need to use this functionality from
- * a scripting language, etc. Also, some of the macro versions call this
- * function behind the scenes, where more heavy lifting can happen inside
- * of SDL. Generally, though, an app written in C/C++/etc should use the macro
+ * version, which might be useful if you need to use this functionality from a
+ * scripting language, etc. Also, some of the macro versions call this
+ * function behind the scenes, where more heavy lifting can happen inside of
+ * SDL. Generally, though, an app written in C/C++/etc should use the macro
  * version, as it will be more efficient.
  *
  * \threadsafety Obviously this function is safe to use from any thread at any
@@ -195,10 +195,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
  * Insert a memory acquire barrier (function version).
  *
  * Please refer to SDL_MemoryBarrierRelease for details. This is a function
- * version, which might be useful if you need to use this functionality from
- * a scripting language, etc. Also, some of the macro versions call this
- * function behind the scenes, where more heavy lifting can happen inside
- * of SDL. Generally, though, an app written in C/C++/etc should use the macro
+ * version, which might be useful if you need to use this functionality from a
+ * scripting language, etc. Also, some of the macro versions call this
+ * function behind the scenes, where more heavy lifting can happen inside of
+ * SDL. Generally, though, an app written in C/C++/etc should use the macro
  * version, as it will be more efficient.
  *
  * \threadsafety Obviously this function is safe to use from any thread at any
@@ -213,6 +213,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
 
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * Insert a memory release barrier (macro version).
  *
@@ -234,11 +235,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
  * For more information on these semantics, take a look at the blog post:
  * http://preshing.com/20120913/acquire-and-release-semantics
  *
- * This is the macro version of this functionality; if possible, SDL will
- * use compiler intrinsics or inline assembly, but some platforms might
- * need to call the function version of this, SDL_MemoryBarrierReleaseFunction
- * to do the heavy lifting. Apps that can use the macro should favor it over
- * the function.
+ * This is the macro version of this functionality; if possible, SDL will use
+ * compiler intrinsics or inline assembly, but some platforms might need to
+ * call the function version of this, SDL_MemoryBarrierReleaseFunction to do
+ * the heavy lifting. Apps that can use the macro should favor it over the
+ * function.
  *
  * \threadsafety Obviously this macro is safe to use from any thread at any
  *               time, but if you find yourself needing this, you are probably
@@ -257,11 +258,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
  * Please see SDL_MemoryBarrierRelease for the details on what memory barriers
  * are and when to use them.
  *
- * This is the macro version of this functionality; if possible, SDL will
- * use compiler intrinsics or inline assembly, but some platforms might
- * need to call the function version of this,
- * SDL_MemoryBarrierAcquireFunction, to do the heavy lifting. Apps that can
- * use the macro should favor it over the function.
+ * This is the macro version of this functionality; if possible, SDL will use
+ * compiler intrinsics or inline assembly, but some platforms might need to
+ * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do
+ * the heavy lifting. Apps that can use the macro should favor it over the
+ * function.
  *
  * \threadsafety Obviously this macro is safe to use from any thread at any
  *               time, but if you find yourself needing this, you are probably

include/SDL3/SDL_audio.h

@@ -181,9 +181,9 @@ extern "C" {
 /**
  * Define an SDL_AudioFormat value.
  *
- * SDL does not support custom audio formats, so this macro is not of much
- * use externally, but it can be illustrative as to what the various bits of
- * an SDL_AudioFormat mean.
+ * SDL does not support custom audio formats, so this macro is not of much use
+ * externally, but it can be illustrative as to what the various bits of an
+ * SDL_AudioFormat mean.
  *
  * For example, SDL_AUDIO_S32LE looks like this:
  *

include/SDL3/SDL_gpu.h

@@ -2238,24 +2238,24 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader(
  * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing
  *   the program to run, any arguments, and a NULL pointer, e.g. const char
  *   *args[] = { "myprogram", "argument", NULL }. This is a required property.
- * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only)
- *   if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
- *   texture to a color with this red intensity. Defaults to zero.
- * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only)
- *   if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
- *   texture to a color with this green intensity.  Defaults to zero.
- * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only)
- *   if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
- *   texture to a color with this blue intensity. Defaults to zero.
- * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only)
- *   if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
- *   texture to a color with this alpha intensity. Defaults to zero.
+ * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if
+ *   the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
+ *   to a color with this red intensity. Defaults to zero.
+ * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if
+ *   the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
+ *   to a color with this green intensity. Defaults to zero.
+ * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if
+ *   the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
+ *   to a color with this blue intensity. Defaults to zero.
+ * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if
+ *   the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
+ *   to a color with this alpha intensity. Defaults to zero.
  * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only)
  *   if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
  *   the texture to a depth of this value. Defaults to zero.
- * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 only)
- *   if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
- *   the texture to a stencil of this value. Defaults to zero.
+ * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12
+ *   only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
+ *   clear the texture to a stencil of this value. Defaults to zero.
  *
  * \param device a GPU Context.
  * \param createinfo a struct describing the state of the texture to create.

include/SDL3/SDL_init.h

@@ -117,8 +117,8 @@ typedef enum SDL_AppResult
  * Function pointer typedef for SDL_AppInit.
  *
  * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
- * the scenes for apps using the optional main callbacks. Apps that want to use
- * this should just implement SDL_AppInit directly.
+ * the scenes for apps using the optional main callbacks. Apps that want to
+ * use this should just implement SDL_AppInit directly.
  *
  * \param appstate a place where the app can optionally store a pointer for
  *                 future use.
@@ -136,8 +136,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, cha
  * Function pointer typedef for SDL_AppIterate.
  *
  * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
- * the scenes for apps using the optional main callbacks. Apps that want to use
- * this should just implement SDL_AppIterate directly.
+ * the scenes for apps using the optional main callbacks. Apps that want to
+ * use this should just implement SDL_AppIterate directly.
  *
  * \param appstate an optional pointer, provided by the app in SDL_AppInit.
  * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
@@ -151,8 +151,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate);
  * Function pointer typedef for SDL_AppEvent.
  *
  * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
- * the scenes for apps using the optional main callbacks. Apps that want to use
- * this should just implement SDL_AppEvent directly.
+ * the scenes for apps using the optional main callbacks. Apps that want to
+ * use this should just implement SDL_AppEvent directly.
  *
  * \param appstate an optional pointer, provided by the app in SDL_AppInit.
  * \param event the new event for the app to examine.
@@ -167,8 +167,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *ev
  * Function pointer typedef for SDL_AppQuit.
  *
  * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
- * the scenes for apps using the optional main callbacks. Apps that want to use
- * this should just implement SDL_AppEvent directly.
+ * the scenes for apps using the optional main callbacks. Apps that want to
+ * use this should just implement SDL_AppEvent directly.
  *
  * \param appstate an optional pointer, provided by the app in SDL_AppInit.
  * \param result the result code that terminated the app (success or failure).

include/SDL3/SDL_intrin.h

@@ -324,9 +324,9 @@ _m_prefetch(void *__P)
  * #endif
  * ```
  *
- * The application is, on a whole, built without SSE2 instructions, so it
- * will run on Intel machines that don't support SSE2. But then at runtime,
- * it checks if the system supports the instructions, and then calls into a
+ * The application is, on a whole, built without SSE2 instructions, so it will
+ * run on Intel machines that don't support SSE2. But then at runtime, it
+ * checks if the system supports the instructions, and then calls into a
  * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't
  * used on platforms that don't have SSE2 at all.
  *

include/SDL3/SDL_mutex.h

@@ -34,6 +34,7 @@
 #include <SDL3/SDL_thread.h>
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * Enable thread safety attributes, only with clang.
  *

include/SDL3/SDL_pixels.h

@@ -244,8 +244,10 @@ typedef enum SDL_PackedLayout
  * ```
  *
  * \param type the type of the new format, probably a SDL_PixelType value.
- * \param order the order of the new format, probably a SDL_BitmapOrder, SDL_PackedOrder, or SDL_ArrayOrder value.
- * \param layout the layout of the new format, probably an SDL_PackedLayout value or zero.
+ * \param order the order of the new format, probably a SDL_BitmapOrder,
+ *              SDL_PackedOrder, or SDL_ArrayOrder value.
+ * \param layout the layout of the new format, probably an SDL_PackedLayout
+ *               value or zero.
  * \param bits the number of bits per pixel of the new format.
  * \param bytes the number of bytes per pixel of the new format.
  * \returns a format value in the style of SDL_PixelFormat.
@@ -305,8 +307,8 @@ typedef enum SDL_PackedLayout
 /**
  * A macro to retrieve the layout of an SDL_PixelFormat.
  *
- * This is usually a value from the SDL_PackedLayout enumeration, or zero if
- * a layout doesn't make sense for the format type.
+ * This is usually a value from the SDL_PackedLayout enumeration, or zero if a
+ * layout doesn't make sense for the format type.
  *
  * \param format an SDL_PixelFormat to check.
  * \returns the layout of `format`.
@@ -833,10 +835,14 @@ typedef enum SDL_ChromaLocation
  *
  * \param type the type of the new format, probably an SDL_ColorType value.
  * \param range the range of the new format, probably a SDL_ColorRange value.
- * \param primaries the primaries of the new format, probably an SDL_ColorPrimaries value.
- * \param transfer the transfer characteristics of the new format, probably an SDL_TransferCharacteristics value.
- * \param matrix the matrix coefficients of the new format, probably an SDL_MatrixCoefficients value.
- * \param chroma the chroma sample location of the new format, probably an SDL_ChromaLocation value.
+ * \param primaries the primaries of the new format, probably an
+ *                  SDL_ColorPrimaries value.
+ * \param transfer the transfer characteristics of the new format, probably an
+ *                 SDL_TransferCharacteristics value.
+ * \param matrix the matrix coefficients of the new format, probably an
+ *               SDL_MatrixCoefficients value.
+ * \param chroma the chroma sample location of the new format, probably an
+ *               SDL_ChromaLocation value.
  * \returns a format value in the style of SDL_Colorspace.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -920,7 +926,8 @@ typedef enum SDL_ChromaLocation
 #define SDL_COLORSPACEMATRIX(cspace)     (SDL_MatrixCoefficients)((cspace) & 0x1F)
 
 /**
- * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients.
+ * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix
+ * coefficients.
  *
  * Note that this macro double-evaluates its parameter, so do not use
  * expressions with side-effects here.
@@ -947,7 +954,8 @@ typedef enum SDL_ChromaLocation
 #define SDL_ISCOLORSPACE_MATRIX_BT709(cspace)        (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709)
 
 /**
- * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix coefficients.
+ * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix
+ * coefficients.
  *
  * \param cspace an SDL_Colorspace to check.
  * \returns true if BT709, false otherwise.

include/SDL3/SDL_platform_defines.h

@@ -358,6 +358,7 @@
 #endif /* HAVE_WINAPIFAMILY_H */
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * A preprocessor macro that defined to 1 if compiling for Windows Phone.
  *

include/SDL3/SDL_stdinc.h

@@ -826,7 +826,8 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * and is only written to by the function. The compiler or other analysis
  * tools can warn when this doesn't appear to be the case.
  *
- * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for bytes.
+ * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for
+ * bytes.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
@@ -917,13 +918,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  * ```
  *
- * This notes that the second parameter should be a printf-style format string, followed by `...`.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a printf-style format
+ * string, followed by `...`. The compiler or other analysis tools can warn
+ * when this doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -938,13 +940,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
  * ```
  *
- * This notes that the second parameter should be a printf-style format string, followed by a va_list.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a printf-style format
+ * string, followed by a va_list. The compiler or other analysis tools can
+ * warn when this doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -959,13 +962,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2);
  * ```
  *
- * This notes that the second parameter should be a scanf-style format string, followed by `...`.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a scanf-style format string,
+ * followed by `...`. The compiler or other analysis tools can warn when this
+ * doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -980,13 +984,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
  * ```
  *
- * This notes that the second parameter should be a scanf-style format string, followed by a va_list.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a scanf-style format string,
+ * followed by a va_list. The compiler or other analysis tools can warn when
+ * this doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -1001,13 +1006,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2);
  * ```
  *
- * This notes that the second parameter should be a wprintf-style format wide string, followed by `...`.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a wprintf-style format wide
+ * string, followed by `...`. The compiler or other analysis tools can warn
+ * when this doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -1022,13 +1028,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
  * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2);
  * ```
  *
- * This notes that the second parameter should be a wprintf-style format wide string, followed by a va_list.
- * The compiler or other analysis tools can warn when this doesn't appear to be the case.
+ * This notes that the second parameter should be a wprintf-style format wide
+ * string, followed by a va_list. The compiler or other analysis tools can
+ * warn when this doesn't appear to be the case.
  *
  * On compilers without this annotation mechanism, this is defined to nothing.
  *
- * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
- * will cover at least Visual Studio, GCC, and Clang.
+ * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
+ * between them will cover at least Visual Studio, GCC, and Clang.
  *
  * \since This macro is available since SDL 3.1.3.
  */
@@ -2582,9 +2589,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo
  * \param s1 the first buffer to compare. NULL is not permitted!
  * \param s2 the second buffer to compare. NULL is not permitted!
  * \param len the number of bytes to compare between the buffers.
- * \returns less than zero if s1 is "less than" s2, greater than zero if
- *          s1 is "greater than" s2, and zero if the buffers match
- *          exactly for `len` bytes.
+ * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is
+ *          "greater than" s2, and zero if the buffers match exactly for `len`
+ *          bytes.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2606,7 +2613,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_
  * bytes on Linux, 2 on Windows, etc).
  *
  * \param wstr The null-terminated wide string to read. Must not be NULL.
- * \returns the length (in wchar_t values, excluding the null terminator) of `wstr`.
+ * \returns the length (in wchar_t values, excluding the null terminator) of
+ *          `wstr`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2726,15 +2734,16 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
 /**
  * Search a wide string for the first instance of a specific substring.
  *
- * The search ends once it finds the requested substring, or a null
- * terminator byte to end the string.
+ * The search ends once it finds the requested substring, or a null terminator
+ * byte to end the string.
  *
  * Note that this looks for strings of _wide characters_, not _codepoints_, so
  * it's legal to search for malformed and incomplete UTF-16 sequences.
  *
  * \param haystack the wide string to search. Must not be NULL.
  * \param needle the wide string to search for. Must not be NULL.
- * \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
+ * \returns a pointer to the first instance of `needle` in the string, or NULL
+ *          if not found.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2743,20 +2752,23 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
 extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
 
 /**
- * Search a wide string, up to n wide chars, for the first instance of a specific substring.
+ * Search a wide string, up to n wide chars, for the first instance of a
+ * specific substring.
  *
- * The search ends once it finds the requested substring, or a null
- * terminator value to end the string, or `maxlen` wide character have been
- * examined. It is possible to use this function on a wide string without a
- * null terminator.
+ * The search ends once it finds the requested substring, or a null terminator
+ * value to end the string, or `maxlen` wide character have been examined. It
+ * is possible to use this function on a wide string without a null
+ * terminator.
  *
  * Note that this looks for strings of _wide characters_, not _codepoints_, so
  * it's legal to search for malformed and incomplete UTF-16 sequences.
  *
  * \param haystack the wide string to search. Must not be NULL.
  * \param needle the wide string to search for. Must not be NULL.
- * \param maxlen the maximum number of wide characters to search in `haystack`.
- * \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
+ * \param maxlen the maximum number of wide characters to search in
+ *               `haystack`.
+ * \returns a pointer to the first instance of `needle` in the string, or NULL
+ *          if not found.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -3064,19 +3076,19 @@ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str);
  * Allocate a copy of a string, up to n characters.
  *
  * This allocates enough space for a null-terminated copy of `str`, up to
- * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string
- * into this space.
+ * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into
+ * this space.
  *
- * If the string is longer than `maxlen` bytes, the returned string will
- * be `maxlen` bytes long, plus a null-terminator character that isn't
- * included in the count.
+ * If the string is longer than `maxlen` bytes, the returned string will be
+ * `maxlen` bytes long, plus a null-terminator character that isn't included
+ * in the count.
  *
  * The returned string is owned by the caller, and should be passed to
  * SDL_free when no longer needed.
  *
  * \param str the string to copy.
- * \param maxlen the maximum length of the copied string, not counting
- *        the null-terminator character.
+ * \param maxlen the maximum length of the copied string, not counting the
+ *               null-terminator character.
  * \returns a pointer to the newly-allocated string.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -3998,14 +4010,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
 extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
 
 /**
- * This works exactly like vsscanf() but doesn't require access to a C runtime.
+ * This works exactly like vsscanf() but doesn't require access to a C
+ * runtime.
  *
- * Functions identically to SDL_sscanf(), except it takes a `va_list`
- * instead of using `...` variable arguments.
+ * Functions identically to SDL_sscanf(), except it takes a `va_list` instead
+ * of using `...` variable arguments.
  *
  * \param text the string to scan. Must not be NULL.
  * \param fmt a printf-style format string. Must not be NULL.
- * \param ap a `va_list` of pointers to values to be filled in with scanned items.
+ * \param ap a `va_list` of pointers to values to be filled in with scanned
+ *           items.
  * \returns the number of items that matched the format string.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -4015,14 +4029,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_ST
 extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2);
 
 /**
- * This works exactly like snprintf() but doesn't require access to a C runtime.
+ * This works exactly like snprintf() but doesn't require access to a C
+ * runtime.
  *
  * Format a string of up to `maxlen`-1 bytes, converting each '%' item with
  * values provided through variable arguments.
  *
- * While some C runtimes differ on how to deal with too-large strings,
- * this function null-terminates the output, by treating the null-terminator
- * as part of the `maxlen` count. Note that if `maxlen` is zero, however, no
+ * While some C runtimes differ on how to deal with too-large strings, this
+ * function null-terminates the output, by treating the null-terminator as
+ * part of the `maxlen` count. Note that if `maxlen` is zero, however, no
  * bytes will be written at all.
  *
  * This function returns the number of _bytes_ (not _characters_) that should
@@ -4047,15 +4062,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_S
 extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
 
 /**
- * This works exactly like swprintf() but doesn't require access to a C runtime.
+ * This works exactly like swprintf() but doesn't require access to a C
+ * runtime.
  *
- * Format a wide string of up to `maxlen`-1 wchar_t values, converting each '%'
- * item with values provided through variable arguments.
+ * Format a wide string of up to `maxlen`-1 wchar_t values, converting each
+ * '%' item with values provided through variable arguments.
  *
- * While some C runtimes differ on how to deal with too-large strings,
- * this function null-terminates the output, by treating the null-terminator
- * as part of the `maxlen` count. Note that if `maxlen` is zero, however, no
- * wide characters will be written at all.
+ * While some C runtimes differ on how to deal with too-large strings, this
+ * function null-terminates the output, by treating the null-terminator as
+ * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide
+ * characters will be written at all.
  *
  * This function returns the number of _wide characters_ (not _codepoints_)
  * that should be written, excluding the null-terminator character. If this
@@ -4066,7 +4082,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, s
  * behavior.
  *
  * \param text the buffer to write the wide string into. Must not be NULL.
- * \param maxlen the maximum wchar_t values to write, including the null-terminator.
+ * \param maxlen the maximum wchar_t values to write, including the
+ *               null-terminator.
  * \param fmt a printf-style format string. Must not be NULL.
  * \param ... a list of values to be used with the format string.
  * \returns the number of wide characters that should be written, not counting
@@ -4079,7 +4096,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, s
 extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3);
 
 /**
- * This works exactly like vsnprintf() but doesn't require access to a C runtime.
+ * This works exactly like vsnprintf() but doesn't require access to a C
+ * runtime.
  *
  * Functions identically to SDL_snprintf(), except it takes a `va_list`
  * instead of using `...` variable arguments.
@@ -4098,13 +4116,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text
 extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
 
 /**
- * This works exactly like vswprintf() but doesn't require access to a C runtime.
+ * This works exactly like vswprintf() but doesn't require access to a C
+ * runtime.
  *
  * Functions identically to SDL_swprintf(), except it takes a `va_list`
  * instead of using `...` variable arguments.
  *
  * \param text the buffer to write the string into. Must not be NULL.
- * \param maxlen the maximum wide characters to write, including the null-terminator.
+ * \param maxlen the maximum wide characters to write, including the
+ *               null-terminator.
  * \param fmt a printf-style format wide string. Must not be NULL.
  * \param ap a `va_list` values to be used with the format string.
  * \returns the number of wide characters that should be written, not counting
@@ -4117,7 +4137,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text,
 extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3);
 
 /**
- * This works exactly like asprintf() but doesn't require access to a C runtime.
+ * This works exactly like asprintf() but doesn't require access to a C
+ * runtime.
  *
  * Functions identically to SDL_snprintf(), except it allocates a buffer large
  * enough to hold the output string on behalf of the caller.
@@ -4145,7 +4166,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *tex
 extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- * This works exactly like vasprintf() but doesn't require access to a C runtime.
+ * This works exactly like vasprintf() but doesn't require access to a C
+ * runtime.
  *
  * Functions identically to SDL_asprintf(), except it takes a `va_list`
  * instead of using `...` variable arguments.