Merge pull request #2065 from Jesus805/master

Added XML Docs to Prism.Wpf - Prism.Services.Dialogs

src/Wpf/Prism.Wpf/Services/Dialogs/ButtonResult.cs

@@ -1,14 +1,41 @@
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// The result of the dialog.
+    /// </summary>
     public enum ButtonResult
     {
+        /// <summary>
+        /// Abort.
+        /// </summary>
         Abort = 3,
+        /// <summary>
+        /// Cancel.
+        /// </summary>
         Cancel = 2,
+        /// <summary>
+        /// Ignore.
+        /// </summary>
         Ignore = 5,
+        /// <summary>
+        /// No.
+        /// </summary>
         No = 7,
+        /// <summary>
+        /// No result returned.
+        /// </summary>
         None = 0,
+        /// <summary>
+        /// OK.
+        /// </summary>
         OK = 1,
-        Retry = 4,        
+        /// <summary>
+        /// Retry.
+        /// </summary>
+        Retry = 4,
+        /// <summary>
+        /// Yes.
+        /// </summary>
         Yes = 6
     }
 }

src/Wpf/Prism.Wpf/Services/Dialogs/Dialog.cs

@@ -1,31 +1,66 @@
-using System;
-using System.Windows;
+using System.Windows;
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// This class contains <see cref="IDialogWindow"/> attached properties.
+    /// </summary>
     public class Dialog
     {
+        /// <summary>
+        /// Identifies the WindowStyle attached property.
+        /// </summary>
+        /// <remarks>
+        /// This attached property is used to specify the style of a <see cref="IDialogWindow"/>.
+        /// </remarks>
         public static readonly DependencyProperty WindowStyleProperty =
             DependencyProperty.RegisterAttached("WindowStyle", typeof(Style), typeof(Dialog), new PropertyMetadata(null));
 
+        /// <summary>
+        /// Gets the value for the <see cref="WindowStyleProperty"/> attached property.
+        /// </summary>
+        /// <param name="obj">The target element.</param>
+        /// <returns>The <see cref="WindowStyleProperty"/> attached to the <paramref name="obj"/> element.</returns>
         public static Style GetWindowStyle(DependencyObject obj)
         {
             return (Style)obj.GetValue(WindowStyleProperty);
         }
 
+        /// <summary>
+        /// Sets the <see cref="WindowStyleProperty"/> attached property.
+        /// </summary>
+        /// <param name="obj">The target element.</param>
+        /// <param name="value">The Style to attach.</param>
         public static void SetWindowStyle(DependencyObject obj, Style value)
         {
             obj.SetValue(WindowStyleProperty, value);
         }
 
+        /// <summary>
+        /// Identifies the WindowStartupLocation attached property.
+        /// </summary>
+        /// <remarks>
+        /// This attached property is used to specify the startup location of a <see cref="IDialogWindow"/>.
+        /// The default startup location is <c>WindowStartupLocation.CenterOwner</c>.
+        /// </remarks>
         public static readonly DependencyProperty WindowStartupLocationProperty =
             DependencyProperty.RegisterAttached("WindowStartupLocation", typeof(WindowStartupLocation), typeof(Dialog), new UIPropertyMetadata(WindowStartupLocation.CenterOwner, OnWindowStartupLocationChanged));
 
+        /// <summary>
+        /// Gets the value for the <see cref="WindowStartupLocationProperty"/> attached property.
+        /// </summary>
+        /// <param name="obj">The target element.</param>
+        /// <returns>The <see cref="WindowStartupLocationProperty"/> attached to the <paramref name="obj"/> element.</returns>
         public static WindowStartupLocation GetWindowStartupLocation(DependencyObject obj)
         {
             return (WindowStartupLocation)obj.GetValue(WindowStartupLocationProperty);
         }
 
+        /// <summary>
+        /// Sets the <see cref="WindowStartupLocationProperty"/> attached property.
+        /// </summary>
+        /// <param name="obj">The target element.</param>
+        /// <param name="value">The WindowStartupLocation to attach.</param>
         public static void SetWindowStartupLocation(DependencyObject obj, WindowStartupLocation value)
         {
             obj.SetValue(WindowStartupLocationProperty, value);

src/Wpf/Prism.Wpf/Services/Dialogs/DialogResult.cs

@@ -1,18 +1,40 @@
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// An <see cref="IDialogResult"/> that contains <see cref="IDialogParameters"/> from the dialog
+    /// and the <see cref="ButtonResult"/> of the dialog.
+    /// </summary>
     public class DialogResult : IDialogResult
     {
+        /// <summary>
+        /// The parameters from the dialog.
+        /// </summary>
         public IDialogParameters Parameters { get; private set; } = new DialogParameters();
 
+        /// <summary>
+        /// The result of the dialog.
+        /// </summary>
         public ButtonResult Result { get; private set; } = ButtonResult.None;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogResult"/> class.
+        /// </summary>
         public DialogResult() { }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogResult"/> class.
+        /// </summary>
+        /// <param name="result">The result of the dialog.</param>
         public DialogResult(ButtonResult result)
         {
             Result = result;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogResult"/> class.
+        /// </summary>
+        /// <param name="result">The result of the dialog.</param>
+        /// <param name="parameters">The parameters from the dialog.</param>
         public DialogResult(ButtonResult result, IDialogParameters parameters)
         {
             Result = result;

src/Wpf/Prism.Wpf/Services/Dialogs/DialogService.cs

@@ -7,30 +7,66 @@
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Implements <see cref="IDialogService"/> to show modal and non-modal dialogs.
+    /// </summary>
+    /// <remarks>
+    /// The dialog's ViewModel must implement IDialogAware.
+    /// </remarks>
     public class DialogService : IDialogService
     {
         private readonly IContainerExtension _containerExtension;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogService"/> class.
+        /// </summary>
+        /// <param name="containerExtension"></param>
         public DialogService(IContainerExtension containerExtension)
         {
             _containerExtension = containerExtension;
         }
 
+        /// <summary>
+        /// Shows a non-modal dialog.
+        /// </summary>
+        /// <param name="name">The name of the dialog to show.</param>
+        /// <param name="parameters">The parameters to pass to the dialog.</param>
+        /// <param name="callback">The action to perform when the dialog is closed.</param>
         public void Show(string name, IDialogParameters parameters, Action<IDialogResult> callback)
         {
             ShowDialogInternal(name, parameters, callback, false);
         }
 
+        /// <summary>
+        /// Shows a non-modal dialog.
+        /// </summary>
+        /// <param name="name">The name of the dialog to show.</param>
+        /// <param name="parameters">The parameters to pass to the dialog.</param>
+        /// <param name="callback">The action to perform when the dialog is closed.</param>
+        /// <param name="windowName">The name of the hosting window registered with the IContainerRegistry.</param>
         public void Show(string name, IDialogParameters parameters, Action<IDialogResult> callback, string windowName)
         {
             ShowDialogInternal(name, parameters, callback, false, windowName);
         }
 
+        /// <summary>
+        /// Shows a modal dialog.
+        /// </summary>
+        /// <param name="name">The name of the dialog to show.</param>
+        /// <param name="parameters">The parameters to pass to the dialog.</param>
+        /// <param name="callback">The action to perform when the dialog is closed.</param>
         public void ShowDialog(string name, IDialogParameters parameters, Action<IDialogResult> callback)
         {
             ShowDialogInternal(name, parameters, callback, true);
         }
 
+        /// <summary>
+        /// Shows a modal dialog.
+        /// </summary>
+        /// <param name="name">The name of the dialog to show.</param>
+        /// <param name="parameters">The parameters to pass to the dialog.</param>
+        /// <param name="callback">The action to perform when the dialog is closed.</param>
+        /// <param name="windowName">The name of the hosting window registered with the IContainerRegistry.</param>
         public void ShowDialog(string name, IDialogParameters parameters, Action<IDialogResult> callback, string windowName)
         {
             ShowDialogInternal(name, parameters, callback, true, windowName);
@@ -48,6 +84,11 @@ void ShowDialogInternal(string name, IDialogParameters parameters, Action<IDialo
                 dialogWindow.Show();
         }
 
+        /// <summary>
+        /// Create a new <see cref="IDialogWindow"/>.
+        /// </summary>
+        /// <param name="name">The name of the hosting window registered with the IContainerRegistry.</param>
+        /// <returns>The created <see cref="IDialogWindow"/>.</returns>
         protected virtual IDialogWindow CreateDialogWindow(string name)
         {
             if (string.IsNullOrWhiteSpace(name))
@@ -56,6 +97,12 @@ protected virtual IDialogWindow CreateDialogWindow(string name)
                 return _containerExtension.Resolve<IDialogWindow>(name);
         }
 
+        /// <summary>
+        /// Configure <see cref="IDialogWindow"/> content.
+        /// </summary>
+        /// <param name="dialogName">The name of the dialog to show.</param>
+        /// <param name="window">The hosting window.</param>
+        /// <param name="parameters">The parameters to pass to the dialog.</param>
         protected virtual void ConfigureDialogWindowContent(string dialogName, IDialogWindow window, IDialogParameters parameters)
         {
             var content = _containerExtension.Resolve<object>(dialogName);
@@ -72,6 +119,11 @@ protected virtual void ConfigureDialogWindowContent(string dialogName, IDialogWi
             MvvmHelpers.ViewAndViewModelAction<IDialogAware>(viewModel, d => d.OnDialogOpened(parameters));
         }
 
+        /// <summary>
+        /// Configure <see cref="IDialogWindow"/> and <see cref="IDialogAware"/> events.
+        /// </summary>
+        /// <param name="dialogWindow">The hosting window.</param>
+        /// <param name="callback">The action to perform when the dialog is closed.</param>
         protected virtual void ConfigureDialogWindowEvents(IDialogWindow dialogWindow, Action<IDialogResult> callback)
         {
             Action<IDialogResult> requestCloseHandler = null;
@@ -117,14 +169,20 @@ protected virtual void ConfigureDialogWindowEvents(IDialogWindow dialogWindow, A
             dialogWindow.Closed += closedHandler;
         }
 
+        /// <summary>
+        /// Configure <see cref="IDialogWindow"/> properties.
+        /// </summary>
+        /// <param name="window">The hosting window.</param>
+        /// <param name="dialogContent">The dialog to show.</param>
+        /// <param name="viewModel">The dialog's ViewModel.</param>
         protected virtual void ConfigureDialogWindowProperties(IDialogWindow window, FrameworkElement dialogContent, IDialogAware viewModel)
         {
             var windowStyle = Dialog.GetWindowStyle(dialogContent);
             if (windowStyle != null)
                 window.Style = windowStyle;
 
             window.Content = dialogContent;
-            window.DataContext = viewModel; //we want the host window and the dialog to share the same data contex
+            window.DataContext = viewModel; //we want the host window and the dialog to share the same data context
 
             if (window.Owner == null)
                 window.Owner = Application.Current?.Windows.OfType<Window>().FirstOrDefault(x => x.IsActive);

src/Wpf/Prism.Wpf/Services/Dialogs/DialogWindow.xaml.cs

@@ -3,12 +3,18 @@
 namespace Prism.Services.Dialogs
 {
     /// <summary>
-    /// Interaction logic for DialogWindow.xaml
+    /// Prism's default dialog host.
     /// </summary>
     public partial class DialogWindow : Window, IDialogWindow
     {
+        /// <summary>
+        /// The <see cref="IDialogResult"/> of the dialog.
+        /// </summary>
         public IDialogResult Result { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogWindow"/> class.
+        /// </summary>
         public DialogWindow()
         {
             InitializeComponent();

src/Wpf/Prism.Wpf/Services/Dialogs/IDialogAware.cs

@@ -2,12 +2,15 @@
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Interface that provides dialog functions and events to ViewModels.
+    /// </summary>
     public interface IDialogAware
     {
         /// <summary>
         /// Determines if the dialog can be closed.
         /// </summary>
-        /// <returns>True: close the dialog; False: the dialog will not close</returns>
+        /// <returns>If <c>true</c> the dialog can be closed. If <c>false</c> the dialog will not close.</returns>
         bool CanCloseDialog();
 
         /// <summary>
@@ -18,16 +21,16 @@ public interface IDialogAware
         /// <summary>
         /// Called when the dialog is opened.
         /// </summary>
-        /// <param name="parameters">The parameters passed to the dialog</param>
+        /// <param name="parameters">The parameters passed to the dialog.</param>
         void OnDialogOpened(IDialogParameters parameters);
 
         /// <summary>
-        /// The title of the dialog that will show in the Window title bar.
+        /// The title of the dialog that will show in the window title bar.
         /// </summary>
         string Title { get; }
 
         /// <summary>
-        /// Instructs the IDialogWindow to close the dialog.
+        /// Instructs the <see cref="IDialogWindow"/> to close the dialog.
         /// </summary>
         event Action<IDialogResult> RequestClose;
     }

src/Wpf/Prism.Wpf/Services/Dialogs/IDialogResult.cs

@@ -1,9 +1,13 @@
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Contains <see cref="IDialogParameters"/> from the dialog
+    /// and the <see cref="ButtonResult"/> of the dialog.
+    /// </summary>
     public interface IDialogResult
     {
         /// <summary>
-        /// The parameters from the dialog
+        /// The parameters from the dialog.
         /// </summary>
         IDialogParameters Parameters { get; }