From cb85894e949a8a24bec25fbd3d3366bf13a2d4bc Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Fri, 16 Aug 2024 15:20:11 -0700
Subject: [PATCH] Clarified device ID documentation
Fixes https://github.com/libsdl-org/SDL/issues/10558
---
include/SDL3/SDL_camera.h | 3 +--
include/SDL3/SDL_haptic.h | 3 +--
include/SDL3/SDL_joystick.h | 3 +--
include/SDL3/SDL_keyboard.h | 3 +--
include/SDL3/SDL_mouse.h | 19 ++++++++++++++++++-
include/SDL3/SDL_sensor.h | 3 +--
6 files changed, 23 insertions(+), 11 deletions(-)
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 46dcee1de0ed2..ad9c826b07626 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -48,8 +48,7 @@ extern "C" {
*
* If the device is disconnected and reconnected, it will get a new ID.
*
- * The ID value starts at 1 and increments from there. The value 0 is an
- * invalid ID.
+ * The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h
index 1d0a54efee750..93935e9b87ccf 100644
--- a/include/SDL3/SDL_haptic.h
+++ b/include/SDL3/SDL_haptic.h
@@ -919,8 +919,7 @@ typedef union SDL_HapticEffect
*
* If the haptic device is disconnected and reconnected, it will get a new ID.
*
- * The ID value starts at 1 and increments from there. The value 0 is an
- * invalid ID.
+ * The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 1a1707664c10e..9ae4b6ae7b710 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -91,8 +91,7 @@ typedef struct SDL_Joystick SDL_Joystick;
*
* If the joystick is disconnected and reconnected, it will get a new ID.
*
- * The ID value starts at 1 and increments from there. The value 0 is an
- * invalid ID.
+ * The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h
index d4f9b22cd9d95..0fe05b938f1b3 100644
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@@ -45,8 +45,7 @@ extern "C" {
*
* If the keyboard is disconnected and reconnected, it will get a new ID.
*
- * The ID value starts at 1 and increments from there. The value 0 is an
- * invalid ID.
+ * The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h
index c1f1e0e99900f..c7810c69e5a34 100644
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@@ -38,9 +38,26 @@
extern "C" {
#endif
+/**
+ * This is a unique ID for a mouse for the time it is connected to the
+ * system, and is never reused for the lifetime of the application.
+ *
+ * If the mouse is disconnected and reconnected, it will get a new ID.
+ *
+ * The value 0 is an invalid ID.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ */
typedef Uint32 SDL_MouseID;
-typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
+/**
+ * The structure used to identify an SDL cursor.
+ *
+ * This is opaque data.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
+typedef struct SDL_Cursor SDL_Cursor;
/**
* Cursor types for SDL_CreateSystemCursor().
diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index 2d4aa468d946a..f3beac42eb2db 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -55,8 +55,7 @@ typedef struct SDL_Sensor SDL_Sensor;
* This is a unique ID for a sensor for the time it is connected to the
* system, and is never reused for the lifetime of the application.
*
- * The ID value starts at 1 and increments from there. The value 0 is an
- * invalid ID.
+ * The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/