diff --git a/docs/input.dox b/docs/input.dox
index 8a9b5710..88b8d351 100644
--- a/docs/input.dox
+++ b/docs/input.dox
@@ -590,6 +590,12 @@ void joystick_callback(int jid, int event)
 }
 @endcode
 
+For joystick connection and disconnection events to be delivered on all
+platforms, you need to call one of the [event processing](@ref events)
+functions.  Joystick disconnection may also be detected and the callback
+called by joystick functions.  The function will then return whatever it
+returns for a disconnected joystick.
+
 
 @section time Time input
 
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 8b2fe860..ca5fa37e 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -4032,6 +4032,12 @@ GLFWAPI const char* glfwGetJoystickName(int jid);
  *  currently set callback.  This is called when a joystick is connected to or
  *  disconnected from the system.
  *
+ *  For joystick connection and disconnection events to be delivered on all
+ *  platforms, you need to call one of the [event processing](@ref events)
+ *  functions.  Joystick disconnection may also be detected and the callback
+ *  called by joystick functions.  The function will then return whatever it
+ *  returns for a disconnected joystick.
+ *
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
  *  @return The previously set callback, or `NULL` if no callback was set or the