Documentation work
Fixes #1596
(cherry picked from commit aa80d24d01d150e26d664ff2d5da22e95db6bb82)
diff --git a/docs/input.dox b/docs/input.dox
index 7514e95..1d61e5b 100644
--- a/docs/input.dox
+++ b/docs/input.dox
@@ -123,9 +123,21 @@
}
@endcode
-The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. The key
-will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it, for example
-_E-mail_ and _Play_ keys.
+The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. Events with
+`GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press. Most
+keys will also emit events with `GLFW_REPEAT` actions while a key is held down.
+
+Key events with `GLFW_REPEAT` actions are intended for text input. They are
+emitted at the rate set in the user's keyboard settings. At most one key is
+repeated even if several keys are held down. `GLFW_REPEAT` actions should not
+be relied on to know which keys are being held down or to drive animation.
+Instead you should either save the state of relevant keys based on `GLFW_PRESS`
+and `GLFW_RELEASE` actions, or call @ref glfwGetKey, which provides basic cached
+key state.
+
+The key will be one of the existing [key tokens](@ref keys), or
+`GLFW_KEY_UNKNOWN` if GLFW lacks a token for it, for example _E-mail_ and _Play_
+keys.
The scancode is unique for every key, regardless of whether it has a key token.
Scancodes are platform-specific but consistent over time, so keys will have
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 5dcfa86..31b201a 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -4278,8 +4278,7 @@
*
* This function returns the last state reported for the specified key to the
* specified window. The returned state is one of `GLFW_PRESS` or
- * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to
- * the key callback.
+ * `GLFW_RELEASE`. The action `GLFW_REPEAT` is only reported to the key callback.
*
* If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns
* `GLFW_PRESS` the first time you call it for a key that was pressed, even if
