DOCS: Improved script API docs of InputAction.CallbackContext

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

@@ -1791,7 +1791,80 @@ internal int BindingIndexOnMapToBindingIndexOnAction(int indexOfBindingOnMap)
         /// Information provided to action callbacks about what triggered an action.
         /// </summary>
         /// <remarks>
-        /// This struct should not be held on to past the duration of the callback.
+        /// The callback context represents the current state of an <see cref="action"/> associated with the callback
+        /// and provides information associated with the bound <see cref="control"/>, its value, and its
+        /// <see cref="phase"/>.
+        ///
+        /// The callback context provides you with a way to consume events (push-based input) as part of an update when using
+        /// input action callback notifications. For example, <see cref="InputAction.started"/>,
+        /// <see cref="InputAction.performed"/>, <see cref="InputAction.canceled"/> rather than relying on
+        /// pull-based reading.
+        ///
+        /// Use this struct to read the current input value through any of the read-method overloads:
+        /// <see cref="ReadValue{T}()"/>, <see cref="ReadValueAsButton"/>,
+        /// <see cref="ReadValueAsObject()"/> or <see cref="ReadValue" /> (unsafe). If you don't know the expected value type,
+        /// you might need to check <see cref="valueType"/> before reading the value.
+        ///
+        /// Use the <see cref="phase"/> property to get the current phase of the associated action or
+        /// evaluate it directly using any of the convenience methods <see cref="started"/>, <see cref="performed"/>,
+        /// <see cref="canceled"/>.
+        ///
+        /// To obtain information about the current timestamp of the associated event, or to check when the event
+        /// started, use <see cref="time"/> or <see cref="startTime"/> respectively.
+        ///
+        /// You should not use or keep this struct outside of the callback.
+        ///
+        /// <example>
+        /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem;
+        /// using UnityEngine.InputSystem.Interactions;
+        ///
+        /// public class MyController : MonoBehaviour
+        ///  {
+        ///      [SerializeField] InputActionReference move;
+        ///      [SerializeField] InputActionReference fire;
+        ///
+        ///      void Awake()
+        ///      {
+        ///          /// Receive notifications when move or fire actions are performed
+        ///          move.action.performed += MovePerformed;
+        ///          fire.action.performed += FirePerformed;
+        ///      }
+        ///
+        ///      void OnEnable()
+        ///      {
+        ///          /// Enable actions as part of enabling this behavior.
+        ///          move.action?.Enable();
+        ///          fire.action?.Enable();
+        ///      }
+        ///
+        ///      void OnDisable()
+        ///      {
+        ///          /// Disable actions as part of disabling this behavior.
+        ///          move.action?.Disable();
+        ///          fire.action?.Disable();
+        ///      }
+        ///
+        ///      void MovePerformed(InputAction.CallbackContext context)
+        ///      {
+        ///          /// Read the current 2D vector value reported by the associated input action.
+        ///          var direction = context.ReadValue<Vector2>();
+        ///          Debug.Log("Move: " + direction * Time.deltaTime);
+        ///      }
+        ///
+        ///      void FirePerformed(InputAction.CallbackContext context)
+        ///      {
+        ///          /// If underlying interaction is a slow-tap fire charged projectile, otherwise fire regular
+        ///          /// projectile.
+        ///          if (context.interaction is SlowTapInteraction)
+        ///              Debug.Log("Fire charged projectile");
+        ///          else
+        ///              Debug.Log("Fire projectile");
+        ///      }
+        ///  }
+        /// </code>
+        /// </example>
         /// </remarks>
         /// <seealso cref="performed"/>
         /// <seealso cref="started"/>
@@ -1881,14 +1954,31 @@ public unsafe InputActionPhase phase
             /// <remarks>
             /// <example>
             /// <code>
-            /// void FirePerformed(InputAction.CallbackContext context)
+            /// using UnityEngine;
+            /// using UnityEngine.InputSystem;
+            /// using UnityEngine.InputSystem.Interactions;
+            ///
+            /// class Example : MonoBehaviour
             /// {
-            ///     // If SlowTap interaction was performed, perform a charged
-            ///     // firing. Otherwise, fire normally.
-            ///     if (context.interaction is SlowTapInteraction)
-            ///         FireChargedProjectile();
-            ///     else
-            ///         FireNormalProjectile();
+            ///     public InputActionReference fire;
+            ///
+            ///     public void Awake()
+            ///     {
+            ///         fire.action.performed += FirePerformed;
+            ///     }
+            ///
+            ///     void OnEnable() => fire.action.Enable();
+            ///     void OnDisable() => fire.action.Disable();
+            ///
+            ///     void FirePerformed(InputAction.CallbackContext context)
+            ///     {
+            ///          /// If SlowTap interaction was performed, perform a charged
+            ///          /// firing. Otherwise, fire normally.
+            ///          if (context.interaction is SlowTapInteraction)
+            ///              Debug.Log("Fire charged projectile");
+            ///          else
+            ///              Debug.Log("Fire projectile");
+            ///     }
             /// }
             /// </code>
             /// </example>
@@ -2096,6 +2186,44 @@ public unsafe void ReadValue(void* buffer, int bufferSize)
             /// <seealso cref="InputAction.ReadValue{TValue}"/>
             /// <seealso cref="ReadValue(void*,int)"/>
             /// <seealso cref="ReadValueAsObject"/>
+            /// <remarks>
+            /// The following example shows how to read the current value of a specific type:
+            ///
+            /// <example>
+            /// <code>
+            /// using UnityEngine;
+            /// using UnityEngine.InputSystem;
+            ///
+            /// public class Example : MonoBehaviour
+            /// {
+            ///     public InputActionReference move;
+            ///
+            ///     void Awake()
+            ///     {
+            ///         if (move.action != null)
+            ///         {
+            ///             move.action.performed += context =>
+            ///             {
+            ///                 // Note: Assumes the underlying value type is Vector2.
+            ///                 Vector2 value = context.ReadValue&lt;Vector2&gt;();
+            ///                 Debug.Log($"Value is: {value}");
+            ///             };
+            ///         }
+            ///     }
+            ///
+            ///     void OnEnable()
+            ///     {
+            ///         move.action?.Enable();
+            ///     }
+            ///
+            ///     void OnDisable()
+            ///     {
+            ///         move.action?.Disable();
+            ///     }
+            /// }
+            /// </code>
+            /// </example>
+            /// </remarks>
             public TValue ReadValue<TValue>()
                 where TValue : struct
             {
@@ -2119,6 +2247,40 @@ public TValue ReadValue<TValue>()
             /// If the currently active control is a <see cref="ButtonControl"/>, the <see cref="ButtonControl.pressPoint"/>
             /// of the button will be taken into account (if set). If there is no custom button press point, the
             /// global <see cref="InputSettings.defaultButtonPressPoint"/> will be used.
+            /// <example>
+            /// <code>
+            /// using UnityEngine;
+            /// using UnityEngine.InputSystem;
+            ///
+            /// public class Example : MonoBehaviour
+            /// {
+            ///     public InputActionReference fire;
+            ///
+            ///     void Awake()
+            ///     {
+            ///         if (fire.action != null)
+            ///         {
+            ///             fire.action.performed += context =>
+            ///             {
+            ///                 // ReadValueAsButton attempts to interpret the value as a button.
+            ///                 bool value = context.ReadValueAsButton();
+            ///                 Debug.Log($"Button state is: {value}");
+            ///             };
+            ///         }
+            ///     }
+            ///
+            ///     void OnEnable()
+            ///     {
+            ///         fire.action?.Enable();
+            ///     }
+            ///
+            ///     void OnDisable()
+            ///     {
+            ///         fire.action?.Disable();
+            ///     }
+            /// }
+            /// </code>
+            /// </example>
             /// </remarks>
             /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
             /// <seealso cref="ButtonControl.pressPoint"/>
@@ -2131,14 +2293,51 @@ public bool ReadValueAsButton()
             }
 
             /// <summary>
-            /// Same as <see cref="ReadValue{TValue}"/> except that it is not necessary to
-            /// know the type of value at compile time.
+            /// Same as <see cref="ReadValue{TValue}"/> except that it is not necessary to know the type of the value
+            /// at compile time.
             /// </summary>
             /// <returns>The current value from the binding that triggered the action or <c>null</c> if the action
             /// is not currently in progress.</returns>
             /// <remarks>
-            /// This method allocates GC heap memory. Using it during normal gameplay will lead
+            /// This method allocates GC heap memory due to boxing. Using it during normal gameplay will lead
             /// to frame-rate instabilities.
+            /// <example>
+            /// <code>
+            /// using UnityEngine;
+            /// using UnityEngine.InputSystem;
+            ///
+            /// public class Example : MonoBehaviour
+            /// {
+            ///     public InputActionReference move;
+            ///
+            ///     void Awake()
+            ///     {
+            ///         if (move.action != null)
+            ///         {
+            ///             move.action.performed += context =>
+            ///             {
+            ///                 // ReadValueAsObject allows reading the associated value as a boxed reference type.
+            ///                 object obj = context.ReadValueAsObject();
+            ///                 if (obj is Vector2)
+            ///                     Debug.Log($"Current value is Vector2 type: {obj}");
+            ///                 else
+            ///                     Debug.Log($"Current value is of another type: {context.valueType}");
+            ///             };
+            ///         }
+            ///     }
+            ///
+            ///     void OnEnable()
+            ///     {
+            ///         move.action?.Enable();
+            ///     }
+            ///
+            ///     void OnDisable()
+            ///     {
+            ///         move.action?.Disable();
+            ///     }
+            /// }
+            /// </code>
+            /// </example>
             /// </remarks>
             /// <seealso cref="ReadValue{TValue}"/>
             /// <seealso cref="InputAction.ReadValueAsObject"/>