gosu 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d58f7d332c57be8c599f33a6c60df54d7143e6ef2980eacd1a84f5d51f7a26a
-  data.tar.gz: e22cf468c5392985d6429aac77b958d71c63c33ac40a4a06b1f01187837bb224
+  metadata.gz: 98e9ee1c852cb1d1a27cfebd4f4e2e28eed5348feb2ec1e5a26970ab16ceadca
+  data.tar.gz: 2191e45a7decbf43a919dd1acd9517bd778572893475d9c6801c6f4109b04afa
 SHA512:
-  metadata.gz: 69605aee52675d916c27e58ad596d294ea4268e24520b137a2afa184a38f92b4120646a1e0c3ada0e6293088db9f965adf907a99b164052ee741b81cfd2a779c
-  data.tar.gz: 55615664e9ababb8ee986af01191a296b364d53d42986fcd45a94436b33f4d59aa46643da62a14e0e0a960def6a699d782f03bf74876c70405e4f6ec4d8591df
+  metadata.gz: 8827283b9324763479b211360259fb85798d9a33e91cd14aace844ad50ac78bb7668255d32bc82c8873229ec16f12c32be44ecbc8facb998cf6756ca47c3b212
+  data.tar.gz: 6544155d5b65c73e653ac7172dfe9ab89f6ca079a4fc1daea3bc14d4db23c0b77b15c638049d6f9ee3b69699c546450ae6a40f1f7d88a81d095c67482a59ded4

data/dependencies/SDL/include/SDL.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -42,6 +42,7 @@
 #include "SDL_filesystem.h"
 #include "SDL_gamecontroller.h"
 #include "SDL_haptic.h"
+#include "SDL_hidapi.h"
 #include "SDL_hints.h"
 #include "SDL_joystick.h"
 #include "SDL_loadso.h"
@@ -93,37 +94,130 @@ extern "C" {
 /* @} */
 
 /**
- *  This function initializes  the subsystems specified by \c flags
+ * Initialize the SDL library.
+ *
+ * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
+ * two may be used interchangeably. Though for readability of your code
+ * SDL_InitSubSystem() might be preferred.
+ *
+ * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
+ * subsystems are initialized by default. Message boxes
+ * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
+ * video subsystem, in hopes of being useful in showing an error dialog when
+ * SDL_Init fails. You must specifically initialize other subsystems if you
+ * use them in your application.
+ *
+ * Logging (such as SDL_Log) works without initialization, too.
+ *
+ * `flags` may be any of the following OR'd together:
+ *
+ * - `SDL_INIT_TIMER`: timer subsystem
+ * - `SDL_INIT_AUDIO`: audio subsystem
+ * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
+ *   subsystem
+ * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
+ *   events subsystem
+ * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
+ * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
+ *   initializes the joystick subsystem
+ * - `SDL_INIT_EVENTS`: events subsystem
+ * - `SDL_INIT_EVERYTHING`: all of the above subsystems
+ * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
+ *
+ * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
+ * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
+ * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
+ * this call will increase the ref-count and return.
+ *
+ * \param flags subsystem initialization flags
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
+ * \sa SDL_SetMainReady
+ * \sa SDL_WasInit
  */
 extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
 
 /**
- *  This function initializes specific SDL subsystems
+ * Compatibility function to initialize the SDL library.
+ *
+ * In SDL2, this function and SDL_Init() are interchangeable.
  *
- *  Subsystem initialization is ref-counted, you must call
- *  SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
- *  shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
- *  If a subsystem is already loaded then this call will
- *  increase the ref-count and return.
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_Quit
+ * \sa SDL_QuitSubSystem
  */
 extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
 
 /**
- *  This function cleans up specific SDL subsystems
+ * Shut down specific SDL subsystems.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
+ * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
+ * generally, you should not be using those functions directly anyhow; use
+ * SDL_Init() instead.
+ *
+ * You still need to call SDL_Quit() even if you close all open subsystems
+ * with SDL_QuitSubSystem().
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
  */
 extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
 
 /**
- *  This function returns a mask of the specified subsystems which have
- *  previously been initialized.
+ * Get a mask of the specified subsystems which are currently initialized.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
+ *          returns the initialization status of the specified subsystems.
+ *
+ *          The return value does not include SDL_INIT_NOPARACHUTE.
  *
- *  If \c flags is 0, it returns a mask of all initialized subsystems.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
  */
 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
 
 /**
- *  This function cleans up all initialized subsystems. You should
- *  call it upon all exit conditions.
+ * Clean up all initialized subsystems.
+ *
+ * You should call this function even if you have already shutdown each
+ * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
+ * function even in the case of errors in initialization.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
+ * it down before calling SDL_Quit(). But generally, you should not be using
+ * those functions directly anyhow; use SDL_Init() instead.
+ *
+ * You can use this function with atexit() to ensure that it is run when your
+ * application is shutdown, but it is not wise to do this from a library or
+ * other dynamically loaded code.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
  */
 extern DECLSPEC void SDLCALL SDL_Quit(void);
 

data/dependencies/SDL/include/SDL_assert.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -53,8 +53,10 @@ assert can have unique static variables associated with it.
     #define SDL_TriggerBreakpoint() __debugbreak()
 #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) )
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
-#elif ( defined(__APPLE__) && defined(__arm64__) )  /* this might work on other ARM targets, but this is a known quantity... */
+#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) )  /* this might work on other ARM targets, but this is a known quantity... */
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" )
+#elif defined(__APPLE__) && defined(__arm__)
+    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
 #elif defined(__386__) && defined(__WATCOMC__)
     #define SDL_TriggerBreakpoint() { _asm { int 0x03 } }
 #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__)
@@ -187,92 +189,121 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
 #define SDL_assert_always(condition) SDL_enabled_assert(condition)
 
 
+/**
+ * A callback that fires when an SDL assertion fails.
+ *
+ * \param data a pointer to the SDL_AssertData structure corresponding to the
+ *             current assertion
+ * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
+ * \returns an SDL_AssertState value indicating how to handle the failure.
+ */
 typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
                                  const SDL_AssertData* data, void* userdata);
 
 /**
- *  \brief Set an application-defined assertion handler.
+ * Set an application-defined assertion handler.
  *
- *  This allows an app to show its own assertion UI and/or force the
- *  response to an assertion failure. If the app doesn't provide this, SDL
- *  will try to do the right thing, popping up a system-specific GUI dialog,
- *  and probably minimizing any fullscreen windows.
+ * This function allows an application to show its own assertion UI and/or
+ * force the response to an assertion failure. If the application doesn't
+ * provide this, SDL will try to do the right thing, popping up a
+ * system-specific GUI dialog, and probably minimizing any fullscreen windows.
  *
- *  This callback may fire from any thread, but it runs wrapped in a mutex, so
- *  it will only fire from one thread at a time.
+ * This callback may fire from any thread, but it runs wrapped in a mutex, so
+ * it will only fire from one thread at a time.
  *
- *  Setting the callback to NULL restores SDL's original internal handler.
+ * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
  *
- *  This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ * \param handler the SDL_AssertionHandler function to call when an assertion
+ *                fails or NULL for the default handler
+ * \param userdata a pointer that is passed to `handler`
  *
- *  Return SDL_AssertState value of how to handle the assertion failure.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \param handler Callback function, called when an assertion fails.
- *  \param userdata A pointer passed to the callback as-is.
+ * \sa SDL_GetAssertionHandler
  */
 extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
                                             SDL_AssertionHandler handler,
                                             void *userdata);
 
 /**
- *  \brief Get the default assertion handler.
+ * Get the default assertion handler.
  *
- *  This returns the function pointer that is called by default when an
- *   assertion is triggered. This is an internal function provided by SDL,
- *   that is used for assertions when SDL_SetAssertionHandler() hasn't been
- *   used to provide a different function.
+ * This returns the function pointer that is called by default when an
+ * assertion is triggered. This is an internal function provided by SDL, that
+ * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
+ * provide a different function.
  *
- *  \return The default SDL_AssertionHandler that is called when an assert triggers.
+ * \returns the default SDL_AssertionHandler that is called when an assert
+ *          triggers.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GetAssertionHandler
  */
 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
 
 /**
- *  \brief Get the current assertion handler.
+ * Get the current assertion handler.
+ *
+ * This returns the function pointer that is called when an assertion is
+ * triggered. This is either the value last passed to
+ * SDL_SetAssertionHandler(), or if no application-specified function is set,
+ * is equivalent to calling SDL_GetDefaultAssertionHandler().
  *
- *  This returns the function pointer that is called when an assertion is
- *   triggered. This is either the value last passed to
- *   SDL_SetAssertionHandler(), or if no application-specified function is
- *   set, is equivalent to calling SDL_GetDefaultAssertionHandler().
+ * The parameter `puserdata` is a pointer to a void*, which will store the
+ * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
+ * will always be NULL for the default handler. If you don't care about this
+ * data, it is safe to pass a NULL pointer to this function to ignore it.
  *
- *   \param puserdata Pointer to a void*, which will store the "userdata"
- *                    pointer that was passed to SDL_SetAssertionHandler().
- *                    This value will always be NULL for the default handler.
- *                    If you don't care about this data, it is safe to pass
- *                    a NULL pointer to this function to ignore it.
- *  \return The SDL_AssertionHandler that is called when an assert triggers.
+ * \param puserdata pointer which is filled with the "userdata" pointer that
+ *                  was passed to SDL_SetAssertionHandler()
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_SetAssertionHandler
  */
 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
 
 /**
- *  \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
+ *
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
  *
- *  Get all assertions triggered since last call to SDL_ResetAssertionReport(),
- *  or the start of the program.
+ * The proper way to examine this data looks something like this:
  *
- *  The proper way to examine this data looks something like this:
+ * ```c
+ * const SDL_AssertData *item = SDL_GetAssertionReport();
+ * while (item) {
+ *    printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
+ *           item->condition, item->function, item->filename,
+ *           item->linenum, item->trigger_count,
+ *           item->always_ignore ? "yes" : "no");
+ *    item = item->next;
+ * }
+ * ```
  *
- *  <code>
- *  const SDL_AssertData *item = SDL_GetAssertionReport();
- *  while (item) {
- *      printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
- *             item->condition, item->function, item->filename,
- *             item->linenum, item->trigger_count,
- *             item->always_ignore ? "yes" : "no");
- *      item = item->next;
- *  }
- *  </code>
+ * \returns a list of all failed assertions or NULL if the list is empty. This
+ *          memory should not be modified or freed by the application.
  *
- *  \return List of all assertions.
- *  \sa SDL_ResetAssertionReport
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ResetAssertionReport
  */
 extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
 
 /**
- *  \brief Reset the list of all assertion failures.
+ * Clear the list of all assertion failures.
+ *
+ * This function will clear the list of all assertions triggered up to that
+ * point. Immediately following this call, SDL_GetAssertionReport will return
+ * no items. In addition, any previously-triggered assertions will be reset to
+ * a trigger_count of zero, and their always_ignore state will be false.
  *
- *  Reset list of all assertions triggered.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_GetAssertionReport
+ * \sa SDL_GetAssertionReport
  */
 extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
 

data/dependencies/SDL/include/SDL_atomic.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -89,25 +89,51 @@ extern "C" {
 typedef int SDL_SpinLock;
 
 /**
- * \brief Try to lock a spin lock by setting it to a non-zero value.
+ * Try to lock a spin lock by setting it to a non-zero value.
  *
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
  *
- * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
+ * \param lock a pointer to a lock variable
+ * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
+ *          held.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicUnlock
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
 
 /**
- * \brief Lock a spin lock by setting it to a non-zero value.
+ * Lock a spin lock by setting it to a non-zero value.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- * \param lock Points to the lock.
+ * \sa SDL_AtomicTryLock
+ * \sa SDL_AtomicUnlock
  */
 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
 
 /**
- * \brief Unlock a spin lock by setting it to 0. Always returns immediately
+ * Unlock a spin lock by setting it to 0.
+ *
+ * Always returns immediately.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- * \param lock Points to the lock.
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
  */
 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
 
@@ -126,7 +152,7 @@ void _ReadWriteBarrier(void);
 /* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */
 #define SDL_CompilerBarrier()   __asm__ __volatile__ ("" : : : "memory")
 #elif defined(__WATCOMC__)
-extern _inline void SDL_CompilerBarrier (void);
+extern __inline void SDL_CompilerBarrier(void);
 #pragma aux SDL_CompilerBarrier = "" parm [] modify exact [];
 #else
 #define SDL_CompilerBarrier()   \
@@ -137,20 +163,22 @@ extern _inline void SDL_CompilerBarrier (void);
  * 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.
  *
- * A typical pattern would be for thread A to write some data and a flag,
- * and for thread B to read the flag and get the data. In this case you
- * would insert a release barrier between writing the data and the flag,
+ * A typical pattern would be for thread A to write some data and a flag, and
+ * for thread B to read the flag and get the data. In this case you would
+ * insert a release barrier between writing the data and the flag,
  * guaranteeing that the data write completes no later than the flag is
- * written, and you would insert an acquire barrier between reading the
- * flag and reading the data, to ensure that all the reads associated
- * with the flag have completed.
+ * written, and you would insert an acquire barrier between reading the flag
+ * and reading the data, to ensure that all the reads associated with the flag
+ * have completed.
  *
- * In this pattern you should always see a release barrier paired with
- * an acquire barrier and you should gate the data reads/writes with a
- * single flag variable.
+ * In this pattern you should always see a release barrier paired with an
+ * acquire barrier and you should gate the data reads/writes with a single
+ * flag variable.
  *
  * For more information on these semantics, take a look at the blog post:
  * http://preshing.com/20120913/acquire-and-release-semantics
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
 extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
@@ -216,32 +244,73 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
 typedef struct { int value; } SDL_atomic_t;
 
 /**
- * \brief Set an atomic variable to a new value if it is currently an old value.
+ * Set an atomic variable to a new value if it is currently an old value.
  *
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param oldval the old value
+ * \param newval the new value
+ * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGet
+ * \sa SDL_AtomicSet
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
 
 /**
- * \brief Set an atomic variable to a value.
+ * Set an atomic variable to a value.
+ *
+ * This function also acts as a full memory barrier.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value
+ * \returns the previous value of the atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
  *
- * \return The previous value of the atomic variable.
+ * \sa SDL_AtomicGet
  */
 extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
 
 /**
- * \brief Get the value of an atomic variable
+ * Get the value of an atomic variable.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable
+ * \returns the current value of an atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicSet
  */
 extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
 
 /**
- * \brief Add to an atomic variable.
+ * Add to an atomic variable.
+ *
+ * This function also acts as a full memory barrier.
  *
- * \return The previous value of the atomic variable.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note This same style can be used for any number operation
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value to add
+ * \returns the previous value of the atomic variable.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
  */
 extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 
@@ -263,23 +332,54 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 #endif
 
 /**
- * \brief Set a pointer to a new value if it is currently an old value.
+ * Set a pointer to a new value if it is currently an old value.
  *
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to a pointer
+ * \param oldval the old pointer value
+ * \param newval the new pointer value
+ * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCAS
+ * \sa SDL_AtomicGetPtr
+ * \sa SDL_AtomicSetPtr
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
 
 /**
- * \brief Set a pointer to a value atomically.
+ * Set a pointer to a value atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \param v the desired pointer value
+ * \returns the previous value of the pointer.
+ *
+ * \since This function is available since SDL 2.0.2.
  *
- * \return The previous value of the pointer.
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGetPtr
  */
 extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
 
 /**
- * \brief Get the value of a pointer atomically.
+ * Get the value of a pointer atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \returns the current value of a pointer.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
  */
 extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);