DOCS: Update Keyboard documentation

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

@@ -77,7 +77,7 @@ namespace UnityEngine.InputSystem
     /// which has APIs specific to the type of value of the control (e.g. <see cref="InputControl{TValue}.ReadValue()"/>.
     ///
     /// The following example demonstrates various common operations performed on input controls:
-    ///
+    /// </remarks>
     /// <example>
     /// <code>
     /// // Look up dpad/up control on current gamepad.
@@ -99,10 +99,7 @@ namespace UnityEngine.InputSystem
     /// leftStickHistory.Enable();
     /// </code>
     /// </example>
-    /// <example>
-    /// </example>
-    /// </remarks>
-    /// <see cref="InputControl{TValue}"/>
+    /// <seealso cref="InputControl{TValue}"/>
     /// <seealso cref="InputDevice"/>
     /// <seealso cref="InputControlPath"/>
     /// <seealso cref="InputStateBlock"/>
@@ -611,6 +608,8 @@ public virtual unsafe void WriteValueFromObjectIntoState(object value, void* sta
         /// Note that if the given path matches multiple child controls, only the first control
         /// encountered in the search will be returned.
         ///
+        /// This method is equivalent to calling <see cref="InputControlPath.TryFindChild"/>.
+        /// </remarks>
         /// <example>
         /// <code>
         /// // Returns the leftStick control of the current gamepad.
@@ -625,9 +624,6 @@ public virtual unsafe void WriteValueFromObjectIntoState(object value, void* sta
         /// Gamepad.current.TryGetChildControl("*stick");
         /// </code>
         /// </example>
-        ///
-        /// This method is equivalent to calling <see cref="InputControlPath.TryFindChild"/>.
-        /// </remarks>
         public InputControl TryGetChildControl(string path)
         {
             if (string.IsNullOrEmpty(path))
@@ -689,7 +685,7 @@ protected InputControl()
         /// <remarks>
         /// This method can be overridden to perform control- or device-specific setup work. The most
         /// common use case is for looking up child controls and storing them in local getters.
-        ///
+        /// </remarks>
         /// <example>
         /// <code>
         /// public class MyDevice : InputDevice
@@ -706,7 +702,6 @@ protected InputControl()
         /// }
         /// </code>
         /// </example>
-        /// </remarks>
         protected virtual void FinishSetup()
         {
         }
@@ -723,9 +718,12 @@ protected virtual void FinishSetup()
         ///
         /// This method should be called if you are accessing cached data set up by
         /// <see cref="RefreshConfiguration"/>.
-        ///
+        /// </remarks>
         /// <example>
         /// <code>
+        /// using UnityEngine.InputSystem;
+        /// using UnityEngine.InputSystem.Utilities;
+        ///
         /// // Let's say your device has an associated orientation which it can be held with
         /// // and you want to surface both as a property and as a usage on the device.
         /// // Whenever your backend code detects a change in orientation, it should send
@@ -779,7 +777,6 @@ protected virtual void FinishSetup()
         /// }
         /// </code>
         /// </example>
-        /// </remarks>
         /// <seealso cref="RefreshConfiguration"/>
         protected void RefreshConfigurationIfNeeded()
         {
@@ -790,6 +787,61 @@ protected void RefreshConfigurationIfNeeded()
             }
         }
 
+        /// <summary>
+        /// Refresh the configuration of the control. This is used to update the control's state (e.g. Keyboard Layout or display Name of Keys).
+        /// </summary>
+        /// <remarks>
+        /// The system will call this method automatically whenever change is made to one of the control's configuration properties.
+        /// See <see cref="RefreshConfigurationIfNeeded"/>.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// using UnityEngine.InputSystem;
+        /// using UnityEngine.InputSystem.Utilities;
+        ///
+        /// public class MyDevice : InputDevice
+        /// {
+        ///     public enum Orientation
+        ///     {
+        ///         Horizontal,
+        ///         Vertical,
+        ///     }
+        ///     private Orientation m_Orientation;
+        ///     private static InternedString s_Vertical = new InternedString("Vertical");
+        ///     private static InternedString s_Horizontal = new InternedString("Horizontal");
+        ///
+        ///     public Orientation orientation
+        ///     {
+        ///         get
+        ///         {
+        ///             // Call RefreshOrientation if the configuration of the device has been
+        ///             // invalidated since last time we initialized m_Orientation.
+        ///             // Calling RefreshConfigurationIfNeeded() is sufficient in most cases, RefreshConfiguration() forces the refresh.
+        ///             RefreshConfiguration();
+        ///             return m_Orientation;
+        ///         }
+        ///     }
+        ///     protected override void RefreshConfiguration()
+        ///     {
+        ///         // Set Orientation back to horizontal. Alternatively fetch from device.
+        ///         m_Orientation = Orientation.Horizontal;
+        ///         // Reflect the orientation on the device.
+        ///         switch (m_Orientation)
+        ///         {
+        ///             case Orientation.Vertical:
+        ///                 InputSystem.RemoveDeviceUsage(this, s_Horizontal);
+        ///                 InputSystem.AddDeviceUsage(this, s_Vertical);
+        ///                 break;
+        ///
+        ///             case Orientation.Horizontal:
+        ///                 InputSystem.RemoveDeviceUsage(this, s_Vertical);
+        ///                 InputSystem.AddDeviceUsage(this, s_Horizontal);
+        ///                 break;
+        ///         }
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         protected virtual void RefreshConfiguration()
         {
         }
@@ -902,8 +954,6 @@ protected virtual FourCC CalculateOptimizedControlDataType()
         /// <summary>
         /// Apply built-in parameters changes (e.g. <see cref="AxisControl.invert"/>, others), recompute <see cref="InputControl.optimizedControlDataType"/> for impacted controls and clear cached value.
         /// </summary>
-        /// <remarks>
-        /// </remarks>
         public void ApplyParameterChanges()
         {
             // First we go through all children of our own hierarchy

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

@@ -58,7 +58,7 @@ public int scanCode
                 return m_ScanCode;
             }
         }
-
+        /// <inheritdoc/>
         protected override void RefreshConfiguration()
         {
             // Wipe our last cached set of data (if any).

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

@@ -41,21 +41,32 @@ namespace UnityEngine.InputSystem
     /// runtime. However, it is possible to manually add devices using methods such as <see
     /// cref="InputSystem.AddDevice{TDevice}(string)"/>.
     ///
-    /// <example>
-    /// <code>
-    /// // Add a "synthetic" gamepad that isn't actually backed by hardware.
-    /// var gamepad = InputSystem.AddDevice&lt;Gamepad&gt;();
-    /// </code>
-    /// </example>
-    ///
     /// There are subclasses representing the most common types of devices, like <see cref="Mouse"/>,
     /// <see cref="Keyboard"/>, <see cref="Gamepad"/>, and <see cref="Touchscreen"/>.
     ///
     /// To create your own types of devices, you can derive from InputDevice and register your device
     /// as a new "layout".
     ///
+    /// Devices can have usages like any other control (<see cref="InputControl.usages"/>). Unlike other controls,
+    /// however, usages of InputDevices are allowed to be changed on the fly without requiring a change to the
+    /// device layout (see <see cref="InputSystem.SetDeviceUsage(InputDevice,string)"/>).
+    ///
+    /// For a more complete example of how to implement custom input devices, check out the "Custom Device"
+    /// sample which you can install from the Unity package manager.
+    ///
+    /// And, as always, you can also find more information in the <a href="../manual/Devices.html">manual</a>.
+    /// </remarks>
     /// <example>
     /// <code>
+    /// using System.Runtime.InteropServices;
+    /// using UnityEditor;
+    /// using UnityEngine;
+    /// using UnityEngine.InputSystem;
+    /// using UnityEngine.InputSystem.Controls;
+    /// using UnityEngine.InputSystem.Layouts;
+    /// using UnityEngine.InputSystem.LowLevel;
+    /// using UnityEngine.InputSystem.Utilities;
+    ///
     /// // InputControlLayoutAttribute attribute is only necessary if you want
     /// // to override default behavior that occurs when registering your device
     /// // as a layout.
@@ -70,6 +81,9 @@ namespace UnityEngine.InputSystem
     ///     public ButtonControl button { get; private set; }
     ///     public AxisControl axis { get; private set; }
     ///
+    ///     // This is an example on how to add a "synthetic" gamepad that isn't actually backed by hardware.
+    ///     Gamepad gamepad = InputSystem.AddDevice&lt;Gamepad&gt;();
+    ///
     ///     // Register the device.
     ///     static MyDevice()
     ///     {
@@ -113,34 +127,24 @@ namespace UnityEngine.InputSystem
     ///     // particular device is connected and fed into the input system.
     ///     // The format is a simple FourCC code that "tags" state memory blocks for the
     ///     // device to give a base level of safety checks on memory operations.
-    ///     public FourCC format => return new FourCC('H', 'I', 'D');
+    ///     public FourCC format => new FourCC('H', 'I', 'D');
     ///
     ///     // InputControlAttributes on fields tell the input system to create controls
     ///     // for the public fields found in the struct.
     ///
     ///     // Assume a 16bit field of buttons. Create one button that is tied to
     ///     // bit #3 (zero-based). Note that buttons do not need to be stored as bits.
     ///     // They can also be stored as floats or shorts, for example.
-    ///     [InputControl(name = "button", layout = "Button", bit = 3)]
+    ///     [InputControl(name = "button", layout = "Button", bit = 3)] [FieldOffset(0)]
     ///     public ushort buttons;
     ///
     ///     // Create a floating-point axis. The name, if not supplied, is taken from
     ///     // the field.
-    ///     [InputControl(layout = "Axis")]
+    ///     [InputControl(layout = "Axis")] [FieldOffset(0)]
     ///     public short axis;
     /// }
     /// </code>
     /// </example>
-    ///
-    /// Devices can have usages like any other control (<see cref="InputControl.usages"/>). Unlike other controls,
-    /// however, usages of InputDevices are allowed to be changed on the fly without requiring a change to the
-    /// device layout (see <see cref="InputSystem.SetDeviceUsage(InputDevice,string)"/>).
-    ///
-    /// For a more complete example of how to implement custom input devices, check out the "Custom Device"
-    /// sample which you can install from the Unity package manager.
-    ///
-    /// And, as always, you can also find more information in the <a href="../manual/Devices.html">manual</a>.
-    /// </remarks>
     /// <seealso cref="InputControl"/>
     /// <seealso cref="Mouse"/>
     /// <seealso cref="Keyboard"/>
@@ -508,10 +512,26 @@ public virtual void MakeCurrent()
         /// </summary>
         /// <remarks>
         /// This is called <em>after</em> the device has already been added.
+        /// <see cref="InputSystem.devices"/>
+        /// <see cref="InputDeviceChange.Added"/>
+        /// <see cref="OnRemoved"/>
         /// </remarks>
-        /// <seealso cref="InputSystem.devices"/>
-        /// <seealso cref="InputDeviceChange.Added"/>
-        /// <seealso cref="OnRemoved"/>
+        /// <example>
+        /// <code>
+        /// using UnityEngine.InputSystem;
+        ///
+        /// public class MyDevice : InputDevice
+        /// {
+        ///     public static MyDevice current { get; private set; }
+        ///     protected override void OnAdded()
+        ///     {
+        ///         // use this context to assign the current device for instance
+        ///         base.OnAdded();
+        ///         current = this;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         protected virtual void OnAdded()
         {
         }
@@ -521,10 +541,27 @@ protected virtual void OnAdded()
         /// </summary>
         /// <remarks>
         /// This is called <em>after</em> the device has already been removed.
+        /// <see cref="InputSystem.devices"/>
+        /// <see cref="InputDeviceChange.Removed"/>
+        /// <see cref="OnAdded"/>
         /// </remarks>
-        /// <seealso cref="InputSystem.devices"/>
-        /// <seealso cref="InputDeviceChange.Removed"/>
-        /// <seealso cref="OnRemoved"/>
+        /// <example>
+        /// <code>
+        /// using UnityEngine.InputSystem;
+        ///
+        /// public class MyDevice : InputDevice
+        /// {
+        ///     public static MyDevice current { get; private set; }
+        ///     protected override void OnRemoved()
+        ///     {
+        ///         // use this context to unassign the current device for instance
+        ///         base.OnRemoved();
+        ///         if (current == this)
+        ///             current = null;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         protected virtual void OnRemoved()
         {
         }
@@ -542,7 +579,7 @@ protected virtual void OnRemoved()
         /// </remarks>
         /// <seealso cref="InputManager.OnUpdate"/>
         /// <seealso cref="InputDeviceChange.ConfigurationChanged"/>
-        /// <seealso cref="OnConfigurationChanged"/>///
+        /// <seealso cref="OnConfigurationChanged"/>
         protected virtual void OnConfigurationChanged()
         {
         }
@@ -560,8 +597,8 @@ protected virtual void OnConfigurationChanged()
         /// the device API. This is most useful for devices implemented in the native Unity runtime
         /// which, through the command interface, may provide custom, device-specific functions.
         ///
-        /// This is a low-level API. It works in a similar way to <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa363216%28v=vs.85%29.aspx?f=255&amp;MSPPError=-2147217396" target="_blank">
-        /// DeviceIoControl</a> on Windows and <a href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/ioctl.2.html#//apple_ref/doc/man/2/ioctl" target="_blank">ioctl</a>
+        /// This is a low-level API. It works in a similar way to <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa363216%28v=vs.85%29.aspx?f=255&amp;MSPPError=-2147217396">
+        /// DeviceIoControl</a> on Windows and <a href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/ioctl.2.html#//apple_ref/doc/man/2/ioctl">ioctl</a>
         /// on UNIX-like systems.
         /// </remarks>
         public unsafe long ExecuteCommand<TCommand>(ref TCommand command)