diff --git a/include/SDL_events.h b/include/SDL_events.h
index 33d6da4b7e..6dcaa5cb15 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -412,6 +412,11 @@ typedef struct SDL_JoyButtonEvent
 
 /**
  * Joystick device event structure (event.jdevice.*)
+ *
+ * SDL will send JOYSTICK_ADDED events for devices that
+ * are already plugged in during SDL_Init.
+ *
+ * \sa SDL_ControllerDeviceEvent
  */
 typedef struct SDL_JoyDeviceEvent
 {
@@ -465,6 +470,12 @@ typedef struct SDL_ControllerButtonEvent
 
 /**
  * Controller device event structure (event.cdevice.*)
+ *
+ * Joysticks that are supported game controllers receive both an
+ * SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent.
+ *
+ * SDL will send CONTROLLERDEVICEADDED events for joysticks that are already plugged
+ * in during SDL_Init() and are recognized as game controllers.
  */
 typedef struct SDL_ControllerDeviceEvent
 {
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 030e0f0154..8ef27c53c9 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -146,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind
  * If a new mapping is loaded for an already known controller GUID, the later
  * version will overwrite the one currently loaded.
  *
+ * If this function is called before SDL_Init, SDL will generate
+ * an SDL_CONTROLLERDEVICEADDED event for matching controllers that are
+ * plugged in at the time that SDL_Init is called.
+ *
  * Mappings not belonging to the current platform or with no platform field
  * specified will be ignored (i.e. mappings for Linux will be ignored in
  * Windows, etc).
@@ -164,6 +168,7 @@ typedef struct SDL_GameControllerButtonBind
  * \sa SDL_GameControllerAddMapping
  * \sa SDL_GameControllerAddMappingsFromFile
  * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
 
@@ -193,6 +198,10 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
  * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
  * ```
  *
+ * If this function is called before SDL_Init, SDL will generate
+ * an SDL_CONTROLLERDEVICEADDED event for matching controllers that are
+ * plugged in at the time that SDL_Init is called.
+ *
  * \param mappingString the mapping string.
  * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
  *          -1 on error; call SDL_GetError() for more information.
@@ -201,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
  *
  * \sa SDL_GameControllerMapping
  * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);