include: Several documentation tweaks; cleaned up new wikiheaders warnings.

include/SDL3/SDL_main.h

@@ -438,6 +438,10 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate);
 /**
  * The prototype for the application's main() function
  *
+ * \param argc an ANSI-C style main function's argc.
+ * \param argv an ANSI-C style main function's argv.
+ * \returns Generally 0 is considered successful program completion, small non-zero values are considered errors.
+ *
  * \since This datatype is available since SDL 3.0.0.
  */
 typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
@@ -463,6 +467,10 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
  * docs/README-main-functions.md in the source tree) for a more detailed
  * explanation.
  *
+ * \param argc an ANSI-C style main function's argc.
+ * \param argv an ANSI-C style main function's argv.
+ * \returns Generally 0 is considered successful program completion, small non-zero values are considered errors.
+ *
  * \threadsafety This is the program entry point.
  *
  * \since This function is available since SDL 3.0.0.
@@ -498,15 +506,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void);
  *             if the platform's main-equivalent has no argc
  * \param argv The argv parameter from the application's main() function, or
  *             NULL if the platform's main-equivalent has no argv
- * \param mainFunction Your SDL app's C-style main(), an SDL_main_func. NOT
+ * \param mainFunction Your SDL app's C-style main(). NOT
  *                     the function you're calling this from! Its name doesn't
- *                     matter, but its signature must be like int my_main(int
- *                     argc, char* argv[])
+ *                     matter; it doesn't literally have to be `main`.
  * \param reserved should be NULL (reserved for future use, will probably be
  *                 platform-specific then)
  * \returns the return value from mainFunction: 0 on success, -1 on failure;
  *          SDL_GetError() might have more information on the failure
  *
+ * \threadsafety Generally this is called once, near startup, from the
+ *               process's initial thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved);

include/SDL3/SDL_rect.h

@@ -354,6 +354,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r)
  *
  * \param a the first rectangle to test.
  * \param b the second rectangle to test.
+ * \param epsilon the epsilon value for comparison.
  * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_stdinc.h

@@ -504,11 +504,18 @@ typedef void (SDLCALL *SDL_free_func)(void *mem);
 /**
  * Get the original set of SDL memory functions.
  *
+ * This is what SDL_malloc and friends will use by default, if there has been
+ * no call to SDL_SetMemoryFunctions. This is not necessarily using the C
+ * runtime's `malloc` functions behind the scenes! Different platforms and
+ * build configurations might do any number of unexpected things.
+ *
  * \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
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func,
@@ -524,7 +531,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func
  * \param realloc_func filled with realloc function
  * \param free_func filled with free function
  *
+ * \threadsafety This does not hold a lock, so do not call this in the unlikely
+ *               event of a background thread calling SDL_SetMemoryFunctions
+ *               simultaneously.
+ *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetMemoryFunctions
+ * \sa SDL_GetOriginalMemoryFunctions
  */
 extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
                                                     SDL_calloc_func *calloc_func,
@@ -534,6 +548,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_
 /**
  * Replace SDL's memory allocation functions with a custom set.
  *
+ * It is not safe to call this function once any allocations have been made,
+ * as future calls to SDL_free will use the new allocator, even if they came
+ * from an SDL_malloc made with the old one!
+ *
+ * If used, usually this needs to be the first call made into the SDL library,
+ * if not the very first thing done at program startup time.
+ *
  * \param malloc_func custom malloc function
  * \param calloc_func custom calloc function
  * \param realloc_func custom realloc function
@@ -541,7 +562,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread, but one
+ *               should not replace the memory functions once any allocations
+ *               are made!
+ *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetMemoryFunctions
+ * \sa SDL_GetOriginalMemoryFunctions
  */
 extern SDL_DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
                                                    SDL_calloc_func calloc_func,
@@ -557,12 +585,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_fu
  * The returned memory address will be a multiple of the alignment value, and
  * the amount of memory allocated will be a multiple of the alignment value.
  *
- * The memory returned by this function must be freed with SDL_aligned_free()
+ * The memory returned by this function must be freed with SDL_aligned_free(),
+ * and _not_ SDL_free.
  *
  * \param alignment the alignment requested
  * \param size the size to allocate
  * \returns a pointer to the aligned memory
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_aligned_free
@@ -572,6 +603,13 @@ extern SDL_DECLSPEC SDL_MALLOC void *SDLCALL SDL_aligned_alloc(size_t alignment,
 /**
  * Free memory allocated by SDL_aligned_alloc().
  *
+ * The pointer is no longer valid after this call and cannot be dereferenced
+ * anymore.
+ *
+ * \param mem a pointer previously returned by SDL_aligned_alloc.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_aligned_alloc
@@ -583,6 +621,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
  *
  * \returns the number of allocations
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
@@ -1036,6 +1076,9 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strrev(char *str);
  * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their
  * uppercase equivalents in-place, returning the original `str` pointer.
  *
+ * \param str The string to convert in-place. Can not be NULL.
+ * \returns The `str` pointer passed into this function.
+ *
  * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1054,7 +1097,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strupr(char *str);
  * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their
  * lowercase equivalents in-place, returning the original `str` pointer.
  *
- * \param str The string to convert in-place.
+ * \param str The string to convert in-place. Can not be NULL.
  * \returns The `str` pointer passed into this function.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -2494,8 +2537,23 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
                                          size_t * outbytesleft);
 
 /**
- * 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.
+ * Helper function to convert a string's encoding in one call.
+ *
+ * This function converts a buffer or string between encodings in one pass.
+ *
+ * The string does not need to be NULL-terminated; this function operates
+ * on the number of bytes specified in `inbytesleft` whether there is a
+ * NULL character anywhere in the buffer.
+ *
+ * The returned string is owned by the caller, and should be passed to
+ * SDL_free when no longer needed.
+ *
+ * \param tocode the character encoding of the output string. Examples are "UTF-8", "UCS-4", etc.
+ * \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 3.0.0.
  */
@@ -2577,9 +2635,18 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
 #endif
 
 /**
- * If a * b would overflow, return -1.
+ * Multiply two integers, checking for overflow.
  *
- * Otherwise store a * b via ret and return 0.
+ * If `a * b` would overflow, return -1.
+ *
+ * Otherwise store `a * b` via ret and return 0.
+ *
+ * \param a the multiplicand
+ * \param b the multiplier
+ * \param ret on non-overflow output, stores the multiplication result. May not be NULL.
+ * \returns -1 on overflow, 0 if result doesn't overflow.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -2610,9 +2677,18 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a,
 #endif
 
 /**
- * If a + b would overflow, return -1.
+ * Add two integers, checking for overflow.
  *
- * Otherwise store a + b via ret and return 0.
+ * If `a + b` would overflow, return -1.
+ *
+ * Otherwise store `a + b` via ret and return 0.
+ *
+ * \param a the first addend.
+ * \param b the second addend.
+ * \param ret on non-overflow output, stores the addition result. May not be NULL.
+ * \returns -1 on overflow, 0 if result doesn't overflow.
+ *
+ * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
  */