include: A ton of little documentation tweaks, fixes, and improvements.

This is just stuff I noticed while working on the wikiheaders updates. A thorough pass over all the docs would not be terrible, and maybe a simple script to check for consistency (does everything have a `\since` on it? etc) might be nice, too.
2024-04-08 22:36:57 -04:00 · 2024-04-08 22:36:57 -04:00 · ad090d2444
parent 645073961d
commit ad090d2444
45 changed files with 1565 additions and 833 deletions
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@ -125,6 +125,15 @@ typedef enum
    SDL_ASSERTION_ALWAYS_IGNORE  /**< Ignore the assert from now on. */
 } SDL_AssertState;

+/**
+ * Information about an assertion failure.
+ *
+ * This structure is filled in with information about a triggered assertion,
+ * used by the assertion handler, then added to the assertion report.
+ * This is returned as a linked list from SDL_GetAssertionReport().
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_AssertData
 {
    SDL_bool always_ignore;
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@ -146,6 +146,13 @@ typedef Uint32 SDL_AudioDeviceID;
 #define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF)
 #define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE)

+/**
+ * Format specifier for audio data.
+ *
+ * \sa SDL_AudioFormat
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_AudioSpec
 {
    SDL_AudioFormat format;     /**< Audio data format */
@ -156,18 +163,30 @@ typedef struct SDL_AudioSpec
 /* Calculate the size of each audio frame (in bytes) */
 #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)

-/* SDL_AudioStream is an audio conversion interface.
-    - It can handle resampling data in chunks without generating
-      artifacts, when it doesn't have the complete buffer available.
-    - It can handle incoming data in any variable size.
-    - It can handle input/output format changes on the fly.
-    - You push data as you have it, and pull it when you need it
-    - It can also function as a basic audio data queue even if you
-      just have sound that needs to pass from one place to another.
-    - You can hook callbacks up to them when more data is added or
-      requested, to manage data on-the-fly.
+/**
+ * The opaque handle that represents an audio stream.
+ *
+ * SDL_AudioStream is an audio conversion interface.
+ *
+ * - It can handle resampling data in chunks without generating
+ *   artifacts, when it doesn't have the complete buffer available.
+ * - It can handle incoming data in any variable size.
+ * - It can handle input/output format changes on the fly.
+ * - You push data as you have it, and pull it when you need it
+ * - It can also function as a basic audio data queue even if you
+ *   just have sound that needs to pass from one place to another.
+ * - You can hook callbacks up to them when more data is added or
+ *   requested, to manage data on-the-fly.
+ *
+ * Audio streams are the core of the SDL3 audio interface. You create
+ * one or more of them, bind them to an opened audio device, and feed
+ * data to them (or for recording, consume data from them).
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateAudioStream
 */
-struct SDL_AudioStream;  /* this is opaque to the outside world. */
+struct SDL_AudioStream;  /**< this is opaque to the outside world. */
 typedef struct SDL_AudioStream SDL_AudioStream;


@ -903,7 +922,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
 extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);

 /**
- * Clear any pending data in the stream without converting it
+ * Clear any pending data in the stream without converting it.
 *
 * \param stream The audio stream to clear
 * \returns 0 on success or a negative error code on failure; call
@ -1090,7 +1109,7 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *strea


 /**
- * Free an audio stream
+ * Free an audio stream.
 *
 * \param stream The audio stream to free
 *
--- a/include/SDL3/SDL_blendmode.h
+++ b/include/SDL3/SDL_blendmode.h
@ -35,9 +35,15 @@ extern "C" {
 #endif

 /**
- *  The blend mode used in SDL_RenderTexture() and drawing operations.
+ * An enumeration of blend modes used in drawing operations.
+ *
+ * Note that additional values may be obtained from SDL_ComposeCustomBlendMode.
+ *
+ * \sa SDL_ComposeCustomBlendMode
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_BlendMode
 {
    SDL_BLENDMODE_NONE = 0x00000000,     /**< no blending
                                              dstRGBA = srcRGBA */
@ -60,9 +66,11 @@ typedef enum
 } SDL_BlendMode;

 /**
- *  The blend operation used when combining source and destination pixel components
+ * The blend operation used when combining source and destination pixel components.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_BlendOperation
 {
    SDL_BLENDOPERATION_ADD              = 0x1,  /**< dst + src: supported by all renderers */
    SDL_BLENDOPERATION_SUBTRACT         = 0x2,  /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */
@ -72,9 +80,16 @@ typedef enum
 } SDL_BlendOperation;

 /**
- *  The normalized factor used to multiply pixel components
+ * The normalized factor used to multiply pixel components.
+ *
+ * The blend factors are multiplied with the pixels from a drawing
+ * operation (src) and the pixels from the render target (dst) before
+ * the blend operation. The comma-separated factors listed above are always
+ * applied in the component order red, green, blue, and alpha.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_BlendFactor
 {
    SDL_BLENDFACTOR_ZERO                = 0x1,  /**< 0, 0, 0, 0 */
    SDL_BLENDFACTOR_ONE                 = 0x2,  /**< 1, 1, 1, 1 */
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@ -48,19 +48,23 @@ extern "C" {
 */
 typedef Uint32 SDL_CameraDeviceID;

-
 /**
- * The structure used to identify an opened SDL camera
+ * The opaque structure used to identify an opened SDL camera.
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 struct SDL_Camera;
 typedef struct SDL_Camera SDL_Camera;

 /**
- *  SDL_CameraSpec structure
+ * The details of an output format for a camera device.
+ *
+ * Cameras often support multiple formats; each one will be encapsulated in this struct.
 *
 * \sa SDL_GetCameraDeviceSupportedFormats
 * \sa SDL_GetCameraFormat
 *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_CameraSpec
 {
@ -75,6 +79,8 @@ typedef struct SDL_CameraSpec
 * The position of camera in relation to system device.
 *
 * \sa SDL_GetCameraDevicePosition
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
 typedef enum SDL_CameraPosition
 {
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@ -165,7 +165,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c
 typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);

 /**
- * Offer clipboard data to the OS
+ * Offer clipboard data to the OS.
 *
 * Tell the operating system that the application is offering clipboard data
 * for each of the proivded mime-types. Once another application requests the
@ -195,7 +195,7 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
 extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types);

 /**
- * Clear the clipboard data
+ * Clear the clipboard data.
 *
 * \returns 0 on success or a negative error code on failure; call
 *          SDL_GetError() for more information.
@ -207,7 +207,7 @@ extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callb
 extern DECLSPEC int SDLCALL SDL_ClearClipboardData(void);

 /**
- * Get the data from clipboard for a given mime type
+ * Get the data from clipboard for a given mime type.
 *
 * The size of text data does not include the terminator, but the text is
 * guaranteed to be null terminated.
@ -225,7 +225,7 @@ extern DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
 extern DECLSPEC void *SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);

 /**
- * Query whether there is data in the clipboard for the provided mime type
+ * Query whether there is data in the clipboard for the provided mime type.
 *
 * \param mime_type The mime type to check for data for
 * \returns SDL_TRUE if there exists data in clipboard for the provided mime
--- a/include/SDL3/SDL_dialog.h
+++ b/include/SDL3/SDL_dialog.h
@ -46,7 +46,7 @@ extern "C" {
 * \sa SDL_ShowSaveFileDialog
 * \sa SDL_ShowOpenFolderDialog
 */
-typedef struct
+typedef struct SDL_DialogFileFilter
 {
    const char *name;
    const char *pattern;
--- a/include/SDL3/SDL_error.h
+++ b/include/SDL3/SDL_error.h
@ -122,7 +122,7 @@ extern DECLSPEC void SDLCALL SDL_ClearError(void);
 #define SDL_OutOfMemory()   SDL_Error(SDL_ENOMEM)
 #define SDL_Unsupported()   SDL_Error(SDL_UNSUPPORTED)
 #define SDL_InvalidParamError(param)    SDL_SetError("Parameter '%s' is invalid", (param))
-typedef enum
+typedef enum SDL_errorcode
 {
    SDL_ENOMEM,
    SDL_EFREAD,
@ -133,7 +133,7 @@ typedef enum
 } SDL_errorcode;

 /**
- * SDL_Error()
+ * Set an SDL error from a list of error codes.
 *
 * \param code Error code
 * \returns unconditionally -1.
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@ -54,7 +54,7 @@ extern "C" {
 /**
 * The types of events that can be delivered.
 */
-typedef enum
+typedef enum SDL_EventType
 {
    SDL_EVENT_FIRST     = 0,     /**< Unused (do not remove) */

@ -671,10 +671,10 @@ typedef struct SDL_PenButtonEvent
 } SDL_PenButtonEvent;

 /**
- *  An event used to drop text or request a file open by the system (event.drop.*)
+ * An event used to drop text or request a file open by the system (event.drop.*)
 *
- *  The `data` is owned by SDL and should be copied if the application
- *  wants to hold onto it beyond the scope of handling this event.
+ * The `data` is owned by SDL and should be copied if the application
+ * wants to hold onto it beyond the scope of handling this event. Do not free it!
 */
 typedef struct SDL_DropEvent
 {
@ -722,7 +722,13 @@ typedef struct SDL_QuitEvent
 } SDL_QuitEvent;

 /**
- *  A user-defined event type (event.user.*)
+ * A user-defined event type (event.user.*)
+ *
+ * This event is unique; it is never created by SDL, but only by the
+ * application. The event can be pushed onto the event queue using
+ * SDL_PushEvent(). The contents of the structure members are completely
+ * up to the programmer; the only requirement is that '''type''' is a value
+ * obtained from SDL_RegisterEvents().
 */
 typedef struct SDL_UserEvent
 {
@ -737,7 +743,7 @@ typedef struct SDL_UserEvent


 /**
- *  General event structure
+ * The structure for all events in SDL.
 */
 typedef union SDL_Event
 {
@ -823,7 +829,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);

 /* @{ */
-typedef enum
+typedef enum SDL_eventaction
 {
    SDL_ADDEVENT,
    SDL_PEEKEVENT,
@ -1263,7 +1269,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type);
 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);

 /**
- * Allocate dynamic memory for an SDL event
+ * Allocate dynamic memory for an SDL event.
 *
 * You can use this to allocate memory for user events that will be
 * automatically freed after the event is processed.
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@ -162,11 +162,11 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
 * | TEMPLATES   | X       | X         |      | X          |       |            |
 * | VIDEOS      | X       | X*        |      | X          |       |            |
 *
- * * Note that on macOS/iOS, the Videos folder is called "Movies".
+ * Note that on macOS/iOS, the Videos folder is called "Movies".
 *
 * \sa SDL_GetUserFolder
 */
-typedef enum
+typedef enum SDL_Folder
 {
    /** The folder which contains all of the current user's data, preferences,
      and documents. It usually contains most of the other folders. If a
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@ -59,7 +59,7 @@ extern "C" {
 struct SDL_Gamepad;
 typedef struct SDL_Gamepad SDL_Gamepad;

-typedef enum
+typedef enum SDL_GamepadType
 {
    SDL_GAMEPAD_TYPE_UNKNOWN = 0,
    SDL_GAMEPAD_TYPE_STANDARD,
@ -95,7 +95,7 @@ typedef enum
 *
 *  You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
 */
-typedef enum
+typedef enum SDL_GamepadButton
 {
    SDL_GAMEPAD_BUTTON_INVALID = -1,
    SDL_GAMEPAD_BUTTON_SOUTH,           /* Bottom face button (e.g. Xbox A button) */
@ -134,7 +134,7 @@ typedef enum
 *
 *  For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
 */
-typedef enum
+typedef enum SDL_GamepadButtonLabel
 {
    SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN,
    SDL_GAMEPAD_BUTTON_LABEL_A,
@ -158,7 +158,7 @@ typedef enum
 *  (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
 *  same range that will be reported by the lower-level SDL_GetJoystickAxis().
 */
-typedef enum
+typedef enum SDL_GamepadAxis
 {
    SDL_GAMEPAD_AXIS_INVALID = -1,
    SDL_GAMEPAD_AXIS_LEFTX,
@ -170,7 +170,7 @@ typedef enum
    SDL_GAMEPAD_AXIS_MAX
 } SDL_GamepadAxis;

-typedef enum
+typedef enum SDL_GamepadBindingType
 {
    SDL_GAMEPAD_BINDTYPE_NONE = 0,
    SDL_GAMEPAD_BINDTYPE_BUTTON,
@ -886,7 +886,7 @@ extern DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *game
 extern DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);

 /**
- * Get the underlying joystick from a gamepad
+ * Get the underlying joystick from a gamepad.
 *
 * This function will give you a SDL_Joystick object, which allows you to use
 * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful
@ -935,7 +935,7 @@ extern DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled);
 extern DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);

 /**
- * Get the SDL joystick layer bindings for a gamepad
+ * Get the SDL joystick layer bindings for a gamepad.
 *
 * \param gamepad a gamepad
 * \param count a pointer filled in with the number of bindings returned
@ -1350,7 +1350,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint
 extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue);

 /**
- * Send a gamepad specific effect packet
+ * Send a gamepad specific effect packet.
 *
 * \param gamepad The gamepad to affect
 * \param data The data to send to the gamepad
--- a/include/SDL3/SDL_haptic.h
+++ b/include/SDL3/SDL_haptic.h
@ -25,18 +25,20 @@
 *  The SDL haptic subsystem manages haptic (force feedback) devices.
 *
 *  The basic usage is as follows:
- *   - Initialize the subsystem (::SDL_INIT_HAPTIC).
+ *
+ *   - Initialize the subsystem (SDL_INIT_HAPTIC).
 *   - Open a haptic device.
 *    - SDL_OpenHaptic() to open from index.
 *    - SDL_OpenHapticFromJoystick() to open from an existing joystick.
- *   - Create an effect (::SDL_HapticEffect).
+ *   - Create an effect (SDL_HapticEffect).
 *   - Upload the effect with SDL_CreateHapticEffect().
 *   - Run the effect with SDL_RunHapticEffect().
 *   - (optional) Free the effect with SDL_DestroyHapticEffect().
 *   - Close the haptic device with SDL_CloseHaptic().
 *
- * \par Simple rumble example:
- * \code
+ * Simple rumble example:
+ *
+ * ```c
 *    SDL_Haptic *haptic = NULL;
 *
 *    // Open the device
@ -59,10 +61,11 @@
 *
 *    // Clean up
 *    SDL_CloseHaptic(haptic);
- * \endcode
+ * ```
 *
- * \par Complete example:
- * \code
+ * Complete example:
+ *
+ * ```c
 * int test_haptic(SDL_Joystick *joystick)
 * {
 *    SDL_Haptic *haptic;
@ -105,7 +108,7 @@
 *
 *    return 0; // Success
 * }
- * \endcode
+ * ```
 *
 * Note that the SDL haptic subsystem is not thread-safe.
 */
@ -386,52 +389,56 @@ typedef struct SDL_Haptic SDL_Haptic;
 *  instead of the direction in which the force is exerted.
 *
 *  Directions can be specified by:
- *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
- *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
- *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
+ *
+ *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
+ *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
+ *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
 *
 *  Cardinal directions of the haptic device are relative to the positioning
 *  of the device.  North is considered to be away from the user.
 *
 *  The following diagram represents the cardinal directions:
- *  \verbatim
-                 .--.
-                 |__| .-------.
-                 |=.| |.-----.|
-                 |--| ||     ||
-                 |  | |'-----'|
-                 |__|~')_____('
-                   [ COMPUTER ]
-
-
-                     North (0,-1)
-                         ^
-                         |
-                         |
-   (-1,0)  West <----[ HAPTIC ]----> East (1,0)
-                         |
-                         |
-                         v
-                      South (0,1)
-
-
-                      [ USER ]
-                        \|||/
-                        (o o)
-                  ---ooO-(_)-Ooo---
-    \endverbatim
 *
- *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
- *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
- *  the first \c dir parameter.  The cardinal directions would be:
+ *  ```
+ *                .--.
+ *                |__| .-------.
+ *                |=.| |.-----.|
+ *                |--| ||     ||
+ *                |  | |'-----'|
+ *                |__|~')_____('
+ *                  [ COMPUTER ]
+ *
+ *
+ *                    North (0,-1)
+ *                        ^
+ *                        |
+ *                        |
+ *  (-1,0)  West <----[ HAPTIC ]----> East (1,0)
+ *                        |
+ *                        |
+ *                        v
+ *                     South (0,1)
+ *
+ *
+ *                     [ USER ]
+ *                       \|||/
+ *                       (o o)
+ *                 ---ooO-(_)-Ooo---
+ *  ```
+ *
+ *  If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
+ *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
+ *  the first `dir` parameter.  The cardinal directions would be:
+ *
 *   - North: 0 (0 degrees)
 *   - East: 9000 (90 degrees)
 *   - South: 18000 (180 degrees)
 *   - West: 27000 (270 degrees)
 *
- *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
- *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
- *  the first three \c dir parameters.  The cardinal directions would be:
+ *  If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
+ *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
+ *  the first three `dir` parameters.  The cardinal directions would be:
+ *
 *   - North:  0,-1, 0
 *   - East:   1, 0, 0
 *   - South:  0, 1, 0
@ -441,16 +448,17 @@ typedef struct SDL_Haptic SDL_Haptic;
 *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
 *  can use any multiple you want, only the direction matters.
 *
- *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
- *  The first two \c dir parameters are used.  The \c dir parameters are as
+ *  If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
+ *  The first two `dir` parameters are used.  The `dir` parameters are as
 *  follows (all values are in hundredths of degrees):
+ *
 *   - Degrees from (1, 0) rotated towards (0, 1).
 *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
 *
- *
 *  Example of force coming from the south with all encodings (force coming
 *  from the south means the user will have to pull the stick to counteract):
- *  \code
+ *
+ *  ```c
 *  SDL_HapticDirection direction;
 *
 *  // Cartesian directions
@ -466,7 +474,7 @@ typedef struct SDL_Haptic SDL_Haptic;
 *  // Spherical coordinates
 *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
 *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
- *  \endcode
+ *  ```
 *
 *  \sa SDL_HAPTIC_POLAR
 *  \sa SDL_HAPTIC_CARTESIAN
@ -485,7 +493,7 @@ typedef struct SDL_HapticDirection
 /**
 *  A structure containing a template for a Constant effect.
 *
- *  This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect.
+ *  This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
 *
 *  A constant effect applies a constant force in the specified direction
 *  to the joystick.
@ -496,7 +504,7 @@ typedef struct SDL_HapticDirection
 typedef struct SDL_HapticConstant
 {
    /* Header */
-    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
+    Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */
@ -521,11 +529,12 @@ typedef struct SDL_HapticConstant
 *  A structure containing a template for a Periodic effect.
 *
 *  The struct handles the following effects:
- *   - ::SDL_HAPTIC_SINE
- *   - ::SDL_HAPTIC_SQUARE
- *   - ::SDL_HAPTIC_TRIANGLE
- *   - ::SDL_HAPTIC_SAWTOOTHUP
- *   - ::SDL_HAPTIC_SAWTOOTHDOWN
+ *
+ *   - SDL_HAPTIC_SINE
+ *   - SDL_HAPTIC_SQUARE
+ *   - SDL_HAPTIC_TRIANGLE
+ *   - SDL_HAPTIC_SAWTOOTHUP
+ *   - SDL_HAPTIC_SAWTOOTHDOWN
 *
 *  A periodic effect consists in a wave-shaped effect that repeats itself
 *  over time.  The type determines the shape of the wave and the parameters
@ -533,6 +542,7 @@ typedef struct SDL_HapticConstant
 *
 *  Phase is given by hundredth of a degree meaning that giving the phase a value
 *  of 9000 will displace it 25% of its period.  Here are sample values:
+ *
 *   -     0: No phase displacement.
 *   -  9000: Displaced 25% of its period.
 *   - 18000: Displaced 50% of its period.
@ -540,32 +550,33 @@ typedef struct SDL_HapticConstant
 *   - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
 *
 *  Examples:
- *  \verbatim
-    SDL_HAPTIC_SINE
-      __      __      __      __
-     /  \    /  \    /  \    /
-    /    \__/    \__/    \__/
-
-    SDL_HAPTIC_SQUARE
-     __    __    __    __    __
-    |  |  |  |  |  |  |  |  |  |
-    |  |__|  |__|  |__|  |__|  |
-
-    SDL_HAPTIC_TRIANGLE
-      /\    /\    /\    /\    /\
-     /  \  /  \  /  \  /  \  /
-    /    \/    \/    \/    \/
-
-    SDL_HAPTIC_SAWTOOTHUP
-      /|  /|  /|  /|  /|  /|  /|
-     / | / | / | / | / | / | / |
-    /  |/  |/  |/  |/  |/  |/  |
-
-    SDL_HAPTIC_SAWTOOTHDOWN
-    \  |\  |\  |\  |\  |\  |\  |
-     \ | \ | \ | \ | \ | \ | \ |
-      \|  \|  \|  \|  \|  \|  \|
-    \endverbatim
+ *
+ *  ```
+ *   SDL_HAPTIC_SINE
+ *     __      __      __      __
+ *    /  \    /  \    /  \    /
+ *   /    \__/    \__/    \__/
+ *
+ *   SDL_HAPTIC_SQUARE
+ *    __    __    __    __    __
+ *   |  |  |  |  |  |  |  |  |  |
+ *   |  |__|  |__|  |__|  |__|  |
+ *
+ *   SDL_HAPTIC_TRIANGLE
+ *     /\    /\    /\    /\    /\
+ *    /  \  /  \  /  \  /  \  /
+ *   /    \/    \/    \/    \/
+ *
+ *   SDL_HAPTIC_SAWTOOTHUP
+ *     /|  /|  /|  /|  /|  /|  /|
+ *    / | / | / | / | / | / | / |
+ *   /  |/  |/  |/  |/  |/  |/  |
+ *
+ *   SDL_HAPTIC_SAWTOOTHDOWN
+ *   \  |\  |\  |\  |\  |\  |\  |
+ *    \ | \ | \ | \ | \ | \ | \ |
+ *     \|  \|  \|  \|  \|  \|  \|
+ *   ```
 *
 *  \sa SDL_HAPTIC_SINE
 *  \sa SDL_HAPTIC_SQUARE
@ -577,9 +588,9 @@ typedef struct SDL_HapticConstant
 typedef struct SDL_HapticPeriodic
 {
    /* Header */
-    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE
-                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
-                             ::SDL_HAPTIC_SAWTOOTHDOWN */
+    Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE
+                             SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
+                             SDL_HAPTIC_SAWTOOTHDOWN */
    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */
@ -607,17 +618,18 @@ typedef struct SDL_HapticPeriodic
 *  A structure containing a template for a Condition effect.
 *
 *  The struct handles the following effects:
- *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
- *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
- *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
- *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
+ *
+ *   - SDL_HAPTIC_SPRING: Effect based on axes position.
+ *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
+ *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
+ *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
 *
 *  Direction is handled by condition internals instead of a direction member.
 *  The condition effect specific members have three parameters.  The first
 *  refers to the X axis, the second refers to the Y axis and the third
 *  refers to the Z axis.  The right terms refer to the positive side of the
 *  axis and the left terms refer to the negative side of the axis.  Please
- *  refer to the ::SDL_HapticDirection diagram for which side is positive and
+ *  refer to the SDL_HapticDirection diagram for which side is positive and
 *  which is negative.
 *
 *  \sa SDL_HapticDirection
@ -630,8 +642,8 @@ typedef struct SDL_HapticPeriodic
 typedef struct SDL_HapticCondition
 {
    /* Header */
-    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
-                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
+    Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
+                                 SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
    SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */

    /* Replay */
@ -654,7 +666,7 @@ typedef struct SDL_HapticCondition
 /**
 *  A structure containing a template for a Ramp effect.
 *
- *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
+ *  This struct is exclusively for the SDL_HAPTIC_RAMP effect.
 *
 *  The ramp effect starts at start strength and ends at end strength.
 *  It augments in linear fashion.  If you use attack and fade with a ramp
@ -667,7 +679,7 @@ typedef struct SDL_HapticCondition
 typedef struct SDL_HapticRamp
 {
    /* Header */
-    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
+    Uint16 type;            /**< SDL_HAPTIC_RAMP */
    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */
@ -692,7 +704,7 @@ typedef struct SDL_HapticRamp
 /**
 * A structure containing a template for a Left/Right effect.
 *
- * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
+ * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect.
 *
 * The Left/Right effect is used to explicitly control the large and small
 * motors, commonly found in modern game controllers. The small (right) motor
@ -704,7 +716,7 @@ typedef struct SDL_HapticRamp
 typedef struct SDL_HapticLeftRight
 {
    /* Header */
-    Uint16 type;            /**< ::SDL_HAPTIC_LEFTRIGHT */
+    Uint16 type;            /**< SDL_HAPTIC_LEFTRIGHT */

    /* Replay */
    Uint32 length;          /**< Duration of the effect in milliseconds. */
@ -715,9 +727,9 @@ typedef struct SDL_HapticLeftRight
 } SDL_HapticLeftRight;

 /**
- *  A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
+ *  A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
 *
- *  This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect.
+ *  This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
 *
 *  A custom force feedback effect is much like a periodic effect, where the
 *  application can define its exact shape.  You will have to allocate the
@ -732,7 +744,7 @@ typedef struct SDL_HapticLeftRight
 typedef struct SDL_HapticCustom
 {
    /* Header */
-    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
+    Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */
@ -762,12 +774,12 @@ typedef struct SDL_HapticCustom
 *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
 *  Time values unless specified otherwise are in milliseconds.
 *
- *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767
+ *  You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767
 *  value.  Neither delay, interval, attack_length nor fade_length support
- *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
+ *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
 *
- *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
- *  ::SDL_HAPTIC_INFINITY.
+ *  Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
+ *  SDL_HAPTIC_INFINITY.
 *
 *  Button triggers may not be supported on all devices, it is advised to not
 *  use them if possible.  Buttons start at index 1 instead of index 0 like
@ -777,7 +789,8 @@ typedef struct SDL_HapticCustom
 *  otherwise both values are used.
 *
 *  Common parts:
- *  \code
+ *
+ *  ```c
 *  // Replay - All effects have this
 *  Uint32 length;        // Duration of effect (ms).
 *  Uint16 delay;         // Delay before starting effect.
@ -791,29 +804,29 @@ typedef struct SDL_HapticCustom
 *  Uint16 attack_level;  // Level at the start of the attack.
 *  Uint16 fade_length;   // Duration of the fade out (ms).
 *  Uint16 fade_level;    // Level at the end of the fade.
- *  \endcode
- *
+ *  ```
 *
 *  Here we have an example of a constant effect evolution in time:
- *  \verbatim
-    Strength
-    ^
-    |
-    |    effect level -->  _________________
-    |                     /                 \
-    |                    /                   \
-    |                   /                     \
-    |                  /                       \
-    | attack_level --> |                        \
-    |                  |                        |  <---  fade_level
-    |
-    +--------------------------------------------------> Time
-                       [--]                 [---]
-                       attack_length        fade_length
-
-    [------------------][-----------------------]
-    delay               length
-    \endverbatim
+ *
+ *  ```
+ *  Strength
+ *  ^
+ *  |
+ *  |    effect level -->  _________________
+ *  |                     /                 \
+ *  |                    /                   \
+ *  |                   /                     \
+ *  |                  /                       \
+ *  | attack_level --> |                        \
+ *  |                  |                        |  <---  fade_level
+ *  |
+ *  +--------------------------------------------------> Time
+ *                     [--]                 [---]
+ *                     attack_length        fade_length
+ *
+ *  [------------------][-----------------------]
+ *  delay               length
+ *  ```
 *
 *  Note either the attack_level or the fade_level may be above the actual
 *  effect level.
@ -1058,7 +1071,6 @@ extern DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *haptic);
 */
 extern DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic);

-
 /**
 * Get the number of haptic axes the device has.
 *
@ -1153,8 +1165,6 @@ extern DECLSPEC int SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect,
 /**
 * Stop the haptic effect on its associated haptic device.
 *
- * *
- *
 * \param haptic the SDL_Haptic device to stop the effect on
 * \param effect the ID of the haptic effect to stop
 * \returns 0 on success or a negative error code on failure; call
--- a/include/SDL3/SDL_hidapi.h
+++ b/include/SDL3/SDL_hidapi.h
@ -74,13 +74,13 @@ extern "C" {
 /**
 *  A handle representing an open HID device
 */
-struct SDL_hid_device_;
-typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
+struct SDL_hid_device;
+typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */

 /**
 *  HID underlying bus types.
 */
-typedef enum {
+typedef enum SDL_hid_bus_type {
    /** Unknown bus type */
    SDL_HID_API_BUS_UNKNOWN = 0x00,

@ -243,7 +243,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
 extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id);

 /**
- * Free an enumeration Linked List
+ * Free an enumeration linked list.
 *
 * This function frees a linked list created by SDL_hid_enumerate().
 *
@ -534,7 +534,7 @@ extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_de
 extern DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size);

 /**
- * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers
+ * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
 *
 * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan
 *
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
--- a/include/SDL3/SDL_init.h
+++ b/include/SDL3/SDL_init.h
@ -51,7 +51,7 @@ extern "C" {
 * \sa SDL_QuitSubSystem
 * \sa SDL_WasInit
 */
-typedef enum
+typedef enum SDL_InitFlags
 {
    SDL_INIT_TIMER        = 0x00000001,
    SDL_INIT_AUDIO        = 0x00000010,  /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */
--- a/include/SDL3/SDL_iostream.h
+++ b/include/SDL3/SDL_iostream.h
@ -53,6 +53,17 @@ typedef enum SDL_IOStatus
    SDL_IO_STATUS_WRITEONLY  /**< Tried to read a write-only buffer */
 } SDL_IOStatus;

+/**
+ * The function pointers that drive an SDL_IOStream.
+ *
+ * Applications can provide this struct to SDL_OpenIO() to
+ * create their own implementation of SDL_IOStream. This is
+ * not necessarily required, as SDL already offers several
+ * common types of I/O streams, via functions like SDL_IOFromFile()
+ * and SDL_IOFromMem().
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
 typedef struct SDL_IOStreamInterface
 {
    /**
@ -107,7 +118,14 @@ typedef struct SDL_IOStreamInterface


 /**
- * This is the read/write operation structure -- opaque, as of SDL3!
+ * The read/write operation structure.
+ *
+ * This operates as an opaque handle. There are several APIs to create
+ * various types of I/O streams, or an app can supply an
+ * SDL_IOStreamInterface to SDL_OpenIO() to provide their own stream
+ * implementation behind this struct's abstract interface.
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_IOStream SDL_IOStream;

@ -305,6 +323,9 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
 *
 * You must free the returned pointer with SDL_CloseIO().
 *
+ * This function makes a copy of `iface` and the caller does not need to
+ * keep this data around after this call.
+ *
 * \param iface The function pointers that implement this SDL_IOStream.
 * \param userdata The app-controlled pointer that is passed to iface's
 *                 functions when called.
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@ -118,7 +118,7 @@ typedef enum
 /* Function prototypes */

 /**
- * Locking for atomic access to the joystick API
+ * Locking for atomic access to the joystick API.
 *
 * The SDL joystick functions are thread-safe, however you can lock the
 * joysticks while processing to guarantee that the joystick list won't change
@ -129,7 +129,7 @@ typedef enum
 extern DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock);

 /**
- * Unlocking for atomic access to the joystick API
+ * Unlocking for atomic access to the joystick API.
 *
 * \since This function is available since SDL 3.0.0.
 */
@ -388,7 +388,7 @@ typedef struct SDL_VirtualJoystickDesc
 } SDL_VirtualJoystickDesc;

 /**
- * The current version of the SDL_VirtualJoystickDesc structure
+ * The current version of the SDL_VirtualJoystickDesc structure.
 */
 #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION   1

@ -714,7 +714,7 @@ extern DECLSPEC int SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, cha
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUIDFromString(const char *pchGUID);

 /**
- * Get the device information encoded in a SDL_JoystickGUID structure
+ * Get the device information encoded in a SDL_JoystickGUID structure.
 *
 * \param guid the SDL_JoystickGUID you wish to get info about
 * \param vendor A pointer filled in with the device VID, or 0 if not
@ -1007,7 +1007,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int
 extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);

 /**
- * Start a rumble effect in the joystick's triggers
+ * Start a rumble effect in the joystick's triggers.
 *
 * Each call to this function cancels any previous trigger rumble effect, and
 * calling it with 0 intensity stops any rumbling.
@ -1056,7 +1056,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U
 extern DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);

 /**
- * Send a joystick specific effect packet
+ * Send a joystick specific effect packet.
 *
 * \param joystick The joystick to affect
 * \param data The data to send to the joystick
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@ -44,7 +44,7 @@ typedef Uint32 SDL_KeyboardID;
 /**
 *  The SDL keysym structure, used in key events.
 *
- *  \note  If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event.
+ *  If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event.
 */
 typedef struct SDL_Keysym
 {
@ -143,7 +143,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);

 /**
- * Clear the state of the keyboard
+ * Clear the state of the keyboard.
 *
 * This function will generate key up events for all pressed keys.
 *
--- a/include/SDL3/SDL_keycode.h
+++ b/include/SDL3/SDL_keycode.h
@ -47,7 +47,15 @@ typedef Sint32 SDL_Keycode;
 #define SDLK_SCANCODE_MASK (1<<30)
 #define SDL_SCANCODE_TO_KEYCODE(X)  (X | SDLK_SCANCODE_MASK)

-typedef enum
+/**
+ * Possible SDL virtual key values.
+ *
+ * Values from this enum are used to represent keyboard keys using the current
+ * layout of the keyboard.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_KeyCode
 {
    SDLK_UNKNOWN = 0,

@ -328,27 +336,29 @@ typedef enum

 /**
 * Enumeration of valid key mods (possibly OR'd together).
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_Keymod
 {
-    SDL_KMOD_NONE = 0x0000,
-    SDL_KMOD_LSHIFT = 0x0001,
-    SDL_KMOD_RSHIFT = 0x0002,
-    SDL_KMOD_LCTRL = 0x0040,
-    SDL_KMOD_RCTRL = 0x0080,
-    SDL_KMOD_LALT = 0x0100,
-    SDL_KMOD_RALT = 0x0200,
-    SDL_KMOD_LGUI = 0x0400,
-    SDL_KMOD_RGUI = 0x0800,
-    SDL_KMOD_NUM = 0x1000,
-    SDL_KMOD_CAPS = 0x2000,
-    SDL_KMOD_MODE = 0x4000,
-    SDL_KMOD_SCROLL = 0x8000,
+    SDL_KMOD_NONE = 0x0000,    /**< no modifier is applicable. */
+    SDL_KMOD_LSHIFT = 0x0001,  /**< the left Shift key is down. */
+    SDL_KMOD_RSHIFT = 0x0002,  /**< the right Shift key is down. */
+    SDL_KMOD_LCTRL = 0x0040,   /**< the left Ctrl (Control) key is down. */
+    SDL_KMOD_RCTRL = 0x0080,   /**< the right Ctrl (Control) key is down. */
+    SDL_KMOD_LALT = 0x0100,    /**< the left Alt key is down. */
+    SDL_KMOD_RALT = 0x0200,    /**< the right Alt key is down. */
+    SDL_KMOD_LGUI = 0x0400,    /**< the left GUI key (often the Windows key) is down. */
+    SDL_KMOD_RGUI = 0x0800,    /**< the right GUI key (often the Windows key) is down. */
+    SDL_KMOD_NUM = 0x1000,     /**< the Num Lock key (may be located on an extended keypad) is down. */
+    SDL_KMOD_CAPS = 0x2000,    /**< the Caps Lock key is down. */
+    SDL_KMOD_MODE = 0x4000,    /**< the !AltGr key is down. */
+    SDL_KMOD_SCROLL = 0x8000,  /**< the Scoll Lock key is down. */

-    SDL_KMOD_CTRL = SDL_KMOD_LCTRL | SDL_KMOD_RCTRL,
-    SDL_KMOD_SHIFT = SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT,
-    SDL_KMOD_ALT = SDL_KMOD_LALT | SDL_KMOD_RALT,
-    SDL_KMOD_GUI = SDL_KMOD_LGUI | SDL_KMOD_RGUI,
+    SDL_KMOD_CTRL = SDL_KMOD_LCTRL | SDL_KMOD_RCTRL,    /**< Any Ctrl key is down. */
+    SDL_KMOD_SHIFT = SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT, /**< Any Shift key is down. */
+    SDL_KMOD_ALT = SDL_KMOD_LALT | SDL_KMOD_RALT,       /**< Any Alt key is down. */
+    SDL_KMOD_GUI = SDL_KMOD_LGUI | SDL_KMOD_RGUI,       /**< Any GUI key is down. */

    SDL_KMOD_RESERVED = SDL_KMOD_SCROLL /* This is for source-level compatibility with SDL 2.0.0. */
 } SDL_Keymod;
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@ -39,7 +39,18 @@ extern "C" {
 /* *INDENT-ON* */
 #endif

-
+/**
+ * A struct to provide locale data.
+ *
+ * Locale data is split into a spoken language, like English, and an
+ * optional country, like Canada. The language will be in ISO-639 format
+ * (so English would be "en"), and the country, if not NULL, will be an
+ * ISO-3166 country code (so Canada would be "CA").
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetPreferredLocales
+ */
 typedef struct SDL_Locale
 {
    const char *language;  /**< A language name, like "en" for English. */
--- a/include/SDL3/SDL_log.h
+++ b/include/SDL3/SDL_log.h
@ -47,7 +47,7 @@ extern "C" {


 /**
- *  The maximum size of a log message prior to SDL 2.0.24
+ *  The maximum size of a log message prior to SDL 2.0.24.
 *
 *  As of 2.0.24 there is no limit to the length of SDL log messages.
 */
@ -61,7 +61,7 @@ extern "C" {
 *  at the VERBOSE level and all other categories are enabled at the
 *  ERROR level.
 */
-typedef enum
+typedef enum SDL_LogCategory
 {
    SDL_LOG_CATEGORY_APPLICATION,
    SDL_LOG_CATEGORY_ERROR,
@ -99,7 +99,7 @@ typedef enum
 /**
 *  The predefined log priorities
 */
-typedef enum
+typedef enum SDL_LogPriority
 {
    SDL_LOG_PRIORITY_VERBOSE = 1,
    SDL_LOG_PRIORITY_DEBUG,
--- a/include/SDL3/SDL_messagebox.h
+++ b/include/SDL3/SDL_messagebox.h
@ -35,7 +35,7 @@ extern "C" {
 /**
 * SDL_MessageBox flags. If supported will display warning icon, etc.
 */
-typedef enum
+typedef enum SDL_MessageBoxFlags
 {
    SDL_MESSAGEBOX_ERROR                 = 0x00000010,   /**< error dialog */
    SDL_MESSAGEBOX_WARNING               = 0x00000020,   /**< warning dialog */
@ -47,7 +47,7 @@ typedef enum
 /**
 * Flags for SDL_MessageBoxButtonData.
 */
-typedef enum
+typedef enum SDL_MessageBoxButtonFlags
 {
    SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001,  /**< Marks the default button when return is hit */
    SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002   /**< Marks the default button when escape is hit */
@ -56,7 +56,7 @@ typedef enum
 /**
 * Individual button data.
 */
-typedef struct
+typedef struct SDL_MessageBoxButtonData
 {
    Uint32 flags;       /**< ::SDL_MessageBoxButtonFlags */
    int buttonID;       /**< User defined button id (value returned via SDL_ShowMessageBox) */
@ -66,12 +66,12 @@ typedef struct
 /**
 * RGB value used in a message box color scheme
 */
-typedef struct
+typedef struct SDL_MessageBoxColor
 {
    Uint8 r, g, b;
 } SDL_MessageBoxColor;

-typedef enum
+typedef enum SDL_MessageBoxColorType
 {
    SDL_MESSAGEBOX_COLOR_BACKGROUND,
    SDL_MESSAGEBOX_COLOR_TEXT,
@ -84,7 +84,7 @@ typedef enum
 /**
 * A set of colors to use for message box dialogs
 */
-typedef struct
+typedef struct SDL_MessageBoxColorScheme
 {
    SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX];
 } SDL_MessageBoxColorScheme;
@ -92,7 +92,7 @@ typedef struct
 /**
 * MessageBox structure containing title, text, window, etc.
 */
-typedef struct
+typedef struct SDL_MessageBoxData
 {
    Uint32 flags;                       /**< ::SDL_MessageBoxFlags */
    SDL_Window *window;                 /**< Parent window, can be NULL */
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@ -45,7 +45,7 @@ typedef struct SDL_Cursor SDL_Cursor;   /**< Implementation dependent */
 /**
 * Cursor types for SDL_CreateSystemCursor().
 */
-typedef enum
+typedef enum SDL_SystemCursor
 {
    SDL_SYSTEM_CURSOR_ARROW,     /**< Arrow */
    SDL_SYSTEM_CURSOR_IBEAM,     /**< I-beam */
@ -73,7 +73,7 @@ typedef enum
 /**
 * Scroll direction types for the Scroll event
 */
-typedef enum
+typedef enum SDL_MouseWheelDirection
 {
    SDL_MOUSEWHEEL_NORMAL,    /**< The scroll direction is normal */
    SDL_MOUSEWHEEL_FLIPPED    /**< The scroll direction is flipped / natural */
--- a/include/SDL3/SDL_pen.h
+++ b/include/SDL3/SDL_pen.h
@ -28,18 +28,18 @@
 *    and drawing tablets or suitably equipped mobile / tablet devices.
 *
 *  To get started with pens:
- *  - Listen to ::SDL_PenMotionEvent and ::SDL_PenButtonEvent
- *  - To avoid treating pen events as mouse events, ignore  ::SDL_MouseMotionEvent and ::SDL_MouseButtonEvent
- *    whenever "which" == ::SDL_PEN_MOUSEID.
+ *  - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
+ *  - To avoid treating pen events as mouse events, ignore  SDL_MouseMotionEvent and SDL_MouseButtonEvent
+ *    whenever "which" == SDL_PEN_MOUSEID.
 *
 *  This header file describes advanced functionality that can be useful for managing user configuration
 *    and understanding the capabilities of the attached pens.
 *
- *  We primarily identify pens by ::SDL_PenID.  The implementation makes a best effort to relate each :SDL_PenID
- *    to the same physical device during a session.  Formerly valid ::SDL_PenID values remain valid
+ *  We primarily identify pens by SDL_PenID.  The implementation makes a best effort to relate each :SDL_PenID
+ *    to the same physical device during a session.  Formerly valid SDL_PenID values remain valid
 *    even if a device disappears.
 *
- *  For identifying pens across sessions, the API provides the type ::SDL_GUID .
+ *  For identifying pens across sessions, the API provides the type SDL_GUID .
 */

 #ifndef SDL_pen_h_
@ -57,7 +57,7 @@ extern "C" {

 typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */

-#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid ::SDL_PenID is valid */
+#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid SDL_PenID is valid */

 #define SDL_PEN_MOUSEID ((SDL_MouseID)-2) /**< Device ID for mouse events triggered by pen events */

@ -66,16 +66,20 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio
 /**
 * Pen axis indices
 *
- * Below are the valid indices to the "axis" array from ::SDL_PenMotionEvent and ::SDL_PenButtonEvent.
- * The axis indices form a contiguous range of ints from 0 to ::SDL_PEN_AXIS_LAST, inclusive.
+ * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and SDL_PenButtonEvent.
+ * The axis indices form a contiguous range of ints from 0 to SDL_PEN_AXIS_LAST, inclusive.
 * All "axis[]" entries are either normalised to  0..1 or report a (positive or negative)
 * angle in degrees, with 0.0 representing the centre.
 * Not all pens/backends support all axes: unsupported entries are always "0.0f".
 *
 * To convert angles for tilt and rotation into vector representation, use
- * SDL_sinf on the XTILT, YTILT, or ROTATION component, e.g., "SDL_sinf(xtilt * SDL_PI_F / 180.0)".
+ * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
+ *
+ * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`.
+ *
+ * \since This enum is available since SDL 3.0.0
 */
-typedef enum
+typedef enum SDL_PenAxis
 {
    SDL_PEN_AXIS_PRESSURE = 0,               /**< Pen pressure.  Unidirectional: 0..1.0 */
    SDL_PEN_AXIS_XTILT,                      /**< Pen horizontal tilt angle.  Bidirectional: -90.0..90.0 (left-to-right).
@ -89,7 +93,7 @@ typedef enum
    SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
 } SDL_PenAxis;

-/* Pen flags.  These share a bitmask space with ::SDL_BUTTON_LEFT and friends. */
+/* Pen flags.  These share a bitmask space with SDL_BUTTON_LEFT and friends. */
 #define SDL_PEN_FLAG_DOWN_BIT_INDEX   13 /* Bit for storing that pen is touching the surface */
 #define SDL_PEN_FLAG_INK_BIT_INDEX    14 /* Bit for storing has-non-eraser-capability status */
 #define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */
@ -98,41 +102,31 @@ typedef enum
 #define SDL_PEN_CAPABILITY(capbit)    (1ul << (capbit))
 #define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)

-/**
- * Pen tips
- * @{
- */
+/* Pen tips */
 #define SDL_PEN_TIP_INK    SDL_PEN_FLAG_INK_BIT_INDEX     /**< Regular pen tip (for drawing) touched the surface */
 #define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX  /**< Eraser pen tip touched the surface */
-/** @} */

-
-/**
- * \defgroup SDL_PEN_CAPABILITIES Pen capabilities
- * Pen capabilities reported by ::SDL_GetPenCapabilities
- * @{
- */
+/* Pen capabilities reported by SDL_GetPenCapabilities */
 #define SDL_PEN_DOWN_MASK          SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX)   /**< Pen tip is currently touching the drawing surface. */
-#define SDL_PEN_INK_MASK           SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX)    /**< Pen has a regular drawing tip (::SDL_GetPenCapabilities).  For events (::SDL_PenButtonEvent, ::SDL_PenMotionEvent, ::SDL_GetPenStatus) this flag is mutually exclusive with ::SDL_PEN_ERASER_MASK .  */
-#define SDL_PEN_ERASER_MASK        SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (::SDL_GetPenCapabilities) or is being used as eraser (::SDL_PenButtonEvent , ::SDL_PenMotionEvent , ::SDL_GetPenStatus)  */
-#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE)    /**< Pen provides pressure information in axis ::SDL_PEN_AXIS_PRESSURE */
-#define SDL_PEN_AXIS_XTILT_MASK    SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT)       /**< Pen provides horizontal tilt information in axis ::SDL_PEN_AXIS_XTILT */
-#define SDL_PEN_AXIS_YTILT_MASK    SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT)       /**< Pen provides vertical tilt information in axis ::SDL_PEN_AXIS_YTILT */
-#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE)    /**< Pen provides distance to drawing tablet in ::SDL_PEN_AXIS_DISTANCE */
-#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION)    /**< Pen provides barrel rotation information in axis ::SDL_PEN_AXIS_ROTATION */
-#define SDL_PEN_AXIS_SLIDER_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER)      /**< Pen provides slider / finger wheel or similar in axis ::SDL_PEN_AXIS_SLIDER */
+#define SDL_PEN_INK_MASK           SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX)    /**< Pen has a regular drawing tip (SDL_GetPenCapabilities).  For events (SDL_PenButtonEvent, SDL_PenMotionEvent, SDL_GetPenStatus) this flag is mutually exclusive with SDL_PEN_ERASER_MASK .  */
+#define SDL_PEN_ERASER_MASK        SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (SDL_GetPenCapabilities) or is being used as eraser (SDL_PenButtonEvent , SDL_PenMotionEvent , SDL_GetPenStatus)  */
+#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE)    /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */
+#define SDL_PEN_AXIS_XTILT_MASK    SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT)       /**< Pen provides horizontal tilt information in axis SDL_PEN_AXIS_XTILT */
+#define SDL_PEN_AXIS_YTILT_MASK    SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT)       /**< Pen provides vertical tilt information in axis SDL_PEN_AXIS_YTILT */
+#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE)    /**< Pen provides distance to drawing tablet in SDL_PEN_AXIS_DISTANCE */
+#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION)    /**< Pen provides barrel rotation information in axis SDL_PEN_AXIS_ROTATION */
+#define SDL_PEN_AXIS_SLIDER_MASK   SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER)      /**< Pen provides slider / finger wheel or similar in axis SDL_PEN_AXIS_SLIDER */

 #define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
-/**< Masks for all axes that may be bidirectional */
-/** @} */

 /**
 * Pen types
 *
 * Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
 *
+ * \since This enum is available since SDL 3.0.0
 */
-typedef enum
+typedef enum SDL_PenSubtype
 {
    SDL_PEN_TYPE_UNKNOWN = 0,
    SDL_PEN_TYPE_ERASER = 1,                  /**< Eraser */
@ -149,15 +143,15 @@ typedef enum
 /**
 * Retrieves all pens that are connected to the system.
 *
- * Yields an array of ::SDL_PenID values. These identify and track pens
+ * Yields an array of SDL_PenID values. These identify and track pens
 * throughout a session. To track pens across sessions (program restart), use
- * ::SDL_GUID .
+ * SDL_GUID .
 *
 * \param count The number of pens in the array (number of array elements
 *              minus 1, i.e., not counting the terminator 0).
- * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
- *          array must be freed with ::SDL_free(). On a NULL return,
- *          ::SDL_GetError() is set.
+ * \returns A 0 terminated array of SDL_PenID values, or NULL on error. The
+ *          array must be freed with SDL_free(). On a NULL return,
+ *          SDL_GetError() is set.
 *
 * \since This function is available since SDL 3.0.0
 */
@ -166,29 +160,29 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
 /**
 * Retrieves the pen's current status.
 *
- * If the pen is detached (cf. ::SDL_PenConnected), this operation may return
+ * If the pen is detached (cf. SDL_PenConnected), this operation may return
 * default values.
 *
 * \param instance_id The pen to query.
 * \param x Out-mode parameter for pen x coordinate. May be NULL.
 * \param y Out-mode parameter for pen y coordinate. May be NULL.
 * \param axes Out-mode parameter for axis information. May be null. The axes
- *             are in the same order as ::SDL_PenAxis.
+ *             are in the same order as SDL_PenAxis.
 * \param num_axes Maximum number of axes to write to "axes".
- * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
- *          etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
- *          ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
- *          ::SDL_GetError()).
+ * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
+ *          etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
+ *          SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
+ *          SDL_GetError()).
 *
 * \since This function is available since SDL 3.0.0
 */
 extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);

 /**
- * Retrieves an ::SDL_PenID for the given ::SDL_GUID.
+ * Retrieves an SDL_PenID for the given SDL_GUID.
 *
 * \param guid A pen GUID.
- * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
+ * \returns A valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
 *          SDL_PenID.
 *
 * \since This function is available since SDL 3.0.0
@ -196,11 +190,11 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x,
 extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);

 /**
- * Retrieves the ::SDL_GUID for a given ::SDL_PenID.
+ * Retrieves the SDL_GUID for a given SDL_PenID.
 *
 * \param instance_id The pen to query.
 * \returns The corresponding pen GUID; persistent across multiple sessions.
- *          If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
+ *          If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
 *
 * \since This function is available since SDL 3.0.0
 */
@ -209,7 +203,7 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
 /**
 * Checks whether a pen is still attached.
 *
- * If a pen is detached, it will not show up for ::SDL_GetPens(). Other
+ * If a pen is detached, it will not show up for SDL_GetPens(). Other
 * operations will still be available but may return default values.
 *
 * \param instance_id A pen ID.
@ -221,23 +215,23 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
 extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);

 /**
- * Retrieves a human-readable description for a ::SDL_PenID.
+ * Retrieves a human-readable description for a SDL_PenID.
 *
 * \param instance_id The pen to query.
 * \returns A string that contains the name of the pen, intended for human
 *          consumption. The string might or might not be localised, depending
 *          on platform settings. It is not guaranteed to be unique; use
- *          ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
+ *          SDL_GetPenGUID() for (best-effort) unique identifiers. The
 *          pointer is managed by the SDL pen subsystem and must not be
 *          deallocated. The pointer remains valid until SDL is shut down.
- *          Returns NULL on error (cf. ::SDL_GetError())
+ *          Returns NULL on error (cf. SDL_GetError())
 *
 * \since This function is available since SDL 3.0.0
 */
 extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);

 /**
- * Pen capabilities, as reported by ::SDL_GetPenCapabilities()
+ * Pen capabilities, as reported by SDL_GetPenCapabilities()
 */
 typedef struct SDL_PenCapabilityInfo
 {
@ -247,7 +241,7 @@ typedef struct SDL_PenCapabilityInfo
 } SDL_PenCapabilityInfo;

 /**
- * Retrieves capability flags for a given ::SDL_PenID.
+ * Retrieves capability flags for a given SDL_PenID.
 *
 * \param instance_id The pen to query.
 * \param capabilities Detail information about pen capabilities, such as the
@ -259,14 +253,14 @@ typedef struct SDL_PenCapabilityInfo
 extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);

 /**
- * Retrieves the pen type for a given ::SDL_PenID.
+ * Retrieves the pen type for a given SDL_PenID.
 *
 * \param instance_id The pen to query.
- * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
+ * \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
 *          Note that the pen type does not dictate whether the pen tip is
- *          ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
+ *          SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a
 *          pen is being used for drawing or in eraser mode, check either the
- *          pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
+ *          pen tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK
 *          in the pen state.
 *
 * \since This function is available since SDL 3.0.0
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@ -85,7 +85,7 @@ extern "C" {
 /* @} */

 /** Pixel type. */
-typedef enum
+typedef enum SDL_PixelType
 {
    SDL_PIXELTYPE_UNKNOWN,
    SDL_PIXELTYPE_INDEX1,
@ -104,7 +104,7 @@ typedef enum
 } SDL_PixelType;

 /** Bitmap pixel order, high bit -> low bit. */
-typedef enum
+typedef enum SDL_BitmapOrder
 {
    SDL_BITMAPORDER_NONE,
    SDL_BITMAPORDER_4321,
@ -112,7 +112,7 @@ typedef enum
 } SDL_BitmapOrder;

 /** Packed component order, high bit -> low bit. */
-typedef enum
+typedef enum SDL_PackedOrder
 {
    SDL_PACKEDORDER_NONE,
    SDL_PACKEDORDER_XRGB,
@ -126,7 +126,7 @@ typedef enum
 } SDL_PackedOrder;

 /** Array component order, low byte -> high byte. */
-typedef enum
+typedef enum SDL_ArrayOrder
 {
    SDL_ARRAYORDER_NONE,
    SDL_ARRAYORDER_RGB,
@ -138,7 +138,7 @@ typedef enum
 } SDL_ArrayOrder;

 /** Packed component layout. */
-typedef enum
+typedef enum SDL_PackedLayout
 {
    SDL_PACKEDLAYOUT_NONE,
    SDL_PACKEDLAYOUT_332,
@ -212,7 +212,7 @@ typedef enum
    ((format) && (SDL_PIXELFLAG(format) != 1))

 /* Note: If you modify this list, update SDL_GetPixelFormatName() */
-typedef enum
+typedef enum SDL_PixelFormatEnum
 {
    SDL_PIXELFORMAT_UNKNOWN,
    SDL_PIXELFORMAT_INDEX1LSB =
@ -449,7 +449,7 @@ typedef enum
 /**
 * The color type
 */
-typedef enum
+typedef enum SDL_ColorType
 {
    SDL_COLOR_TYPE_UNKNOWN = 0,
    SDL_COLOR_TYPE_RGB = 1,
@ -459,7 +459,7 @@ typedef enum
 /**
 * The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
 */
-typedef enum
+typedef enum SDL_ColorRange
 {
    SDL_COLOR_RANGE_UNKNOWN = 0,
    SDL_COLOR_RANGE_LIMITED = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */
@ -469,7 +469,7 @@ typedef enum
 /**
 * The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
 */
-typedef enum
+typedef enum SDL_ColorPrimaries
 {
    SDL_COLOR_PRIMARIES_UNKNOWN = 0,
    SDL_COLOR_PRIMARIES_BT709 = 1,                  /**< ITU-R BT.709-6 */
@ -490,7 +490,7 @@ typedef enum
 /**
 * The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
 */
-typedef enum
+typedef enum SDL_TransferCharacteristics
 {
    SDL_TRANSFER_CHARACTERISTICS_UNKNOWN = 0,
    SDL_TRANSFER_CHARACTERISTICS_BT709 = 1,         /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */
@ -516,7 +516,7 @@ typedef enum
 /**
 * The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
 */
-typedef enum
+typedef enum SDL_MatrixCoefficients
 {
    SDL_MATRIX_COEFFICIENTS_IDENTITY = 0,
    SDL_MATRIX_COEFFICIENTS_BT709 = 1,              /**< ITU-R BT.709-6 */
@ -538,7 +538,7 @@ typedef enum
 /**
 * The chroma sample location
 */
-typedef enum
+typedef enum SDL_ChromaLocation
 {
    SDL_CHROMA_LOCATION_NONE = 0,   /**< RGB, no chroma sampling */
    SDL_CHROMA_LOCATION_LEFT = 1,   /**< In MPEG-2, MPEG-4, and AVC, Cb and Cr are taken on midpoint of the left-edge of the 2x2 square. In other words, they have the same horizontal location as the top-left pixel, but is shifted one-half pixel down vertically. */
@ -565,7 +565,7 @@ typedef enum
 #define SDL_ISCOLORSPACE_LIMITED_RANGE(X)       (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL)
 #define SDL_ISCOLORSPACE_FULL_RANGE(X)          (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL)

-typedef enum
+typedef enum SDL_Colorspace
 {
    SDL_COLORSPACE_UNKNOWN,

@ -661,9 +661,13 @@ typedef enum
 } SDL_Colorspace;

 /**
+ * A structure that represents a color as RGBA components.
+ *
 * The bits of this structure can be directly reinterpreted as an integer-packed
 * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
 * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_Color
 {
@ -677,6 +681,8 @@ typedef struct SDL_Color
 /**
 * The bits of this structure can be directly reinterpreted as a float-packed
 * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_FColor
 {
@ -687,16 +693,30 @@ typedef struct SDL_FColor
 } SDL_FColor;
 #define SDL_FColour SDL_FColor

+/**
+ * A set of indexed colors representing a palette.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_PixelFormat
+ * \sa SDL_SetPaletteColors
+ */
 typedef struct SDL_Palette
 {
-    int ncolors;
-    SDL_Color *colors;
-    Uint32 version;
-    int refcount;
+    int ncolors;        /*< number of elements in `colors`. */
+    SDL_Color *colors;  /*< an array of colors, `ncolors` long. */
+    Uint32 version;     /*< internal use only, do not touch. */
+    int refcount;       /*< internal use only, do not touch. */
 } SDL_Palette;

 /**
- *  \note Everything in the pixel format structure is read-only.
+ * Details about the format of a pixel.
+ *
+ * Generally this is used with SDL_Surface, and covers many
+ * possible configurations, including paletted data and various
+ * bit patterns.
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_PixelFormat
 {
--- a/include/SDL3/SDL_power.h
+++ b/include/SDL3/SDL_power.h
@ -38,9 +38,13 @@ extern "C" {
 #endif

 /**
- *  The basic state for the system's power supply.
+ * The basic state for the system's power supply.
+ *
+ * These are results returned by SDL_GetPowerInfo().
+ *
+ * \since This enum is available since SDL 3.0.0
 */
-typedef enum
+typedef enum SDL_PowerState
 {
    SDL_POWERSTATE_ERROR = -1,   /**< error determining power status */
    SDL_POWERSTATE_UNKNOWN,      /**< cannot determine power status */
--- a/include/SDL3/SDL_properties.h
+++ b/include/SDL3/SDL_properties.h
@ -45,7 +45,7 @@ typedef Uint32 SDL_PropertiesID;
 /**
 * SDL property type
 */
-typedef enum
+typedef enum SDL_PropertyType
 {
    SDL_PROPERTY_TYPE_INVALID,
    SDL_PROPERTY_TYPE_POINTER,
@ -56,7 +56,7 @@ typedef enum
 } SDL_PropertyType;

 /**
- * Get the global SDL properties
+ * Get the global SDL properties.
 *
 * \returns a valid property ID on success or 0 on failure; call
 *          SDL_GetError() for more information.
@ -69,7 +69,7 @@ typedef enum
 extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);

 /**
- * Create a set of properties
+ * Create a set of properties.
 *
 * All properties are automatically destroyed when SDL_Quit() is called.
 *
@ -85,7 +85,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
 extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);

 /**
- * Copy a set of properties
+ * Copy a set of properties.
 *
 * Copy all the properties from one set of properties to another, with the
 * exception of properties requiring cleanup (set using
@ -104,7 +104,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
 extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);

 /**
- * Lock a set of properties
+ * Lock a set of properties.
 *
 * Obtain a multi-threaded lock for these properties. Other threads will wait
 * while trying to lock these properties until they are unlocked. Properties
@ -128,7 +128,7 @@ extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Propert
 extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);

 /**
- * Unlock a set of properties
+ * Unlock a set of properties.
 *
 * \param props the properties to unlock
 *
@ -142,7 +142,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);

 /**
 * Set a property on a set of properties with a cleanup function that is
- * called when the property is deleted
+ * called when the property is deleted.
 *
 * The cleanup function is also called if setting the property fails for any
 * reason.
@ -166,7 +166,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
 extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);

 /**
- * Set a property on a set of properties
+ * Set a property on a set of properties.
 *
 * \param props the properties to modify
 * \param name the name of the property to modify
@ -189,7 +189,7 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c
 extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);

 /**
- * Set a string property on a set of properties
+ * Set a string property on a set of properties.
 *
 * This function makes a copy of the string; the caller does not have to
 * preserve the data after this call completes.
@ -209,7 +209,7 @@ extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *
 extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);

 /**
- * Set an integer property on a set of properties
+ * Set an integer property on a set of properties.
 *
 * \param props the properties to modify
 * \param name the name of the property to modify
@ -226,7 +226,7 @@ extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const
 extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);

 /**
- * Set a floating point property on a set of properties
+ * Set a floating point property on a set of properties.
 *
 * \param props the properties to modify
 * \param name the name of the property to modify
@ -243,7 +243,7 @@ extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const
 extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);

 /**
- * Set a boolean property on a set of properties
+ * Set a boolean property on a set of properties.
 *
 * \param props the properties to modify
 * \param name the name of the property to modify
@ -275,7 +275,7 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const
 extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);

 /**
- * Get the type of a property on a set of properties
+ * Get the type of a property on a set of properties.
 *
 * \param props the properties to query
 * \param name the name of the property to query
@ -291,7 +291,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const c
 extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);

 /**
- * Get a property on a set of properties
+ * Get a property on a set of properties.
 *
 * By convention, the names of properties that SDL exposes on objects will
 * start with "SDL.", and properties that SDL uses internally will start with
@ -323,7 +323,7 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr
 extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);

 /**
- * Get a string property on a set of properties
+ * Get a string property on a set of properties.
 *
 * \param props the properties to query
 * \param name the name of the property to query
@ -342,7 +342,7 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char
 extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);

 /**
- * Get a number property on a set of properties
+ * Get a number property on a set of properties.
 *
 * You can use SDL_GetPropertyType() to query whether the property exists and
 * is a number property.
@ -364,7 +364,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props
 extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);

 /**
- * Get a floating point property on a set of properties
+ * Get a floating point property on a set of properties.
 *
 * You can use SDL_GetPropertyType() to query whether the property exists and
 * is a floating point property.
@ -386,7 +386,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con
 extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);

 /**
- * Get a boolean property on a set of properties
+ * Get a boolean property on a set of properties.
 *
 * You can use SDL_GetPropertyType() to query whether the property exists and
 * is a boolean property.
@ -408,7 +408,7 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const
 extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);

 /**
- * Clear a property on a set of properties
+ * Clear a property on a set of properties.
 *
 * \param props the properties to modify
 * \param name the name of the property to clear
@ -424,7 +424,7 @@ extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char
 typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);

 /**
- * Enumerate the properties on a set of properties
+ * Enumerate the properties on a set of properties.
 *
 * The callback function is called for each property on the set of properties.
 * The properties are locked during enumeration.
@ -442,7 +442,7 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop
 extern DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);

 /**
- * Destroy a set of properties
+ * Destroy a set of properties.
 *
 * All properties are deleted and their cleanup functions will be called, if
 * any.
--- a/include/SDL3/SDL_rect.h
+++ b/include/SDL3/SDL_rect.h
@ -38,10 +38,12 @@ extern "C" {
 #endif

 /**
- * The structure that defines a point (integer)
+ * The structure that defines a point (using integers).
 *
 * \sa SDL_GetRectEnclosingPoints
 * \sa SDL_PointInRect
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_Point
 {
@ -50,10 +52,12 @@ typedef struct SDL_Point
 } SDL_Point;

 /**
- * The structure that defines a point (floating point)
+ * The structure that defines a point (using floating point values).
 *
 * \sa SDL_GetRectEnclosingPointsFloat
 * \sa SDL_PointInRectFloat
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_FPoint
 {
@ -63,7 +67,7 @@ typedef struct SDL_FPoint


 /**
- * A rectangle, with the origin at the upper left (integer).
+ * A rectangle, with the origin at the upper left (using integers).
 *
 * \sa SDL_RectEmpty
 * \sa SDL_RectsEqual
@ -72,6 +76,8 @@ typedef struct SDL_FPoint
 * \sa SDL_GetRectAndLineIntersection
 * \sa SDL_GetRectUnion
 * \sa SDL_GetRectEnclosingPoints
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_Rect
 {
@ -81,7 +87,7 @@ typedef struct SDL_Rect


 /**
- * A rectangle, with the origin at the upper left (floating point).
+ * A rectangle, with the origin at the upper left (using floating point values).
 *
 * \sa SDL_RectEmptyFloat
 * \sa SDL_RectsEqualFloat
@ -92,6 +98,8 @@ typedef struct SDL_Rect
 * \sa SDL_GetRectUnionFloat
 * \sa SDL_GetRectEnclosingPointsFloat
 * \sa SDL_PointInRectFloat
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_FRect
 {
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@ -62,14 +62,14 @@ extern "C" {
 #endif

 /**
- * The name of the software renderer
+ * The name of the software renderer.
 */
 #define SDL_SOFTWARE_RENDERER   "software"

 /**
- * Flags used when creating a rendering context
+ * Flags used when creating a rendering context.
 */
-typedef enum
+typedef enum SDL_RendererFlags
 {
    SDL_RENDERER_PRESENTVSYNC = 0x00000004  /**< Present is synchronized with the refresh rate */
 } SDL_RendererFlags;
@ -88,7 +88,7 @@ typedef struct SDL_RendererInfo
 } SDL_RendererInfo;

 /**
- *  Vertex structure
+ *  Vertex structure.
 */
 typedef struct SDL_Vertex
 {
@ -100,7 +100,7 @@ typedef struct SDL_Vertex
 /**
 * The access pattern allowed for a texture.
 */
-typedef enum
+typedef enum SDL_TextureAccess
 {
    SDL_TEXTUREACCESS_STATIC,    /**< Changes rarely, not lockable */
    SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */
@ -108,9 +108,9 @@ typedef enum
 } SDL_TextureAccess;

 /**
- * How the logical size is mapped to the output
+ * How the logical size is mapped to the output.
 */
-typedef enum
+typedef enum SDL_RendererLogicalPresentation
 {
    SDL_LOGICAL_PRESENTATION_DISABLED,  /**< There is no logical size in effect */
    SDL_LOGICAL_PRESENTATION_STRETCH,   /**< The rendered content is stretched to the output resolution */
@ -2078,7 +2078,7 @@ extern DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer);
 extern DECLSPEC void *SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer);

 /**
- * Get the Metal command encoder for the current frame
+ * Get the Metal command encoder for the current frame.
 *
 * This function returns `void *`, so SDL doesn't have to include Metal's
 * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
--- a/include/SDL3/SDL_scancode.h
+++ b/include/SDL3/SDL_scancode.h
@ -31,19 +31,20 @@
 #include <SDL3/SDL_stdinc.h>

 /**
- *  The SDL keyboard scancode representation.
+ * The SDL keyboard scancode representation.
 *
- *  An SDL scancode is the physical representation of a key on the keyboard,
- *  independent of language and keyboard mapping.
+ * An SDL scancode is the physical representation of a key on the keyboard,
+ * independent of language and keyboard mapping.
 *
- *  Values of this type are used to represent keyboard keys, among other places
- *  in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the
- *  SDL_Event structure.
+ * Values of this type are used to represent keyboard keys, among other places
+ * in the `keysym.scancode` field of the SDL_KeyboardEvent structure.
 *
- *  The values in this enumeration are based on the USB usage page standard:
- *  https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
+ * The values in this enumeration are based on the USB usage page standard:
+ * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_Scancode
 {
    SDL_SCANCODE_UNKNOWN = 0,

--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@ -79,7 +79,7 @@ typedef enum
 } SDL_SensorType;

 /**
- * Accelerometer sensor
+ * Accelerometer sensor.
 *
 * The accelerometer returns the current acceleration in SI meters per
 * second squared. This measurement includes the force of gravity, so
@ -91,9 +91,10 @@ typedef enum
 * values[2]: Acceleration on the z axis
 *
 * For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:
- * -X ... +X : left ... right
- * -Y ... +Y : bottom ... top
- * -Z ... +Z : farther ... closer
+ *
+ * - -X ... +X : left ... right
+ * - -Y ... +Y : bottom ... top
+ * - -Z ... +Z : farther ... closer
 *
 * The axis data is not changed when the device is rotated.
 *
@ -102,7 +103,7 @@ typedef enum
 #define SDL_STANDARD_GRAVITY    9.80665f

 /**
- * Gyroscope sensor
+ * Gyroscope sensor.
 *
 * The gyroscope returns the current rate of rotation in radians per second.
 * The rotation is positive in the counter-clockwise direction. That is,
@ -115,9 +116,10 @@ typedef enum
 * values[2]: Angular speed around the z axis (roll)
 *
 * For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:
- * -X ... +X : left ... right
- * -Y ... +Y : bottom ... top
- * -Z ... +Z : farther ... closer
+ *
+ * - -X ... +X : left ... right
+ * - -Y ... +Y : bottom ... top
+ * - -Z ... +Z : farther ... closer
 *
 * The axis data is not changed when the device is rotated.
 *
@ -205,7 +207,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID ins
 extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor);

 /**
- * Get the implementation dependent name of a sensor
+ * Get the implementation dependent name of a sensor.
 *
 * \param sensor The SDL_Sensor object
 * \returns the sensor name, or NULL if `sensor` is NULL.
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@ -93,9 +93,13 @@ char *alloca();
 #define SDL_TABLESIZE(table)    SDL_arraysize(table)

 /**
- *  Macro useful for building other macros with strings in them
+ *  Macro useful for building other macros with strings in them.
 *
- *  e.g. #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")
+ *  For example:
+ *
+ * ```c
+ * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")`
+ * ```
 */
 #define SDL_STRINGIFY_ARG(arg)  #arg

@ -187,7 +191,7 @@ typedef int64_t Sint64;
 typedef uint64_t Uint64;

 /**
- * SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970)
+ * SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970).
 *
 * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() and SDL_SECONDS_TO_NS(),
 * and between Windows FILETIME values with SDL_TimeToWindows() and SDL_TimeFromWindows().
@ -417,7 +421,7 @@ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
 typedef void (SDLCALL *SDL_free_func)(void *mem);

 /**
- * Get the original set of SDL memory functions
+ * Get the original set of SDL memory functions.
 *
 * \param malloc_func filled with malloc function
 * \param calloc_func filled with calloc function
@ -432,7 +436,7 @@ extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *mal
                                                            SDL_free_func *free_func);

 /**
- * Get the current set of SDL memory functions
+ * Get the current set of SDL memory functions.
 *
 * \param malloc_func filled with malloc function
 * \param calloc_func filled with calloc function
@ -447,7 +451,7 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
                                                    SDL_free_func *free_func);

 /**
- * Replace SDL's memory allocation functions with a custom set
+ * Replace SDL's memory allocation functions with a custom set.
 *
 * \param malloc_func custom malloc function
 * \param calloc_func custom calloc function
@ -464,7 +468,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
                                                   SDL_free_func free_func);

 /**
- * Allocate memory aligned to a specific value
+ * Allocate memory aligned to a specific value.
 *
 * If `alignment` is less than the size of `void *`, then it will be increased
 * to match that.
@ -485,7 +489,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
 extern DECLSPEC SDL_MALLOC void *SDLCALL SDL_aligned_alloc(size_t alignment, size_t size);

 /**
- * Free memory allocated by SDL_aligned_alloc()
+ * Free memory allocated by SDL_aligned_alloc().
 *
 * \since This function is available since SDL 3.0.0.
 *
@ -494,7 +498,7 @@ extern DECLSPEC SDL_MALLOC void *SDLCALL SDL_aligned_alloc(size_t alignment, siz
 extern DECLSPEC void SDLCALL SDL_aligned_free(void *mem);

 /**
- * Get the number of outstanding (unfreed) allocations
+ * Get the number of outstanding (unfreed) allocations.
 *
 * \returns the number of allocations
 *
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@ -69,7 +69,7 @@ typedef struct SDL_BlitMap SDL_BlitMap;  /* this is an opaque type. */
 /**
 * The scaling mode
 */
-typedef enum
+typedef enum SDL_ScaleMode
 {
    SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */
    SDL_SCALEMODE_LINEAR,  /**< linear filtering */
@ -79,7 +79,7 @@ typedef enum
 /**
 * The flip mode
 */
-typedef enum
+typedef enum SDL_FlipMode
 {
    SDL_FLIP_NONE,          /**< Do not flip */
    SDL_FLIP_HORIZONTAL,    /**< flip horizontally */
@ -419,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file);
 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, int flag);

 /**
- * Returns whether the surface is RLE enabled
+ * Returns whether the surface is RLE enabled.
 *
 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
 *
@ -459,7 +459,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, int flag, Uint32 key);

 /**
- * Returns whether the surface has a color key
+ * Returns whether the surface has a color key.
 *
 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
 *
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@ -112,7 +112,7 @@ typedef union _XEvent XEvent;
 typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);

 /**
- * Set a callback for every X11 event
+ * Set a callback for every X11 event.
 *
 * The callback may modify the event, and should return SDL_TRUE if the event
 * should continue to be processed, or SDL_FALSE to prevent further
@ -125,9 +125,7 @@ typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
 */
 extern DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);

-/*
- * Platform specific functions for Linux
- */
+/* Platform specific functions for Linux*/
 #ifdef SDL_PLATFORM_LINUX

 /**
@ -483,7 +481,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
 /**
 *  WinRT / Windows Phone path types
 */
-typedef enum
+typedef enum SDL_WinRT_Path
 {
    /** The installed app's root directory.
        Files here are likely to be read-only. */
@ -507,7 +505,7 @@ typedef enum
 /**
 *  WinRT Device Family
 */
-typedef enum
+typedef enum SDL_WinRT_DeviceFamily
 {
    /** Unknown family  */
    SDL_WINRT_DEVICEFAMILY_UNKNOWN,
--- a/include/SDL3/SDL_test_assert.h
+++ b/include/SDL3/SDL_test_assert.h
@ -42,17 +42,13 @@
 extern "C" {
 #endif

-/**
- * Fails the assert.
- */
+/* Fails the assert. */
 #define ASSERT_FAIL     0

-/**
- * Passes the assert.
- */
+/* Passes the assert. */
 #define ASSERT_PASS     1

-/**
+/*
 * Assert that logs and break execution flow on failures.
 *
 * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
@ -60,7 +56,7 @@ extern "C" {
 */
 void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);

-/**
+/*
 * Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters.
 *
 * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
@ -70,25 +66,25 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
 */
 int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);

-/**
+/*
 * Explicitly pass without checking an assertion condition. Updates assertion counter.
 *
 * \param assertDescription Message to log with the assert describing it.
 */
 void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1);

-/**
+/*
 * Resets the assert summary counters to zero.
 */
 void SDLTest_ResetAssertSummary(void);

-/**
+/*
 * Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR.
 */
 void SDLTest_LogAssertSummary(void);


-/**
+/*
 * Converts the current assert summary state to a test result.
 *
 * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT
--- a/include/SDL3/SDL_test_crc32.h
+++ b/include/SDL3/SDL_test_crc32.h
@ -60,7 +60,7 @@ extern "C" {
 #define CRC32_POLY 0xEDB88320   /* Perl String::CRC32 compatible */
 #endif

-/**
+/*
 * Data structure for CRC32 (checksum) computation
 */
  typedef struct SDLTest_Crc32Context {
@ -69,7 +69,7 @@ extern "C" {

 /* ---------- Function Prototypes ------------- */

-/**
+/*
 * Initialize the CRC context
 *
 * Note: The function initializes the crc table required for all crc calculations.
@ -82,7 +82,7 @@ extern "C" {
 int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext);


-/**
+/*
 * calculate a crc32 from a data block
 *
 * \param crcContext         pointer to context variable
@ -101,7 +101,7 @@ int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
 int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);


-/**
+/*
 * clean up CRC context
 *
 * \param crcContext        pointer to context variable
--- a/include/SDL3/SDL_test_font.h
+++ b/include/SDL3/SDL_test_font.h
@ -19,7 +19,7 @@
  3. This notice may not be removed or altered from any source distribution.
 */

-/**
+/*
 *  \file SDL_test_font.h
 *
 *  Font related functions of SDL test framework.
@ -42,7 +42,7 @@ extern int FONT_CHARACTER_SIZE;

 #define FONT_LINE_HEIGHT    (FONT_CHARACTER_SIZE + 2)

-/**
+/*
 *  Draw a string in the currently set font.
 *
 *  \param renderer The renderer to draw on.
@ -54,7 +54,7 @@ extern int FONT_CHARACTER_SIZE;
 */
 int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);

-/**
+/*
 *  Draw a UTF-8 string in the currently set font.
 *
 *  The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets.
@ -68,7 +68,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);
 */
 int SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s);

-/**
+/*
 *  Data used for multi-line text output
 */
 typedef struct SDLTest_TextWindow
@ -79,7 +79,7 @@ typedef struct SDLTest_TextWindow
    char **lines;
 } SDLTest_TextWindow;

-/**
+/*
 *  Create a multi-line text output window
 *
 *  \param x The X coordinate of the upper left corner of the window.
@ -93,7 +93,7 @@ typedef struct SDLTest_TextWindow
 */
 SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h);

-/**
+/*
 *  Display a multi-line text output window
 *
 *  This function should be called every frame to display the text
@ -105,7 +105,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h)
 */
 void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer);

-/**
+/*
 *  Add text to a multi-line text output window
 *
 *  Adds UTF-8 text to the end of the current text. The newline character starts a
@ -120,7 +120,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render
 */
 void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);

-/**
+/*
 *  Add text to a multi-line text output window
 *
 *  Adds UTF-8 text to the end of the current text. The newline character starts a
@ -135,7 +135,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST
 */
 void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len);

-/**
+/*
 *  Clear the text in a multi-line text output window
 *
 *  \param textwin The text output window
@ -144,7 +144,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char
 */
 void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);

-/**
+/*
 *  Free the storage associated with a multi-line text output window
 *
 *  \param textwin The text output window
@ -153,7 +153,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
 */
 void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin);

-/**
+/*
 *  Cleanup textures used by font drawing functions.
 */
 void SDLTest_CleanupTextDrawing(void);
--- a/include/SDL3/SDL_test_harness.h
+++ b/include/SDL3/SDL_test_harness.h
@ -69,7 +69,7 @@ typedef int (*SDLTest_TestCaseFp)(void *arg);
 /* !< Function pointer to a test case teardown function (run after every test) */
 typedef void  (*SDLTest_TestCaseTearDownFp)(void *arg);

-/**
+/*
 * Holds information about a single test case.
 */
 typedef struct SDLTest_TestCaseReference {
@ -83,7 +83,7 @@ typedef struct SDLTest_TestCaseReference {
    int enabled;
 } SDLTest_TestCaseReference;

-/**
+/*
 * Holds information about a test suite (multiple test cases).
 */
 typedef struct SDLTest_TestSuiteReference {
@ -98,7 +98,7 @@ typedef struct SDLTest_TestSuiteReference {
 } SDLTest_TestSuiteReference;


-/**
+/*
 * Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z).
 *
 * Note: The returned string needs to be deallocated by the caller.
@ -109,7 +109,7 @@ typedef struct SDLTest_TestSuiteReference {
 */
 char *SDLTest_GenerateRunSeed(const int length);

-/**
+/*
 * Execute a test suite using the given run seed and execution key.
 *
 * \param testSuites Suites containing the test case.
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@ -65,7 +65,7 @@ typedef Uint32 SDL_TLSID;
 *
 *  \note On many systems you require special privileges to set high or time critical priority.
 */
-typedef enum {
+typedef enum SDL_ThreadPriority {
    SDL_THREAD_PRIORITY_LOW,
    SDL_THREAD_PRIORITY_NORMAL,
    SDL_THREAD_PRIORITY_HIGH,
--- a/include/SDL3/SDL_time.h
+++ b/include/SDL3/SDL_time.h
@ -76,8 +76,8 @@ typedef enum SDL_TimeFormat
    SDL_TIME_FORMAT_12HR = 1, /**< 12 hour time */
 } SDL_TimeFormat;

-/**
- *  Global date/time properties
+/*
+ *  Global date/time properties.
 *
 *  - `SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER`: the SDL_DateFormat to use as the preferred date display format
 *    for the current system locale.
@ -148,7 +148,7 @@ extern DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDate

 /**
 * Converts a Windows FILETIME (100-nanosecond intervals since January 1,
- * 1601) to an SDL time
+ * 1601) to an SDL time.
 *
 * This function takes the two 32-bit values of the FILETIME structure as
 * parameters.
--- a/include/SDL3/SDL_timer.h
+++ b/include/SDL3/SDL_timer.h
@ -37,9 +37,7 @@
 extern "C" {
 #endif

-/**
- * SDL time constants
- */
+/* SDL time constants */
 #define SDL_MS_PER_SECOND   1000
 #define SDL_US_PER_SECOND   1000000
 #define SDL_NS_PER_SECOND   1000000000LL
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@ -50,12 +50,23 @@ typedef enum
    SDL_TOUCH_DEVICE_INDIRECT_RELATIVE  /* trackpad with screen cursor-relative coordinates */
 } SDL_TouchDeviceType;

+/**
+ * Data about a single finger in a multitouch event.
+ *
+ * Each touch even is a collection of fingers that are simultaneously in
+ * contact with the touch device (so a "touch" can be a "multitouch," in
+ * reality), and this struct reports details of the specific fingers.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetTouchFinger
+ */
 typedef struct SDL_Finger
 {
-    SDL_FingerID id;
-    float x;
-    float y;
-    float pressure;
+    SDL_FingerID id;  /**< the finger ID */
+    float x;  /**< the x-axis location of the touch event, normalized (0...1) */
+    float y;  /**< the y-axis location of the touch event, normalized (0...1) */
+    float pressure; /**< the quantity of pressure applied, normalized (0...1) */
 } SDL_Finger;

 /* Used as the device ID for mouse events simulated with touch input */
--- a/include/SDL3/SDL_version.h
+++ b/include/SDL3/SDL_version.h
@ -48,6 +48,8 @@ extern "C" {
 *
 * \sa SDL_VERSION
 * \sa SDL_GetVersion
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
 typedef struct SDL_Version
 {
@ -56,8 +58,7 @@ typedef struct SDL_Version
    Uint8 patch;        /**< update version */
 } SDL_Version;

-/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
-*/
+/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL */
 #define SDL_MAJOR_VERSION   3
 #define SDL_MINOR_VERSION   1
 #define SDL_PATCHLEVEL      1
@ -76,6 +77,8 @@ typedef struct SDL_Version
 *
 * \sa SDL_Version
 * \sa SDL_GetVersion
+ *
+ * \since This macro is available since SDL 3.0.0.
 */
 #define SDL_VERSION(x)                \
 {                                     \
@ -85,22 +88,31 @@ typedef struct SDL_Version
 }

 /**
- *  This macro turns the version numbers into a numeric value:
- *  \verbatim
-    (1,2,3) -> (0x1000203)
-    \endverbatim
+ * This macro turns the version numbers into a numeric value.
+ *
+ * (1,2,3) becomes 0x1000203.
+ *
+ * \param major the major version number.
+ * \param minor the minorversion number.
+ * \param patch the patch version number.
+ *
+ * \since This macro is available since SDL 3.0.0.
 */
-#define SDL_VERSIONNUM(X, Y, Z) \
-    ((X) << 24 | (Y) << 8 | (Z) << 0)
+#define SDL_VERSIONNUM(major, minor, patch) \
+    ((major) << 24 | (minor) << 8 | (patch) << 0)

 /**
 *  This is the version number macro for the current SDL version.
+ *
+ * \since This macro is available since SDL 3.0.0.
 */
 #define SDL_COMPILEDVERSION \
    SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL)

 /**
 *  This macro will evaluate to true if compiled with SDL at least X.Y.Z.
+ *
+ * \since This macro is available since SDL 3.0.0.
 */
 #define SDL_VERSION_ATLEAST(X, Y, Z) \
    (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@ -45,8 +45,8 @@ extern "C" {
 typedef Uint32 SDL_DisplayID;
 typedef Uint32 SDL_WindowID;

-/**
- *  Global video properties
+/*
+ *  Global video properties.
 *
 *  - `SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to
 *    the global `wl_display` object used by the Wayland video backend. Can be
@ -62,9 +62,11 @@ typedef Uint32 SDL_WindowID;
 #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display"

 /**
- *  System theme
+ * System theme.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_SystemTheme
 {
    SDL_SYSTEM_THEME_UNKNOWN,   /**< Unknown system theme */
    SDL_SYSTEM_THEME_LIGHT,     /**< Light colored system theme */
@ -72,15 +74,17 @@ typedef enum
 } SDL_SystemTheme;

 /**
- *  The structure that defines a display mode
+ * The structure that defines a display mode.
 *
- *  \sa SDL_GetFullscreenDisplayModes()
- *  \sa SDL_GetDesktopDisplayMode()
- *  \sa SDL_GetCurrentDisplayMode()
- *  \sa SDL_SetWindowFullscreenMode()
- *  \sa SDL_GetWindowFullscreenMode()
+ * \sa SDL_GetFullscreenDisplayModes()
+ * \sa SDL_GetDesktopDisplayMode()
+ * \sa SDL_GetCurrentDisplayMode()
+ * \sa SDL_SetWindowFullscreenMode()
+ * \sa SDL_GetWindowFullscreenMode()
+ *
+ * \since This struct is available since SDL 3.0.0.
 */
-typedef struct
+typedef struct SDL_DisplayMode
 {
    SDL_DisplayID displayID;    /**< the display this mode is associated with */
    SDL_PixelFormatEnum format; /**< pixel format */
@ -92,9 +96,11 @@ typedef struct
 } SDL_DisplayMode;

 /**
- *  Display orientation
+ * Display orientation values; the way a display is rotated.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_DisplayOrientation
 {
    SDL_ORIENTATION_UNKNOWN,            /**< The display orientation can't be determined */
    SDL_ORIENTATION_LANDSCAPE,          /**< The display is in landscape mode, with the right side up, relative to portrait mode */
@ -104,14 +110,23 @@ typedef enum
 } SDL_DisplayOrientation;

 /**
- *  The type used to identify a window
+ *  The struct used as an opaque handle to a window.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateWindow
 */
 typedef struct SDL_Window SDL_Window;

 /**
- *  The flags on a window
+ * The flags on a window.
 *
- *  \sa SDL_GetWindowFlags
+ * These cover a lot of true/false, or on/off, window state. Some of it
+ * is immutable after being set through SDL_CreateWindow(), some of it can
+ * be changed on existing windows by the app, and some of it might be altered
+ * by the user or system outside of the app's control.
+ *
+ * \sa SDL_GetWindowFlags
 */
 typedef Uint32 SDL_WindowFlags;

@ -158,9 +173,11 @@ typedef Uint32 SDL_WindowFlags;
            (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)

 /**
- *  Window flash operation
+ * Window flash operation.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_FlashOperation
 {
    SDL_FLASH_CANCEL,                   /**< Cancel any window flash state */
    SDL_FLASH_BRIEFLY,                  /**< Flash the window briefly to get attention */
@ -188,9 +205,15 @@ typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void);
 typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);

 /**
- *  OpenGL configuration attributes
+ * An enumeration of OpenGL configuration attributes.
+ *
+ * While you can set most OpenGL attributes normally, the attributes listed above must be known before SDL creates the window that will be used with the OpenGL context. These attributes are set and read with SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
+ *
+ * In some cases, these attributes are minimum requests; the GL does not promise to give you exactly what you asked for. It's possible to ask for a 16-bit depth buffer and get a 24-bit one instead, for example, or to ask for no stencil buffer and still have one available. Context creation should fail if the GL can't provide your requested attributes at a minimum, but you should check to see exactly what you got.
+ *
+ * \since This enum is available since SDL 3.0.0.
 */
-typedef enum
+typedef enum SDL_GLattr
 {
    SDL_GL_RED_SIZE,
    SDL_GL_GREEN_SIZE,
@ -222,14 +245,24 @@ typedef enum
    SDL_GL_EGL_PLATFORM
 } SDL_GLattr;

-typedef enum
+/**
+ * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_GLprofile
 {
    SDL_GL_CONTEXT_PROFILE_CORE           = 0x0001,
    SDL_GL_CONTEXT_PROFILE_COMPATIBILITY  = 0x0002,
    SDL_GL_CONTEXT_PROFILE_ES             = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */
 } SDL_GLprofile;

-typedef enum
+/**
+ * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_GLcontextFlag
 {
    SDL_GL_CONTEXT_DEBUG_FLAG              = 0x0001,
    SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002,
@ -237,13 +270,23 @@ typedef enum
    SDL_GL_CONTEXT_RESET_ISOLATION_FLAG    = 0x0008
 } SDL_GLcontextFlag;

-typedef enum
+/**
+ * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR attribute.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_GLcontextReleaseFlag
 {
    SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE   = 0x0000,
    SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH  = 0x0001
 } SDL_GLcontextReleaseFlag;

-typedef enum
+/**
+ * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_GLContextResetNotification
 {
    SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000,
    SDL_GL_CONTEXT_RESET_LOSE_CONTEXT    = 0x0001
@ -292,7 +335,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
 extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);

 /**
- * Get the current system theme
+ * Get the current system theme.
 *
 * \returns the current system theme, light, dark, or unknown
 *
@ -2004,18 +2047,18 @@ extern DECLSPEC int SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x,
 *
 * \sa SDL_HitTest
 */
-typedef enum
+typedef enum SDL_HitTestResult
 {
-    SDL_HITTEST_NORMAL,  /**< Region is normal. No special properties. */
-    SDL_HITTEST_DRAGGABLE,  /**< Region can drag entire window. */
-    SDL_HITTEST_RESIZE_TOPLEFT,
-    SDL_HITTEST_RESIZE_TOP,
-    SDL_HITTEST_RESIZE_TOPRIGHT,
-    SDL_HITTEST_RESIZE_RIGHT,
-    SDL_HITTEST_RESIZE_BOTTOMRIGHT,
-    SDL_HITTEST_RESIZE_BOTTOM,
-    SDL_HITTEST_RESIZE_BOTTOMLEFT,
-    SDL_HITTEST_RESIZE_LEFT
+    SDL_HITTEST_NORMAL,             /**< Region is normal. No special properties. */
+    SDL_HITTEST_DRAGGABLE,          /**< Region can drag entire window. */
+    SDL_HITTEST_RESIZE_TOPLEFT,     /**< Region is the resizable top-left corner border. */
+    SDL_HITTEST_RESIZE_TOP,         /**< Region is the resizable top border. */
+    SDL_HITTEST_RESIZE_TOPRIGHT,    /**< Region is the resizable top-right corner border. */
+    SDL_HITTEST_RESIZE_RIGHT,       /**< Region is the resizable right border. */
+    SDL_HITTEST_RESIZE_BOTTOMRIGHT, /**< Region is the resizable bottom-right corner border. */
+    SDL_HITTEST_RESIZE_BOTTOM,      /**< Region is the resizable bottom border. */
+    SDL_HITTEST_RESIZE_BOTTOMLEFT,  /**< Region is the resizable bottom-left corner border. */
+    SDL_HITTEST_RESIZE_LEFT         /**< Region is the resizable left border. */
 } SDL_HitTestResult;

 /**
--- a/include/SDL3/SDL_vulkan.h
+++ b/include/SDL3/SDL_vulkan.h
@ -128,7 +128,7 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
 extern DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);

 /**
- * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
+ * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary().
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/src/hidapi/SDL_hidapi.c
+++ b/src/hidapi/SDL_hidapi.c
@ -998,7 +998,7 @@ static const struct hidapi_backend LIBUSB_Backend = {
 };
 #endif /* HAVE_LIBUSB */

-struct SDL_hid_device_
+struct SDL_hid_device
 {
    const void *magic;
    void *device;