From 12119cbaad70cb5e814f1f9fe32b15763c361ccb Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Thu, 13 Jun 2024 17:03:31 -0400 Subject: [PATCH] include: Several documentation tweaks; cleaned up new wikiheaders warnings. --- include/SDL3/SDL_main.h | 16 +++++-- include/SDL3/SDL_rect.h | 1 + include/SDL3/SDL_stdinc.h | 92 +++++++++++++++++++++++++++++++++++---- 3 files changed, 98 insertions(+), 11 deletions(-) diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index 757f660a2..c8294b5ac 100644 --- a/include/SDL3/SDL_main.h +++ b/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); diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index e9137a5b8..46e2a8c3f 100644 --- a/include/SDL3/SDL_rect.h +++ b/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. diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 2efcc093d..a1cd72259 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/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. */