From e4f097805bad7db4101f10cd9235a45af3218e2d Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot Date: Sun, 14 Apr 2024 00:22:23 +0000 Subject: [PATCH] Sync SDL3 wiki -> header --- include/SDL3/SDL_bits.h | 12 +++--- include/SDL3/SDL_endian.h | 29 +++++++------- include/SDL3/SDL_rect.h | 80 ++++++++++++++++++++------------------- include/SDL3/SDL_stdinc.h | 10 +++-- 4 files changed, 68 insertions(+), 63 deletions(-) diff --git a/include/SDL3/SDL_bits.h b/include/SDL3/SDL_bits.h index 1c76d1570..7b137b091 100644 --- a/include/SDL3/SDL_bits.h +++ b/include/SDL3/SDL_bits.h @@ -52,13 +52,13 @@ extern __inline int _SDL_bsr_watcom(Uint32); /** * Get the index of the most significant (set) bit in a 32-bit number. * - * Result is undefined when called with 0. This operation can also be - * stated as "count leading zeroes" and "log base 2". + * Result is undefined when called with 0. This operation can also be stated + * as "count leading zeroes" and "log base 2". * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine * \returns the index of the most significant bit, or -1 if the value is 0. @@ -125,8 +125,8 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h index 7021132bd..208fb593b 100644 --- a/include/SDL3/SDL_endian.h +++ b/include/SDL3/SDL_endian.h @@ -293,8 +293,8 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the value to byte-swap. * \returns x, with its bytes in the opposite endian order. @@ -322,17 +322,18 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) #ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** * Byte-swap an unsigned 16-bit number. * * This will always byte-swap the value, whether it's currently in the native - * byteorder of the system or not. You should use SDL_SwapLE16 or - * SDL_SwapBE16 instead, in most cases. + * byteorder of the system or not. You should use SDL_SwapLE16 or SDL_SwapBE16 + * instead, in most cases. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the value to byte-swap. * \returns `x`, with its bytes in the opposite endian order. @@ -347,13 +348,13 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * Byte-swap an unsigned 32-bit number. * * This will always byte-swap the value, whether it's currently in the native - * byteorder of the system or not. You should use SDL_SwapLE32 or - * SDL_SwapBE32 instead, in most cases. + * byteorder of the system or not. You should use SDL_SwapLE32 or SDL_SwapBE32 + * instead, in most cases. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the value to byte-swap. * \returns `x`, with its bytes in the opposite endian order. @@ -368,13 +369,13 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * Byte-swap an unsigned 64-bit number. * * This will always byte-swap the value, whether it's currently in the native - * byteorder of the system or not. You should use SDL_SwapLE64 or - * SDL_SwapBE64 instead, in most cases. + * byteorder of the system or not. You should use SDL_SwapLE64 or SDL_SwapBE64 + * instead, in most cases. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param x the value to byte-swap. * \returns `x`, with its bytes in the opposite endian order. diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index 616a02642..c925281b7 100644 --- a/include/SDL3/SDL_rect.h +++ b/include/SDL3/SDL_rect.h @@ -114,15 +114,15 @@ typedef struct SDL_FRect /** * Determine whether a point resides inside a rectangle. * - * A point is considered part of a rectangle if both `p` and `r` are - * not NULL, and `p`'s x and y coordinates are >= to the rectangle's - * top left corner, and < the rectangle's x+w and y+h. So a 1x1 rectangle - * considers point (0,0) as "inside" and (0,1) as not. + * A point is considered part of a rectangle if both `p` and `r` are not NULL, + * and `p`'s x and y coordinates are >= to the rectangle's top left corner, + * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0) + * as "inside" and (0,1) as not. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param p the point to test. * \param r the rectangle to test. @@ -141,13 +141,13 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) /** * Determine whether a rectangle has no area. * - * A rectangle is considered "empty" for this function if `r` is NULL, - * or if `r`'s width and/or height are <= 0. + * A rectangle is considered "empty" for this function if `r` is NULL, or if + * `r`'s width and/or height are <= 0. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param r the rectangle to test. * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. @@ -164,13 +164,13 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) /** * Determine whether two rectangles are equal. * - * Rectangles are considered equal if both are not NULL and each of their - * x, y, width and height match. + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height match. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param a the first rectangle to test. * \param b the second rectangle to test. @@ -290,15 +290,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect * /** * Determine whether a point resides inside a floating point rectangle. * - * A point is considered part of a rectangle if both `p` and `r` are - * not NULL, and `p`'s x and y coordinates are >= to the rectangle's - * top left corner, and < the rectangle's x+w and y+h. So a 1x1 rectangle - * considers point (0,0) as "inside" and (0,1) as not. + * A point is considered part of a rectangle if both `p` and `r` are not NULL, + * and `p`'s x and y coordinates are >= to the rectangle's top left corner, + * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0) + * as "inside" and (0,1) as not. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param p the point to test. * \param r the rectangle to test. @@ -317,13 +317,13 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR /** * Determine whether a floating point rectangle has no area. * - * A rectangle is considered "empty" for this function if `r` is NULL, - * or if `r`'s width and/or height are <= 0.0f. + * A rectangle is considered "empty" for this function if `r` is NULL, or if + * `r`'s width and/or height are <= 0.0f. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param r the rectangle to test. * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. @@ -338,17 +338,18 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) } /** - * Determine whether two floating point rectangles are equal, within some given epsilon. + * Determine whether two floating point rectangles are equal, within some + * given epsilon. * - * Rectangles are considered equal if both are not NULL and each of their - * x, y, width and height are within `epsilon` of each other. If you don't - * know what value to use for `epsilon`, you should call the - * SDL_RectsEqualFloat function instead. + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height are within `epsilon` of each other. If you don't know + * what value to use for `epsilon`, you should call the SDL_RectsEqualFloat + * function instead. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param a the first rectangle to test. * \param b the second rectangle to test. @@ -371,18 +372,19 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR } /** - * Determine whether two floating point rectangles are equal, within a default epsilon. + * Determine whether two floating point rectangles are equal, within a default + * epsilon. * - * Rectangles are considered equal if both are not NULL and each of their - * x, y, width and height are within SDL_FLT_EPSILON of each other. This is - * often a reasonable way to compare two floating point rectangles and - * deal with the slight precision variations in floating point calculations - * that tend to pop up. + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height are within SDL_FLT_EPSILON of each other. This is often + * a reasonable way to compare two floating point rectangles and deal with the + * slight precision variations in floating point calculations that tend to pop + * up. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is - * embedded in the calling program and the linker and dynamic loader will - * not be able to find this function inside SDL itself). + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). * * \param a the first rectangle to test. * \param b the second rectangle to test. diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index beb6ca75f..b3b12a616 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -2459,8 +2459,9 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif /** - * If a * b would overflow, return -1. Otherwise store a * b via ret - * and return 0. + * If a * b would overflow, return -1. + * + * Otherwise store a * b via ret and return 0. * * \since This function is available since SDL 3.0.0. */ @@ -2489,8 +2490,9 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, #endif /** - * If a + b would overflow, return -1. Otherwise store a + b via ret - * and return 0. + * If a + b would overflow, return -1. + * + * Otherwise store a + b via ret and return 0. * * \since This function is available since SDL 3.0.0. */