Improve documentation relating to key tokens

Shifted the documentation away from the term 'named keys' as something
different than keys that glfwGetKeyName will return a name for.  The
already existing term 'key token' should now be used to refer to the
GLFW_KEY_* constants.

The associated term 'named mouse button' was also replaced with
'supported mouse button'.

The parts explaining which key tokens will return a valid scancode from
glfwGetKeyScancode have hopefully been clarified.  This issue was
reported in glfw#2055.

The GLFW_KEY_UNKNOWN constant has been moved out of the list of key
tokens to simplify and hopefully clarify the related documentation.

Various other keyboard key related edits were made, hopefully resulting
in improvements.

Related to glfw#2055

docs/input.dox

@@ -95,7 +95,7 @@ new size before everything returns back out of the @ref glfwSetWindowSize call.
 
 GLFW divides keyboard input into two categories; key events and character
 events.  Key events relate to actual physical keyboard keys, whereas character
-events relate to the Unicode code points generated by pressing some of them.
+events relate to the text that is generated by pressing some of them.
 
 Keys and characters do not map 1:1.  A single key press may produce several
 characters, and a single character may require several keys to produce.  This
@@ -127,6 +127,10 @@ 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.
 
+Note that many keyboards have a limit on how many keys being simultaneous held
+down that they can detect.  This limit is called
+[key rollover](https://en.wikipedia.org/wiki/Key_rollover).
+
 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
@@ -142,16 +146,16 @@ 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
 different scancodes depending on the platform but they are safe to save to disk.
-You can query the scancode for any [named key](@ref keys) on the current
-platform with @ref glfwGetKeyScancode.
+You can query the scancode for any [key token](@ref keys) supported on the
+current platform with @ref glfwGetKeyScancode.
 
 @code
 const int scancode = glfwGetKeyScancode(GLFW_KEY_X);
 set_key_mapping(scancode, swap_weapons);
 @endcode
 
-The last reported state for every [named key](@ref keys) is also saved in
-per-window state arrays that can be polled with @ref glfwGetKey.
+The last reported state for every physical key with a [key token](@ref keys) is
+also saved in per-window state arrays that can be polled with @ref glfwGetKey.
 
 @code
 int state = glfwGetKey(window, GLFW_KEY_E);
@@ -164,7 +168,8 @@ if (state == GLFW_PRESS)
 The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
 
 This function only returns cached key event state.  It does not poll the
-system for the current physical state of the key.
+system for the current state of the physical key.  It also does not provide any
+key repeat information.
 
 @anchor GLFW_STICKY_KEYS
 Whenever you poll state, you risk missing the state change you are looking for.
@@ -195,15 +200,15 @@ Lock was on when the event occurred and the @ref GLFW_MOD_NUM_LOCK bit set if
 Num Lock was on.
 
 The `GLFW_KEY_LAST` constant holds the highest value of any
-[named key](@ref keys).
+[key token](@ref keys).
 
 
 @subsection input_char Text input
 
 GLFW supports text input in the form of a stream of
 [Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
-operating system text input system.  Unlike key input, text input obeys keyboard
-layouts and modifier keys and supports composing characters using
+operating system text input system.  Unlike key input, text input is affected by
+keyboard layouts and modifier keys and supports composing characters using
 [dead keys](https://en.wikipedia.org/wiki/Dead_key).  Once received, you can
 encode the code points into UTF-8 or any other encoding you prefer.
 
@@ -502,8 +507,9 @@ void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
 
 The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
 
-Mouse button states for [named buttons](@ref buttons) are also saved in
-per-window state arrays that can be polled with @ref glfwGetMouseButton.
+The last reported state for every [supported mouse button](@ref buttons) is also
+saved in per-window state arrays that can be polled with @ref
+glfwGetMouseButton.
 
 @code
 int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
@@ -536,7 +542,7 @@ had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
 otherwise it will remain `GLFW_PRESS`.
 
 The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
-[named button](@ref buttons).
+[supported mouse button](@ref buttons).
 
 
 @subsection scrolling Scroll input

include/GLFW/glfw3.h

@@ -361,10 +361,15 @@ extern "C" {
 #define GLFW_HAT_RIGHT_DOWN         (GLFW_HAT_RIGHT | GLFW_HAT_DOWN)
 #define GLFW_HAT_LEFT_UP            (GLFW_HAT_LEFT  | GLFW_HAT_UP)
 #define GLFW_HAT_LEFT_DOWN          (GLFW_HAT_LEFT  | GLFW_HAT_DOWN)
+
+/*! @ingroup input
+ */
+#define GLFW_KEY_UNKNOWN            -1
+
 /*! @} */
 
-/*! @defgroup keys Keyboard keys
- *  @brief Keyboard key IDs.
+/*! @defgroup keys Keyboard key tokens
+ *  @brief Keyboard key tokens.
  *
  *  See [key input](@ref input_key) for how these are used.
  *
@@ -387,9 +392,6 @@ extern "C" {
  *  @{
  */
 
-/* The unknown key */
-#define GLFW_KEY_UNKNOWN            -1
-
 /* Printable keys */
 #define GLFW_KEY_SPACE              32
 #define GLFW_KEY_APOSTROPHE         39  /* ' */
@@ -4741,15 +4743,18 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
  *
  *  This function returns the platform-specific scancode of the specified key.
  *
- *  If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
- *  method will return `-1`.
+ *  If the specified [key token](@ref keys) corresponds to a physical key not
+ *  supported on the current platform then this method will return `-1`.
+ *  Calling this function with anything other than a key token will return `-1`
+ *  and generate a @ref GLFW_INVALID_ENUM error.
  *
- *  @param[in] key Any [named key](@ref keys).
- *  @return The platform-specific scancode for the key, or `-1` if an
- *  [error](@ref error_handling) occurred.
+ *  @param[in] key Any [key token](@ref keys).
+ *  @return The platform-specific scancode for the key, or `-1` if the key is
+ *  not supported on the current platform or an [error](@ref error_handling)
+ *  occurred.
  *
- *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
- *  GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
+ *  GLFW_INVALID_ENUM.
  *
  *  @thread_safety This function may be called from any thread.
  *
@@ -5058,9 +5063,9 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
  *  [character callback](@ref glfwSetCharCallback) instead.
  *
  *  When a window loses input focus, it will generate synthetic key release
- *  events for all pressed named keys.  You can tell these events from
- *  user-generated events by the fact that the synthetic ones are generated
- *  after the focus loss event has been processed, i.e. after the
+ *  events for all pressed keys with associated key tokens.  You can tell these
+ *  events from user-generated events by the fact that the synthetic ones are
+ *  generated after the focus loss event has been processed, i.e. after the
  *  [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
  *
  *  The scancode of a key is specific to that platform or sometimes even to that