DOCS: Misc changes (#1396).

Author: Rene Damm

Packages/com.unity.inputsystem/Documentation~/Events.md

@@ -9,7 +9,8 @@
     * [Reading state events](#reading-state-events)
     * [Creating events](#creating-events)
     * [Capturing events](#capturing-events)
-* [Merging of events](#merging-of-events)
+* [Processing events](#processing-events)
+    * [Merging of events](#merging-of-events)
 
 The Input System is event-driven. All input is delivered as events, and you can generate custom input by injecting events. You can also observe all source input by listening in on the events flowing through the system.
 
@@ -233,7 +234,27 @@ controller.PlayAllFramesOnyByOne();
 controller.PlayAllEventsAccordingToTimestamps();
 ```
 
-## Merging of events
+## Processing events
+
+[Events](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) are collected on a queue by the Unity runtime. This queue is regularly flushed out and the events on it processed. Events can be added to the queue manually by calling [`InputSystem.QueueEvent`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_QueueEvent_UnityEngine_InputSystem_LowLevel_InputEventPtr_).
+
+Each time input is processed, [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_) is called implicitly by the Unity runtime.
+
+The interval at which this happens is determined by the ["Update Mode"](Settings.md#update-mode) configured in the settings. By default, input is processed in each frame __before__ <c>MonoBehaviour.Update</c> methods are called. If the setting is changed to process input in fixed updates, then this changes to input being processed each time before <c>MonoBehaviour.FixedUpdate</c> methods are called.
+
+Normally, when input is processed, __all__ outstanding input events on the queue will be consumed. There are two exceptions to this, however.
+
+When using [`UpdateMode.ProcessEventsInFixedUpdate`](../api/UnityEngine.InputSystem.InputSettings.UpdateMode.html#UnityEngine_InputSystem_InputSettings_UpdateMode_ProcessEventsInFixedUpdate), the Input System attempts to associate events with the timeslice of the corresponding <c>FixedUpdate</c>. This is based on the [timestamps](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_time) of the events and a "best effort" at calculating the corresponding timeslice of the current <c>FixedUpdated</c>.
+
+The other exception are [`BeforeRender`](../api/UnityEngine.InputSystem.LowLevel.InputUpdateType.html#UnityEngine_InputSystem_LowLevel_InputUpdateType_BeforeRender) updates. These updates are run after fixed or dynamic updates but before rendering and used used exclusively to update devices such as VR headsets that need the most up-to-date tracking data. Other input is not consumed from such updates and these updates are only enabled if such devices are actually present. `BeforeRender` updates are not considered separate frames as far as input is concerned.
+
+>__Note__: Manually calling [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_) is strongly advised against except within tests employing [`InputTestFixture`](../api/UnityEngine.InputSystem.InputTestFixture.html) or when explicitly setting the system to [manual update mode](../api/UnityEngine.InputSystem.InputSettings.UpdateMode.html#UnityEngine_InputSystem_InputSettings_UpdateMode_ProcessEventsManually).
+
+Methods such as [`InputAction.WasPerformedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) and [`InputAction.WasPerformedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) operate implicitly based on the [`InputSystem.Update`] cadence described above. Meaning, that they refer to the state as per the __last__ fixed/dynamic/manual update happened.
+
+You can query the [current/last update type](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_currentUpdateType) and [count](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_updateCount) from [`InputState`](../api/UnityEngine.InputSystem.LowLevel.InputState.html).
+
+### Merging of events
 
 Input system uses event mering to reduce amount of events required to be processed.
 This greatly improves performance when working with high refresh rate devices like 8000 Hz mice, touchscreens and others.

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs

@@ -507,6 +507,11 @@ public ReadOnlyArray<InputControl> controls
         /// </remarks>
         public InputActionPhase phase => currentState.phase;
 
+        /// <summary>
+        /// True if the action is currently in <see cref="InputActionPhase.Started"/> or <see cref="InputActionPhase.Performed"/>
+        /// phase. False in all other cases.
+        /// </summary>
+        /// <see cref="phase"/>
         public bool inProgress => phase.IsInProgress();
 
         /// <summary>
@@ -1121,6 +1126,9 @@ public unsafe bool IsPressed()
         ///
         /// This method will disregard whether the action is currently enabled or disabled. It will keep returning
         /// true for the duration of the frame even if the action was subsequently disabled in the frame.
+        ///
+        /// The meaning of "frame" is either the current "dynamic" update (<c>MonoBehaviour.Update</c>) or the current
+        /// fixed update (<c>MonoBehaviour.FixedUpdate</c>) depending on the value of the <see cref="InputSettings.updateMode"/> setting.
         /// </remarks>
         /// <seealso cref="IsPressed"/>
         /// <seealso cref="WasReleasedThisFrame"/>
@@ -1167,6 +1175,9 @@ public unsafe bool WasPressedThisFrame()
         ///
         /// This method will disregard whether the action is currently enabled or disabled. It will keep returning
         /// true for the duration of the frame even if the action was subsequently disabled in the frame.
+        ///
+        /// The meaning of "frame" is either the current "dynamic" update (<c>MonoBehaviour.Update</c>) or the current
+        /// fixed update (<c>MonoBehaviour.FixedUpdate</c>) depending on the value of the <see cref="InputSettings.updateMode"/> setting.
         /// </remarks>
         /// <seealso cref="IsPressed"/>
         /// <seealso cref="WasPressedThisFrame"/>
@@ -1223,6 +1234,9 @@ public unsafe bool WasReleasedThisFrame()
         ///
         /// This method will disregard whether the action is currently enabled or disabled. It will keep returning
         /// true for the duration of the frame even if the action was subsequently disabled in the frame.
+        ///
+        /// The meaning of "frame" is either the current "dynamic" update (<c>MonoBehaviour.Update</c>) or the current
+        /// fixed update (<c>MonoBehaviour.FixedUpdate</c>) depending on the value of the <see cref="InputSettings.updateMode"/> setting.
         /// </remarks>
         /// <seealso cref="WasPressedThisFrame"/>
         /// <seealso cref="phase"/>

Packages/com.unity.inputsystem/InputSystem/Plugins/PlayerInput/PlayerInput.cs

@@ -350,6 +350,7 @@ public InputActionAsset actions
         /// </remarks>
         /// <seealso cref="SwitchCurrentControlScheme(UnityEngine.InputSystem.InputDevice[])"/>
         /// <seealso cref="defaultControlScheme"/>
+        /// <seealso cref="InputActionAsset.controlSchemes"/>
         public string currentControlScheme
         {
             get
@@ -877,6 +878,28 @@ public void PassivateInput()
             DeactivateInput();
         }
 
+        /// <summary>
+        /// Switch the current control scheme to one that fits the given set of devices.
+        /// </summary>
+        /// <param name="devices">A list of input devices. Note that if any of the devices is already paired to another
+        /// player, the device will end up paired to both players.</param>
+        /// <returns>True if the switch was successful, false otherwise. The latter can happen, for example, if
+        /// <see cref="actions"/> does not have a control scheme that fits the given set of devices.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="devices"/> is <c>null</c>.</exception>
+        /// <exception cref="InvalidOperationException"><see cref="actions"/> has not been assigned.</exception>
+        /// <remarks>
+        /// The player's currently paired devices (see <see cref="devices"/>) will get unpaired.
+        ///
+        /// <example>
+        /// <code>
+        /// // Switch the first player to keyboard and mouse.
+        /// PlayerInput.all[0]
+        ///     .SwitchCurrentControlScheme(Keyboard.current, Mouse.current);
+        /// </code>
+        /// </example>
+        /// </remarks>
+        /// <seealso cref="currentControlScheme"/>
+        /// <seealso cref="InputActionAsset.controlSchemes"/>
         public bool SwitchCurrentControlScheme(params InputDevice[] devices)
         {
             if (devices == null)
@@ -895,6 +918,31 @@ public bool SwitchCurrentControlScheme(params InputDevice[] devices)
 
         ////REVIEW: these should just be SwitchControlScheme
 
+        /// <summary>
+        /// Switch the player to use the given control scheme together with the given devices.
+        /// </summary>
+        /// <param name="controlScheme">Name of the control scheme. See <see cref="InputControlScheme.name"/>.</param>
+        /// <param name="devices">A list of devices.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="devices"/> is <c>null</c> -or- <paramref name="controlScheme"/> is
+        /// <c>null</c> or empty.</exception>
+        /// <remarks>
+        /// This method can be used to explicitly force a combination of control scheme and a specific set of
+        /// devices.
+        ///
+        /// <example>
+        /// <code>
+        /// // Put player 1 on the "Gamepad" control scheme together
+        /// // with the second gamepad.
+        /// PlayerInput.all[0].SwitchControlScheme(
+        ///     "Gamepad",
+        ///     Gamepad.all[1]);
+        /// </code>
+        /// </example>
+        ///
+        /// The player's currently paired devices (see <see cref="devices"/>) will get unpaired.
+        /// </remarks>
+        /// <seealso cref="InputActionAsset.controlSchemes"/>
+        /// <seealso cref="currentControlScheme"/>
         public void SwitchCurrentControlScheme(string controlScheme, params InputDevice[] devices)
         {
             if (string.IsNullOrEmpty(controlScheme))