Sync SDL3 wiki -> header

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
+ * Result is undefined when called with 0. This operation can also be stated
- * stated as "count leading zeroes" and "log base 2".
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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.

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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * byteorder of the system or not. You should use SDL_SwapLE16 or SDL_SwapBE16
- * SDL_SwapBE16 instead, in most cases.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * byteorder of the system or not. You should use SDL_SwapLE32 or SDL_SwapBE32
- * SDL_SwapBE32 instead, in most cases.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * byteorder of the system or not. You should use SDL_SwapLE64 or SDL_SwapBE64
- * SDL_SwapBE64 instead, in most cases.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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.

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
+ * A point is considered part of a rectangle if both `p` and `r` are not NULL,
- * not NULL, and `p`'s x and y coordinates are >= to the rectangle's
+ * and `p`'s x and y coordinates are >= to the rectangle's top left corner,
- * top left corner, and < the rectangle's x+w and y+h. So a 1x1 rectangle
+ * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0)
- * considers point (0,0) as "inside" and (0,1) as not.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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,
+ * A rectangle is considered "empty" for this function if `r` is NULL, or if
- * or if `r`'s width and/or height are <= 0.
+ * `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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * Rectangles are considered equal if both are not NULL and each of their x,
- * x, y, width and height match.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * A point is considered part of a rectangle if both `p` and `r` are not NULL,
- * not NULL, and `p`'s x and y coordinates are >= to the rectangle's
+ * and `p`'s x and y coordinates are >= to the rectangle's top left corner,
- * top left corner, and < the rectangle's x+w and y+h. So a 1x1 rectangle
+ * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0)
- * considers point (0,0) as "inside" and (0,1) as not.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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,
+ * A rectangle is considered "empty" for this function if `r` is NULL, or if
- * or if `r`'s width and/or height are <= 0.0f.
+ * `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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * Rectangles are considered equal if both are not NULL and each of their x,
- * x, y, width and height are within `epsilon` of each other. If you don't
+ * y, width and height are within `epsilon` of each other. If you don't know
- * know what value to use for `epsilon`, you should call the
+ * what value to use for `epsilon`, you should call the SDL_RectsEqualFloat
- * SDL_RectsEqualFloat function instead.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * 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
+ * Rectangles are considered equal if both are not NULL and each of their x,
- * x, y, width and height are within SDL_FLT_EPSILON of each other. This is
+ * y, width and height are within SDL_FLT_EPSILON of each other. This is often
- * often a reasonable way to compare two floating point rectangles and
+ * a reasonable way to compare two floating point rectangles and deal with the
- * deal with the slight precision variations in floating point calculations
+ * slight precision variations in floating point calculations that tend to pop
- * that tend to pop up.
+ * 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
+ * embedded in the calling program and the linker and dynamic loader will not
- * not be able to find this function inside SDL itself).
+ * be able to find this function inside SDL itself).
  *
  * \param a the first rectangle to test.
  * \param b the second rectangle to test.

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
+ * If a * b would overflow, return -1.
- * and return 0.
+ *
+ * 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
+ * If a + b would overflow, return -1.
- * and return 0.
+ *
+ * Otherwise store a + b via ret and return 0.
  *
  * \since This function is available since SDL 3.0.0.
  */