Adding more summary comments to MRTK3 types and members (microsoft#11622

)

Adding more summary and remark comments to MRTK3 types and members

com.microsoft.mrtk.core/Subsystems/Speech/DictationSubsystem.cs

@@ -8,7 +8,7 @@
 namespace Microsoft.MixedReality.Toolkit.Subsystems
 {
     /// <summary>
-    /// A subsystem that enables dictation.
+    /// A Unity subsystem that enables dictation.
     /// </summary>
     [Preserve]
     public class DictationSubsystem :

com.microsoft.mrtk.input/Interactors/InteractorVisuals/MRTKRayReticleVisual.cs

@@ -36,7 +36,7 @@ public class MRTKRayReticleVisual : BaseReticleVisual
         private Vector3 reticleNormal;
 
         /// <summary>
-        /// Determines whether a reticle should appear on all surfaces hit by the interactor or interactables only
+        /// Determines whether a reticle should appear on all surfaces hit by the interactor or interactables only.
         /// </summary>
         public ReticleVisibilitySettings VisibilitySettings
         {
@@ -173,9 +173,20 @@ private void LocateTargetHitPoint(SelectEnterEventArgs args)
             }
         }
 
+        /// <summary>
+        /// An enumeration used to control when a <see cref="Microsoft.MixedReality.Toolkit.Input.MRTKRayReticleVisual">MRTKRayReticleVisual</see> 
+        /// is visible. 
+        /// </summary>
         public enum ReticleVisibilitySettings
         {
+            /// <summary>
+            /// The reticle is only visible when it intersects an interactable object.
+            /// </summary> 
             InteractablesOnly,
+
+            /// <summary>
+            /// The reticle is visible anytime it intersects with another object, regardless of it being interactable.
+            /// </summary>
             AllValidSurfaces
         }
     }

com.microsoft.mrtk.input/Simulation/Devices/ControllerSimulationSettings.cs

@@ -52,9 +52,18 @@ public ControllerAnchorPoint AnchorPoint
         [Tooltip("The input action used to toggle between using the default or Secondary Handshape settings.")]
         private InputActionReference toggleSecondaryHandshapes;
 
-        [Obsolete("Use ChangeNeutralHandshape instead")]
+        /// <summary>
+        /// The input action used to toggle between using the default or Secondary Handshape settings.
+        /// </summary>
+        /// <remarks>
+        /// This property is deprecated, use <see cref="ToggleSecondaryHandshapes"/> instead.
+        /// </remarks>
+        [Obsolete("This property is deprecated, use ToggleSecondaryHandshapes instead.")]
         public InputActionReference ChangeNeutralPose => ToggleSecondaryHandshapes;
 
+        /// <summary>
+        /// The input action used to toggle between using the default or Secondary Handshape settings.
+        /// </summary>
         public InputActionReference ToggleSecondaryHandshapes
         {
             get => toggleSecondaryHandshapes;

com.microsoft.mrtk.input/Subsystems/SyntheticHands/SyntheticHandsConfig.cs

@@ -6,6 +6,11 @@
 
 namespace Microsoft.MixedReality.Toolkit.Input
 {
+    /// <summary>
+    /// A configuration object for <see cref="Microsoft.MixedReality.Toolkit.Input.SyntheticHandsSubsystem">SyntheticHandsSubsystem</see>.
+    /// This class defines the Unity input actions that <see cref="Microsoft.MixedReality.Toolkit.Input.SyntheticHandsSubsystem">SyntheticHandsSubsystem</see>
+    /// uses when simulating articulated hands.
+    /// </summary>
     [CreateAssetMenu(fileName = "MRTKSyntheticHandsConfig.asset", menuName = "MRTK/Subsystems/MRTK Synthetic Hands Config")]
     public class SyntheticHandsConfig : BaseSubsystemConfig
     {

com.microsoft.mrtk.input/Subsystems/SyntheticHands/SyntheticHandsSubsystem.cs

@@ -14,6 +14,9 @@
 
 namespace Microsoft.MixedReality.Toolkit.Input
 {
+    /// <summary>
+    /// A Unity subsystem that enables articulated hand simulation.
+    /// </summary>    
     [Preserve]
     [MRTKSubsystem(
         Name = "com.microsoft.mixedreality.synthhands",
@@ -25,6 +28,10 @@ namespace Microsoft.MixedReality.Toolkit.Input
     public class SyntheticHandsSubsystem : HandsSubsystem
     {
         private SyntheticHandsProvider syntheticProvider;
+
+        /// <summary>
+        /// Get the subsystem provider for this object.
+        /// </summary>
         private SyntheticHandsProvider SyntheticProvider
         {
             get
@@ -392,6 +399,10 @@ private static void MirrorJoint(ref HandJointPose pose)
             }
         }
 
+        /// <summary>
+        /// A subsystem provider for <see cref="SyntheticHandsSubsystem"/> that provides methods for getting and setting
+        /// the simulated hand poses, as well as methods for obtain hand joint poses.
+        /// </summary>
         [Preserve]
         class SyntheticHandsProvider : Provider
         {

com.microsoft.mrtk.spatialmanipulation/Constraints/FixedDistanceConstraint.cs

@@ -7,9 +7,12 @@ namespace Microsoft.MixedReality.Toolkit.SpatialManipulation
 {
     /// <summary>
     /// Component for setting the min/max scale values for ObjectManipulator
-    /// or BoundsControl
-    /// We're looking to rework this system in the future. These existing components will be deprecated then.
+    /// or BoundsControl.
     /// </summary>
+    /// <remarks>
+    /// MRTK's constraint system might be redesigned in the near future. When
+    /// this occurs, the old constraint components will be deprecated.
+    /// </remarks>
     public class FixedDistanceConstraint : TransformConstraint
     {
         #region Properties
@@ -27,6 +30,7 @@ public Transform ConstraintTransform
             set => constraintTransform = value;
         }
 
+        /// <inheritdoc />
         public override TransformFlags ConstraintType => TransformFlags.Move;
 
         private float distanceAtManipulationStart;
@@ -35,7 +39,7 @@ public Transform ConstraintTransform
 
         #region MonoBehaviour Methods
 
-        public void Start()
+        private void Start()
         {
             EnsureConstraintTransform();
         }

com.microsoft.mrtk.spatialmanipulation/Constraints/FixedRotationToUserConstraint.cs

@@ -6,13 +6,17 @@
 namespace Microsoft.MixedReality.Toolkit.SpatialManipulation
 {
     /// <summary>
-    /// Component for fixing the rotation of a manipulated object relative to the user
-    /// We're looking to rework this system in the future. These existing components will be deprecated then.
+    /// Component for fixing the rotation of a manipulated object relative to the user.
     /// </summary>
+    /// <remarks>
+    /// MRTK's constraint system might be redesigned in the near future. When
+    /// this occurs, the old constraint components will be deprecated.
+    /// </remarks>
     public class FixedRotationToUserConstraint : TransformConstraint
     {
         #region Properties
 
+        /// <inheritdoc />
         public override TransformFlags ConstraintType => TransformFlags.Rotate;
 
         private Quaternion startObjectRotationCameraSpace;

com.microsoft.mrtk.spatialmanipulation/Constraints/FixedRotationToWorldConstraint.cs

@@ -4,13 +4,17 @@
 namespace Microsoft.MixedReality.Toolkit.SpatialManipulation
 {
     /// <summary>
-    /// Component for fixing the rotation of a manipulated object relative to the world
-    /// We're looking to rework this system in the future. These existing components will be deprecated then.
+    /// Component for fixing the rotation of a manipulated object relative to the world.
     /// </summary>
+    /// <remarks>
+    /// MRTK's constraint system might be redesigned in the near future. When
+    /// this occurs, the old constraint components will be deprecated.
+    /// </remarks>
     public class FixedRotationToWorldConstraint : TransformConstraint
     {
         #region Properties
 
+        /// <inheritdoc />
         public override TransformFlags ConstraintType => TransformFlags.Rotate;
 
         #endregion Properties

com.microsoft.mrtk.spatialmanipulation/Constraints/MaintainApparentSizeConstraint.cs

@@ -7,15 +7,19 @@ namespace Microsoft.MixedReality.Toolkit.SpatialManipulation
 {
     /// <summary>
     /// Component for setting the min/max scale values for ObjectManipulator
-    /// or BoundsControl
-    /// We're looking to rework this system in the future. These existing components will be deprecated then.
+    /// or BoundsControl.
     /// </summary>
+    /// <remarks>
+    /// MRTK's constraint system might be redesigned in the near future. When
+    /// this occurs, the old constraint components will be deprecated.
+    /// </remarks>
     public class MaintainApparentSizeConstraint : TransformConstraint
     {
         #region Properties
 
         private float initialDist;
 
+        /// <inheritdoc />
         public override TransformFlags ConstraintType => TransformFlags.Scale;
 
         #endregion Properties

com.microsoft.mrtk.spatialmanipulation/Constraints/MoveAxisConstraint.cs

@@ -7,9 +7,12 @@ namespace Microsoft.MixedReality.Toolkit.SpatialManipulation
 {
     /// <summary>
     /// Component for limiting the translation axes for ObjectManipulator
-    /// or BoundsControl
-    /// We're looking to rework this system in the future. These existing components will be deprecated then.
+    /// or BoundsControl.
     /// </summary>
+    /// <remarks>
+    /// MRTK's constraint system might be redesigned in the near future. When
+    /// this occurs, the old constraint components will be deprecated.
+    /// </remarks>
     public class MoveAxisConstraint : TransformConstraint
     {
         #region Properties
@@ -41,6 +44,7 @@ public bool UseLocalSpaceForConstraint
             set => useLocalSpaceForConstraint = value;
         }
 
+        /// <inheritdoc />
         public override TransformFlags ConstraintType => TransformFlags.Move;
 
         #endregion Properties

com.microsoft.mrtk.spatialmanipulation/Constraints/TransformConstraint.cs

@@ -74,6 +74,9 @@ public int ExecutionPriority
         /// </summary>
         protected MixedRealityTransform InitialWorldPose;
 
+        /// <summary>
+        /// Get flags that describe the type of transformations this constraint applies to.
+        /// </summary> 
         public abstract TransformFlags ConstraintType { get; }
 
         #endregion Properties

com.microsoft.mrtk.uxcore/Button/BasicPressableButtonVisuals.cs

@@ -6,8 +6,8 @@
 namespace Microsoft.MixedReality.Toolkit.UX
 {
     /// <summary>
-    /// A simple visuals script to provide a visual layer on top of
-    /// <see cref="PressableButton"/>.
+    /// A simple visuals script to provide a visual layer on top of a 
+    /// <see cref="Microsoft.MixedReality.Toolkit.UX.PressableButton">PressableButton</see>.
     /// </summary>
     [RequireComponent(typeof(PressableButton))]
     [ExecuteAlways]
@@ -17,23 +17,27 @@ public class BasicPressableButtonVisuals : MonoBehaviour
         private PressableButton buttonState;
 
         [SerializeField]
+        [Tooltip("The front plate object that will move with the button displacement.")]
         private Transform movingVisuals;
 
         /// <summary>
         /// The "front plate" object that will move with the button displacement.
         /// </summary>
         public Transform MovingVisuals => movingVisuals;
 
-        protected void Awake()
+        private void Awake()
         {
             buttonState = GetComponent<PressableButton>();
         }
 
-        protected void LateUpdate()
+        private void LateUpdate()
         {
             UpdateMovingVisualsPosition();
         }
 
+        /// <summary>
+        /// Update the local position of the specified <see cref="MovingVisuals"/> transform.
+        /// </summary>
         protected virtual void UpdateMovingVisualsPosition()
         {
             if (movingVisuals != null)

com.microsoft.mrtk.uxcore/Button/PressableButton.cs

@@ -29,11 +29,18 @@ public class PressableButton : StatefulInteractable
         public bool SmoothSelectedness { get => smoothSelectedness; set => smoothSelectedness = value; }
 
         /// <summary>
-        /// Enum for defining space of plane distances.
+        /// An enumeration defining the coordinate space of plane distances.
         /// </summary>
         public enum SpaceMode
         {
+            /// <summary>
+            /// The world coordinate space system should be used.
+            // </summary>
             World,
+
+            /// <summary>
+            /// The button's local coordinate space system should be used.
+            // </summary>
             Local
         }
 

com.microsoft.mrtk.uxcore/Dialog/Dialog.cs

@@ -19,7 +19,13 @@ namespace Microsoft.MixedReality.Toolkit.UX
     /// <summary>
     /// The Dialog script hydrates and controls the various sub-components
     /// of the dialog view.
-    /// </summary>
+    /// </summary> 
+    /// <remarks>
+    /// Dialogs are typically spawned, pooled, and killed
+    /// by <see cref="Microsoft.MixedReality.Toolkit.UX.DialogPool">DialogPools</see>. 
+    /// Generally, developers should not directly manage or instantiate instances of their dialogs,
+    /// as it is essential that they are pooled and managed correctly by a pooler.
+    /// </remarks>
     [AddComponentMenu("MRTK/UX/Dialog")]
     public class Dialog : MonoBehaviour, IDialog
     {

com.microsoft.mrtk.uxcore/Dialog/DialogEvents.cs

@@ -21,10 +21,8 @@ public abstract class BaseDialogEventArgs
     }
 
     /// <summary>
-    /// Button events emit these parameters. For subclassed dialogs
-    /// with custom buttons or other types of events, return
-    /// a <see cref="DialogButtonType.Other"/> with some additional
-    /// context in a subclassed <see cref="DialogButtonEventArgs" type.
+    /// Event arguments used when buttons in a <see cref="Microsoft.MixedReality.Toolkit.UX.IDialog">IDialog</see>
+    /// are clicked or activated.
     /// </summary>
     public class DialogButtonEventArgs : BaseDialogEventArgs
     {
@@ -45,6 +43,10 @@ public class DialogButtonEventArgs : BaseDialogEventArgs
         public string ButtonText { get; set; }
     }
 
+    /// <summary>
+    /// Event arguments used a <see cref="Microsoft.MixedReality.Toolkit.UX.IDialog">IDialog</see>
+    /// is dismissed or closed.
+    /// </summary>
     public class DialogDismissedEventArgs : BaseDialogEventArgs
     {
         /// <summary>
@@ -53,5 +55,4 @@ public class DialogDismissedEventArgs : BaseDialogEventArgs
         /// </summary>
         public DialogButtonEventArgs Choice { get; set; }
     }
-
 }

com.microsoft.mrtk.uxcore/Dialog/DialogPool.cs

@@ -15,8 +15,8 @@
 namespace Microsoft.MixedReality.Toolkit.UX
 {
     /// <summary>
-    /// Spawns dialogs with the requested parameters and manages
-    /// the lifecycle of the resulting dialog component.
+    /// Spawns <see cref="Microsoft.MixedReality.Toolkit.UX.IDialog">IDialog</see> with the requested parameters and manages
+    /// the lifecycle of the resulting <see cref="Microsoft.MixedReality.Toolkit.UX.IDialog">IDialog</see> component.
     /// </summary>
     [ExecuteAlways]
     [AddComponentMenu("MRTK/UX/Dialog Pool")]
@@ -36,9 +36,10 @@ public enum Policy
         }
 
         /// <summary>
-        /// The default prefab to instantiate when spawning a dialog.
+        /// The default prefab to instantiate when spawning a dialog. This prefab must
+        /// contain a <see cref="Microsoft.MixedReality.Toolkit.UX.IDialog">IDialog</see> component.
         /// </summary>
-        [field: SerializeField, Tooltip("The default prefab to instantiate when spawning a dialog.")]
+        [field: SerializeField, Tooltip("The default prefab to instantiate when spawning a dialog. This prefab must contain a IDialog component.")]
         public GameObject DialogPrefab { get; set; }
 
         // Static reference to the dialog instance, if active and spawned.

com.microsoft.mrtk.uxcore/Dialog/IDialog.cs

@@ -30,11 +30,14 @@ public enum DialogButtonType
 
     /// <summary>
     /// An IDialog hydrates and controls the various sub-components
-    /// of the dialog view. IDialogs are spawned, pooled, and killed
-    /// by DialogPools. Generally, developers should not directly
-    /// manage or instantiate instances of their dialogs, as it is
-    /// essential that they are pooled and managed correctly by a pooler.
+    /// of the dialog view.
     /// </summary>
+    /// <remarks>
+    /// IDialogs are typically spawned, pooled, and killed
+    /// by <see cref="Microsoft.MixedReality.Toolkit.UX.DialogPool">DialogPools</see>. 
+    /// Generally, developers should not directly manage or instantiate instances of their dialogs,
+    /// as it is essential that they are pooled and managed correctly by a pooler.
+    /// </remarks>
     public interface IDialog
     {
         /// <summary>