include: Filled in all remaining missing documentation!

include/SDL3/SDL_assert.h

···
     #define SDL_TriggerBreakpoint()
 #endif
 
-#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro that reports the current function being compiled.
+ *
+ * If SDL can't figure how the compiler reports this, it will use "???".
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_FUNCTION __FUNCTION__
+
+#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
 #   define SDL_FUNCTION __func__
 #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__))
 #   define SDL_FUNCTION __FUNCTION__
 #else
 #   define SDL_FUNCTION "???"
 #endif
+
+/**
+ * A macro that reports the current file being compiled.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_FILE    __FILE__
+
+/**
+ * A macro that reports the current line number of the file being compiled.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_LINE    __LINE__
 
 /*
···
 disable assertions.
 */
 
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro for wrapping code in `do {} while (0);` without compiler warnings.
+ *
+ * Visual Studio with really aggressive warnings enabled needs this to avoid
+ * 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.
+ *
+ * To use:
+ *
+ * ```c
+ * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0));
+ * ```
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_NULL_WHILE_LOOP_CONDITION (0)
+
+#elif defined _MSC_VER  /* Avoid /W4 warnings. */
 /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking
     this condition isn't constant. And looks like an owl's face! */
-#ifdef _MSC_VER  /* stupid /W4 warnings. */
 #define SDL_NULL_WHILE_LOOP_CONDITION (0,0)
 #else
 #define SDL_NULL_WHILE_LOOP_CONDITION (0)
 #endif
 
+/**
+ * The macro used when an assertion is disabled.
+ *
+ * This isn't for direct use by apps, but this is the code that is inserted
+ * when an SDL_assert is disabled (perhaps in a release build).
+ *
+ * The code does nothing, but wraps `condition` in a sizeof operator, which
+ * generates no code and has no side effects, but avoid compiler warnings
+ * about unused variables.
+ *
+ * \param condition the condition to assert (but not actually run here).
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_disabled_assert(condition) \
     do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
 
···
 /**
  * Never call this directly.
  *
- * Use the SDL_assert* macros instead.
+ * Use the SDL_assert macros instead.
  *
  * \param data assert data structure.
  * \param func function name.
···
                                                             const char *func,
                                                             const char *file, int line) SDL_ANALYZER_NORETURN;
 
-/* Define the trigger breakpoint call used in asserts */
-#ifndef SDL_AssertBreakpoint
-#if defined(ANDROID) && defined(assert)
-/* Define this as empty in case assert() is defined as SDL_assert */
-#define SDL_AssertBreakpoint()
-#else
+
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * The macro used when an assertion triggers a breakpoint.
+ *
+ * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint
+ * instead.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint()
-#endif
+
+#elif !defined(SDL_AssertBreakpoint)
+#  if defined(ANDROID) && defined(assert)
+     /* Define this as empty in case assert() is defined as SDL_assert */
+#    define SDL_AssertBreakpoint()
+#  else
+#    define SDL_AssertBreakpoint() SDL_TriggerBreakpoint()
+#  endif
 #endif /* !SDL_AssertBreakpoint */
 
-/* the do {} while(0) avoids dangling else problems:
-    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
-   SDL_ReportAssertion(), in SDL_assert.c.
-*/
+/**
+ * The macro used when an assertion is enabled.
+ *
+ * This isn't for direct use by apps, but this is the code that is inserted
+ * when an SDL_assert is enabled.
+ *
+ * The `do {} while(0)` avoids dangling else problems:
+ *
+ * ```c
+ * 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
+ * SDL_ReportAssertion().
+ *
+ * \param condition the condition to assert.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_enabled_assert(condition) \
     do { \
         while ( !(condition) ) { \

include/SDL3/SDL_atomic.h

···
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier()
+
 #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__)
 void _ReadWriteBarrier(void);
 #pragma intrinsic(_ReadWriteBarrier)
···
 #endif
 
 /**
- * Insert a memory release barrier.
+ * 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, as it will be more efficient.
+ *
+ * \threadsafety Obviously this function is safe to use from any thread at any
+ *               time, but if you find yourself needing this, you are probably
+ *               dealing with some very sensitive code; be careful!
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_MemoryBarrierRelease
+ */
+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, as it will be more efficient.
+ *
+ * \threadsafety Obviously this function is safe to use from any thread at any
+ *               time, but if you find yourself needing this, you are probably
+ *               dealing with some very sensitive code; be careful!
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_MemoryBarrierAcquire
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
+
+
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * Insert a memory release barrier (macro version).
  *
  * Memory barriers are designed to prevent reads and writes from being
  * reordered by the compiler and being seen out of order on multi-core CPUs.
···
  *
  * 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.
  *
  * \threadsafety Obviously this macro is safe to use from any thread at any
  *               time, but if you find yourself needing this, you are probably
  *               dealing with some very sensitive code; be careful!
  *
- * \since This function is available since SDL 3.1.3.
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_MemoryBarrierAcquire
+ * \sa SDL_MemoryBarrierReleaseFunction
  */
-extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
+#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction()
 
 /**
- * Insert a memory acquire barrier.
+ * Insert a memory acquire barrier (macro version).
  *
- * Please refer to SDL_MemoryBarrierReleaseFunction for the details!
+ * Please see SDL_MemoryBarrierRelease for the details on what memory barriers
+ * are and when to use them.
  *
- * \threadsafety Obviously this function is safe to use from any thread at any
+ * 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
  *               dealing with some very sensitive code; be careful!
  *
- * \since This function is available since SDL 3.1.3.
+ * \since This macro is available since SDL 3.1.3.
  *
- * \sa SDL_MemoryBarrierReleaseFunction
+ * \sa SDL_MemoryBarrierRelease
+ * \sa SDL_MemoryBarrierAcquireFunction
  */
-extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
+#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction()
 
-/* !!! FIXME: this should have documentation! */
-#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
+#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
 #define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("lwsync" : : : "memory")
 #define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("lwsync" : : : "memory")
 #elif defined(__GNUC__) && defined(__aarch64__)
···
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay
+
 #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))
     #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n")  /* Some assemblers can't do REP NOP, so go with PAUSE. */
 #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__)

include/SDL3/SDL_audio.h

···
 extern "C" {
 #endif
 
-/* masks for different parts of SDL_AudioFormat. */
+/**
+ * Mask of bits in an SDL_AudioFormat that contains the format bit size.
+ *
+ * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_AUDIO_MASK_BITSIZE       (0xFFu)
+
+/**
+ * Mask of bits in an SDL_AudioFormat that contain the floating point flag.
+ *
+ * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_AUDIO_MASK_FLOAT         (1u<<8)
+
+/**
+ * Mask of bits in an SDL_AudioFormat that contain the bigendian flag.
+ *
+ * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN
+ * instead of this macro directly.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_AUDIO_MASK_BIG_ENDIAN    (1u<<12)
+
+/**
+ * Mask of bits in an SDL_AudioFormat that contain the signed data flag.
+ *
+ * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_AUDIO_MASK_SIGNED        (1u<<15)
 
-#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \
-    (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
+/**
+ * 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.
+ *
+ * For example, SDL_AUDIO_S32LE looks like this:
+ *
+ * ```c
+ * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32)
+ * ```
+ *
+ * \param signed 1 for signed data, 0 for unsigned data.
+ * \param bigendian 1 for bigendian data, 0 for littleendian data.
+ * \param flt 1 for floating point data, 0 for integer data.
+ * \param size number of bits per sample.
+ * \returns a format value in the style of SDL_AudioFormat.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \
+    (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
 
 /**
  * Audio format.
···
 /* Function prototypes */
 
 /**
- *  \name Driver discovery functions
- *
- *  These functions return the list of built in audio drivers, in the
- *  order that they are normally initialized by default.
- */
-/* @{ */
-
-/**
  * Use this function to get the number of built-in audio drivers.
  *
  * This function returns a hardcoded number. This never returns a negative
···
  * \sa SDL_GetNumAudioDrivers
  */
 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
-/* @} */
 
 /**
  * Get the name of the current audio driver.

include/SDL3/SDL_begin_code.h

···
 /* WIKI CATEGORY: BeginCode */
 
 /**
- * SDL_begin_code.h sets things up for C dynamic library function definitions,
- * static inlined functions, and structures aligned at 4-byte alignment.
- * If you don't like ugly C preprocessor code, don't look at this file. :)
+ * # CategoryBeginCode
+ *
+ * `SDL_begin_code.h` sets things up for C dynamic library function
+ * definitions, static inlined functions, and structures aligned at 4-byte
+ * alignment. If you don't like ugly C preprocessor code, don't look at this
+ * file. :)
  *
  * SDL's headers use this; applications generally should not include this
  * header directly.

include/SDL3/SDL_gpu.h

···
     SDL_PropertiesID props;           /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
 } SDL_GPUTextureCreateInfo;
 
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT       "SDL.gpu.createtexture.d3d12.clear.r"
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT       "SDL.gpu.createtexture.d3d12.clear.g"
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT       "SDL.gpu.createtexture.d3d12.clear.b"
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT       "SDL.gpu.createtexture.d3d12.clear.a"
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT   "SDL.gpu.createtexture.d3d12.clear.depth"
-#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil"
-
 /**
  * A structure specifying the parameters of a buffer.
  *
···
  * implementation will automatically fall back to the highest available sample
  * count.
  *
+ * There are optional properties that can be provided through
+ * SDL_GPUTextureCreateInfo's `props`. These are the supported properties:
+ *
+ * - `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_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.
+ *
  * \param device a GPU Context.
  * \param createinfo a struct describing the state of the texture to create.
  * \returns a texture object on success, or NULL on failure; call
···
 extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture(
     SDL_GPUDevice *device,
     const SDL_GPUTextureCreateInfo *createinfo);
+
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT       "SDL.gpu.createtexture.d3d12.clear.r"
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT       "SDL.gpu.createtexture.d3d12.clear.g"
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT       "SDL.gpu.createtexture.d3d12.clear.b"
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT       "SDL.gpu.createtexture.d3d12.clear.a"
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT   "SDL.gpu.createtexture.d3d12.clear.depth"
+#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil"
+
 
 /**
  * Creates a buffer object to be used in graphics or compute workflows.

include/SDL3/SDL_haptic.h

···
 #define SDL_HAPTIC_LEFTRIGHT    (1u<<11)
 
 /**
- * Reserved for future use
+ * Reserved for future use.
  *
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_HAPTIC_RESERVED1    (1u<<12)
+
+/**
+ * Reserved for future use.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_HAPTIC_RESERVED2    (1u<<13)
+
+/**
+ * Reserved for future use.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_HAPTIC_RESERVED3    (1u<<14)
 
 /**

include/SDL3/SDL_hints.h

···
  * \since This hint is available since SDL 3.1.3.
  */
 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON       "SDL_WINDOWS_INTRESOURCE_ICON"
+
+/**
+ * A variable to specify custom icon resource id from RC file on Windows
+ * platform.
+ *
+ * This hint should be set before SDL is initialized.
+ *
+ * \since This hint is available since SDL 3.1.3.
+ */
 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
 
 /**

include/SDL3/SDL_init.h

···
     SDL_APP_FAILURE     /**< Value that requests termination with error from the main callbacks. */
 } 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.
+ *
+ * \param appstate a place where the app can optionally store a pointer for
+ *                 future use.
+ * \param argc the standard ANSI C main's argc; number of elements in `argv`.
+ * \param argv the standard ANSI C main's argv; array of command line
+ *             arguments.
+ * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
+ *          terminate with success, SDL_APP_CONTINUE to continue.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]);
+
+/**
+ * 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.
+ *
+ * \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
+ *          terminate with success, SDL_APP_CONTINUE to continue.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 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.
+ *
+ * \param appstate an optional pointer, provided by the app in SDL_AppInit.
+ * \param event the new event for the app to examine.
+ * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
+ *          terminate with success, SDL_APP_CONTINUE to continue.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event);
+
+/**
+ * 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.
+ *
+ * \param appstate an optional pointer, provided by the app in SDL_AppInit.
+ * \param result the result code that terminated the app (success or failure).
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result);
+
 
 /**
  * Initialize the SDL library.

include/SDL3/SDL_intrin.h

···
 #endif
 #endif /* compiler version */
 
-#if defined(__clang__) && defined(__has_attribute)
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A macro to decide if the compiler supports `__attribute__((target))`.
+ *
+ * Even though this is defined in SDL's public headers, it is generally not
+ * used directly by apps. Apps should probably just use SDL_TARGETING
+ * directly, instead.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_TARGETING
+ */
+#define SDL_HAS_TARGET_ATTRIBS
+
+#elif defined(__clang__) && defined(__has_attribute)
 # if __has_attribute(target)
 # define SDL_HAS_TARGET_ATTRIBS
 # endif
···
 # define SDL_HAS_TARGET_ATTRIBS
 #endif
 
-#ifdef SDL_HAS_TARGET_ATTRIBS
+
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * A macro to tag a function as targeting a specific CPU architecture.
+ *
+ * This is a hint to the compiler that a function should be built with support
+ * for a CPU instruction set that might be different than the rest of the
+ * program.
+ *
+ * The particulars of this are explained in the GCC documentation:
+ *
+ * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute
+ *
+ * An example of using this feature is to turn on SSE2 support for a specific
+ * function, even if the rest of the source code is not compiled to use SSE2
+ * code:
+ *
+ * ```c
+ * #ifdef SDL_SSE2_INTRINSICS
+ * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) {
+ *    ...use SSE2 intrinsic functions, etc...
+ * }
+ * #endif
+ *
+ * // later...
+ * #ifdef SDL_SSE2_INTRINSICS
+ * if (SDL_HasSSE2()) {
+ *     DoSomethingWithSSE2(str);
+ * }
+ * #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
+ * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't
+ * used on platforms that don't have SSE2 at all.
+ *
+ * On compilers without target support, this is defined to nothing.
+ *
+ * This symbol is used by SDL internally, but apps and other libraries are
+ * welcome to use it for their own interfaces as well.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_TARGETING(x) __attribute__((target(x)))
+
+#elif defined(SDL_HAS_TARGET_ATTRIBS)
 # define SDL_TARGETING(x) __attribute__((target(x)))
 #else
 # define SDL_TARGETING(x)

include/SDL3/SDL_main.h

···
  * should look like this:
  *
  * ```c
- *  int main(int argc, char *argv[])
- *  {
- *  }
+ * int main(int argc, char *argv[])
+ * {
+ * }
  * ```
  *
  * SDL will take care of platform specific details on how it gets called.
···
 #include <SDL3/SDL_error.h>
 #include <SDL3/SDL_events.h>
 
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * Inform SDL that the app is providing an entry point instead of SDL.
+ *
+ * SDL does not define this macro, but will check if it is defined when
+ * including `SDL_main.h`. If defined, SDL will expect the app to provide the
+ * proper entry point for the platform, and all the other magic details
+ * needed, like manually calling SDL_SetMainReady.
+ *
+ * Please see [README/main-functions](README/main-functions), (or
+ * docs/README-main-functions.md in the source tree) for a more detailed
+ * explanation.
+ *
+ * \since This macro is used by the headers since SDL 3.1.3.
+ */
+#define SDL_MAIN_HANDLED 1
+
+/**
+ * Inform SDL to use the main callbacks instead of main.
+ *
+ * SDL does not define this macro, but will check if it is defined when
+ * including `SDL_main.h`. If defined, SDL will expect the app to provide
+ * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and
+ * SDL_AppQuit. The app should not provide a `main` function in this case, and
+ * doing so will likely cause the build to fail.
+ *
+ * Please see [README/main-functions](README/main-functions), (or
+ * docs/README-main-functions.md in the source tree) for a more detailed
+ * explanation.
+ *
+ * \since This macro is used by the headers since SDL 3.1.3.
+ *
+ * \sa SDL_AppInit
+ * \sa SDL_AppEvent
+ * \sa SDL_AppIterate
+ * \sa SDL_AppQuit
+ */
+#define SDL_MAIN_USE_CALLBACKS 1
+
+/**
+ * Defined if the target platform offers a special mainline through SDL.
+ *
+ * This won't be defined otherwise. If defined, SDL's headers will redefine
+ * `main` to `SDL_main`.
+ *
+ * This macro is defined by `SDL_main.h`, which is not automatically included
+ * by `SDL.h`.
+ *
+ * Even if available, an app can define SDL_MAIN_HANDLED and provide their
+ * own, if they know what they're doing.
+ *
+ * This macro is used internally by SDL, and apps probably shouldn't rely on it.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_MAIN_AVAILABLE
+
+/**
+ * Defined if the target platform _requires_ a special mainline through SDL.
+ *
+ * This won't be defined otherwise. If defined, SDL's headers will redefine
+ * `main` to `SDL_main`.
+ *
+ * This macro is defined by `SDL_main.h`, which is not automatically included
+ * by `SDL.h`.
+ *
+ * Even if required, an app can define SDL_MAIN_HANDLED and provide their
+ * own, if they know what they're doing.
+ *
+ * This macro is used internally by SDL, and apps probably shouldn't rely on it.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_MAIN_NEEDED
+
+#endif
+
 #ifndef SDL_MAIN_HANDLED
     #if defined(SDL_PLATFORM_PRIVATE_MAIN)
         /* Private platforms may have their own ideas about entry points. */
···
     #endif
 #endif /* SDL_MAIN_HANDLED */
 
-#ifdef SDL_MAIN_EXPORTED
-/* We need to export SDL_main so it can be launched from external code,
-   like SDLActivity.java on Android */
-#define SDLMAIN_DECLSPEC    SDL_DECLSPEC
-#else
-/* usually this is empty */
-#define SDLMAIN_DECLSPEC
-#endif /* SDL_MAIN_EXPORTED */
 
 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
 
 /**
- * Inform SDL to use the main callbacks instead of main.
+ * A macro to tag a main entry point function as exported.
  *
- * SDL does not define this macro, but will check if it is defined when
- * including `SDL_main.h`. If defined, SDL will expect the app to provide
- * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and
- * SDL_AppQuit. The app should not provide a `main` function in this case, and
- * doing so will likely cause the build to fail.
+ * Most platforms don't need this, and the macro will be defined to nothing.
+ * Some, like Android, keep the entry points in a shared library and need to
+ * explicitly export the symbols.
  *
- * Please see [README/main-functions](README/main-functions), (or
- * docs/README-main-functions.md in the source tree) for a more detailed
- * explanation.
+ * External code rarely needs this, and if it needs something, it's almost
+ * always SDL_DECLSPEC instead.
  *
- * \since This macro is used by the headers since SDL 3.1.3.
+ * \since This macro is available since SDL 3.1.3.
  *
- * \sa SDL_AppInit
- * \sa SDL_AppEvent
- * \sa SDL_AppIterate
- * \sa SDL_AppQuit
+ * \sa SDL_DECLSPEC
  */
-#define SDL_MAIN_USE_CALLBACKS 1
-#endif
+#define SDLMAIN_DECLSPEC
+
+#elif defined(SDL_MAIN_EXPORTED)
+/* We need to export SDL_main so it can be launched from external code,
+   like SDLActivity.java on Android */
+#define SDLMAIN_DECLSPEC    SDL_DECLSPEC
+#else
+/* usually this is empty */
+#define SDLMAIN_DECLSPEC
+#endif /* SDL_MAIN_EXPORTED */
 
 #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS)
 #define main SDL_main

include/SDL3/SDL_mutex.h

···
 #include <SDL3/SDL_error.h>
 #include <SDL3/SDL_thread.h>
 
-/******************************************************************************/
-/* Enable thread safety attributes only with clang.
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * Enable thread safety attributes, only with clang.
+ *
  * The attributes can be safely erased when compiling with other compilers.
  *
  * To enable analysis, set these environment variables before running cmake:
- *      export CC=clang
- *      export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety"
+ *
+ * ```bash
+ * export CC=clang
+ * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety"
+ * ```
  */
-#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \
-    defined(__clang__) && (!defined(SWIG))
+#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
+
+#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG))
 #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
 #else
 #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x)   /* no-op */
 #endif
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_CAPABILITY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_SCOPED_CAPABILITY \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_GUARDED_BY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_PT_GUARDED_BY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ACQUIRED_BEFORE(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ACQUIRED_AFTER(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_REQUIRES(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_REQUIRES_SHARED(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ACQUIRE(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ACQUIRE_SHARED(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_RELEASE(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_RELEASE_SHARED(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_RELEASE_GENERIC(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_TRY_ACQUIRE(x, y) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_TRY_ACQUIRE_SHARED(x, y) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_EXCLUDES(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ASSERT_CAPABILITY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ASSERT_SHARED_CAPABILITY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_RETURN_CAPABILITY(x) \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
 
+/**
+ * Wrapper around Clang thread safety analysis annotations.
+ *
+ * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_NO_THREAD_SAFETY_ANALYSIS \
   SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 

include/SDL3/SDL_pixels.h

···
     SDL_PACKEDLAYOUT_1010102
 } SDL_PackedLayout;
 
+/**
+ * A macro for defining custom FourCC pixel formats.
+ *
+ * For example, defining SDL_PIXELFORMAT_YV12 looks like this:
+ *
+ * ```c
+ * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2')
+ * ```
+ *
+ * \param A the first character of the FourCC code.
+ * \param B the second character of the FourCC code.
+ * \param C the third character of the FourCC code.
+ * \param D the fourth character of the FourCC code.
+ * \returns a format value in the style of SDL_PixelFormat.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
 
+/**
+ * A macro for defining custom non-FourCC pixel formats.
+ *
+ * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this:
+ *
+ * ```c
+ * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4)
+ * ```
+ *
+ * \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 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.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
     ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
      ((bits) << 8) | ((bytes) << 0))
 
-#define SDL_PIXELFLAG(X)    (((X) >> 28) & 0x0F)
-#define SDL_PIXELTYPE(X)    (((X) >> 24) & 0x0F)
-#define SDL_PIXELORDER(X)   (((X) >> 20) & 0x0F)
-#define SDL_PIXELLAYOUT(X)  (((X) >> 16) & 0x0F)
-#define SDL_BITSPERPIXEL(X) \
-    (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF))
-#define SDL_BYTESPERPIXEL(X) \
-    (SDL_ISPIXELFORMAT_FOURCC(X) ? \
-        ((((X) == SDL_PIXELFORMAT_YUY2) || \
-          ((X) == SDL_PIXELFORMAT_UYVY) || \
-          ((X) == SDL_PIXELFORMAT_YVYU) || \
-          ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF))
+/**
+ * A macro to retrieve the flags of an SDL_PixelFormat.
+ *
+ * This macro is generally not needed directly by an app, which should use
+ * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the flags of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PIXELFLAG(format)    (((format) >> 28) & 0x0F)
 
+/**
+ * A macro to retrieve the type of an SDL_PixelFormat.
+ *
+ * This is usually a value from the SDL_PixelType enumeration.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the type of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PIXELTYPE(format)    (((format) >> 24) & 0x0F)
+
+/**
+ * A macro to retrieve the order of an SDL_PixelFormat.
+ *
+ * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or
+ * SDL_ArrayOrder enumerations, depending on the format type.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the order of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PIXELORDER(format)   (((format) >> 20) & 0x0F)
+
+/**
+ * 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.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the layout of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PIXELLAYOUT(format)  (((format) >> 16) & 0x0F)
+
+/**
+ * A macro to determine an SDL_PixelFormat's bits per pixel.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * FourCC formats will report zero here, as it rarely makes sense to measure
+ * them per-pixel.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the bits-per-pixel of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BYTESPERPIXEL
+ */
+#define SDL_BITSPERPIXEL(format) \
+    (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF))
+
+/**
+ * A macro to determine an SDL_PixelFormat's bytes per pixel.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * FourCC formats do their best here, but many of them don't have a meaningful
+ * measurement of bytes per pixel.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns the bytes-per-pixel of `format`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_BITSPERPIXEL
+ */
+#define SDL_BYTESPERPIXEL(format) \
+    (SDL_ISPIXELFORMAT_FOURCC(format) ? \
+        ((((format) == SDL_PIXELFORMAT_YUY2) || \
+          ((format) == SDL_PIXELFORMAT_UYVY) || \
+          ((format) == SDL_PIXELFORMAT_YVYU) || \
+          ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF))
+
+
+/**
+ * A macro to determine if an SDL_PixelFormat is an indexed format.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format is indexed, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_INDEXED(format)   \
     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
···
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
 
+/**
+ * A macro to determine if an SDL_PixelFormat is a packed format.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format is packed, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_PACKED(format) \
     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))
 
+/**
+ * A macro to determine if an SDL_PixelFormat is an array format.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format is an array, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_ARRAY(format) \
     (!SDL_ISPIXELFORMAT_FOURCC(format) && \
      ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
···
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
       (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
 
+/**
+ * A macro to determine if an SDL_PixelFormat is a 10-bit format.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format is 10-bit, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_10BIT(format)    \
       (!SDL_ISPIXELFORMAT_FOURCC(format) && \
        ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \
         (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010)))
 
+/**
+ * A macro to determine if an SDL_PixelFormat is a floating point format.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format is 10-bit, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_FLOAT(format)    \
       (!SDL_ISPIXELFORMAT_FOURCC(format) && \
        ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
         (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
 
+/**
+ * A macro to determine if an SDL_PixelFormat has an alpha channel.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format has alpha, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ISPIXELFORMAT_ALPHA(format)   \
     ((SDL_ISPIXELFORMAT_PACKED(format) && \
       ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
···
        (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \
        (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA))))
 
-/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
-#define SDL_ISPIXELFORMAT_FOURCC(format)    \
+
+/**
+ * A macro to determine if an SDL_PixelFormat is a "FourCC" format.
+ *
+ * This covers custom and other unusual formats.
+ *
+ * Note that this macro double-evaluates its parameter, so do not use
+ * expressions with side-effects here.
+ *
+ * \param format an SDL_PixelFormat to check.
+ * \returns true if the format has alpha, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_ISPIXELFORMAT_FOURCC(format)  /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \
     ((format) && (SDL_PIXELFLAG(format) != 1))
 
 /* Note: If you modify this enum, update SDL_GetPixelFormatName() */
···
 
 
 /* Colorspace definition */
+
+/**
+ * A macro for defining custom SDL_Colorspace formats.
+ *
+ * For example, defining SDL_COLORSPACE_SRGB looks like this:
+ *
+ * ```c
+ * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB,
+ *                       SDL_COLOR_RANGE_FULL,
+ *                       SDL_COLOR_PRIMARIES_BT709,
+ *                       SDL_TRANSFER_CHARACTERISTICS_SRGB,
+ *                       SDL_MATRIX_COEFFICIENTS_IDENTITY,
+ *                       SDL_CHROMA_LOCATION_NONE)
+ * ```
+ *
+ * \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.
+ * \returns a format value in the style of SDL_Colorspace.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \
     (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \
     ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0))
 
-#define SDL_COLORSPACETYPE(X)       (SDL_ColorType)(((X) >> 28) & 0x0F)
-#define SDL_COLORSPACERANGE(X)      (SDL_ColorRange)(((X) >> 24) & 0x0F)
-#define SDL_COLORSPACECHROMA(X)     (SDL_ChromaLocation)(((X) >> 20) & 0x0F)
-#define SDL_COLORSPACEPRIMARIES(X)  (SDL_ColorPrimaries)(((X) >> 10) & 0x1F)
-#define SDL_COLORSPACETRANSFER(X)   (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F)
-#define SDL_COLORSPACEMATRIX(X)     (SDL_MatrixCoefficients)((X) & 0x1F)
+/**
+ * A macro to retrieve the type of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_ColorType for `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACETYPE(cspace)       (SDL_ColorType)(((cspace) >> 28) & 0x0F)
+
+/**
+ * A macro to retrieve the range of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_ColorRange of `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACERANGE(cspace)      (SDL_ColorRange)(((cspace) >> 24) & 0x0F)
+
+/**
+ * A macro to retrieve the chroma sample location of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_ChromaLocation of `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACECHROMA(cspace)     (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F)
+
+/**
+ * A macro to retrieve the primaries of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_ColorPrimaries of `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACEPRIMARIES(cspace)  (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F)
+
+/**
+ * A macro to retrieve the transfer characteristics of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_TransferCharacteristics of `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACETRANSFER(cspace)   (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F)
+
+/**
+ * A macro to retrieve the matrix coefficients of an SDL_Colorspace.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns the SDL_MatrixCoefficients of `cspace`.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_COLORSPACEMATRIX(cspace)     (SDL_MatrixCoefficients)((cspace) & 0x1F)
+
+/**
+ * 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.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns true if BT601 or BT470BG, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace)        (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG)
+
+/**
+ * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns true if BT709, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#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.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns true if BT709, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace)   (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
 
-#define SDL_ISCOLORSPACE_MATRIX_BT601(X)        (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG)
-#define SDL_ISCOLORSPACE_MATRIX_BT709(X)        (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709)
-#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X)   (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
-#define SDL_ISCOLORSPACE_LIMITED_RANGE(X)       (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL)
-#define SDL_ISCOLORSPACE_FULL_RANGE(X)          (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL)
+/**
+ * A macro to determine if an SDL_Colorspace has a limited range.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns true if limited range, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace)       (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL)
+
+/**
+ * A macro to determine if an SDL_Colorspace has a full range.
+ *
+ * \param cspace an SDL_Colorspace to check.
+ * \returns true if full range, false otherwise.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_ISCOLORSPACE_FULL_RANGE(cspace)          (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL)
 
 /**
  * Colorspace definitions.

include/SDL3/SDL_platform_defines.h

···
     #define WINAPI_FAMILY_WINRT 0
 #endif /* HAVE_WINAPIFAMILY_H */
 
-#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A preprocessor macro that defined to 1 if compiling for Windows Phone.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
+
+#elif HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H
     #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
 #else
     #define SDL_WINAPI_FAMILY_PHONE 0

include/SDL3/SDL_process.h

···
 extern "C" {
 #endif
 
+/**
+ * An opaque handle representing a system process.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ *
+ * \sa SDL_CreateProcess
+ */
 typedef struct SDL_Process SDL_Process;
 
 /**

include/SDL3/SDL_stdinc.h

···
 #endif
 
 /* Annotations to help code analysis tools */
-#ifdef SDL_DISABLE_ANALYZE_MACROS
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * Macro that annotates function params with input buffer size.
+ *
+ * If we were to annotate `memcpy`:
+ *
+ * ```c
+ * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
+ * ```
+ *
+ * This notes that `src` should be `len` bytes in size and is only read by the
+ * function. 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_IN_BYTECAP(x) _In_bytecount_(x)
+
+/**
+ * Macro that annotates function params with input/output string buffer size.
+ *
+ * If we were to annotate `strlcat`:
+ *
+ * ```c
+ * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
+ * ```
+ *
+ * This notes that `dst` is a null-terminated C string, should be `maxlen`
+ * bytes in size, and is both read from and written to by the function. 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)
+
+/**
+ * Macro that annotates function params with output string buffer size.
+ *
+ * If we were to annotate `snprintf`:
+ *
+ * ```c
+ * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...);
+ * ```
+ *
+ * This notes that `text` is a null-terminated C string, should be `maxlen`
+ * bytes in size, 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.
+ *
+ * On compilers without this annotation mechanism, this is defined to nothing.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x)
+
+/**
+ * Macro that annotates function params with output buffer size.
+ *
+ * If we were to annotate `wcsncpy`:
+ *
+ * ```c
+ * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize);
+ * ```
+ *
+ * This notes that `dst` should have a capacity of `bufsize` wchar_t in size,
+ * 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.
+ *
+ * On compilers without this annotation mechanism, this is defined to nothing.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_OUT_CAP(x) _Out_cap_(x)
+
+/**
+ * Macro that annotates function params with output buffer size.
+ *
+ * If we were to annotate `memcpy`:
+ *
+ * ```c
+ * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize);
+ * ```
+ *
+ * This notes that `dst` should have a capacity of `bufsize` bytes in size,
+ * 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.
+ *
+ * On compilers without this annotation mechanism, this is defined to nothing.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x)
+
+/**
+ * Macro that annotates function params with output buffer string size.
+ *
+ * If we were to annotate `strcpy`:
+ *
+ * ```c
+ * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize);
+ * ```
+ *
+ * This notes that `dst` should have a capacity of `bufsize` bytes in size,
+ * and a zero-terminated string is written to it by the function. 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x)
+
+/**
+ * Macro that annotates function params as printf-style format strings.
+ *
+ * If we were to annotate `fprintf`:
+ *
+ * ```c
+ * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...);
+ * ```
+ *
+ * This notes that `fmt` should be a printf-style format string. 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_
+
+/**
+ * Macro that annotates function params as scanf-style format strings.
+ *
+ * If we were to annotate `fscanf`:
+ *
+ * ```c
+ * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...);
+ * ```
+ *
+ * This notes that `fmt` should be a scanf-style format string. 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_
+
+/**
+ * Macro that annotates a vararg function that operates like printf.
+ *
+ * If we were to annotate `fprintf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
+
+/**
+ * Macro that annotates a va_list function that operates like printf.
+ *
+ * If we were to annotate `vfprintf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
+
+/**
+ * Macro that annotates a vararg function that operates like scanf.
+ *
+ * If we were to annotate `fscanf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
+
+/**
+ * Macro that annotates a va_list function that operates like scanf.
+ *
+ * If we were to annotate `vfscanf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
+
+/**
+ * Macro that annotates a vararg function that operates like wprintf.
+ *
+ * If we were to annotate `fwprintf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
+
+/**
+ * Macro that annotates a va_list function that operates like wprintf.
+ *
+ * If we were to annotate `vfwprintf`:
+ *
+ * ```c
+ * 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.
+ *
+ * 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.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */
+
+#elif defined(SDL_DISABLE_ANALYZE_MACROS)
 #define SDL_IN_BYTECAP(x)
 #define SDL_INOUT_Z_CAP(x)
 #define SDL_OUT_Z_CAP(x)
···
 #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x)))
 
 
+/**
+ * Compare two buffers of memory.
+ *
+ * \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.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len);
 
+/**
+ * This works exactly like wcslen() but doesn't require access to a C runtime.
+ *
+ * Counts the number of wchar_t values in `wstr`, excluding the null
+ * terminator.
+ *
+ * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string,
+ * this counts wchar_t values in a string, even if the string's encoding is of
+ * variable width, like UTF-16.
+ *
+ * Also be aware that wchar_t is different sizes on different platforms (4
+ * 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`.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_wcsnlen
+ * \sa SDL_utf8strlen
+ * \sa SDL_utf8strnlen
+ */
 extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr);
+
+/**
+ * This works exactly like wcsnlen() but doesn't require access to a C
+ * runtime.
+ *
+ * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the
+ * null terminator.
+ *
+ * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string,
+ * this counts wchar_t values in a string, even if the string's encoding is of
+ * variable width, like UTF-16.
+ *
+ * Also be aware that wchar_t is different sizes on different platforms (4
+ * bytes on Linux, 2 on Windows, etc).
+ *
+ * Also, `maxlen` is a count of wide characters, not bytes!
+ *
+ * \param wstr The null-terminated wide string to read. Must not be NULL.
+ * \param maxlen The maximum amount of wide characters to count.
+ * \returns the length (in wide characters, excluding the null terminator) of
+ *          `wstr` but never more than `maxlen`.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ *
+ * \sa SDL_wcslen
+ * \sa SDL_utf8strlen
+ * \sa SDL_utf8strnlen
+ */
 extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen);
 
 /**
···
  * \param src The null-terminated wide string to copy. Must not be NULL, and
  *            must not overlap with `dst`.
  * \param maxlen The length (in wide characters) of the destination buffer.
- * \returns The length (in wide characters, excluding the null terminator) of
+ * \returns the length (in wide characters, excluding the null terminator) of
  *          `src`.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  * \param src The second null-terminated wide string. Must not be NULL, and
  *            must not overlap with `dst`.
  * \param maxlen The length (in wide characters) of the destination buffer.
- * \returns The length (in wide characters, excluding the null terminator) of
+ * \returns the length (in wide characters, excluding the null terminator) of
  *          the string in `dst` plus the length of `src`.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  */
 extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
 
+/**
+ * Allocate a copy of a wide string.
+ *
+ * This allocates enough space for a null-terminated copy of `wstr`, using
+ * SDL_malloc, and then makes a copy of the string into this space.
+ *
+ * The returned string is owned by the caller, and should be passed to
+ * SDL_free when no longer needed.
+ *
+ * \param wstr the string to copy.
+ * \returns a pointer to the newly-allocated wide string.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen);
 
 /**
···
  *             to 36 inclusive. If 0, the base will be inferred from the
  *             number's prefix (0x for hexadecimal, 0 for octal, decimal
  *             otherwise).
- * \returns The parsed `long`, or 0 if no number could be parsed.
+ * \returns the parsed `long`, or 0 if no number could be parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  * If you need the length of a UTF-8 string, consider using SDL_utf8strlen().
  *
  * \param str The null-terminated string to read. Must not be NULL.
- * \returns The length (in bytes, excluding the null terminator) of `src`.
+ * \returns the length (in bytes, excluding the null terminator) of `src`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  *
  * \param str The null-terminated string to read. Must not be NULL.
  * \param maxlen The maximum amount of bytes to count.
- * \returns The length (in bytes, excluding the null terminator) of `src` but
+ * \returns the length (in bytes, excluding the null terminator) of `src` but
  *          never more than `maxlen`.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  * \param src The null-terminated string to copy. Must not be NULL, and must
  *            not overlap with `dst`.
  * \param maxlen The length (in characters) of the destination buffer.
- * \returns The length (in characters, excluding the null terminator) of
+ * \returns the length (in characters, excluding the null terminator) of
  *          `src`.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  *            must not overlap with `dst`.
  * \param dst_bytes The length (in bytes) of the destination buffer. Must not
  *                  be 0.
- * \returns The number of bytes written, excluding the null terminator.
+ * \returns the number of bytes written, excluding the null terminator.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  * \param src The second null-terminated string. Must not be NULL, and must
  *            not overlap with `dst`.
  * \param maxlen The length (in characters) of the destination buffer.
- * \returns The length (in characters, excluding the null terminator) of the
+ * \returns the length (in characters, excluding the null terminator) of the
  *          string in `dst` plus the length of `src`.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  */
 extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
 
+/**
+ * Allocate a copy of a string.
+ *
+ * This allocates enough space for a null-terminated copy of `str`, using
+ * SDL_malloc, and then makes a copy of the string into this space.
+ *
+ * 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.
+ * \returns a pointer to the newly-allocated string.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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.
+ * \returns a pointer to the newly-allocated string.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen);
+
+/**
+ * Reverse a string's contents.
+ *
+ * This reverses a null-terminated string in-place. Only the content of the
+ * string is reversed; the null-terminator character remains at the end of the
+ * reversed string.
+ *
+ * **WARNING**: This function reverses the _bytes_ of the string, not the
+ * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this
+ * will ruin the string data. You should only use this function on strings
+ * that are completely comprised of low ASCII characters.
+ *
+ * \param str the string to reverse.
+ * \returns `str`.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str);
 
 /**
···
  * `(int)SDL_strtol(str, NULL, 10)`.
  *
  * \param str The null-terminated string to read. Must not be NULL.
- * \returns The parsed `int`.
+ * \returns the parsed `int`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  * NULL)`.
  *
  * \param str The null-terminated string to read. Must not be NULL.
- * \returns The parsed `double`.
+ * \returns the parsed `double`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  *             to 36 inclusive. If 0, the base will be inferred from the
  *             number's prefix (0x for hexadecimal, 0 for octal, decimal
  *             otherwise).
- * \returns The parsed `long`, or 0 if no number could be parsed.
+ * \returns the parsed `long`, or 0 if no number could be parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  *             to 36 inclusive. If 0, the base will be inferred from the
  *             number's prefix (0x for hexadecimal, 0 for octal, decimal
  *             otherwise).
- * \returns The parsed `unsigned long`, or 0 if no number could be parsed.
+ * \returns the parsed `unsigned long`, or 0 if no number could be parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  *             to 36 inclusive. If 0, the base will be inferred from the
  *             number's prefix (0x for hexadecimal, 0 for octal, decimal
  *             otherwise).
- * \returns The parsed `long long`, or 0 if no number could be parsed.
+ * \returns the parsed `long long`, or 0 if no number could be parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  *             to 36 inclusive. If 0, the base will be inferred from the
  *             number's prefix (0x for hexadecimal, 0 for octal, decimal
  *             otherwise).
- * \returns The parsed `unsigned long long`, or 0 if no number could be
+ * \returns the parsed `unsigned long long`, or 0 if no number could be
  *          parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
···
  * - Whether or not INF and NAN can be parsed is unspecified.
  * - The precision of the result is unspecified.
  *
- * \param str The null-terminated string to read. Must not be NULL.
- * \param endp If not NULL, the address of the first invalid character (i.e.
+ * \param str the null-terminated string to read. Must not be NULL.
+ * \param endp if not NULL, the address of the first invalid character (i.e.
  *             the next character after the parsed number) will be written to
  *             this pointer.
- * \returns The parsed `double`, or 0 if no number could be parsed.
+ * \returns the parsed `double`, or 0 if no number could be parsed.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
···
  */
 extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
 
+/**
+ * This works exactly like sscanf() but doesn't require access to a C runtime.
+ *
+ * Scan a string, matching a format string, converting each '%' item and
+ * storing it to pointers provided through variable arguments.
+ *
+ * \param text the string to scan. Must not be NULL.
+ * \param fmt a printf-style format string. Must not be NULL.
+ * \param ... a 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.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
+extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
 
-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.
+ *
+ * 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.
+ * \returns the number of items that matched the format string.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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
+ * bytes will be written at all.
+ *
+ * This function returns the number of _bytes_ (not _characters_) that should
+ * be written, excluding the null-terminator character. If this returns a
+ * number >= `maxlen`, it means the output string was truncated. A negative
+ * return value means an error occurred.
+ *
+ * Referencing the output string's pointer with a format item is undefined
+ * behavior.
+ *
+ * \param text the buffer to write the string into. Must not be NULL.
+ * \param maxlen the maximum bytes 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 bytes that should be written, not counting the
+ *          null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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.
+ *
+ * This function returns the number of _wide characters_ (not _codepoints_)
+ * that should be written, excluding the null-terminator character. If this
+ * returns a number >= `maxlen`, it means the output string was truncated. A
+ * negative return value means an error occurred.
+ *
+ * Referencing the output string's pointer with a format item is undefined
+ * 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 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
+ *          the null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * Functions identically to SDL_snprintf(), 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 bytes to write, including the null-terminator.
+ * \param fmt a printf-style format string. Must not be NULL.
+ * \param ap a `va_list` values to be used with the format string.
+ * \returns the number of bytes that should be written, not counting the
+ *          null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * 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 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
+ *          the null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * Functions identically to SDL_snprintf(), except it allocates a buffer large
+ * enough to hold the output string on behalf of the caller.
+ *
+ * On success, this function returns the number of bytes (not characters)
+ * comprising the output string, not counting the null-terminator character,
+ * and sets `*strp` to the newly-allocated string.
+ *
+ * On error, this function returns a negative number, and the value of `*strp`
+ * is undefined.
+ *
+ * The returned string is owned by the caller, and should be passed to
+ * SDL_free when no longer needed.
+ *
+ * \param strp on output, is set to the new string. Must not be NULL.
+ * \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 bytes in the newly-allocated string, not counting
+ *          the null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 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.
+ *
+ * Functions identically to SDL_asprintf(), except it takes a `va_list`
+ * instead of using `...` variable arguments.
+ *
+ * \param strp on output, is set to the new string. Must not be NULL.
+ * \param fmt a printf-style format string. Must not be NULL.
+ * \param ap a `va_list` values to be used with the format string.
+ * \returns the number of bytes in the newly-allocated string, not counting
+ *          the null-terminator char, or a negative value on error.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.1.3.
+ */
 extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
 
 /**

include/SDL3/SDL_system.h

···
  * Platform specific functions for UNIX
  */
 
+/* this is defined in Xlib's headers, just need a simple declaration here. */
 typedef union _XEvent XEvent;
+
+/**
+ * A callback to be used with SDL_SetX11EventHook.
+ *
+ * This callback may modify the event, and should return true if the event
+ * should continue to be processed, or false to prevent further processing.
+ *
+ * As this is processing an event directly from the X11 event loop, this
+ * callback should do the minimum required work and return quickly.
+ *
+ * \param userdata the app-defined pointer provided to SDL_SetX11EventHook.
+ * \param xevent a pointer to an Xlib XEvent union to process.
+ * \returns true to let event continue on, false to drop it.
+ *
+ * \threadsafety This may only be called (by SDL) from the thread handling the
+ *               X11 event loop.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ *
+ * \sa SDL_SetX11EventHook
+ */
 typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
 
 /**
···
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_ANDROID_EXTERNAL_STORAGE_READ   0x01
+
+/**
+ * See the official Android developer guide for more information:
+ * http://developer.android.com/guide/topics/data/data-storage.html
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE  0x02
 
 /**
···
  */
 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
 
-
+/**
+ * Callback that presents a response from a SDL_RequestAndroidPermission call.
+ *
+ * \param userdata an app-controlled pointer that is passed to the callback.
+ * \param permission the Android-specific permission name that was requested.
+ * \param granted true if permission is granted, false if denied.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ *
+ * \sa SDL_RequestAndroidPermission
+ */
 typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted);
 
 /**

include/SDL3/SDL_video.h

···
     SDL_SYSTEM_THEME_DARK       /**< Dark colored system theme */
 } SDL_SystemTheme;
 
-/* Internal display mode data */
+/**
+ * Internal display mode data.
+ *
+ * This lives as a field in SDL_DisplayMode, as opaque data.
+ *
+ * \since This struct is available since SDL 3.1.3.
+ *
+ * \sa SDL_DisplayMode
+ */
 typedef struct SDL_DisplayModeData SDL_DisplayModeData;
 
 /**
···
 
 
 /**
+ * A magic value used with SDL_WINDOWPOS_UNDEFINED.
+ *
+ * Generally this macro isn't used directly, but rather through
+ * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_WINDOWPOS_UNDEFINED_MASK    0x1FFF0000u
+
+/**
  * Used to indicate that you don't care what the window position is.
  *
+ * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always
+ * uses the primary display instead of specifying one.
+ *
+ * \param X the SDL_DisplayID of the display to use.
+ *
  * \since This macro is available since SDL 3.1.3.
  */
-#define SDL_WINDOWPOS_UNDEFINED_MASK    0x1FFF0000u
 #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X)  (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
+
+/**
+ * Used to indicate that you don't care what the window position/display is.
+ *
+ * This always uses the primary display.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_WINDOWPOS_UNDEFINED         SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
-#define SDL_WINDOWPOS_ISUNDEFINED(X)    \
-            (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
+
+/**
+ * A macro to test if the window position is marked as "undefined."
+ *
+ * \param X the window position value.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
+#define SDL_WINDOWPOS_ISUNDEFINED(X)    (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
 
 /**
- * Used to indicate that the window position should be centered.
+ * A magic value used with SDL_WINDOWPOS_CENTERED.
+ *
+ * Generally this macro isn't used directly, but rather through
+ * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY.
  *
  * \since This macro is available since SDL 3.1.3.
  */
 #define SDL_WINDOWPOS_CENTERED_MASK    0x2FFF0000u
+
+/**
+ * Used to indicate that the window position should be centered.
+ *
+ * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display
+ * instead of specifying one.
+ *
+ * \param X the SDL_DisplayID of the display to use.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_WINDOWPOS_CENTERED_DISPLAY(X)  (SDL_WINDOWPOS_CENTERED_MASK|(X))
+
+/**
+ * Used to indicate that the window position should be centered.
+ *
+ * This always uses the primary display.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_WINDOWPOS_CENTERED         SDL_WINDOWPOS_CENTERED_DISPLAY(0)
+
+/**
+ * A macro to test if the window position is marked as "centered."
+ *
+ * \param X the window position value.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_WINDOWPOS_ISCENTERED(X)    \
             (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
+
 
 /**
  * Window flash operation.
···
 typedef struct SDL_GLContextState *SDL_GLContext;
 
 /**
- * Opaque EGL types.
+ * Opaque type for an EGL display.
  *
  * \since This datatype is available since SDL 3.1.3.
  */
 typedef void *SDL_EGLDisplay;
+
+/**
+ * Opaque type for an EGL config.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef void *SDL_EGLConfig;
+
+/**
+ * Opaque type for an EGL surface.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef void *SDL_EGLSurface;
+
+/**
+ * An EGL attribute, used when creating an EGL context.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef intptr_t SDL_EGLAttrib;
+
+/**
+ * An EGL integer attribute, used when creating an EGL surface.
+ *
+ * \since This datatype is available since SDL 3.1.3.
+ */
 typedef int SDL_EGLint;
 
 /**