From 0eb6d70d09298cda3e424b63d3ef4cdb534a672e Mon Sep 17 00:00:00 2001 From: cabauman Date: Sun, 18 Oct 2020 13:34:05 +0900 Subject: [PATCH] Add XML Docs to various interfaces and classes --- .../Prism.Forms/Common/ApplicationProvider.cs | 4 ++ .../Common/IApplicationProvider.cs | 6 +++ .../Navigation/INavigationParameters.cs | 2 +- .../Services/Dialogs/DialogService.cs | 12 +++++ .../Services/Dialogs/IDialogParameters.cs | 3 ++ .../Services/Dialogs/IDialogService.cs | 21 +++++++++ .../Dialogs/IDialogServiceExtensions.cs | 30 ++++++++++++ src/Prism.Core/Common/IParameters.cs | 47 ++++++++++++++++++- src/Prism.Core/Common/ParametersExtensions.cs | 2 + 9 files changed, 125 insertions(+), 2 deletions(-) diff --git a/src/Forms/Prism.Forms/Common/ApplicationProvider.cs b/src/Forms/Prism.Forms/Common/ApplicationProvider.cs index 4d836b9b45..a33860f2a6 100644 --- a/src/Forms/Prism.Forms/Common/ApplicationProvider.cs +++ b/src/Forms/Prism.Forms/Common/ApplicationProvider.cs @@ -2,8 +2,12 @@ namespace Prism.Common { + /// + /// Provides Application components. + /// public class ApplicationProvider : IApplicationProvider { + /// public Page MainPage { get { return Application.Current.MainPage; } diff --git a/src/Forms/Prism.Forms/Common/IApplicationProvider.cs b/src/Forms/Prism.Forms/Common/IApplicationProvider.cs index a440f60d74..b4dc7b093c 100644 --- a/src/Forms/Prism.Forms/Common/IApplicationProvider.cs +++ b/src/Forms/Prism.Forms/Common/IApplicationProvider.cs @@ -2,8 +2,14 @@ namespace Prism.Common { + /// + /// Defines a contract for providing Application components. + /// public interface IApplicationProvider { + /// + /// Gets or sets the main page of the Application. + /// Page MainPage { get; set; } } } diff --git a/src/Forms/Prism.Forms/Navigation/INavigationParameters.cs b/src/Forms/Prism.Forms/Navigation/INavigationParameters.cs index fe723eec93..2e663f1a5f 100644 --- a/src/Forms/Prism.Forms/Navigation/INavigationParameters.cs +++ b/src/Forms/Prism.Forms/Navigation/INavigationParameters.cs @@ -3,7 +3,7 @@ namespace Prism.Navigation { /// - /// Provides a way for the to pass parameteres during navigation. + /// Provides a way for the to pass parameters during navigation. /// public interface INavigationParameters : IParameters { diff --git a/src/Forms/Prism.Forms/Services/Dialogs/DialogService.cs b/src/Forms/Prism.Forms/Services/Dialogs/DialogService.cs index fe1271dd4b..a1862e1a67 100644 --- a/src/Forms/Prism.Forms/Services/Dialogs/DialogService.cs +++ b/src/Forms/Prism.Forms/Services/Dialogs/DialogService.cs @@ -9,19 +9,31 @@ namespace Prism.Services.Dialogs { + /// + /// Provides the ability to display dialogs from ViewModels. + /// public sealed class DialogService : IDialogService { + /// + /// Gets the key for specifying or retrieving popup overlay style from Application Resources. + /// public const string PopupOverlayStyle = "PrismDialogMaskStyle"; private IContainerProvider _containerExtension { get; } private IApplicationProvider _applicationProvider { get; } + /// + /// Initializes a new instance of the class. + /// + /// An object that provides Application components. + /// An object that can resolve services. public DialogService(IApplicationProvider applicationProvider, IContainerProvider containerProvider) { _applicationProvider = applicationProvider; _containerExtension = containerProvider; } + /// public void ShowDialog(string name, IDialogParameters parameters, Action callback) { try diff --git a/src/Forms/Prism.Forms/Services/Dialogs/IDialogParameters.cs b/src/Forms/Prism.Forms/Services/Dialogs/IDialogParameters.cs index 16d1acf2d6..cd78238838 100644 --- a/src/Forms/Prism.Forms/Services/Dialogs/IDialogParameters.cs +++ b/src/Forms/Prism.Forms/Services/Dialogs/IDialogParameters.cs @@ -2,6 +2,9 @@ namespace Prism.Services.Dialogs { + /// + /// Provides a way for the to pass parameters when displaying a dialog. + /// public interface IDialogParameters : IParameters { } diff --git a/src/Forms/Prism.Forms/Services/Dialogs/IDialogService.cs b/src/Forms/Prism.Forms/Services/Dialogs/IDialogService.cs index 6f0cac4f96..b613e67e0b 100644 --- a/src/Forms/Prism.Forms/Services/Dialogs/IDialogService.cs +++ b/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 { + /// + /// Defines a contract for displaying dialogs from ViewModels. + /// public interface IDialogService { + /// + /// Displays a dialog. + /// + /// The unique name of the dialog to display. Must match an entry in the . + /// Parameters that the dialog can use for custom functionality. + /// The action to be invoked upon successful or failed completion of displaying the dialog. + /// + /// This example shows how to display a dialog with two parameters. + /// + /// var parameters = new DialogParameters + /// { + /// { "title", "Connection Lost!" }, + /// { "message", "We seem to have lost network connectivity" } + /// }; + /// _dialogService.ShowDialog("DemoDialog", parameters, : null); + /// + /// void ShowDialog(string name, IDialogParameters parameters, Action callback); } } diff --git a/src/Forms/Prism.Forms/Services/Dialogs/IDialogServiceExtensions.cs b/src/Forms/Prism.Forms/Services/Dialogs/IDialogServiceExtensions.cs index 6b5fd0eb39..2109232c69 100644 --- a/src/Forms/Prism.Forms/Services/Dialogs/IDialogServiceExtensions.cs +++ b/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 { + /// + /// Common extensions for + /// public static class IDialogServiceExtensions { + /// + /// Displays a dialog. + /// + /// The dialog service. + /// The unique name of the dialog to display. Must match an entry in the . public static void ShowDialog(this IDialogService dialogService, string name) => dialogService.ShowDialog(name, null, null); + + /// + /// Displays a dialog. + /// + /// The dialog service. + /// The unique name of the dialog to display. Must match an entry in the . + /// The action to be invoked upon successful or failed completion of displaying the dialog. public static void ShowDialog(this IDialogService dialogService, string name, Action callback) => dialogService.ShowDialog(name, null, callback); + + /// + /// Displays a dialog. + /// + /// The dialog service. + /// The unique name of the dialog to display. Must match an entry in the . + /// Parameters that the dialog can use for custom functionality. public static void ShowDialog(this IDialogService dialogService, string name, IDialogParameters parameters) => dialogService.ShowDialog(name, parameters, null); + /// + /// Displays a dialog asynchronously. + /// + /// The dialog service. + /// The unique name of the dialog to display. Must match an entry in the . + /// Parameters that the dialog can use for custom functionality. + /// indicating whether the request was successful or if there was an encountered . public static Task ShowDialogAsync(this IDialogService dialogService, string name, IDialogParameters parameters = null) { var tcs = new TaskCompletionSource(); diff --git a/src/Prism.Core/Common/IParameters.cs b/src/Prism.Core/Common/IParameters.cs index 0b6de31eaa..22025874c4 100644 --- a/src/Prism.Core/Common/IParameters.cs +++ b/src/Prism.Core/Common/IParameters.cs @@ -4,23 +4,68 @@ namespace Prism.Common { + /// + /// Defines a contract for specifying values associated with a unique key. + /// public interface IParameters : IEnumerable> { + /// + /// Adds the specified key and value to the parameter collection. + /// + /// The key of the parameter to add. + /// The value of the parameter to add. void Add(string key, object value); + /// + /// Determines whether the contains the specified . + /// + /// The key to search the parameters for existence. + /// true if the contains a parameter with the specified key; otherwise, false. bool ContainsKey(string key); + /// + /// Gets the number of parameters contained in the . + /// int Count { get; } + /// + /// Gets a collection containing the keys in the . + /// IEnumerable Keys { get; } + /// + /// Gets the parameter associated with the specified . + /// + /// The type of the parameter to get. + /// The key of the parameter to find. + /// A matching value of if it exists. T GetValue(string key); + /// + /// Gets the parameter associated with the specified . + /// + /// The type of the parameter to get. + /// The key of the parameter to find. + /// An of all the values referenced by key. IEnumerable GetValues(string key); + /// + /// Gets the parameter associated with the specified . + /// + /// The type of the parameter to get. + /// The key of the parameter to get. + /// + /// 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. + /// + /// true if the contains a parameter with the specified key; otherwise, false. bool TryGetValue(string key, out T value); - //legacy + /// + /// Gets the parameter associated with the specified key (legacy). + /// + /// The key of the parameter to get. + /// A matching value if it exists. object this[string key] { get; } } } diff --git a/src/Prism.Core/Common/ParametersExtensions.cs b/src/Prism.Core/Common/ParametersExtensions.cs index 013290821e..a630e8f767 100644 --- a/src/Prism.Core/Common/ParametersExtensions.cs +++ b/src/Prism.Core/Common/ParametersExtensions.cs @@ -50,6 +50,7 @@ public static object GetValue(this IEnumerable> par /// /// Searches for value referenced by /// + /// The type of the parameter to return /// A collection of parameters to search /// The key of the parameter to find /// The value of parameter to return @@ -76,6 +77,7 @@ public static bool TryGetValue(this IEnumerable> /// /// Searches for value referenced by /// + /// The type of the parameter to return /// A collection of parameters to search /// The key of the parameter to find /// An IEnumberable{T} of all the values referenced by key