From 16b1e980613e8daf2c595a61d2fa201f290cf68d Mon Sep 17 00:00:00 2001 From: Chris Schraer Date: Fri, 17 Mar 2023 11:35:03 -0700 Subject: [PATCH] Added comments for the CSharp API surface --- .../CommandSystemBuilder/ConfigUiBuilder.cs | 2 + src/cs/Interfaces/ICommandSystem.cs | 2 +- src/cs/Interfaces/ICommandSystemBuilder.cs | 55 ++++++++++++++++++- .../Interfaces/IConfigureClipboardBuilder.cs | 22 ++++++++ src/cs/Interfaces/IConfigureMediaBuilder.cs | 40 ++++++++++++++ src/cs/Interfaces/IConfigureMessageBuilder.cs | 16 ++++++ .../Interfaces/IConfigureResolverBuilder.cs | 27 +++++++++ src/cs/Interfaces/IConfigureSecretBuilder.cs | 40 ++++++++++++++ src/cs/Interfaces/IConfigureSourceBuilder.cs | 26 +++++++++ src/cs/Interfaces/IConfigureUiBuilder.cs | 43 +++++++++++++++ 10 files changed, 271 insertions(+), 2 deletions(-) diff --git a/src/cs/CommandSystemBuilder/ConfigUiBuilder.cs b/src/cs/CommandSystemBuilder/ConfigUiBuilder.cs index b569fe52..e47b9302 100644 --- a/src/cs/CommandSystemBuilder/ConfigUiBuilder.cs +++ b/src/cs/CommandSystemBuilder/ConfigUiBuilder.cs @@ -74,12 +74,14 @@ private void BuildMessageBoxService(IServiceCollection services, ConfigUiBuilder if (alertOk || confirmOk || promptOk || pickOk) { + // If we don't have funcs then pretend the actions are funcs and return true. _useAlertFunc ??= _useAlertFunc = _useAlertAction != null ? new Func((message, title, timeout) => { _useAlertAction(message, title, timeout); return true; }) : new Func((message, title, timeout) => { return false; }); _useConfirmFunc ??= _useConfirmAction != null ? new Func((message, title, timeout) => { _useConfirmAction(message, title, timeout); return true; }) : new Func((message, title, timeout) => { return false; }); + _usePromptFunc ??= new Func((message, title, text, timeout) => { return null; }); _usePickFunc ??= new Func, string?, string?>((message, title, timeout, choices, choice) => { return null; }); diff --git a/src/cs/Interfaces/ICommandSystem.cs b/src/cs/Interfaces/ICommandSystem.cs index d858500e..b5bff125 100644 --- a/src/cs/Interfaces/ICommandSystem.cs +++ b/src/cs/Interfaces/ICommandSystem.cs @@ -17,7 +17,7 @@ public interface ICommandSystem : IHost /// /// Used to abort program start. /// A System.Threading.Tasks.Task that will be completed when the Microsoft.Extensions.Hosting.IHost - // starts. + // starts. new Task StartAsync(CancellationToken cancellationToken = default(CancellationToken)); diff --git a/src/cs/Interfaces/ICommandSystemBuilder.cs b/src/cs/Interfaces/ICommandSystemBuilder.cs index 67e097f0..cbed8f7f 100644 --- a/src/cs/Interfaces/ICommandSystemBuilder.cs +++ b/src/cs/Interfaces/ICommandSystemBuilder.cs @@ -10,17 +10,70 @@ public interface ICommandSystemBuilder ICommandSystemBuilder ConfigureAppConfiguration(Action configureDelegate); ICommandSystemBuilder ConfigureContainer(Action configureDelegate); ICommandSystemBuilder ConfigureHostConfiguration(Action configureDelegate); - ICommandSystemBuilder ConfigureServices(Action configureDelegate); ICommandSystemBuilder UseServiceProviderFactory(Func> factory) where TContainerBuilder : notnull; ICommandSystemBuilder UseServiceProviderFactory(IServiceProviderFactory factory) where TContainerBuilder : notnull; + ICommandSystemBuilder ConfigureServices(Action configureDelegate); + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureSources(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureSecrets(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureResolvers(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureMessages(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureUi(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureMedia(Action configureDelegate); + + /// + /// Takes an that operates on an . + /// This can be called multiple times and the results will be additive. + /// + /// + /// The that it was called on for chaining. ICommandSystemBuilder ConfigureClipboard(Action configureDelegate); + /// + /// Runs all of the configured delegates and builds an instance of the + /// object. + /// + /// The built instance of ICommandSystem Build(); } diff --git a/src/cs/Interfaces/IConfigureClipboardBuilder.cs b/src/cs/Interfaces/IConfigureClipboardBuilder.cs index 85f2ab38..b724697e 100644 --- a/src/cs/Interfaces/IConfigureClipboardBuilder.cs +++ b/src/cs/Interfaces/IConfigureClipboardBuilder.cs @@ -2,7 +2,29 @@ namespace macaroni; public interface IConfigureClipboardBuilder { + + /// + /// Registers an callback to be used when the clipboard executor is executed. + /// The string parameter is the text that should be placed on the clipboard. + /// + /// The text that should be placed on the clipboard. + /// The object this was called on for chaining. IConfigureClipboardBuilder UseSet(Action setText); + + /// + /// Registers an callback to be used when the clipboard resolver is executed. + /// The string return is the text that should be used as the clipboard text. Null means it is not available. + /// + /// The callback to be used. + /// The object this was called on for chaining. IConfigureClipboardBuilder UseGet(Func getText); + + /// + /// Registers an callback to be used when the clipboard executor is executed + /// with the clear flag. This means the clipboard should be cleared of all data. + /// + /// The callback to be used when the clipboard executor is executed + /// with the clear flag. + /// The object this was called on for chaining. IConfigureClipboardBuilder UseClear(Action clear); } diff --git a/src/cs/Interfaces/IConfigureMediaBuilder.cs b/src/cs/Interfaces/IConfigureMediaBuilder.cs index 3af372b1..b1195218 100644 --- a/src/cs/Interfaces/IConfigureMediaBuilder.cs +++ b/src/cs/Interfaces/IConfigureMediaBuilder.cs @@ -2,11 +2,51 @@ namespace macaroni; public interface IConfigureMediaBuilder { + /// + /// Adds an to be called when the beep executor is executed. + /// The first int is the duration. + /// The second int is the frequency. + /// + /// The to be called when the beep executor is executed. + /// The object this was called on for chaining. IConfigureMediaBuilder UseBeep(Action beep); + + /// + /// Adds an to be called when the play executor is executed. + /// The string is the filepath to an audio file to play. + /// The int is the position within the file to begin playback. + /// + /// The to be called when the play executor is executed. + /// The object this was called on for chaining. IConfigureMediaBuilder UsePlay(Action play); + + /// + /// Adds an to be called when the pause executor is executed. + /// + /// The to be called when the pause executor is executed. + /// The object this was called on for chaining. IConfigureMediaBuilder UsePause(Action pause); + + /// + /// Adds an to be called when the resume executor is executed. + /// + /// The to be called when the resume executor is executed. + /// The object this was called on for chaining. IConfigureMediaBuilder UseResume(Action resume); + + /// + /// Adds an to be called when the stop executor is executed. + /// + /// The to be called when the stop executor is executed. + /// The object this was called on for chaining. IConfigureMediaBuilder UseStop(Action stop); + /// + /// Sets the to not attempt to open the microphone. This can + /// be useful when running in a server environment. By default the + /// will attempt to open the microphone as an input stream. + /// + /// This parameter defaults to true. + /// The object this was called on for chaining. IConfigureMediaBuilder UseNullAudio(bool useNullAudio = true); } diff --git a/src/cs/Interfaces/IConfigureMessageBuilder.cs b/src/cs/Interfaces/IConfigureMessageBuilder.cs index 0d369563..8c8f35c4 100644 --- a/src/cs/Interfaces/IConfigureMessageBuilder.cs +++ b/src/cs/Interfaces/IConfigureMessageBuilder.cs @@ -2,6 +2,22 @@ namespace macaroni; public interface IConfigureMessageBuilder { + /// + /// Adds an to the to be + /// called when a broadcast with the title "name" is broadcast. The broadcast value will be + /// passed in as the parameter. + /// + /// The name of the broadcast message to register for. + /// The to call with the value of the broadcast. + /// The object this was called on for chaining. IConfigureMessageBuilder AddHandler(string name, Action handler); + + /// + /// Adds an to the to be + /// called when a broadcast is sent. The broadcast name and value will be + /// passed in as the parameter. + /// + /// The to call with the name and value of the broadcast. + /// The object this was called on for chaining. IConfigureMessageBuilder AddHandler(Action handler); } diff --git a/src/cs/Interfaces/IConfigureResolverBuilder.cs b/src/cs/Interfaces/IConfigureResolverBuilder.cs index b8f13c8b..64a7eee6 100644 --- a/src/cs/Interfaces/IConfigureResolverBuilder.cs +++ b/src/cs/Interfaces/IConfigureResolverBuilder.cs @@ -2,7 +2,34 @@ namespace macaroni; public interface IConfigureResolverBuilder { + /// + /// Sets the context of the name to the value specified. + /// + /// The name of the context. + /// The value to be set. + /// The object this was called on for chaining. IConfigureResolverBuilder UseContext(string name, object value); + + /// + /// Adds a resolver callback for the specified name to the + /// The will be called when the needs the value + /// for the interpolation. + /// + /// The resolver interpolation. + /// The to use to resolve the context value. It must return an object or null. + /// Null means it is unable to resolve the value and other attempts should continue. + /// The object this was called on for chaining. IConfigureResolverBuilder AddResolver(string name, Func resolver); + + /// + /// Adds a resolver callback for the specified name to the + /// The will be called when the needs the value + /// of the interpolation. + /// + /// The to use to resolve the context value. + /// The first parameter is a string that specifies the alias to resolve. + /// It must return an object or null. + /// Null means it is unable to resolve the interpolation and other attempts should continue. + /// The object this was called on for chaining. IConfigureResolverBuilder AddResolver(Func resolver); } diff --git a/src/cs/Interfaces/IConfigureSecretBuilder.cs b/src/cs/Interfaces/IConfigureSecretBuilder.cs index 5cc874a7..b7506b54 100644 --- a/src/cs/Interfaces/IConfigureSecretBuilder.cs +++ b/src/cs/Interfaces/IConfigureSecretBuilder.cs @@ -17,10 +17,50 @@ public enum SecretKind public interface IConfigureSecretBuilder { + /// + /// Adds a secret to the of the specified + /// with the value. + /// + /// The . + /// The value to use for the specified . + /// The object this was called on for chaining. IConfigureSecretBuilder AddSecret(SecretKind secret, string value); + + /// + /// Adds a secret to the of the specified + /// with the return value of the . The will + /// be called when the needs the secret. + /// + /// The . + /// The to use to resolve the secret. It must return a string. + /// The object this was called on for chaining. IConfigureSecretBuilder AddSecret(SecretKind secret, Func func); + + /// + /// Adds a secret to the of the specified name + /// with the value. + /// + /// The secret name. + /// The value to use for the specified name. + /// The object this was called on for chaining. IConfigureSecretBuilder AddSecret(string name, string value); + + /// + /// Adds a secret to the of the specified name + /// with the return value of the . The will + /// be called when the needs the secret. + /// + /// The secret name. + /// The to use to resolve the secret. It must return a string. + /// The object this was called on for chaining. IConfigureSecretBuilder AddSecret(string name, Func func); + + /// + /// Specifies whether the should attempt to contact the Azure key vault + /// to resolve secrets. Defaults to true. + /// + /// + /// The object this was called on for chaining. IConfigureSecretBuilder UseKeyVault(bool useKeyVault = true); // IConfigureSecretBuilder UseCredential(CredentialKind kind, Func credentialDelegate); diff --git a/src/cs/Interfaces/IConfigureSourceBuilder.cs b/src/cs/Interfaces/IConfigureSourceBuilder.cs index 45aaf033..d0afa6c7 100644 --- a/src/cs/Interfaces/IConfigureSourceBuilder.cs +++ b/src/cs/Interfaces/IConfigureSourceBuilder.cs @@ -2,8 +2,34 @@ namespace macaroni; public interface IConfigureSourceBuilder { + /// + /// Registers a filepath to be loaded as a macro file for the . + /// + /// The absolute filepath or relative based on the working directory. + /// The object this was called on for chaining. IConfigureSourceBuilder AddFile(string fileName); + + /// + /// Registers a macro file using the text from the reader and identified by the documentName + /// as a macro file for the . + /// + /// The name to associate with this document. + /// The reader for the document text. + /// The object this was called on for chaining. IConfigureSourceBuilder AddDocument(string documentName, TextReader reader); + + /// + /// Registers a folder to monitor for macro files during runtime and a filters files based on the pattern provided. + /// + /// The absolute directory path or relative based on the working directory. + /// The file pattern to apply. + /// The object this was called on for chaining. IConfigureSourceBuilder MonitorFolder(string folder, string pattern = "*.mac"); + + /// + /// Sets whether the will monitor its default folders for macro files. + /// + /// Defaults to true. + /// The object this was called on for chaining. IConfigureSourceBuilder UseDefaultFolderMonitor(bool useDefaultFolderMonitor = true); } diff --git a/src/cs/Interfaces/IConfigureUiBuilder.cs b/src/cs/Interfaces/IConfigureUiBuilder.cs index fdf9cfe2..041c85eb 100644 --- a/src/cs/Interfaces/IConfigureUiBuilder.cs +++ b/src/cs/Interfaces/IConfigureUiBuilder.cs @@ -2,11 +2,54 @@ namespace macaroni; public interface IConfigureUiBuilder { + /// + /// Registers an to be called when a display executor is triggered. + /// + /// The with inputs string and int. The string being + /// the message to display and the int being the timeout in milliseconds. + /// The object this was called on for chaining. IConfigureUiBuilder UseDisplay(Action display); + + /// + /// Registers an to be called when a alert executor is triggered. + /// + /// The with inputs string, string, and int. The first + /// string is the message of the alert. The second string is the title of the alert box or window. + /// The int is the timeout in milliseconds. + /// The object this was called on for chaining. IConfigureUiBuilder UseAlert(Action alert); + + /// + /// Registers an to be called when a alert executor is triggered. + /// + /// The returning a bool with inputs string, string, and int. + /// The return value will determine whether execution of the executor list should continue or not. True means continue, + /// false not. + /// The first string is the message of the alert. The second string is the title of the alert box or window. + /// The int is the timeout in milliseconds. + /// The object this was called on for chaining. IConfigureUiBuilder UseAlert(Func alert); + + /// + /// Registers an to be called when a confirm executor is triggered. + /// + /// The with inputs string, string, and int. The first + /// string is the confirm of the alert. The second string is the title of the confirm box or window. + /// The int is the timeout in milliseconds. + /// The object this was called on for chaining. IConfigureUiBuilder UseConfirm(Action confirm); + + /// + /// Registers an to be called when a confirm executor is triggered. + /// + /// The returning a bool with inputs string, string, and int. + /// The return value will determine whether execution of the executor list should continue or not. True means continue, + /// false not. Canceling a confirm will default to not continuing. + /// The first string is the message of the confirm. The second string is the title of the confirm box or window. + /// The int is the timeout in milliseconds. + /// The object this was called on for chaining. IConfigureUiBuilder UseConfirm(Func confirm); + IConfigureUiBuilder UsePrompt(Func prompt); IConfigureUiBuilder UsePick(Func, string?, string?> pick); }