update keyboard documentation

Author: ritamerkl

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

@@ -790,6 +790,60 @@ 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 <seealso cref="RefreshConfigurationIfNeeded"/>.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// public class MyDevice : InputDevice
+        /// {
+        ///     public enum Orientation
+        ///     {
+        ///         Horizontal,
+        ///         Vertical,
+        ///     }
+        ///     private Orientation m_Orientation;
+        ///
+        ///     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()
+        ///     {
+        ///         // Fetch the current orientation from the backend. How you do this
+        ///         // depends on your device. Using DeviceCommands is one way.
+        ///         var fetchOrientationCommand = new FetchOrientationCommand();
+        ///         ExecuteCommand(ref fetchOrientationCommand);
+        ///         m_Orientation = fetchOrientation;
+        ///
+        ///         // 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()
         {
         }

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

@@ -521,10 +521,24 @@ protected virtual void OnAdded()
         /// </summary>
         /// <remarks>
         /// This is called <em>after</em> the device has already been removed.
-        /// </remarks>
         /// <seealso cref="InputSystem.devices"/>
         /// <seealso cref="InputDeviceChange.Removed"/>
         /// <seealso cref="OnRemoved"/>
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// public class MyDevice : InputDevice
+        /// {
+        ///     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()
         {
         }