DOCF-3045 Clarified information about key layout, text input and key controls (#1695)

* DOCF-3045 Clarified information about key layout, text input and key controls

* DOCF-3045 Fixed broken links

* Fixed formatting (trailing whitespace)

---------

Co-authored-by: Lyndon Homewood <33493311+lyndon-unity@users.noreply.github.com>

Author: duckets

Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs

@@ -12,9 +12,27 @@ namespace UnityEngine.InputSystem.Controls
     /// have symbols associated with them which may change depending on keyboard layout as well as in combination
     /// with other keys.
     ///
-    /// Note that there is no text input associated with individual keys as text composition is highly
-    /// layout specific and does not need to be key-by-key. For general text input, see <see cref="Keyboard.onTextInput"/>.
-    /// To find the text displayed on a key, use <see cref="InputControl.displayName"/>.
+    /// Note:
+    /// Unity input system key codes and input manager key codes are designed with game controls in mind.
+    ///
+    /// This means the way they are assigned is intended to preserve the location of keys on keyboards,
+    /// so that pressing a key in the same location on different keyboards should result in the same action
+    /// regardless of what is printed on a key or what current system language is set.
+    ///
+    /// This means, for example, that <see cref="Key.A"/> is always the key to the right of <see cref="Key.CapsLock"/>,
+    /// regardless of which key (if any) produces the "a" character on the current keyboard layout.
+    ///
+    /// Unity relies on physical hardware in the keyboards to report same USB HID "usage" for the keys in
+    /// the same location.This puts a practical limit on what can be achieved, because different keyboards
+    /// might report different data, and this is outside of Unity's control.
+    ///
+    /// For this reason, you should not use key codes to read text input.
+    /// Instead, you should use the <see cref="Keyboard.onTextInput"/> callback.
+    /// The `onTextInput` callback provides you with the actual text characters which correspond
+    /// to the symbols printed on a keyboard, based on the end user's current system language layout.
+    ///
+    /// To find the text character (if any) generated by a key according to the currently active keyboard
+    /// layout, use the <see cref="InputControl.displayName"/> property of <see cref="KeyControl"/>.
     /// </remarks>
     public class KeyControl : ButtonControl
     {
@@ -24,6 +42,7 @@ public class KeyControl : ButtonControl
         /// <remarks>
         /// This property must be initialized by <see cref="InputControl.FinishSetup"/> of
         /// the device owning the control.
+        /// You should not use `keyCode` to read text input. For more information, <see cref="KeyControl"/>
         /// </remarks>
         public Key keyCode { get; set; }
 

Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs

@@ -197,11 +197,27 @@ namespace UnityEngine.InputSystem
     /// Enumeration of key codes.
     /// </summary>
     /// <remarks>
-    /// Named according to the US keyboard layout which is used as a reference layout. Note, however,
-    /// that keys are identified by physical location, not by the characters they generate. This means,
-    /// for example, that <see cref="A"/> is always the key to the right of <see cref="CapsLock"/>,
+    /// Named according to the US keyboard layout which is used as a reference layout.
+    ///
+    /// Note:
+    /// Unity input system key codes and input manager key codes are designed with game controls in mind.
+    ///
+    /// This means the way they are assigned is intended to preserve the location of keys on keyboards,
+    /// so that pressing a key in the same location on different keyboards should result in the same action
+    /// regardless of what is printed on a key or what current system language is set.
+    ///
+    /// This means, for example, that <see cref="A"/> is always the key to the right of <see cref="CapsLock"/>,
     /// regardless of which key (if any) produces the "a" character on the current keyboard layout.
     ///
+    /// Unity relies on physical hardware in the keyboards to report same USB HID "usage" for the keys in
+    /// the same location.This puts a practical limit on what can be achieved, because different keyboards
+    /// might report different data, and this is outside of Unity's control.
+    ///
+    /// For this reason, you should not use key codes to read text input.
+    /// Instead, you should use the <see cref="Keyboard.onTextInput"/> callback.
+    /// The `onTextInput` callback provides you with the actual text characters which correspond
+    /// to the symbols printed on a keyboard, based on the end user's current system language layout.
+    ///
     /// To find the text character (if any) generated by a key according to the currently active keyboard
     /// layout, use the <see cref="InputControl.displayName"/> property of <see cref="KeyControl"/>.
     ///