From ed95b31dc4eaca92bbe599c0731c057232e426b8 Mon Sep 17 00:00:00 2001
From: Wes Lord <weslord@fisgardlabs.com>
Date: Sun, 1 Jun 2025 22:51:45 -0700
Subject: [PATCH] Add docstrings to SDL_stdinc.h

---
 include/SDL_stdinc.h | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/include/SDL_stdinc.h b/include/SDL_stdinc.h
index 1854698b60..9385b88338 100644
--- a/include/SDL_stdinc.h
+++ b/include/SDL_stdinc.h
@@ -467,6 +467,11 @@ typedef void (SDLCALL *SDL_free_func)(void *mem);
 /**
  * Get the original set of SDL memory functions
  *
+ * \param malloc_func filled with malloc function.
+ * \param calloc_func filled with calloc function.
+ * \param realloc_func filled with realloc function.
+ * \param free_func filled with free function.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func,
@@ -477,6 +482,11 @@ extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *mal
 /**
  * Get the current set of SDL memory functions
  *
+ * \param malloc_func filled with malloc function.
+ * \param calloc_func filled with calloc function.
+ * \param realloc_func filled with realloc function.
+ * \param free_func filled with free function.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
@@ -487,6 +497,13 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
 /**
  * Replace SDL's memory allocation functions with a custom set
  *
+ * \param malloc_func custom malloc function.
+ * \param calloc_func custom calloc function.
+ * \param realloc_func custom realloc function.
+ * \param free_func custom free function.
+ * \returns 0 on success or -1 on failure; call SDL_GetError() for more
+ *          information.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
@@ -497,6 +514,8 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
 /**
  * Get the number of outstanding (unfreed) allocations
  *
+ * \returns number of unfreed allocations.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
@@ -715,6 +734,12 @@ extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
  * This function converts a buffer or string between encodings in one pass,
  * returning a string that must be freed with SDL_free() or NULL on error.
  *
+ * \param tocode the character encoding of the output string.
+ * \param fromcode the character encoding of data in `inbuf`.
+ * \param inbuf the string to convert to a different encoding.
+ * \param inbytesleft the size of the input string _in bytes_.
+ * \returns a new string, converted to the new encoding, or NULL on error.
+ *
  * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
@@ -806,6 +831,11 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B
  *
  * Otherwise store a * b via ret and return 0.
  *
+ * \param a the multiplicand.
+ * \param b the multiplier.
+ * \param ret on non-overflow output, stores the multiplication result.
+ * \returns -1 on overflow, 0 if result is multiplied without overflow.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a,
@@ -837,6 +867,11 @@ SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a,
  *
  * Otherwise store a + b via ret and return 0.
  *
+ * \param a the first addend.
+ * \param b the second addend.
+ * \param ret on non-overflow output, stores the addition result.
+ * \returns false on overflow, true if result is added without overflow.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a,