From 56cf8d8dc9cf37cf8d1e4b2538a132f995ea57e3 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Sun, 22 Dec 2024 07:09:56 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_assert.h | 12 ++-
include/SDL3/SDL_atomic.h | 37 +++----
include/SDL3/SDL_audio.h | 6 +-
include/SDL3/SDL_gpu.h | 30 +++---
include/SDL3/SDL_init.h | 16 +--
include/SDL3/SDL_intrin.h | 6 +-
include/SDL3/SDL_mutex.h | 1 +
include/SDL3/SDL_pixels.h | 28 +++--
include/SDL3/SDL_platform_defines.h | 1 +
include/SDL3/SDL_stdinc.h | 156 ++++++++++++++++------------
10 files changed, 165 insertions(+), 128 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 167c64f5a60bb..258bab2dfce57 100644
--- a/include/SDL3/SDL_assert.h
+++ b/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.
diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index 32eb4ca9594f1..be4c39882cead 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/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
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 3b66fed48fa1f..d9fa496dfcf32 100644
--- a/include/SDL3/SDL_audio.h
+++ b/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:
*
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 6b03a28a110bf..6dabb3a30f109 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/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.
diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h
index 92ced243ea739..10b04b4e9ef6e 100644
--- a/include/SDL3/SDL_init.h
+++ b/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).
diff --git a/include/SDL3/SDL_intrin.h b/include/SDL3/SDL_intrin.h
index 77466b809f769..457328faf143a 100644
--- a/include/SDL3/SDL_intrin.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index b6e65731ae4e0..e21d3df1fefb8 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h
index 112f1df23cbaa..8f0ea63cef0bc 100644
--- a/include/SDL3/SDL_pixels.h
+++ b/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.
diff --git a/include/SDL3/SDL_platform_defines.h b/include/SDL3/SDL_platform_defines.h
index ee687215ac4e1..82661bb3051eb 100644
--- a/include/SDL3/SDL_platform_defines.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 07805287206c4..ab1fb595875a3 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/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(
(Patch may be truncated, please check the link at the top of this post.)