Merge pull request #2215 from cabauman/docs/xml-comments

Add XML Docs to various interfaces and classes

src/Forms/Prism.Forms/Common/ApplicationProvider.cs

@@ -2,8 +2,12 @@
 
 namespace Prism.Common
 {
+    /// <summary>
+    /// Provides Application components.
+    /// </summary>
     public class ApplicationProvider : IApplicationProvider
     {
+        /// <inheritdoc/>
         public Page MainPage
         {
             get { return Application.Current.MainPage; }

src/Forms/Prism.Forms/Common/IApplicationProvider.cs

@@ -2,8 +2,14 @@
 
 namespace Prism.Common
 {
+    /// <summary>
+    /// Defines a contract for providing Application components.
+    /// </summary>
     public interface IApplicationProvider
     {
+        /// <summary>
+        /// Gets or sets the main page of the Application.
+        /// </summary>
         Page MainPage { get; set; }
     }
 }

src/Forms/Prism.Forms/Navigation/INavigationParameters.cs

@@ -3,7 +3,7 @@
 namespace Prism.Navigation
 {
     /// <summary>
-    /// Provides a way for the <see cref="INavigationService"/> to pass parameteres during navigation.
+    /// Provides a way for the <see cref="INavigationService"/> to pass parameters during navigation.
     /// </summary>
     public interface INavigationParameters : IParameters
     {

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

@@ -9,19 +9,31 @@
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Provides the ability to display dialogs from ViewModels.
+    /// </summary>
     public sealed class DialogService : IDialogService
     {
+        /// <summary>
+        /// Gets the key for specifying or retrieving popup overlay style from Application Resources.
+        /// </summary>
         public const string PopupOverlayStyle = "PrismDialogMaskStyle";
 
         private IContainerProvider _containerExtension { get; }
         private IApplicationProvider _applicationProvider { get; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DialogService"/> class.
+        /// </summary>
+        /// <param name="applicationProvider">An object that provides Application components.</param>
+        /// <param name="containerProvider">An object that can resolve services.</param>
         public DialogService(IApplicationProvider applicationProvider, IContainerProvider containerProvider)
         {
             _applicationProvider = applicationProvider;
             _containerExtension = containerProvider;
         }
 
+        /// <inheritdoc/>
         public void ShowDialog(string name, IDialogParameters parameters, Action<IDialogResult> callback)
         {
             try

src/Forms/Prism.Forms/Services/Dialogs/IDialogParameters.cs

@@ -2,6 +2,9 @@
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Provides a way for the <see cref="IDialogService"/> to pass parameters when displaying a dialog.
+    /// </summary>
     public interface IDialogParameters : IParameters
     {
     }

src/Forms/Prism.Forms/Services/Dialogs/IDialogService.cs

@@ -1,10 +1,31 @@
 using System;
 using System.Threading.Tasks;
+using Prism.Ioc;
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Defines a contract for displaying dialogs from ViewModels.
+    /// </summary>
     public interface IDialogService
     {
+        /// <summary>
+        /// Displays a dialog.
+        /// </summary>
+        /// <param name="name">The unique name of the dialog to display. Must match an entry in the <see cref="IContainerRegistry"/>.</param>
+        /// <param name="parameters">Parameters that the dialog can use for custom functionality.</param>
+        /// <param name="callback">The action to be invoked upon successful or failed completion of displaying the dialog.</param>
+        /// <example>
+        /// This example shows how to display a dialog with two parameters.
+        /// <code>
+        /// var parameters = new DialogParameters
+        /// {
+        ///     { "title", "Connection Lost!" },
+        ///     { "message", "We seem to have lost network connectivity" }
+        /// };
+        /// _dialogService.ShowDialog("DemoDialog", parameters, <paramref name="callback"/>: null);
+        /// </code>
+        /// </example>
         void ShowDialog(string name, IDialogParameters parameters, Action<IDialogResult> callback);
     }
 }

src/Forms/Prism.Forms/Services/Dialogs/IDialogServiceExtensions.cs

@@ -2,18 +2,48 @@
 using System.Linq;
 using System.Reflection;
 using System.Threading.Tasks;
+using Prism.Ioc;
 
 namespace Prism.Services.Dialogs
 {
+    /// <summary>
+    /// Common extensions for <see cref="IDialogService"/>
+    /// </summary>
     public static class IDialogServiceExtensions
     {
+        /// <summary>
+        /// Displays a dialog.
+        /// </summary>
+        /// <param name="dialogService">The dialog service.</param>
+        /// <param name="name">The unique name of the dialog to display. Must match an entry in the <see cref="IContainerRegistry"/>.</param>
         public static void ShowDialog(this IDialogService dialogService, string name) =>
             dialogService.ShowDialog(name, null, null);
+
+        /// <summary>
+        /// Displays a dialog.
+        /// </summary>
+        /// <param name="dialogService">The dialog service.</param>
+        /// <param name="name">The unique name of the dialog to display. Must match an entry in the <see cref="IContainerRegistry"/>.</param>
+        /// <param name="callback">The action to be invoked upon successful or failed completion of displaying the dialog.</param>
         public static void ShowDialog(this IDialogService dialogService, string name, Action<IDialogResult> callback) =>
             dialogService.ShowDialog(name, null, callback);
+
+        /// <summary>
+        /// Displays a dialog.
+        /// </summary>
+        /// <param name="dialogService">The dialog service.</param>
+        /// <param name="name">The unique name of the dialog to display. Must match an entry in the <see cref="IContainerRegistry"/>.</param>
+        /// <param name="parameters">Parameters that the dialog can use for custom functionality.</param>
         public static void ShowDialog(this IDialogService dialogService, string name, IDialogParameters parameters) =>
             dialogService.ShowDialog(name, parameters, null);
 
+        /// <summary>
+        /// Displays a dialog asynchronously.
+        /// </summary>
+        /// <param name="dialogService">The dialog service.</param>
+        /// <param name="name">The unique name of the dialog to display. Must match an entry in the <see cref="IContainerRegistry"/>.</param>
+        /// <param name="parameters">Parameters that the dialog can use for custom functionality.</param>
+        /// <returns><see cref="IDialogResult"/> indicating whether the request was successful or if there was an encountered <see cref="Exception"/>.</returns>
         public static Task<IDialogResult> ShowDialogAsync(this IDialogService dialogService, string name, IDialogParameters parameters = null)
         {
             var tcs = new TaskCompletionSource<IDialogResult>();

src/Prism.Core/Common/IParameters.cs

@@ -4,23 +4,68 @@
 
 namespace Prism.Common
 {
+    /// <summary>
+    /// Defines a contract for specifying values associated with a unique key.
+    /// </summary>
     public interface IParameters : IEnumerable<KeyValuePair<string, object>>
     {
+        /// <summary>
+        /// Adds the specified key and value to the parameter collection.
+        /// </summary>
+        /// <param name="key">The key of the parameter to add.</param>
+        /// <param name="value">The value of the parameter to add.</param>
         void Add(string key, object value);
 
+        /// <summary>
+        /// Determines whether the <see cref="IParameters"/> contains the specified <paramref name="key"/>.
+        /// </summary>
+        /// <param name="key">The key to search the parameters for existence.</param>
+        /// <returns>true if the <see cref="IParameters"/> contains a parameter with the specified key; otherwise, false.</returns>
         bool ContainsKey(string key);
 
+        /// <summary>
+        /// Gets the number of parameters contained in the <see cref="IParameters"/>.
+        /// </summary>
         int Count { get; }
 
+        /// <summary>
+        /// Gets a collection containing the keys in the <see cref="IParameters"/>.
+        /// </summary>
         IEnumerable<string> Keys { get; }
 
+        /// <summary>
+        /// Gets the parameter associated with the specified <paramref name="key"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of the parameter to get.</typeparam>
+        /// <param name="key">The key of the parameter to find.</param>
+        /// <returns>A matching value of <typeparamref name="T"/> if it exists.</returns>
         T GetValue<T>(string key);
 
+        /// <summary>
+        /// Gets the parameter associated with the specified <paramref name="key"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of the parameter to get.</typeparam>
+        /// <param name="key">The key of the parameter to find.</param>
+        /// <returns>An <see cref="IEnumerable{T}"/> of all the values referenced by key.</returns>
         IEnumerable<T> GetValues<T>(string key);
 
+        /// <summary>
+        /// Gets the parameter associated with the specified <paramref name="key"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of the parameter to get.</typeparam>
+        /// <param name="key">The key of the parameter to get.</param>
+        /// <param name="value">
+        /// When this method returns, contains the parameter associated with the specified key,
+        /// if the key is found; otherwise, the default value for the type of the value parameter.
+        /// </param>
+        /// <returns>true if the <see cref="IParameters"/> contains a parameter with the specified key; otherwise, false.</returns>
         bool TryGetValue<T>(string key, out T value);
 
-        //legacy
+        /// <summary>
+        /// Gets the parameter associated with the specified key (legacy).
+        /// </summary>
+        /// <param name="key">The key of the parameter to get.</param>
+        /// <returns>A matching value if it exists.</returns>
         object this[string key] { get; }
     }
 }

src/Prism.Core/Common/ParametersExtensions.cs

@@ -50,6 +50,7 @@ public static object GetValue(this IEnumerable<KeyValuePair<string, object>> par
         /// <summary>
         /// Searches <paramref name="parameters"/> for value referenced by <paramref name="key"/>
         /// </summary>
+        /// <typeparam name="T">The type of the parameter to return</typeparam>
         /// <param name="parameters">A collection of parameters to search</param>
         /// <param name="key">The key of the parameter to find</param>
         /// <param name="value">The value of parameter to return</param>
@@ -76,6 +77,7 @@ public static bool TryGetValue<T>(this IEnumerable<KeyValuePair<string, object>>
         /// <summary>
         /// Searches <paramref name="parameters"/> for value referenced by <paramref name="key"/>
         /// </summary>
+        /// <typeparam name="T">The type of the parameter to return</typeparam>
         /// <param name="parameters">A collection of parameters to search</param>
         /// <param name="key">The key of the parameter to find</param>
         /// <returns>An IEnumberable{T} of all the values referenced by key</returns>