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

From ad090d2444b35c54fc38c1353d8f8d00058ca1e4 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 8 Apr 2024 22:36:57 -0400
Subject: [PATCH] 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.
---
 include/SDL3/SDL_assert.h       |    9 +
 include/SDL3/SDL_audio.h        |   45 +-
 include/SDL3/SDL_blendmode.h    |   27 +-
 include/SDL3/SDL_camera.h       |   12 +-
 include/SDL3/SDL_clipboard.h    |    8 +-
 include/SDL3/SDL_dialog.h       |    2 +-
 include/SDL3/SDL_error.h        |    4 +-
 include/SDL3/SDL_events.h       |   22 +-
 include/SDL3/SDL_filesystem.h   |    4 +-
 include/SDL3/SDL_gamepad.h      |   16 +-
 include/SDL3/SDL_haptic.h       |  266 ++++---
 include/SDL3/SDL_hidapi.h       |   10 +-
 include/SDL3/SDL_hints.h        | 1284 ++++++++++++++++++++++---------
 include/SDL3/SDL_init.h         |    2 +-
 include/SDL3/SDL_iostream.h     |   23 +-
 include/SDL3/SDL_joystick.h     |   12 +-
 include/SDL3/SDL_keyboard.h     |    4 +-
 include/SDL3/SDL_keycode.h      |   48 +-
 include/SDL3/SDL_locale.h       |   13 +-
 include/SDL3/SDL_log.h          |    6 +-
 include/SDL3/SDL_messagebox.h   |   14 +-
 include/SDL3/SDL_mouse.h        |    4 +-
 include/SDL3/SDL_pen.h          |  112 ++-
 include/SDL3/SDL_pixels.h       |   56 +-
 include/SDL3/SDL_power.h        |    8 +-
 include/SDL3/SDL_properties.h   |   42 +-
 include/SDL3/SDL_rect.h         |   16 +-
 include/SDL3/SDL_render.h       |   16 +-
 include/SDL3/SDL_scancode.h     |   19 +-
 include/SDL3/SDL_sensor.h       |   20 +-
 include/SDL3/SDL_stdinc.h       |   22 +-
 include/SDL3/SDL_surface.h      |    8 +-
 include/SDL3/SDL_system.h       |   10 +-
 include/SDL3/SDL_test_assert.h  |   20 +-
 include/SDL3/SDL_test_crc32.h   |    8 +-
 include/SDL3/SDL_test_font.h    |   22 +-
 include/SDL3/SDL_test_harness.h |    8 +-
 include/SDL3/SDL_thread.h       |    2 +-
 include/SDL3/SDL_time.h         |    6 +-
 include/SDL3/SDL_timer.h        |    4 +-
 include/SDL3/SDL_touch.h        |   19 +-
 include/SDL3/SDL_version.h      |   28 +-
 include/SDL3/SDL_video.h        |  115 ++-
 include/SDL3/SDL_vulkan.h       |    2 +-
 src/hidapi/SDL_hidapi.c         |    2 +-
 45 files changed, 1566 insertions(+), 834 deletions(-)

diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 9d6cba57f0d36..6863f4c989226 100644
--- 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;
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index feac79c5a3183..7a7ee934b0b8f 100644
--- 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
  *
diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h
index 8b3667c107d02..111bf5a5300a9 100644
--- 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 */
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 923fb481debfd..3546d8b5434ba 100644
--- 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
 {
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index 5f0257ee7e1b5..c1c8386c6e471 100644
--- 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
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
index 134c8194d18e5..6a7402efe28d4 100644
--- 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;
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index b6ae7aec03e0d..93a7865760ff2 100644
--- 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.
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 4b1d139174db8..17417ac432ec6 100644
--- 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.
diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index 971a19bee3949..7b4bff582b69b 100644
--- 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
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 9d2e86eaa72dd..a889c73c72a37 100644
--- 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
diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h
index 3bc17b8a800f0..d79ad4da442b6 100644
--- 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
+ * ```
+ *
+ * Complete example:
  *
- * \par Complete example:
- * \code
+ * ```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 exclusi

(Patch may be truncated, please check the link at the top of this post.)