From e4f097805bad7db4101f10cd9235a45af3218e2d Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
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 1c76d15707d9b..7b137b0915095 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 7021132bd0c58..208fb593b124a 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 616a02642836e..c925281b77e06 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 beb6ca75fbcc1..b3b12a616cf84 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.
*/