Merge branch 'develop' into docs-quality-week-2024-inputstatehistory

Author: lyndon-unity

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

@@ -10,7 +10,7 @@ namespace UnityEngine.InputSystem.Controls
     /// An axis that has a trigger point beyond which it is considered to be pressed.
     /// </summary>
     /// <remarks>
-    /// By default stored as a single bit. In that format, buttons will only yield 0
+    /// By default, stored as a single bit. In that format, buttons will only yield 0
     /// and 1 as values. However, buttons return are <see cref="AxisControl"/>s and
     /// yield full floating-point values and may thus have a range of values. See
     /// <see cref="pressPoint"/> for how button presses on such buttons are handled.
@@ -46,6 +46,9 @@ public class ButtonControl : AxisControl
         ///
         /// <example>
         /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem.Controls;
+        ///
         /// public class MyDevice : InputDevice
         /// {
         ///     [InputControl(parameters = "pressPoint=0.234")]
@@ -56,25 +59,38 @@ public class ButtonControl : AxisControl
         /// </code>
         /// </example>
         /// </remarks>
-        /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
-        /// <seealso cref="pressPointOrDefault"/>
-        /// <seealso cref="isPressed"/>
         public float pressPoint = -1;
 
         /// <summary>
         /// Return <see cref="pressPoint"/> if set, otherwise return <see cref="InputSettings.defaultButtonPressPoint"/>.
         /// </summary>
         /// <value>Effective value to use for press point thresholds.</value>
-        /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
         public float pressPointOrDefault => pressPoint > 0 ? pressPoint : s_GlobalDefaultButtonPressPoint;
 
         /// <summary>
-        /// Default-initialize the control.
+        /// Default-initialize the button control.
         /// </summary>
         /// <remarks>
-        /// The default format for the control is <see cref="InputStateBlock.FormatBit"/>.
-        /// The control's minimum value is set to 0 and the maximum value to 1.
+        /// The default format for the button control is <see cref="InputStateBlock.FormatBit"/>.
+        /// The button control's minimum value is set to 0 and the maximum value to 1.
         /// </remarks>
+        /// <example>
+        /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem.Controls;
+        ///
+        /// public class ButtonControlExample : MonoBehaviour
+        /// {
+        ///     void Start()
+        ///     {
+        ///         var myButton = new ButtonControl();
+        ///     }
+        ///
+        ///     //...
+        /// }
+        /// </code>
+        /// </example>
+        /// <seealso cref="AxisControl"/>
         public ButtonControl()
         {
             m_StateBlock.format = InputStateBlock.FormatBit;
@@ -85,10 +101,39 @@ public ButtonControl()
         /// <summary>
         /// Whether the given value would be considered pressed for this button.
         /// </summary>
-        /// <param name="value">Value for the button.</param>
+        /// <param name="value">Value to check for if the button would be considered pressed or not.</param>
         /// <returns>True if <paramref name="value"/> crosses the threshold to be considered pressed.</returns>
-        /// <seealso cref="pressPoint"/>
-        /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
+        /// <remarks>
+        /// The default format for the control is <see cref="InputStateBlock.FormatBit"/>.
+        /// The control's minimum value is set to 0 and the maximum value to 1.
+        /// See <see cref="InputSettings.defaultButtonPressPoint"/> for the default press point.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem.Controls;
+        ///
+        /// public class IsValueConsideredPressedExample : MonoBehaviour
+        /// {
+        ///     void Start()
+        ///     {
+        ///         var myButton = new ButtonControl();
+        ///         var valueToTest = 0.5f;
+        ///
+        ///         if (myButton.IsValueConsideredPressed(valueToTest))
+        ///         {
+        ///             Debug.Log("myButton is considered pressed at: " + valueToTest.ToString());
+        ///         }
+        ///         else
+        ///         {
+        ///             Debug.Log("myButton is not considered pressed at: " + valueToTest.ToString());
+        ///         }
+        ///     }
+        ///
+        ///     //...
+        /// }
+        /// </code>
+        /// </example>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public new bool IsValueConsideredPressed(float value)
         {
@@ -149,9 +194,6 @@ public ButtonControl()
         /// ]]>
         /// </code>
         /// </example>
-        /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
-        /// <seealso cref="pressPoint"/>
-        /// <seealso cref="InputSystem.onAnyButtonPress"/>
         public bool isPressed
         {
             get
@@ -276,8 +318,8 @@ public bool wasPressedThisFrame
         /// {
         ///     void Update()
         ///     {
-        ///         bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame;
-        ///         bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame;
+        ///         bool buttonReleased = Gamepad.current.aButton.wasReleasedThisFrame;
+        ///         bool spaceKeyReleased = Keyboard.current.spaceKey.wasReleasedThisFrame;
         ///     }
         /// }
         /// </code>

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

@@ -22,10 +22,10 @@ namespace UnityEngine.InputSystem
     public class InputValue
     {
         /// <summary>
-        /// Read the value as an object.
+        /// Read the current value as an object.
         /// </summary>
         /// <remarks>
-        /// This method allocates GC memory and will thus created garbage. If used during gameplay,
+        /// This method allocates GC memory and will thus create garbage. If used during gameplay,
         /// it will lead to GC spikes.
         /// </remarks>
         /// <returns>The current value in the form of a boxed object.</returns>
@@ -35,6 +35,45 @@ public object Get()
         }
 
         ////TODO: add automatic conversions
+        /// <summary>
+        /// Read the current value of the action.
+        /// </summary>
+        /// <returns>The current value from the action cast to the specified type.</returns>
+        /// <typeparam name="TValue">Type of value to read. This must correspond to the
+        /// <see cref="InputControl.valueType"/> of the action or, if it is a composite, by the
+        /// <see cref="InputBindingComposite.valueType"/>.
+        /// The type depends on what type of controls the action is bound to.
+        /// Common types are <c>float</c> and <see cref="UnityEngine.Vector2"/></typeparam>
+        /// <exception cref="InvalidOperationException">The given type <typeparamref name="TValue"/>
+        /// does not match the value type expected by the control or binding composite.</exception>
+        /// <remarks>
+        /// The following example shows how to read a value from a <see cref="PlayerInput"/> message.
+        /// The given <c>InputValue</c> is only valid for the duration of the callback. Storing the <c>InputValue</c> references somewhere and calling Get&lt;T&gt;() later does not work correctly.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem;
+        /// [RequireComponent(typeof(PlayerInput))]
+        /// public class MyPlayerLogic : MonoBehaviour
+        /// {
+        ///     private Vector2 m_Move;
+        ///
+        ///     // 'Move' input action has been triggered.
+        ///     public void OnMove(InputValue value)
+        ///     {
+        ///         // Read value from control. The type depends on what type of controls the action is bound to.
+        ///         m_Move = value.Get&lt;Vector2&gt;();
+        ///     }
+        ///
+        ///     public void Update()
+        ///     {
+        ///         // Update transform from m_Move
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
+        /// <seealso cref="InputAction.CallbackContext.ReadValue{TValue}"/>
         public TValue Get<TValue>()
             where TValue : struct
         {
@@ -45,6 +84,34 @@ public TValue Get<TValue>()
         }
 
         ////TODO: proper message if value type isn't right
+        /// <summary>
+        /// Check if the action button is pressed.
+        /// </summary>
+        /// <remarks>
+        /// True if the button is activated over the button threshold. False otherwise
+        /// The following example check if a button is pressed when receiving a <see cref="PlayerInput"/> message.
+        /// The given <c>InputValue</c> is only valid for the duration of the callback. Storing the <c>InputValue</c> references somewhere and calling Get&lt;T&gt;() later does not work correctly.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// [RequireComponent(typeof(PlayerInput))]
+        /// public class MyPlayerLogic : MonoBehaviour
+        /// {
+        ///     // 'Fire' input action has been triggered.
+        ///     public void OnFire(InputValue value)
+        ///     {
+        ///         if (value.isPressed)
+        ///             FireWeapon();
+        ///     }
+        ///
+        ///     public void FireWeapon()
+        ///     {
+        ///         // Weapon firing code
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
+        /// <seealso cref="ButtonControl.pressPointOrDefault"/>
         public bool isPressed => Get<float>() >= ButtonControl.s_GlobalDefaultButtonPressPoint;
 
         internal InputAction.CallbackContext? m_Context;