From a0e767851cd320f43edad69a13220a277fe649e6 Mon Sep 17 00:00:00 2001
From: Jordan Christiansen <xordspar0@gmail.com>
Date: Sat, 19 Oct 2024 11:03:15 -0500
Subject: [PATCH] docs: Explain events for already plugged in controllers

---
 include/SDL3/SDL_events.h | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index bc5becb5f2299..078cb3e66ffcd 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -549,7 +549,12 @@ typedef struct SDL_JoyButtonEvent
 /**
  * Joystick device event structure (event.jdevice.*)
  *
+ * SDL will populate the event queue with JOYSTICK_ADDED events for devices that
+ * are already plugged in during SDL_Init.
+ *
  * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_GamepadDeviceEvent
  */
 typedef struct SDL_JoyDeviceEvent
 {
@@ -615,7 +620,27 @@ typedef struct SDL_GamepadButtonEvent
 /**
  * Gamepad device event structure (event.gdevice.*)
  *
+ * Joysticks that are supported Gamepads receive both an SDL_JoyDeviceEvent and
+ * an SDL_GamepadDeviceEvent.
+ *
+ * SDL will populate the event queue with GAMEPAD_ADDED events for joysticks
+ * that are already plugged in duing SDL_Init and are recognized as Gamepads.
+ *
+ * GAMEPAD_ADDED events for controllers plugged in at the start of the program
+ * will not occur automatically if their mappings are added after calling
+ * SDL_Init.
+ *
+ * If you rely on GAMEPAD_ADDED events to tell you about controllers that are
+ * already plugged in at the start of the program, and you use
+ * SDL_AddGamepadMappingsFromFile to add support for additional controllers,
+ * you can ensure that you get GAMEPAD_ADDED events for all controllers if you
+ * load the mappings before calling SDL_Init.
+ *
  * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_AddGamepadMappingsFromFile
+ * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
+ * \sa SDL_JoyDeviceEvent
  */
 typedef struct SDL_GamepadDeviceEvent
 {