diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 167c64f5a..258bab2df 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 32eb4ca95..be4c39882 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 3b66fed48..d9fa496df 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 6b03a28a1..6dabb3a30 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 92ced243e..10b04b4e9 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 77466b809..457328faf 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 b6e65731a..e21d3df1f 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -34,6 +34,7 @@ #include #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 112f1df23..8f0ea63ce 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 ee687215a..82661bb30 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 078052872..ab1fb5958 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() 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.