Addressing PR feedback...and fixing some dialog comments

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/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>

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

@@ -16,13 +16,13 @@ namespace Microsoft.MixedReality.Toolkit.UX.Deprecated
     /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
     /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
     /// </remarks>
-    [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog system.")]
+    [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
     public abstract class Dialog : MonoBehaviour
     {
         /// <summary>
         /// The current state of the dialog.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog system.")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public DialogState State { get; protected set; } = DialogState.Uninitialized;
 
         /// <summary>

com.microsoft.mrtk.uxcore/LegacyDialog/DialogButton.cs

@@ -10,7 +10,14 @@ namespace Microsoft.MixedReality.Toolkit.UX.Deprecated
     /// <summary>
     /// Handling click event and dismiss dialog
     /// </summary>
-    [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+    /// <remarks>
+    /// This and the <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog>Legacy Dialog</see> are deprecated. Please migrate to the 
+    /// new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see>. If you'd like to continue using the 
+    /// <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog">Legacy Dialog</see> implementation, it is recommend that the legacy code 
+    /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
+    /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
+    /// </remarks>
+    [SerializeField, Tooltip("The TextMeshPro component for displaying text on the button itself.")]
     public class DialogButton : MonoBehaviour
     {
         [SerializeField, Tooltip("The TextMeshPro component for displaying text on the button itself.")]
@@ -19,7 +26,7 @@ public class DialogButton : MonoBehaviour
         /// <summary>
         /// The TextMeshPro component for displaying text on the button itself.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public TMP_Text ButtonText
         {
             get => buttonText;
@@ -29,13 +36,13 @@ public TMP_Text ButtonText
         /// <summary>
         /// A reference to the Dialog that this button is on.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public Dialog ParentDialog { get; set; }
 
         /// <summary>
         /// The type description of the button.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public DialogButtonTypes ButtonTypeEnum => DialogProperty.Convert(ButtonContext.ButtonType);
 
         [SerializeField, Tooltip("The type description of the button.")]
@@ -44,7 +51,7 @@ public TMP_Text ButtonText
         /// <summary>
         /// The context, including type and an optional label, of the button.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public DialogButtonContext ButtonContext => buttonContext;
 
         private void OnValidate()
@@ -56,7 +63,7 @@ private void OnValidate()
         /// Event handler that runs when button is clicked.
         /// Dismisses the parent dialog.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public void OnButtonClicked()
         {
             if (ParentDialog != null)
@@ -73,7 +80,7 @@ public void OnButtonClicked()
         /// Sets the label text on the button.
         /// </summary>
         /// <param name="label">New label text for the button.</param>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public void SetLabel(string label)
         {
             buttonContext.Label = label;
@@ -88,7 +95,7 @@ public void SetLabel(string label)
         /// Sets the button context and the label text on the button.
         /// </summary>
         /// <param name="buttonContext">New button context for this button.</param>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public void SetButtonContext(DialogButtonContext buttonContext)
         {
             this.buttonContext = buttonContext;

com.microsoft.mrtk.uxcore/LegacyDialog/DialogButtonContext.cs

@@ -9,11 +9,18 @@ namespace Microsoft.MixedReality.Toolkit.UX.Deprecated
     /// <summary>
     /// Represents a button with its type and an optional custom label.
     /// </summary>
+    /// <remarks>
+    /// This and the <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog>Legacy Dialog</see> are deprecated. Please migrate to the 
+    /// new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see>. If you'd like to continue using the 
+    /// <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog">Legacy Dialog</see> implementation, it is recommend that the legacy code 
+    /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
+    /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
+    /// </remarks>
     [Serializable]
-    [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+    [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
     public struct DialogButtonContext
     {
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public DialogButtonContext(DialogButtonType buttonType, string label = null)
         {
             ButtonType = buttonType;
@@ -24,15 +31,15 @@ public DialogButtonContext(DialogButtonType buttonType, string label = null)
         /// The type of this button.
         /// </summary>
         [field: SerializeField, Tooltip("The type of this button.")]
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public DialogButtonType ButtonType { get; internal set; }
 
         /// <summary>
         /// The optional label for this button.
         /// </summary>
         /// <remarks>If none is provided, the string representation of <see cref="ButtonType"/> will be used.</remarks>
         [field: SerializeField, Tooltip("The optional label for this button. If none is provided, the string representation of Button Type will be used.")]
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public string Label { get; internal set; }
     }
 }

com.microsoft.mrtk.uxcore/LegacyDialog/DialogButtonHelpers.cs

@@ -8,24 +8,32 @@ namespace Microsoft.MixedReality.Toolkit.UX.Deprecated
     /// <summary>
     /// Provides a pre-defined set of button contexts for ease of dialog creation.
     /// </summary>
+    /// <remarks>
+    /// This and the <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog>Legacy Dialog</see> are deprecated. Please migrate to the 
+    /// new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see>. If you'd like to continue using the 
+    /// <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog">Legacy Dialog</see> implementation, it is recommend that the legacy code 
+    /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
+    /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
+    /// </remarks>
+    [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
     public static class DialogButtonHelpers
     {
         /// <summary>
         /// Represents a single OK button.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public static DialogButtonContext[] OK { get; } = new DialogButtonContext[] { new DialogButtonContext(DialogButtonType.OK) };
 
         /// <summary>
         /// Represents a pair of OK and Cancel buttons.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public static DialogButtonContext[] OKCancel { get; } = new DialogButtonContext[] { new DialogButtonContext(DialogButtonType.OK), new DialogButtonContext(DialogButtonType.Cancel) };
 
         /// <summary>
         /// Represents a pair of Yes and No buttons.
         /// </summary>
-        [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+        [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
         public static DialogButtonContext[] YesNo { get; } = new DialogButtonContext[] { new DialogButtonContext(DialogButtonType.Yes), new DialogButtonContext(DialogButtonType.No) };
     }
 }

com.microsoft.mrtk.uxcore/LegacyDialog/DialogButtonTypes.cs

@@ -15,7 +15,7 @@ namespace Microsoft.MixedReality.Toolkit.UX.Deprecated
     /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
     /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
     /// </remarks>
-    [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog system.")]
+    [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
     public enum DialogButtonType
     {
         /// <summary>
@@ -24,55 +24,93 @@ public enum DialogButtonType
         None = 0,
 
         /// <summary>
-        /// Represent a close dialog button.
+        /// Represents a close dialog button.
         /// </summary>
         Close = 1,
 
         /// <summary>
-        /// Represent a confirmation dialog button.
+        /// Represents a confirmation dialog button.
         /// </summary>
         Confirm = 2,
 
         /// <summary>
-        /// Represent a cancel dialog button.
+        /// Represents a cancel dialog button.
         /// </summary>
         Cancel = 3,
 
         /// <summary>
-        /// Represent an accept dialog button.
+        /// Represents an accept dialog button.
         /// </summary>
         Accept = 4,
 
         /// <summary>
-        /// Represent a "yes" dialog button.
+        /// Represents a "yes" dialog button.
         /// </summary>
         Yes = 5,
 
         /// <summary>
-        /// Represent a "no" dialog button.
+        /// Represents a "no" dialog button.
         /// </summary>
         No = 6,
 
         /// <summary>
-        /// Represent an "okay" dialog button.
+        /// Represents an "okay" dialog button.
         /// </summary>
         OK = 7,
     }
 
     /// <summary>
-    /// The style of button on a dialog.
+    /// The style of a legacy dialog button.
     /// </summary>
+    /// <remarks>
+    /// This and the <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog>Legacy Dialog</see> are deprecated. Please migrate to the 
+    /// new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see>. If you'd like to continue using the 
+    /// <see cref="Microsoft.MixedReality.Toolkit.UX.Deprecated.Dialog">Legacy Dialog</see> implementation, it is recommend that the legacy code 
+    /// be copied to the application's code base, and maintained independently by the application developer. Otherwise, it is strongly recommended 
+    /// that the application be updated to use the new <see cref="Microsoft.MixedReality.Toolkit.UX.Dialog">Dialog</see> system.
+    /// </remarks>
     [Flags]
-    [Obsolete("Legacy Dialog is deprecated. Please migrate to the new Dialog. See uxcore/LegacyDialog/README.md")]
+    [Obsolete("This legacy dialog system has been deprecated. Please migrate to the new dialog system, see Microsoft.MixedReality.Toolkit.UX.DialogPool for more details.")]
     public enum DialogButtonTypes
     {
+        /// <summary>
+        /// No button style has been specified.
+        /// </summary>
         None = 0 << 0,
+
+        /// <summary>
+        /// Represents a close dialog button.
+        /// </summary>
         Close = 1 << 0,
+
+        /// <summary>
+        /// Represents a confirmation dialog button.
+        /// </summary>
         Confirm = 1 << 1,
+
+        /// <summary>
+        /// Represents a cancel dialog button.
+        /// </summary>
         Cancel = 1 << 2,
+
+        /// <summary>
+        /// Represents an accept dialog button.
+        /// </summary>
         Accept = 1 << 3,
+
+        /// <summary>
+        /// Represents a "yes" dialog button.
+        /// </summary>
         Yes = 1 << 4,
+
+        /// <summary>
+        /// Represents a "no" dialog button.
+        /// </summary>
         No = 1 << 5,
+
+        /// <summary>
+        /// Represents an "okay" dialog button.
+        /// </summary>
         OK = 1 << 6,
     }
 }