DOCS: Improve Mouse & ButtonControl API docs (#2080)

Author: stefanunity

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

@@ -34,7 +34,6 @@ public class ButtonControl : AxisControl
         /// <summary>
         /// The minimum value the button has to reach for it to be considered pressed.
         /// </summary>
-        /// <value>Button press threshold.</value>
         /// <remarks>
         /// The button is considered pressed, if it has a value equal to or greater than
         /// this value.
@@ -64,7 +63,6 @@ public class ButtonControl : AxisControl
         /// <summary>
         /// Return <see cref="pressPoint"/> if set, otherwise return <see cref="InputSettings.defaultButtonPressPoint"/>.
         /// </summary>
-        /// <value>Effective value to use for press point thresholds.</value>
         public float pressPointOrDefault => pressPoint > 0 ? pressPoint : s_GlobalDefaultButtonPressPoint;
 
         /// <summary>
@@ -106,7 +104,7 @@ public ButtonControl()
         /// <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.
+        /// See <see cref="InputSettings.defaultButtonPressPoint"/> and <see cref="pressPoint"/>for the (default) press point.
         /// </remarks>
         /// <example>
         /// <code>
@@ -143,10 +141,9 @@ public ButtonControl()
         /// <summary>
         /// Whether the button is currently pressed.
         /// </summary>
-        /// <value>True if button is currently pressed.</value>
         /// <remarks>
         /// A button is considered pressed if its value is equal to or greater
-        /// than its button press threshold (<see cref="pressPointOrDefault"/>).
+        /// than its button press threshold (<see cref="pressPointOrDefault"/>, <see cref="pressPoint"/>).
         /// </remarks>
         /// <example>
         /// <para>You can use this to read whether specific keys are currently pressed by using isPressed on keys, as shown in the following examples:</para>
@@ -242,7 +239,6 @@ private void BeginTestingForFramePresses(bool currentlyPressed, bool pressedLast
         /// <summary>
         /// Whether the press started this frame.
         /// </summary>
-        /// <value>True if the current press of the button started this frame.</value>
         /// <remarks>
         /// The first time this function - or wasReleasedThisFrame - are called, it's possible that extremely fast
         /// inputs (or very slow frame update times) will result in presses/releases being missed.
@@ -304,12 +300,12 @@ public bool wasPressedThisFrame
         /// <summary>
         /// Whether the press ended this frame.
         /// </summary>
-        /// <value>True if the current press of the button ended this frame.</value>
         /// <remarks>
         /// _Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use <see cref="InputControl.displayName"/>.
         /// </remarks>
         /// <example>
         /// <para>An example showing the use of this property on a gamepad button and a keyboard key:</para>
+        ///
         /// <code>
         /// using UnityEngine;
         /// using UnityEngine.InputSystem;

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

@@ -171,18 +171,37 @@ namespace UnityEngine.InputSystem
     /// An input device representing a mouse.
     /// </summary>
     /// <remarks>
-    /// Adds a scroll wheel and a typical 3-button setup with a left, middle, and right
-    /// button.
+    /// Adds a scroll wheel and a typical 5-button setup with a left, middle, right,
+    /// forward and backward button.
     ///
     /// To control cursor display and behavior, use <see cref="UnityEngine.Cursor"/>.
     /// </remarks>
+    /// <example>
+    ///
+    /// <code>
+    /// using UnityEngine;
+    /// using UnityEngine.InputSystem;
+    ///
+    /// public class ExampleScript : MonoBehaviour
+    /// {
+    ///     void Update()
+    ///     {
+    ///         // If there is a current mouse and the left button was pressed
+    ///         if (Mouse.current != null &amp;&amp; Mouse.current.leftButton.wasPressedThisFrame)
+    ///         {
+    ///              // handle left mouse button being pressed
+    ///         }
+    ///     }
+    /// }
+    /// </code>
+    /// </example>
+    /// <seealso cref="Pointer"/>
     [InputControlLayout(stateType = typeof(MouseState), isGenericTypeOfDevice = true)]
     public class Mouse : Pointer, IInputStateCallbackReceiver
     {
         /// <summary>
-        /// The horizontal and vertical scroll wheels.
+        /// Control representing horizontal and vertical scroll wheels of a Mouse device.
         /// </summary>
-        /// <value>Control representing the mouse scroll wheels.</value>
         /// <remarks>
         /// The <c>x</c> component corresponds to the horizontal scroll wheel, the
         /// <c>y</c> component to the vertical scroll wheel. Most mice do not have
@@ -191,58 +210,57 @@ public class Mouse : Pointer, IInputStateCallbackReceiver
         public DeltaControl scroll { get; protected set; }
 
         /// <summary>
-        /// The left mouse button.
+        /// Control representing left button of a Mouse device.
         /// </summary>
-        /// <value>Control representing the left mouse button.</value>
         public ButtonControl leftButton { get; protected set; }
 
         /// <summary>
-        /// The middle mouse button.
+        /// Control representing middle button of a Mouse device.
         /// </summary>
-        /// <value>Control representing the middle mouse button.</value>
         public ButtonControl middleButton { get; protected set; }
 
         /// <summary>
-        /// The right mouse button.
+        /// Control representing right button of a Mouse device.
         /// </summary>
-        /// <value>Control representing the right mouse button.</value>
         public ButtonControl rightButton { get; protected set; }
 
         /// <summary>
-        /// The first side button, often labeled/used as "back".
+        /// Control representing the first side button, often labeled/used as "back", of a Mouse device.
         /// </summary>
-        /// <value>Control representing the back button on the mouse.</value>
         /// <remarks>
         /// On Windows, this corresponds to <c>RI_MOUSE_BUTTON_4</c>.
         /// </remarks>
         public ButtonControl backButton { get; protected set; }
 
         /// <summary>
-        /// The second side button, often labeled/used as "forward".
+        /// Control representing the second side button, often labeled/used as "forward", of a Mouse device.
         /// </summary>
-        /// <value>Control representing the forward button on the mouse.</value>
         /// <remarks>
         /// On Windows, this corresponds to <c>RI_MOUSE_BUTTON_5</c>.
         /// </remarks>
         public ButtonControl forwardButton { get; protected set; }
 
         /// <summary>
-        /// Number of times any of the mouse buttons has been clicked in succession within
+        /// Control representing the number of times any of the mouse buttons has been clicked in succession within
         /// the system-defined click time threshold.
         /// </summary>
-        /// <value>Control representing the mouse click count.</value>
         public IntegerControl clickCount { get; protected set;  }
 
         /// <summary>
         /// The mouse that was added or updated last or null if there is no mouse
         /// connected to the system.
         /// </summary>
-        /// <seealso cref="InputDevice.MakeCurrent"/>
+        /// <remarks>
+        /// To set a mouse device as current, use <see cref="Mouse.MakeCurrent"/>.
+        /// </remarks>
         public new static Mouse current { get; private set; }
 
         /// <summary>
         /// Called when the mouse becomes the current mouse.
         /// </summary>
+        /// <remarks>
+        /// This is called automatically by the system when there is input on a connected mouse.
+        /// </remarks>
         public override void MakeCurrent()
         {
             base.MakeCurrent();
@@ -274,7 +292,9 @@ protected override void OnRemoved()
 
         ////REVIEW: how should we handle this being called from EditorWindow's? (where the editor window space processor will turn coordinates automatically into editor window space)
         /// <summary>
-        /// Move the operating system's mouse cursor.
+        /// Move the operating system's mouse cursor by performing a device command 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.
         /// </summary>
         /// <param name="position">New position in player window space.</param>
         /// <remarks>
@@ -313,7 +333,9 @@ protected override void FinishSetup()
         /// <summary>
         /// Implements <see cref="IInputStateCallbackReceiver.OnStateEvent"/> for the mouse.
         /// </summary>
-        /// <param name="eventPtr"></param>
+        /// <param name="eventPtr">Pointer to an <see cref="InputEvent"/>. Makes it easier to
+        /// work with InputEvents and hides the unsafe operations necessary to work with them.
+        /// </param>
         protected new unsafe void OnStateEvent(InputEventPtr eventPtr)
         {
             scroll.AccumulateValueInEvent(currentStatePtr, eventPtr);