include: Filled in some missing documentation.

include/SDL3/SDL_gamepad.h

@@ -58,9 +58,18 @@ extern "C" {
  *
  * \since This struct is available since SDL 3.0.0.
  */
-struct SDL_Gamepad;
 typedef struct SDL_Gamepad SDL_Gamepad;
 
+/**
+ * Standard gamepad types.
+ *
+ * This type does not necessarily map to first-party controllers
+ * from Microsoft/Sony/Nintendo; in many cases, third-party controllers
+ * can report as these, either because they were designed for a
+ * specific console, or they simply most closely match that console's
+ * controllers (does it have A/B/X/Y buttons or X/O/Square/Triangle?
+ * Does it have a touchpad? etc).
+ */
 typedef enum SDL_GamepadType
 {
     SDL_GAMEPAD_TYPE_UNKNOWN = 0,
@@ -182,6 +191,16 @@ typedef enum SDL_GamepadAxis
     SDL_GAMEPAD_AXIS_MAX
 } SDL_GamepadAxis;
 
+/**
+ * Types of gamepad control bindings.
+ *
+ * A gamepad is a collection of bindings that map arbitrary joystick
+ * buttons, axes and hat switches to specific positions on a generic
+ * console-style gamepad. This enum is used as part of SDL_GamepadBinding
+ * to specify those mappings.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
 typedef enum SDL_GamepadBindingType
 {
     SDL_GAMEPAD_BINDTYPE_NONE = 0,
@@ -190,6 +209,22 @@ typedef enum SDL_GamepadBindingType
     SDL_GAMEPAD_BINDTYPE_HAT
 } SDL_GamepadBindingType;
 
+/**
+ * A mapping between one joystick input to a gamepad control.
+ *
+ * A gamepad has a collection of several bindings, to say, for
+ * example, when joystick button number 5 is pressed, that should
+ * be treated like the gamepad's "start" button.
+ *
+ * SDL has these bindings built-in for many popular controllers,
+ * and can add more with a simple text string. Those strings are
+ * parsed into a collection of these structs to make it easier
+ * to operate on the data.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadBindings
+ */
 typedef struct SDL_GamepadBinding
 {
     SDL_GamepadBindingType input_type;
@@ -225,7 +260,6 @@ typedef struct SDL_GamepadBinding
         } axis;
 
     } output;
-
 } SDL_GamepadBinding;
 
 

include/SDL3/SDL_joystick.h

@@ -63,16 +63,31 @@ extern "C" {
  *  SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
  */
 
-/**
- * The joystick structure used to identify an SDL joystick
- */
 #ifdef SDL_THREAD_SAFETY_ANALYSIS
+/*
+ * This is not an exported symbol from SDL, this is only in the headers to
+ * help Clang's thread safety analysis tools to function. Do not attempt
+ * to access this symbol from your app, it will not work!
+ */
 extern SDL_Mutex *SDL_joystick_lock;
 #endif
-struct SDL_Joystick;
+
+/**
+ * The joystick structure used to identify an SDL joystick.
+ *
+ * This is opaque data.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_Joystick SDL_Joystick;
 
-/* A structure that encodes the stable unique id for a joystick device */
+/**
+ * A structure that encodes the stable unique id for a joystick device.
+ *
+ * This is just a standard SDL_GUID by a different name.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ */
 typedef SDL_GUID SDL_JoystickGUID;
 
 /**
@@ -88,6 +103,18 @@ typedef SDL_GUID SDL_JoystickGUID;
  */
 typedef Uint32 SDL_JoystickID;
 
+/**
+ * An enum of some common joystick types.
+ *
+ * In some cases, SDL can identify a low-level joystick as being a certain
+ * type of device, and will report it through SDL_GetJoystickType (or
+ * SDL_GetJoystickInstanceType).
+ *
+ * This is by no means a complete list of everything that can be plugged
+ * into a computer.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
 typedef enum SDL_JoystickType
 {
     SDL_JOYSTICK_TYPE_UNKNOWN,
@@ -102,6 +129,14 @@ typedef enum SDL_JoystickType
     SDL_JOYSTICK_TYPE_THROTTLE
 } SDL_JoystickType;
 
+/**
+ * Possible connection states for a joystick device.
+ *
+ * This is used by SDL_GetJoystickConnectionState to report how a device
+ * is connected to the system.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
 typedef enum SDL_JoystickConnectionState
 {
     SDL_JOYSTICK_CONNECTION_INVALID = -1,
@@ -110,9 +145,27 @@ typedef enum SDL_JoystickConnectionState
     SDL_JOYSTICK_CONNECTION_WIRELESS
 } SDL_JoystickConnectionState;
 
+/**
+ * The largest value an SDL_Joystick's axis can report.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_JOYSTICK_AXIS_MIN
+ */
 #define SDL_JOYSTICK_AXIS_MAX   32767
+
+/**
+ * The smallest value an SDL_Joystick's axis can report.
+ *
+ * This is a negative number!
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_JOYSTICK_AXIS_MAX
+ */
 #define SDL_JOYSTICK_AXIS_MIN   -32768
 
+
 /* Set max recognized G-force from accelerometer
    See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed
  */
@@ -929,35 +982,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *j
  */
 extern DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
 
-/**
- *  \name Hat positions
- */
-/* @{ */
-#define SDL_HAT_CENTERED    0x00
-#define SDL_HAT_UP          0x01
-#define SDL_HAT_RIGHT       0x02
-#define SDL_HAT_DOWN        0x04
-#define SDL_HAT_LEFT        0x08
-#define SDL_HAT_RIGHTUP     (SDL_HAT_RIGHT|SDL_HAT_UP)
-#define SDL_HAT_RIGHTDOWN   (SDL_HAT_RIGHT|SDL_HAT_DOWN)
-#define SDL_HAT_LEFTUP      (SDL_HAT_LEFT|SDL_HAT_UP)
-#define SDL_HAT_LEFTDOWN    (SDL_HAT_LEFT|SDL_HAT_DOWN)
-/* @} */
-
 /**
  * Get the current state of a POV hat on a joystick.
  *
- * The returned value will be one of the following positions:
+ * The returned value will be one of the `SDL_HAT_*` values.
- *
- * - `SDL_HAT_CENTERED`
- * - `SDL_HAT_UP`
- * - `SDL_HAT_RIGHT`
- * - `SDL_HAT_DOWN`
- * - `SDL_HAT_LEFT`
- * - `SDL_HAT_RIGHTUP`
- * - `SDL_HAT_RIGHTDOWN`
- * - `SDL_HAT_LEFTUP`
- * - `SDL_HAT_LEFTDOWN`
  *
  * \param joystick an SDL_Joystick structure containing joystick information
  * \param hat the hat index to get the state from; indices start at index 0
@@ -969,6 +997,16 @@ extern DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int hat);
 
+#define SDL_HAT_CENTERED    0x00
+#define SDL_HAT_UP          0x01
+#define SDL_HAT_RIGHT       0x02
+#define SDL_HAT_DOWN        0x04
+#define SDL_HAT_LEFT        0x08
+#define SDL_HAT_RIGHTUP     (SDL_HAT_RIGHT|SDL_HAT_UP)
+#define SDL_HAT_RIGHTDOWN   (SDL_HAT_RIGHT|SDL_HAT_DOWN)
+#define SDL_HAT_LEFTUP      (SDL_HAT_LEFT|SDL_HAT_UP)
+#define SDL_HAT_LEFTDOWN    (SDL_HAT_LEFT|SDL_HAT_DOWN)
+
 /**
  * Get the current state of a button on a joystick.
  *

include/SDL3/SDL_keyboard.h

@@ -39,6 +39,17 @@
 extern "C" {
 #endif
 
+/**
+ * This is a unique ID for a keyboard for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
+ *
+ * If the keyboard is disconnected and reconnected, it will get a new ID.
+ *
+ * The ID value starts at 1 and increments from there. The value 0 is an
+ * invalid ID.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ */
 typedef Uint32 SDL_KeyboardID;
 
 /**

include/SDL3/SDL_mutex.h

@@ -116,8 +116,9 @@ extern "C" {
 #endif
 
 /**
- * Synchronization functions which can time out return this value if they time
+ * Synchronization functions return this value if they time out.
- * out.
+ *
+ * Not all functions _can_ time out; some will block indefinitely.
  *
  * \since This macro is available since SDL 3.0.0.
  */
@@ -129,8 +130,18 @@ extern "C" {
  */
 /* @{ */
 
-/* The SDL mutex structure, defined in SDL_sysmutex.c */
+/**
-struct SDL_Mutex;
+ * A means to serialize access to a resource between threads.
+ *
+ * Mutexes (short for "mutual exclusion") are a synchronization primitive
+ * that allows exactly one thread to proceed at a time.
+ *
+ * Wikipedia has a thorough explanation of the concept:
+ *
+ * https://en.wikipedia.org/wiki/Mutex
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_Mutex SDL_Mutex;
 
 /**
@@ -247,13 +258,37 @@ extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex);
  */
 /* @{ */
 
-/* The SDL read/write lock structure, defined in SDL_sysrwlock.c */
+/**
-struct SDL_RWLock;
+ * A mutex that allows read-only threads to run in parallel.
+ *
+ * A rwlock is roughly the same concept as SDL_Mutex, but allows
+ * threads that request read-only access to all hold the lock at
+ * the same time. If a thread requests write access, it will block
+ * until all read-only threads have released the lock, and no one
+ * else can hold the thread (for reading or writing) at the same
+ * time as the writing thread.
+ *
+ * This can be more efficient in cases where several threads need
+ * to access data frequently, but changes to that data are rare.
+ *
+ * There are other rules that apply to rwlocks that don't apply
+ * to mutexes, about how threads are scheduled and when they can
+ * be recursively locked. These are documented in the other rwlock
+ * functions.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_RWLock SDL_RWLock;
 
 /*
- *  Synchronization functions which can time out return this value
+ * Synchronization functions return this value if they time out.
- *  if they time out.
+ *
+ * Not all functions _can_ time out; some will block indefinitely.
+ *
+ * This symbol is just for clarity when dealing with SDL_RWLock
+ * functions; its value is equivalent to SDL_MUTEX_TIMEOUT.
+ *
+ * \since This macro is available since SDL 3.0.0.
  */
 #define SDL_RWLOCK_TIMEDOUT SDL_MUTEX_TIMEDOUT
 
@@ -479,8 +514,21 @@ extern DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock);
  */
 /* @{ */
 
-/* The SDL semaphore structure, defined in SDL_syssem.c */
+/**
-struct SDL_Semaphore;
+ * A means to manage access to a resource, by count, between threads.
+ *
+ * Semaphores (specifically, "counting semaphores"), let X number of
+ * threads request access at the same time, each thread granted access
+ * decrementing a counter. When the counter reaches zero, future requests
+ * block until a prior thread releases their request, incrementing the
+ * counter again.
+ *
+ * Wikipedia has a thorough explanation of the concept:
+ *
+ * https://en.wikipedia.org/wiki/Semaphore_(programming)
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_Semaphore SDL_Semaphore;
 
 /**
@@ -620,8 +668,19 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem);
  */
 /* @{ */
 
-/* The SDL condition variable structure, defined in SDL_syscond.c */
+/**
-struct SDL_Condition;
+ * A means to block multiple threads until a condition is satisfied.
+ *
+ * Condition variables, paired with an SDL_Mutex, let an app
+ * halt multiple threads until a condition has occurred, at which
+ * time the app can release one or all waiting threads.
+ *
+ * Wikipedia has a thorough explanation of the concept:
+ *
+ * https://en.wikipedia.org/wiki/Condition_variable
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_Condition SDL_Condition;
 
 /**

include/SDL3/SDL_storage.h

@@ -42,6 +42,19 @@ extern "C" {
 
 /* !!! FIXME: Don't let this ship without async R/W support!!! */
 
+/**
+ * Function interface for SDL_Storage.
+ *
+ * Apps that want to supply a custom implementation of SDL_Storage
+ * will fill in all the functions in this struct, and then pass it to
+ * SDL_OpenStorage to create a custom SDL_Storage object.
+ *
+ * It is not usually necessary to do this; SDL provides standard
+ * implementations for many things you might expect to do with
+ * an SDL_Storage.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_StorageInterface
 {
     /* Called when the storage is closed */
@@ -73,9 +86,18 @@ typedef struct SDL_StorageInterface
 
     /* Get the space remaining, optional for read-only storage */
     Uint64 (SDLCALL *space_remaining)(void *userdata);
-
 } SDL_StorageInterface;
 
+/**
+ * An abstract interface for filesystem access.
+ *
+ * This is an opaque datatype. One can create this object
+ * using standard SDL functions like SDL_OpenTitleStorage or
+ * SDL_OpenUserStorage, etc, or create an object with a custom
+ * implementation using SDL_OpenStorage.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_Storage SDL_Storage;
 
 /**