diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 5c9082ced..84cef7dfe 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -163,8 +163,9 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_
 /**
  *  Open a game controller for use.
  *  The index passed as an argument refers to the N'th game controller on the system.
- *  This index is the value which will identify this controller in future controller
- *  events.
+ *  This index is not the value which will identify this controller in future
+ *  controller events.  The joystick's instance id (::SDL_JoystickID) will be
+ *  used there instead.
  *
  *  \return A controller identifier, or NULL if an error occurred.
  */
diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index f26bb9214..c2110716c 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -88,8 +88,9 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
 /**
  *  Open a joystick for use.
  *  The index passed as an argument refers to the N'th joystick on the system.
- *  This index is the value which will identify this joystick in future joystick
- *  events.
+ *  This index is not the value which will identify this joystick in future
+ *  joystick events.  The joystick's instance id (::SDL_JoystickID) will be used
+ *  there instead.
  *
  *  \return A joystick identifier, or NULL if an error occurred.
  */