DOCS: Improved documentation to comply with standards.

Author: ekcoh

Packages/com.unity.inputsystem/InputSystem/Plugins/EnhancedTouch/Touch.cs

@@ -22,7 +22,7 @@ namespace UnityEngine.InputSystem.EnhancedTouch
     /// and touch phases (<see cref="TouchControl.phase"/>) in order to tell one touch apart from another.
     ///
     /// Also, this class protects against losing touches. If a touch is shorter-lived than a single input update,
-    /// <see cref="Touchscreen"/> may overwrite it with a new touch coming in in the same update whereas this class
+    /// <see cref="Touchscreen"/> may overwrite it with a new touch coming in the same update whereas this class
     /// will retain all changes that happened on the touchscreen in any particular update.
     ///
     /// The API makes a distinction between "fingers" and "touches". A touch refers to one contact state change event, that is, a
@@ -42,167 +42,173 @@ public struct Touch : IEquatable<Touch>
         /// <summary>
         /// Whether this touch record holds valid data.
         /// </summary>
-        /// <value>If true, the data contained in the touch is valid.</value>
         /// <remarks>
         /// Touch data is stored in unmanaged memory as a circular input buffer. This means that when
         /// the buffer runs out of capacity, older touch entries will get reused. When this happens,
         /// existing <c>Touch</c> instances referring to the record become invalid.
-        ///
+        /// <para>
         /// This property can be used to determine whether the record held on to by the <c>Touch</c>
         /// instance is still valid.
-        ///
+        /// </para>
+        /// <para>
         /// This property will be <c>false</c> for default-initialized <c>Touch</c> instances.
-        ///
+        /// </para>
+        /// <para>
         /// Note that accessing most of the other properties on this struct when the touch is
-        /// invalid will trigger <c>InvalidOperationException</c>.
+        /// invalid will trigger <see cref="InvalidOperationException"/>.
+        /// </para>
         /// </remarks>
         public bool valid => m_TouchRecord.valid;
 
         /// <summary>
-        /// The finger used for the touch contact. Null only for default-initialized
-        /// instances of the struct.
+        /// The finger used for the touch contact.
         /// </summary>
-        /// <value>Finger used for the touch contact.</value>
-        /// <seealso cref="activeFingers"/>
+        /// <remarks>
+        /// Note that this is only <c>null</c> for default-initialized instances of the struct.
+        /// <para>
+        /// See <see cref="activeFingers"/> for how to access all active fingers.
+        /// </para>
+        /// </remarks>
         public Finger finger => m_Finger;
 
         /// <summary>
         /// Current phase of the touch.
         /// </summary>
-        /// <value>Current phase of the touch.</value>
         /// <remarks>
         /// Every touch goes through a predefined cycle that starts with <see cref="TouchPhase.Began"/>,
         /// then potentially <see cref="TouchPhase.Moved"/> and/or <see cref="TouchPhase.Stationary"/>,
         /// and finally concludes with either <see cref="TouchPhase.Ended"/> or <see cref="TouchPhase.Canceled"/>.
-        ///
-        /// This property indicates where in the cycle the touch is.
+        /// <para>
+        /// This property indicates where in the cycle the touch is and is based on <see cref="TouchControl.phase"/>.
+        /// </para>
+        /// <para>
+        /// Use <see cref="isInProgress"/> to more conveniently evaluate whether this touch is currently active or not.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="isInProgress"/>
-        /// <seealso cref="TouchControl.phase"/>
         public TouchPhase phase => state.phase;
 
         /// <summary>
         /// Whether the touch has begun this frame, i.e. whether <see cref="phase"/> is <see cref="TouchPhase.Began"/>.
         /// </summary>
-        /// <seealso cref="phase"/>
-        /// <seealso cref="ended"/>
-        /// <seealso cref="inProgress"/>
+        /// <remarks>
+        /// <para>
+        /// Use <see cref="isInProgress"/> to more conveniently evaluate whether this touch is currently active or not.
+        /// </para>
+        /// </remarks>
         public bool began => phase == TouchPhase.Began;
 
         /// <summary>
         /// Whether the touch is currently in progress, i.e. whether <see cref="phase"/> is either
         /// <see cref="TouchPhase.Moved"/>, <see cref="TouchPhase.Stationary"/>, or <see cref="TouchPhase.Began"/>.
         /// </summary>
-        /// <seealso cref="phase"/>
-        /// <seealso cref="began"/>
-        /// <seealso cref="ended"/>
         public bool inProgress => phase == TouchPhase.Moved || phase == TouchPhase.Stationary || phase == TouchPhase.Began;
 
         /// <summary>
         /// Whether the touch has ended this frame, i.e. whether <see cref="phase"/> is either
         /// <see cref="TouchPhase.Ended"/> or <see cref="TouchPhase.Canceled"/>.
         /// </summary>
-        /// <seealso cref="phase"/>
-        /// <seealso cref="began"/>
-        /// <seealso cref="isInProgress"/>
+        /// <remarks>
+        /// Use <see cref="isInProgress"/> to more conveniently evaluate whether this touch is currently active or not.
+        /// </remarks>
         public bool ended => phase == TouchPhase.Ended || phase == TouchPhase.Canceled;
 
         /// <summary>
         /// Unique ID of the touch as (usually) assigned by the platform.
         /// </summary>
-        /// <value>Unique, non-zero ID of the touch.</value>
         /// <remarks>
-        /// Each touch contact that is made with the screen receives its own unique ID which is
-        /// normally assigned by the underlying platform.
-        ///
+        /// Each touch contact that is made with the screen receives its own unique, non-zero ID which is
+        /// normally assigned by the underlying platform via <see cref="TouchControl.touchId"/>.
+        /// <para>
         /// Note a platform may reuse touch IDs after their respective touches have finished.
         /// This means that the guarantee of uniqueness is only made with respect to <see cref="activeTouches"/>.
-        ///
+        /// </para>
+        /// <para>
         /// In particular, all touches in <see cref="history"/> will have the same ID whereas
-        /// touches in the a finger's <see cref="Finger.touchHistory"/> may end up having the same
+        /// touches in the finger's <see cref="Finger.touchHistory"/> may end up having the same
         /// touch ID even though constituting different physical touch contacts.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="TouchControl.touchId"/>
         public int touchId => state.touchId;
 
         /// <summary>
         /// Normalized pressure of the touch against the touch surface.
         /// </summary>
-        /// <value>Pressure level of the touch.</value>
         /// <remarks>
         /// Not all touchscreens are pressure-sensitive. If unsupported, this property will
         /// always return 0.
-        ///
+        /// <para>
         /// In general, touch pressure is supported on mobile platforms only.
-        ///
+        /// </para>
+        /// <para>
+        /// Touch pressure may also be retrieved directly from the device control via <see cref="TouchControl.pressure"/>.
+        /// </para>
+        /// <para>
         /// Note that it is possible for the value to go above 1 even though it is considered normalized. The reason is
         /// that calibration on the system can put the maximum pressure point below the physically supported maximum value.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="TouchControl.pressure"/>
         public float pressure => state.pressure;
 
         /// <summary>
-        /// Screen-space radius of the touch.
+        /// Screen-space radius of the touch which define its horizontal and vertical extents.
         /// </summary>
-        /// <value>Horizontal and vertical extents of the touch contact.</value>
         /// <remarks>
         /// If supported by the underlying device, this reports the size of the touch contact based on its
         /// <see cref="screenPosition"/> center point. If not supported, this will be <c>default(Vector2)</c>.
+        /// <para>
+        /// Touch radius may also be retrieved directly from the device control via <see cref="TouchControl.radius"/>.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="TouchControl.radius"/>
         public Vector2 radius => state.radius;
 
         /// <summary>
-        /// Time in seconds on the same timeline as <c>Time.realTimeSinceStartup</c> when the touch began.
+        /// Start time of the touch in seconds on the same timeline as <c>Time.realTimeSinceStartup</c>.
         /// </summary>
-        /// <value>Start time of the touch.</value>
         /// <remarks>
         /// This is the value of <see cref="InputEvent.time"/> when the touch started with
-        /// <see cref="phase"/> <see cref="TouchPhase.Began"/>.
+        /// <see cref="phase"/> <see cref="TouchPhase.Began"/>. Note that start time may also be retrieved directly
+        /// from the device control via <see cref="TouchControl.startTime"/>.
         /// </remarks>
-        /// <seealso cref="TouchControl.startTime"/>
         public double startTime => state.startTime;
 
         /// <summary>
-        /// Time in seconds on the same timeline as <c>Time.realTimeSinceStartup</c> when the touch record was
-        /// reported.
+        /// Time the touch record was reported on the same timeline as <see cref="UnityEngine.Time.realtimeSinceStartup"/>.
         /// </summary>
-        /// <value>Time the touch record was reported.</value>
         /// <remarks>
         /// This is the value <see cref="InputEvent.time"/> of the event that signaled the current state
         /// change for the touch.
         /// </remarks>
         public double time => m_TouchRecord.time;
 
         /// <summary>
-        /// The touchscreen on which the touch occurred.
+        /// The <see cref="Touchscreen"/> associated with the touch contact.
         /// </summary>
-        /// <value>Touchscreen associated with the touch.</value>
         public Touchscreen screen => finger.screen;
 
         /// <summary>
         /// Screen-space position of the touch.
         /// </summary>
-        /// <value>Screen-space position of the touch.</value>
-        /// <seealso cref="TouchControl.position"/>
+        /// <remarks>Also see <see cref="TouchControl.position"/> for retrieving position directly from a device
+        /// control.</remarks>
         public Vector2 screenPosition => state.position;
 
         /// <summary>
         /// Screen-space position where the touch started.
         /// </summary>
-        /// <value>Start position of the touch.</value>
-        /// <seealso cref="TouchControl.startPosition"/>
+        /// <remarks>Also see <see cref="TouchControl.startPosition"/> for retrieving start position directly from
+        /// a device control.</remarks>
         public Vector2 startScreenPosition => state.startPosition;
 
         /// <summary>
         /// Screen-space motion delta of the touch.
         /// </summary>
-        /// <value>Screen-space motion delta of the touch.</value>
         /// <remarks>
         /// Note that deltas have behaviors attached to them different from most other
         /// controls. See <see cref="Pointer.delta"/> for details.
+        /// <para>
+        /// Also see <see cref="TouchControl.delta"/> for retrieving delta directly from a device control.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="TouchControl.delta"/>
         public Vector2 delta => state.delta;
 
         /// <summary>
@@ -214,8 +220,10 @@ public struct Touch : IEquatable<Touch>
         /// to increase the tap count. I.e. if a new tap finishes within that time after <see cref="startTime"/>
         /// of the previous touch, the tap count is increased by one. If more than <see cref="InputSettings.multiTapDelayTime"/>
         /// passes after a tap with no successive tap, the tap count is reset to zero.
+        /// <para>
+        /// Also see <see cref="TouchControl.tapCount"/> for retrieving tap count directly from a device control.
+        /// </para>
         /// </remarks>
-        /// <seealso cref="TouchControl.tapCount"/>
         public int tapCount => state.tapCount;
 
         /// <summary>
@@ -227,8 +235,9 @@ public struct Touch : IEquatable<Touch>
         /// stays within <see cref="InputSettings.tapRadius"/> of its <see cref="startScreenPosition"/>. If this
         /// is the case for a touch, this button is set to 1 at the time the touch goes to <see cref="phase"/>
         /// <see cref="TouchPhase.Ended"/>.
-        ///
+        /// <para>
         /// Resets to 0 only when another touch is started on the control or when the control is reset.
+        /// </para>
         /// </remarks>
         /// <seealso cref="tapCount"/>
         /// <seealso cref="InputSettings.defaultTapTime"/>
@@ -238,16 +247,21 @@ public struct Touch : IEquatable<Touch>
         /// <summary>
         /// The index of the display containing the touch.
         /// </summary>
-        /// <value>A zero based number representing the display index containing the touch.</value>
-        /// <seealso cref="TouchControl.displayIndex"/>
-        /// <seealso cref="Display"/>
+        /// <remarks>
+        /// A zero based number representing the display index of the <see cref="Display"/> that contains the touch.
+        /// <para>
+        /// Also see <see cref="TouchControl.displayIndex"/> for retrieving display index directly from a device
+        /// control.
+        /// </para>
+        /// </remarks>
         public int displayIndex => state.displayIndex;
 
         /// <summary>
-        /// Whether the touch is currently in progress, i.e. has a <see cref="phase"/> of
-        /// <see cref="TouchPhase.Began"/>, <see cref="TouchPhase.Moved"/>, or <see cref="TouchPhase.Stationary"/>.
+        /// Whether the touch is currently in progress.
         /// </summary>
-        /// <value>Whether the touch is currently ongoing.</value>
+        /// <remarks>This is effectively equivalent to checking if <see cref="phase"/> is equal to either of:
+        /// <see cref="TouchPhase.Began"/>, <see cref="TouchPhase.Moved"/>, or <see cref="TouchPhase.Stationary"/>.
+        /// </remarks>
         public bool isInProgress
         {
             get
@@ -287,7 +301,7 @@ public TouchHistory history
         }
 
         /// <summary>
-        /// All touches that are either on-going as of the current frame or have ended in the current frame.
+        /// All touches that are either ongoing as of the current frame or have ended in the current frame.
         /// </summary>
         /// <remarks>
         /// A touch that begins in a frame will always have its phase set to <see cref="TouchPhase.Began"/> even
@@ -351,14 +365,13 @@ public static ReadOnlyArray<Touch> activeTouches
         /// </summary>
         /// <remarks>
         /// For querying only active fingers, use <see cref="activeFingers"/>.
+        /// For querying only active touches, use <see cref="activeTouches"/>.
         ///
         /// The length of this array will always correspond to the maximum number of concurrent touches supported by the system.
         /// Note that the actual number of physically supported concurrent touches as determined by the current hardware and
         /// operating system may be lower than this number.
         /// </remarks>
         /// <exception cref="InvalidOperationException"><c>EnhancedTouch</c> has not been enabled via <see cref="EnhancedTouchSupport.Enable"/>.</exception>
-        /// <seealso cref="activeTouches"/>
-        /// <seealso cref="activeFingers"/>
         public static ReadOnlyArray<Finger> fingers
         {
             get
@@ -371,9 +384,10 @@ public static ReadOnlyArray<Finger> fingers
         /// <summary>
         /// Set of currently active fingers, i.e. touch contacts that currently have an active touch (as defined by <see cref="activeTouches"/>).
         /// </summary>
+        /// <remarks>
+        /// To instead get a collection of all fingers (not only currently active) use <see cref="fingers"/>.
+        /// </remarks>
         /// <exception cref="InvalidOperationException"><c>EnhancedTouch</c> has not been enabled via <see cref="EnhancedTouchSupport.Enable"/>.</exception>
-        /// <seealso cref="activeTouches"/>
-        /// <seealso cref="fingers"/>
         public static ReadOnlyArray<Finger> activeFingers
         {
             get
@@ -401,9 +415,11 @@ public static IEnumerable<Touchscreen> screens
         /// <summary>
         /// Event that is invoked when a finger touches a <see cref="Touchscreen"/>.
         /// </summary>
+        /// <remarks>
+        /// In order to react to a finger being moved or released, see <see cref="onFingerMove"/> and
+        /// <see cref="onFingerUp"/> respectively.
+        /// </remarks>
         /// <exception cref="InvalidOperationException"><c>EnhancedTouch</c> has not been enabled via <see cref="EnhancedTouchSupport.Enable"/>.</exception>
-        /// <seealso cref="onFingerUp"/>
-        /// <seealso cref="onFingerMove"/>
         public static event Action<Finger> onFingerDown
         {
             add
@@ -425,9 +441,11 @@ public static event Action<Finger> onFingerDown
         /// <summary>
         /// Event that is invoked when a finger stops touching a <see cref="Touchscreen"/>.
         /// </summary>
+        /// <remarks>
+        /// In order to react to a finger that touches a <see cref="Touchscreen"/> or a finger that is being moved
+        /// use <see cref="onFingerDown"/> and <see cref="onFingerMove"/> respectively.
+        /// </remarks>
         /// <exception cref="InvalidOperationException"><c>EnhancedTouch</c> has not been enabled via <see cref="EnhancedTouchSupport.Enable"/>.</exception>
-        /// <seealso cref="onFingerDown"/>
-        /// <seealso cref="onFingerMove"/>
         public static event Action<Finger> onFingerUp
         {
             add
@@ -450,9 +468,11 @@ public static event Action<Finger> onFingerUp
         /// Event that is invoked when a finger that is in contact with a <see cref="Touchscreen"/> moves
         /// on the screen.
         /// </summary>
+        /// <remarks>
+        /// In order to react to a finger that touches a <see cref="Touchscreen"/> or a finger that stops touching
+        /// a <see cref="Touchscreen"/>, use <see cref="onFingerDown"/> and <see cref="onFingerUp"/> respectively.
+        /// </remarks>
         /// <exception cref="InvalidOperationException"><c>EnhancedTouch</c> has not been enabled via <see cref="EnhancedTouchSupport.Enable"/>.</exception>
-        /// <seealso cref="onFingerUp"/>
-        /// <seealso cref="onFingerDown"/>
         public static event Action<Finger> onFingerMove
         {
             add
@@ -501,6 +521,7 @@ internal Touch(Finger finger, InputStateHistory<TouchState>.Record touchRecord)
             m_TouchRecord = touchRecord;
         }
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             if (!valid)
@@ -509,16 +530,19 @@ public override string ToString()
             return $"{{id={touchId} finger={finger.index} phase={phase} position={screenPosition} delta={delta} time={time}}}";
         }
 
+        /// <inheritdoc/>
         public bool Equals(Touch other)
         {
             return Equals(m_Finger, other.m_Finger) && m_TouchRecord.Equals(other.m_TouchRecord);
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             return obj is Touch other && Equals(other);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             unchecked