Added comments for the CSharp API surface

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<string, string?, int?, bool>((message, title, timeout) => { _useAlertAction(message, title, timeout); return true; })
                 : new Func<string, string?, int?, bool>((message, title, timeout) => { return false; });
             _useConfirmFunc ??= _useConfirmAction != null
                 ? new Func<string, string?, int?, bool>((message, title, timeout) => { _useConfirmAction(message, title, timeout); return true; })
                 : new Func<string, string?, int?, bool>((message, title, timeout) => { return false; });
+
             _usePromptFunc ??= new Func<string, string?, string?, int?, string?>((message, title, text, timeout) => { return null; });
             _usePickFunc ??= new Func<string?, string?, int?, IEnumerable<string>, string?, string?>((message, title, timeout, choices, choice) => { return null; });
 

src/cs/Interfaces/ICommandSystem.cs

@@ -17,7 +17,7 @@ public interface ICommandSystem : IHost
     /// </summary>
     /// <param name="cancellationToken">Used to abort program start.</param>
     /// <returns>A System.Threading.Tasks.Task that will be completed when the Microsoft.Extensions.Hosting.IHost
-    //     starts.</returns>
+    //   starts.</returns>
     new Task StartAsync(CancellationToken cancellationToken = default(CancellationToken));
 
 

src/cs/Interfaces/ICommandSystemBuilder.cs

@@ -10,17 +10,70 @@ public interface ICommandSystemBuilder
     ICommandSystemBuilder ConfigureAppConfiguration(Action<HostBuilderContext, IConfigurationBuilder> configureDelegate);
     ICommandSystemBuilder ConfigureContainer<TContainerBuilder>(Action<HostBuilderContext, TContainerBuilder> configureDelegate);
     ICommandSystemBuilder ConfigureHostConfiguration(Action<IConfigurationBuilder> configureDelegate);
-    ICommandSystemBuilder ConfigureServices(Action<HostBuilderContext, IServiceCollection> configureDelegate);
     ICommandSystemBuilder UseServiceProviderFactory<TContainerBuilder>(Func<HostBuilderContext, IServiceProviderFactory<TContainerBuilder>> factory) where TContainerBuilder : notnull;
     ICommandSystemBuilder UseServiceProviderFactory<TContainerBuilder>(IServiceProviderFactory<TContainerBuilder> factory) where TContainerBuilder : notnull;
+    ICommandSystemBuilder ConfigureServices(Action<HostBuilderContext, IServiceCollection> configureDelegate);
 
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureSourceBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureSources(Action<IConfigureSourceBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureSecretBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureSecrets(Action<IConfigureSecretBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureResolverBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureResolvers(Action<IConfigureResolverBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureMessageBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureMessages(Action<IConfigureMessageBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureUiBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureUi(Action<IConfigureUiBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureMediaBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureMedia(Action<IConfigureMediaBuilder> configureDelegate);
+
+    /// <summary>
+    /// Takes an <see cref="Action"/> that operates on an <see cref="IConfigureClipboardBuilder"/>.
+    /// This can be called multiple times and the results will be additive.
+    /// </summary>
+    /// <param name="configureDelegate"></param>
+    /// <returns>The <see cref="ICommandSystemBuilder"/> that it was called on for chaining.</returns>
     ICommandSystemBuilder ConfigureClipboard(Action<IConfigureClipboardBuilder> configureDelegate);
 
+    /// <summary>
+    /// Runs all of the configured delegates and builds an instance of the <see cref="ICommandSystem"/>
+    /// object.
+    /// </summary>
+    /// <returns>The built instance of <see cref="ICommandSystem"/></returns>
     ICommandSystem Build();
 }

src/cs/Interfaces/IConfigureClipboardBuilder.cs

@@ -2,7 +2,29 @@ namespace macaroni;
 
 public interface IConfigureClipboardBuilder
 {
+
+    /// <summary>
+    /// Registers an <see cref="Action{string}"/> callback to be used when the clipboard executor is executed.
+    /// The string parameter is the text that should be placed on the clipboard.
+    /// </summary>
+    /// <param name="setText">The text that should be placed on the clipboard.</param>
+    /// <returns>The <see cref="IConfigureClipboardBuilder"/> object this was called on for chaining.</returns>
     IConfigureClipboardBuilder UseSet(Action<string> setText);
+
+    /// <summary>
+    /// Registers an <see cref="Func{string?}"/> 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.
+    /// </summary>
+    /// <param name="getText">The <see cref="Func{string?}"/> callback to be used.</param>
+    /// <returns>The <see cref="IConfigureClipboardBuilder"/> object this was called on for chaining.</returns>
     IConfigureClipboardBuilder UseGet(Func<string?> getText);
+
+    /// <summary>
+    /// Registers an <see cref="Action"/> callback to be used when the clipboard executor is executed 
+    /// with the clear flag. This means the clipboard should be cleared of all data.
+    /// </summary>
+    /// <param name="clear">The <see cref="Action"/> callback to be used when the clipboard executor is executed 
+    /// with the clear flag.</param>
+    /// <returns>The <see cref="IConfigureClipboardBuilder"/> object this was called on for chaining.</returns>
     IConfigureClipboardBuilder UseClear(Action clear);
 }

src/cs/Interfaces/IConfigureMediaBuilder.cs

@@ -2,11 +2,51 @@ namespace macaroni;
 
 public interface IConfigureMediaBuilder
 {
+    /// <summary>
+    /// Adds an <see cref="Action{int, int}"/> to be called when the beep executor is executed.
+    /// The first int is the duration.
+    /// The second int is the frequency.
+    /// </summary>
+    /// <param name="beep">The <see cref="Action{int, int}"/> to be called when the beep executor is executed.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UseBeep(Action<int, int> beep);
+
+    /// <summary>
+    /// Adds an <see cref="Action{string, int}"/> 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.
+    /// </summary>
+    /// <param name="play">The <see cref="Action{string, int}"/> to be called when the play executor is executed.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UsePlay(Action<string, int> play);
+
+    /// <summary>
+    /// Adds an <see cref="Action"/> to be called when the pause executor is executed.
+    /// </summary>
+    /// <param name="pause">The <see cref="Action"/> to be called when the pause executor is executed.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UsePause(Action pause);
+
+    /// <summary>
+    /// Adds an <see cref="Action"/> to be called when the resume executor is executed.
+    /// </summary>
+    /// <param name="resume">The <see cref="Action"/> to be called when the resume executor is executed.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UseResume(Action resume);
+
+    /// <summary>
+    /// Adds an <see cref="Action"/> to be called when the stop executor is executed.
+    /// </summary>
+    /// <param name="stop">The <see cref="Action"/> to be called when the stop executor is executed.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UseStop(Action stop);
 
+    /// <summary>
+    /// Sets the <see cref="ICommandSystem"/> to not attempt to open the microphone. This can
+    /// be useful when running in a server environment. By default the <see cref="ICommandSystem"/>
+    /// will attempt to open the microphone as an input stream.
+    /// </summary>
+    /// <param name="useNullAudio">This parameter defaults to true.</param>
+    /// <returns>The <see cref="IConfigureMediaBuilder"/> object this was called on for chaining.</returns>
     IConfigureMediaBuilder UseNullAudio(bool useNullAudio = true);
 }

src/cs/Interfaces/IConfigureMessageBuilder.cs

@@ -2,6 +2,22 @@ namespace macaroni;
 
 public interface IConfigureMessageBuilder
 {
+    /// <summary>
+    /// Adds an <see cref="Action{string}"/> to the <see cref="ICommandSystem"/> to be
+    /// called when a broadcast with the title "name" is broadcast. The broadcast value will be 
+    /// passed in as the parameter.
+    /// </summary>
+    /// <param name="name">The name of the broadcast message to register for.</param>
+    /// <param name="handler">The <see cref="Action{string}"/> to call with the value of the broadcast.</param>
+    /// <returns>The <see cref="IConfigureMessageBuilder"/> object this was called on for chaining.</returns>
     IConfigureMessageBuilder AddHandler(string name, Action<string?> handler);
+
+    /// <summary>
+    /// Adds an <see cref="Action{string, string?}"/> to the <see cref="ICommandSystem"/> to be
+    /// called when a broadcast is sent. The broadcast name and value will be 
+    /// passed in as the parameter.
+    /// </summary>
+    /// <param name="handler">The <see cref="Action{string, string?}"/> to call with the name and value of the broadcast.</param>
+    /// <returns>The <see cref="IConfigureMessageBuilder"/> object this was called on for chaining.</returns>
     IConfigureMessageBuilder AddHandler(Action<string, string?> handler);
 }

src/cs/Interfaces/IConfigureResolverBuilder.cs

@@ -2,7 +2,34 @@ namespace macaroni;
 
 public interface IConfigureResolverBuilder
 {
+    /// <summary>
+    /// Sets the <see cref="ICommandSystem"/> context of the name to the value specified.
+    /// </summary>
+    /// <param name="name">The name of the context.</param>
+    /// <param name="value">The value to be set.</param>
+    /// <returns>The <see cref="IConfigureResolverBuilder"/> object this was called on for chaining.</returns>
     IConfigureResolverBuilder UseContext(string name, object value);
+
+    /// <summary>
+    /// Adds a resolver callback for the specified name to the <see cref="ICommandSystem"/>
+    /// The <see cref="Func{Object?}"/> will be called when the <see cref="ICommandSystem"/> needs the value
+    /// for the interpolation.
+    /// </summary>
+    /// <param name="name">The resolver interpolation.</param>
+    /// <param name="resolver">The <see cref="Func{object?}"/> 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.</param>
+    /// <returns>The <see cref="IConfigureResolverBuilder"/> object this was called on for chaining.</returns>
     IConfigureResolverBuilder AddResolver(string name, Func<object?> resolver);
+
+    /// <summary>
+    /// Adds a resolver callback for the specified name to the <see cref="ICommandSystem"/>
+    /// The <see cref="Func{string, object?}"/> will be called when the <see cref="ICommandSystem"/> needs the value
+    /// of the interpolation.
+    /// </summary>
+    /// <param name="resolver">The <see cref="Func{string, object?}"/> 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.</param>
+    /// <returns>The <see cref="IConfigureResolverBuilder"/> object this was called on for chaining.</returns>
     IConfigureResolverBuilder AddResolver(Func<string, object?> resolver);
 }

src/cs/Interfaces/IConfigureSecretBuilder.cs

@@ -17,10 +17,50 @@ public enum SecretKind
 
 public interface IConfigureSecretBuilder
 {
+    /// <summary>
+    /// Adds a secret to the <see cref="ICommandSystem"/> of the specified <see cref="SecretKind"/>
+    /// with the value.
+    /// </summary>
+    /// <param name="secret">The <see cref="SecretKind"/>.</param>
+    /// <param name="value">The value to use for the specified <see cref="SecretKind"/>.</param>
+    /// <returns>The <see cref="IConfigureSecretBuilder"/> object this was called on for chaining.</returns>
     IConfigureSecretBuilder AddSecret(SecretKind secret, string value);
+
+    /// <summary>
+    /// Adds a secret to the <see cref="ICommandSystem"/> of the specified <see cref="SecretKind"/>
+    /// with the return value of the <see cref="Func{string}"/>. The <see cref="Func{string}"/> will
+    /// be called when the <see cref="ICommandSystem"/> needs the secret.
+    /// </summary>
+    /// <param name="secret">The <see cref="SecretKind"/>.</param>
+    /// <param name="func">The <see cref="Func{string}"/> to use to resolve the secret. It must return a string.</param>
+    /// <returns>The <see cref="IConfigureSecretBuilder"/> object this was called on for chaining.</returns>
     IConfigureSecretBuilder AddSecret(SecretKind secret, Func<string> func);
+
+    /// <summary>
+    /// Adds a secret to the <see cref="ICommandSystem"/> of the specified name
+    /// with the value.
+    /// </summary>
+    /// <param name="name">The secret name.</param>
+    /// <param name="value">The value to use for the specified name.</param>
+    /// <returns>The <see cref="IConfigureSecretBuilder"/> object this was called on for chaining.</returns>
     IConfigureSecretBuilder AddSecret(string name, string value);
+
+    /// <summary>
+    /// Adds a secret to the <see cref="ICommandSystem"/> of the specified name
+    /// with the return value of the <see cref="Func{string}"/>. The <see cref="Func{string}"/> will
+    /// be called when the <see cref="ICommandSystem"/> needs the secret.
+    /// </summary>
+    /// <param name="name">The secret name.</param>
+    /// <param name="func">The <see cref="Func{string}"/> to use to resolve the secret. It must return a string.</param>
+    /// <returns>The <see cref="IConfigureSecretBuilder"/> object this was called on for chaining.</returns>
     IConfigureSecretBuilder AddSecret(string name, Func<string> func);
+
+    /// <summary>
+    /// Specifies whether the <see cref="ICommandSystem"/> should attempt to contact the Azure key vault
+    /// to resolve secrets. Defaults to true.
+    /// </summary>
+    /// <param name="useKeyVault"></param>
+    /// <returns>The <see cref="IConfigureSecretBuilder"/> object this was called on for chaining.</returns>
     IConfigureSecretBuilder UseKeyVault(bool useKeyVault = true);
 
     // IConfigureSecretBuilder UseCredential(CredentialKind kind, Func<Azure.Core.TokenCredential?> credentialDelegate);

src/cs/Interfaces/IConfigureSourceBuilder.cs

@@ -2,8 +2,34 @@ namespace macaroni;
 
 public interface IConfigureSourceBuilder
 {
+    /// <summary>
+    /// Registers a filepath to be loaded as a macro file for the <see cref="ICommandSystem"/>.
+    /// </summary>
+    /// <param name="fileName">The absolute filepath or relative based on the working directory.</param>
+    /// <returns>The <see cref="IConfigureSourceBuilder"/> object this was called on for chaining.</returns>
     IConfigureSourceBuilder AddFile(string fileName);
+
+    /// <summary>
+    /// Registers a macro file using the text from the reader and identified by the documentName 
+    /// as a macro file for the <see cref="ICommandSystem"/>.
+    /// </summary>
+    /// <param name="documentName">The name to associate with this document.</param>
+    /// <param name="reader">The reader for the document text.</param>
+    /// <returns>The <see cref="IConfigureSourceBuilder"/> object this was called on for chaining.</returns>
     IConfigureSourceBuilder AddDocument(string documentName, TextReader reader);
+
+    /// <summary>
+    /// Registers a folder to monitor for macro files during runtime and a filters files based on the pattern provided.
+    /// </summary>
+    /// <param name="folder">The absolute directory path or relative based on the working directory.</param>
+    /// <param name="pattern">The file pattern to apply.</param>
+    /// <returns>The <see cref="IConfigureSourceBuilder"/> object this was called on for chaining.</returns>
     IConfigureSourceBuilder MonitorFolder(string folder, string pattern = "*.mac");
+
+    /// <summary>
+    /// Sets whether the <see cref="ICommandSystem"/> will monitor its default folders for macro files.
+    /// </summary>
+    /// <param name="useDefaultFolderMonitor">Defaults to true.</param>
+    /// <returns>The <see cref="IConfigureSourceBuilder"/> object this was called on for chaining.</returns>
     IConfigureSourceBuilder UseDefaultFolderMonitor(bool useDefaultFolderMonitor = true);
 }