From f61900465c6a5331f264ec59c37b45ebe728d7aa Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Sun, 14 Jul 2024 16:57:02 -0400
Subject: [PATCH] stdinc: Fixed up documentation details for standard types.

---
 include/SDL3/SDL_stdinc.h | 53 +++++++++++++++++++++++++++++++--------
 1 file changed, 42 insertions(+), 11 deletions(-)

diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index a17306b027..70224c28fc 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -136,10 +136,34 @@ void *alloca(size_t);
      (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \
      (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24))
 
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
 /**
- * Append the 64 bit integer suffix to an integer literal.
+ * Append the 64 bit integer suffix to a signed integer literal.
+ *
+ * This helps compilers that might believe a integer literal larger than
+ * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)`
+ * instead of `0xFFFFFFFF1` by itself.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_UINT64_C
  */
-#if defined(INT64_C)
+#define SDL_SINT64_C(c)  c ## LL  /* or whatever the current compiler uses. */
+
+/**
+ * Append the 64 bit integer suffix to an unsigned integer literal.
+ *
+ * This helps compilers that might believe a integer literal larger than
+ * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)`
+ * instead of `0xFFFFFFFF1` by itself.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_SINT64_C
+ */
+#define SDL_UINT64_C(c)  c ## ULL /* or whatever the current compiler uses. */
+
+#elif defined(INT64_C)
 #define SDL_SINT64_C(c)  INT64_C(c)
 #define SDL_UINT64_C(c)  UINT64_C(c)
 #elif defined(_MSC_VER)
@@ -191,72 +215,76 @@ typedef int SDL_bool;
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef int8_t Sint8;
 #define SDL_MAX_SINT8   ((Sint8)0x7F)           /* 127 */
 #define SDL_MIN_SINT8   ((Sint8)(~0x7F))        /* -128 */
-typedef int8_t Sint8;
 
 /**
  * An unsigned 8-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef uint8_t Uint8;
 #define SDL_MAX_UINT8   ((Uint8)0xFF)           /* 255 */
 #define SDL_MIN_UINT8   ((Uint8)0x00)           /* 0 */
-typedef uint8_t Uint8;
 
 /**
  * A signed 16-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef int16_t Sint16;
 #define SDL_MAX_SINT16  ((Sint16)0x7FFF)        /* 32767 */
 #define SDL_MIN_SINT16  ((Sint16)(~0x7FFF))     /* -32768 */
-typedef int16_t Sint16;
 
 /**
  * An unsigned 16-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef uint16_t Uint16;
 #define SDL_MAX_UINT16  ((Uint16)0xFFFF)        /* 65535 */
 #define SDL_MIN_UINT16  ((Uint16)0x0000)        /* 0 */
-typedef uint16_t Uint16;
 
 /**
  * A signed 32-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef int32_t Sint32;
 #define SDL_MAX_SINT32  ((Sint32)0x7FFFFFFF)    /* 2147483647 */
 #define SDL_MIN_SINT32  ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
-typedef int32_t Sint32;
 
 /**
  * An unsigned 32-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
  */
+typedef uint32_t Uint32;
 #define SDL_MAX_UINT32  ((Uint32)0xFFFFFFFFu)   /* 4294967295 */
 #define SDL_MIN_UINT32  ((Uint32)0x00000000)    /* 0 */
-typedef uint32_t Uint32;
 
 /**
  * A signed 64-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_SINT64_C
  */
+typedef int64_t Sint64;
 #define SDL_MAX_SINT64  SDL_SINT64_C(0x7FFFFFFFFFFFFFFF)   /* 9223372036854775807 */
 #define SDL_MIN_SINT64  ~SDL_SINT64_C(0x7FFFFFFFFFFFFFFF)  /* -9223372036854775808 */
-typedef int64_t Sint64;
 
 /**
  * An unsigned 64-bit integer type.
  *
  * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_UINT64_C
  */
+typedef uint64_t Uint64;
 #define SDL_MAX_UINT64  SDL_UINT64_C(0xFFFFFFFFFFFFFFFF)   /* 18446744073709551615 */
 #define SDL_MIN_UINT64  SDL_UINT64_C(0x0000000000000000)   /* 0 */
-typedef uint64_t Uint64;
 
 /**
  * SDL times are signed, 64-bit integers representing nanoseconds since the
@@ -267,10 +295,13 @@ typedef uint64_t Uint64;
  * SDL_TimeToWindows() and SDL_TimeFromWindows().
  *
  * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_MAX_SINT64
+ * \sa SDL_MIN_SINT64
  */
+typedef Sint64 SDL_Time;
 #define SDL_MAX_TIME SDL_MAX_SINT64
 #define SDL_MIN_TIME SDL_MIN_SINT64
-typedef Sint64 SDL_Time;
 
 /* @} *//* Basic data types */