From 551e7c269a9050c3a45bd0b7e24e05d5b90ff122 Mon Sep 17 00:00:00 2001 From: Ryan Brandenburg Date: Fri, 28 Jun 2019 15:59:10 -0700 Subject: [PATCH] More doc comment additions --- .../Abstractions/src/CacheEntryExtensions.cs | 50 +++++++++++-------- .../src/DistributedCacheEntryExtensions.cs | 12 ++--- .../src/MemoryCacheEntryExtensions.cs | 2 +- .../Abstractions/src/PostEvictionDelegate.cs | 6 +-- .../Memory/test/TokenExpirationTests.cs | 2 +- .../samples/RedisCacheSample/Program.cs | 2 +- .../src/ConfigurationExtensions.cs | 6 +-- .../src/IConfigurationProvider.cs | 2 +- .../src/AzureKeyVaultConfigurationProvider.cs | 8 ++- .../src/IniStreamConfigurationProvider.cs | 4 +- ...wtonsoftJsonStreamConfigurationProvider.cs | 2 +- .../src/XmlStreamConfigurationProvider.cs | 4 +- .../src/ChainedConfigurationProvider.cs | 2 +- .../Config/src/ConfigurationKeyComparer.cs | 6 +-- .../Config/src/ConfigurationProvider.cs | 4 +- .../Config/src/ConfigurationReloadToken.cs | 4 +- .../Config/src/ConfigurationRoot.cs | 6 +-- .../Config/src/ConfigurationSection.cs | 2 +- .../ServiceCollectionDescriptorExtensions.cs | 12 ++--- .../DI/src/ServiceProvider.cs | 4 +- ...ostingAbstractionsHostBuilderExtensions.cs | 2 +- .../src/HostingAbstractionsHostExtensions.cs | 8 +-- src/Hosting/Abstractions/src/IHost.cs | 4 +- src/Hosting/Abstractions/src/IHostBuilder.cs | 2 +- src/Hosting/Abstractions/src/IHostLifetime.cs | 4 +- src/Hosting/Hosting/src/HostBuilder.cs | 26 +++++++--- .../src/HostingHostBuilderExtensions.cs | 31 ++++++++---- .../Deployers/ApplicationDeployerFactory.cs | 6 +-- .../src/SystemdHostBuilderExtensions.cs | 2 +- .../Logging.Abstractions/src/EventId.cs | 2 +- .../Logging.Abstractions/src/NullLogger.cs | 2 +- .../src/NullLoggerFactory.cs | 2 +- src/Logging/Logging/src/LoggerFactory.cs | 2 +- .../Logging/src/LoggingBuilderExtensions.cs | 2 +- src/ObjectPool/src/ObjectPool.cs | 4 +- .../Utilities/ArgumentEscaper.cs | 6 +-- 36 files changed, 144 insertions(+), 101 deletions(-) diff --git a/src/Caching/Abstractions/src/CacheEntryExtensions.cs b/src/Caching/Abstractions/src/CacheEntryExtensions.cs index b9e2f9c1cab..51eb4d7d5fa 100644 --- a/src/Caching/Abstractions/src/CacheEntryExtensions.cs +++ b/src/Caching/Abstractions/src/CacheEntryExtensions.cs @@ -11,8 +11,9 @@ public static class CacheEntryExtensions /// /// Sets the priority for keeping the cache entry in the cache during a memory pressure tokened cleanup. /// - /// - /// + /// The entry to set the priority for. + /// The to set on the entry. + /// The for chaining. public static ICacheEntry SetPriority( this ICacheEntry entry, CacheItemPriority priority) @@ -26,6 +27,7 @@ public static ICacheEntry SetPriority( /// /// The . /// The that causes the cache entry to expire. + /// The for chaining. public static ICacheEntry AddExpirationToken( this ICacheEntry entry, IChangeToken expirationToken) @@ -42,8 +44,9 @@ public static ICacheEntry AddExpirationToken( /// /// Sets an absolute expiration time, relative to now. /// - /// - /// + /// The . + /// The representing the expiration time relative to now. + /// The for chaining. public static ICacheEntry SetAbsoluteExpiration( this ICacheEntry entry, TimeSpan relative) @@ -55,8 +58,9 @@ public static ICacheEntry SetAbsoluteExpiration( /// /// Sets an absolute expiration date for the cache entry. /// - /// - /// + /// The . + /// A representing the expiration time in absolute terms. + /// The for chaining. public static ICacheEntry SetAbsoluteExpiration( this ICacheEntry entry, DateTimeOffset absolute) @@ -69,8 +73,9 @@ public static ICacheEntry SetAbsoluteExpiration( /// Sets how long the cache entry can be inactive (e.g. not accessed) before it will be removed. /// This will not extend the entry lifetime beyond the absolute expiration (if set). /// - /// - /// + /// The . + /// A representing a sliding expiration. + /// The for chaining. public static ICacheEntry SetSlidingExpiration( this ICacheEntry entry, TimeSpan offset) @@ -82,8 +87,9 @@ public static ICacheEntry SetSlidingExpiration( /// /// The given callback will be fired after the cache entry is evicted from the cache. /// - /// - /// + /// The . + /// The callback to run after the entry is evicted. + /// The for chaining. public static ICacheEntry RegisterPostEvictionCallback( this ICacheEntry entry, PostEvictionDelegate callback) @@ -99,9 +105,10 @@ public static ICacheEntry RegisterPostEvictionCallback( /// /// The given callback will be fired after the cache entry is evicted from the cache. /// - /// - /// - /// + /// The . + /// The callback to run after the entry is evicted. + /// The state to pass to the post-eviction callback. + /// The for chaining. public static ICacheEntry RegisterPostEvictionCallback( this ICacheEntry entry, PostEvictionDelegate callback, @@ -123,8 +130,9 @@ public static ICacheEntry RegisterPostEvictionCallback( /// /// Sets the value of the cache entry. /// - /// - /// + /// The . + /// The value to set on the . + /// The for chaining. public static ICacheEntry SetValue( this ICacheEntry entry, object value) @@ -136,8 +144,9 @@ public static ICacheEntry SetValue( /// /// Sets the size of the cache entry value. /// - /// - /// + /// The . + /// The size to set on the . + /// The for chaining. public static ICacheEntry SetSize( this ICacheEntry entry, long size) @@ -154,8 +163,9 @@ public static ICacheEntry SetSize( /// /// Applies the values of an existing to the entry. /// - /// - /// + /// The . + /// Set the values of these options on the . + /// The for chaining. public static ICacheEntry SetOptions(this ICacheEntry entry, MemoryCacheEntryOptions options) { if (options == null) @@ -182,4 +192,4 @@ public static ICacheEntry SetOptions(this ICacheEntry entry, MemoryCacheEntryOpt return entry; } } -} \ No newline at end of file +} diff --git a/src/Caching/Abstractions/src/DistributedCacheEntryExtensions.cs b/src/Caching/Abstractions/src/DistributedCacheEntryExtensions.cs index ef6fabe49a4..2433af9fbea 100644 --- a/src/Caching/Abstractions/src/DistributedCacheEntryExtensions.cs +++ b/src/Caching/Abstractions/src/DistributedCacheEntryExtensions.cs @@ -10,8 +10,8 @@ public static class DistributedCacheEntryExtensions /// /// Sets an absolute expiration time, relative to now. /// - /// - /// + /// The options to be operated on. + /// The expiration time, relative to now. public static DistributedCacheEntryOptions SetAbsoluteExpiration( this DistributedCacheEntryOptions options, TimeSpan relative) @@ -23,8 +23,8 @@ public static DistributedCacheEntryOptions SetAbsoluteExpiration( /// /// Sets an absolute expiration date for the cache entry. /// - /// - /// + /// The options to be operated on. + /// The expiration time, in absolute terms. public static DistributedCacheEntryOptions SetAbsoluteExpiration( this DistributedCacheEntryOptions options, DateTimeOffset absolute) @@ -37,8 +37,8 @@ public static DistributedCacheEntryOptions SetAbsoluteExpiration( /// Sets how long the cache entry can be inactive (e.g. not accessed) before it will be removed. /// This will not extend the entry lifetime beyond the absolute expiration (if set). /// - /// - /// + /// The options to be operated on. + /// The sliding expiration time. public static DistributedCacheEntryOptions SetSlidingExpiration( this DistributedCacheEntryOptions options, TimeSpan offset) diff --git a/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs b/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs index 8089182cfe3..c78391c9505 100644 --- a/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs +++ b/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs @@ -25,7 +25,7 @@ public static MemoryCacheEntryOptions SetPriority( /// /// Sets the size of the cache entry value. /// - /// The option to set the size of. + /// The options to set the entry size on. /// The size to set on the . /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetSize( diff --git a/src/Caching/Abstractions/src/PostEvictionDelegate.cs b/src/Caching/Abstractions/src/PostEvictionDelegate.cs index 8954df8a9a0..2fd394d0df9 100644 --- a/src/Caching/Abstractions/src/PostEvictionDelegate.cs +++ b/src/Caching/Abstractions/src/PostEvictionDelegate.cs @@ -6,9 +6,9 @@ namespace Microsoft.Extensions.Caching.Memory /// /// Signature of the callback which gets called when a cache entry expires. /// - /// - /// + /// The key of the entry being evicted. + /// The value of the entry being evicted. /// The . /// The information that was passed when registering the callback. public delegate void PostEvictionDelegate(object key, object value, EvictionReason reason, object state); -} \ No newline at end of file +} diff --git a/src/Caching/Memory/test/TokenExpirationTests.cs b/src/Caching/Memory/test/TokenExpirationTests.cs index 9c36ab26575..f90b4962491 100644 --- a/src/Caching/Memory/test/TokenExpirationTests.cs +++ b/src/Caching/Memory/test/TokenExpirationTests.cs @@ -249,4 +249,4 @@ public void Dispose() } } } -} \ No newline at end of file +} diff --git a/src/Caching/samples/RedisCacheSample/Program.cs b/src/Caching/samples/RedisCacheSample/Program.cs index 215f2951407..e2569705035 100644 --- a/src/Caching/samples/RedisCacheSample/Program.cs +++ b/src/Caching/samples/RedisCacheSample/Program.cs @@ -21,7 +21,7 @@ public static void Main(string[] args) /// Install this chocolatey package: http://chocolatey.org/packages/redis-64/ /// run "redis-server" from command prompt. /// - /// + /// The that represents the asynchronous operation. public static async Task RunSampleAsync() { var key = "myKey"; diff --git a/src/Configuration/Config.Abstractions/src/ConfigurationExtensions.cs b/src/Configuration/Config.Abstractions/src/ConfigurationExtensions.cs index 31935414174..eb9c9176256 100644 --- a/src/Configuration/Config.Abstractions/src/ConfigurationExtensions.cs +++ b/src/Configuration/Config.Abstractions/src/ConfigurationExtensions.cs @@ -30,7 +30,7 @@ public static class ConfigurationExtensions /// /// The configuration. /// The connection string key. - /// + /// The connection string. public static string GetConnectionString(this IConfiguration configuration, string name) { return configuration?.GetSection("ConnectionStrings")?[name]; @@ -71,7 +71,7 @@ public static IEnumerable> AsEnumerable(this IConfi } /// - /// Determines whether the section has a or has children + /// Determines whether the section has a or has children /// public static bool Exists(this IConfigurationSection section) { @@ -82,4 +82,4 @@ public static bool Exists(this IConfigurationSection section) return section.Value != null || section.GetChildren().Any(); } } -} \ No newline at end of file +} diff --git a/src/Configuration/Config.Abstractions/src/IConfigurationProvider.cs b/src/Configuration/Config.Abstractions/src/IConfigurationProvider.cs index 949826fd565..b230a15809e 100644 --- a/src/Configuration/Config.Abstractions/src/IConfigurationProvider.cs +++ b/src/Configuration/Config.Abstractions/src/IConfigurationProvider.cs @@ -29,7 +29,7 @@ public interface IConfigurationProvider /// /// Returns a change token if this provider supports change tracking, null otherwise. /// - /// + /// The change token. IChangeToken GetReloadToken(); /// diff --git a/src/Configuration/Config.AzureKeyVault/src/AzureKeyVaultConfigurationProvider.cs b/src/Configuration/Config.AzureKeyVault/src/AzureKeyVaultConfigurationProvider.cs index 5040cc322c1..d2f9a750026 100644 --- a/src/Configuration/Config.AzureKeyVault/src/AzureKeyVaultConfigurationProvider.cs +++ b/src/Configuration/Config.AzureKeyVault/src/AzureKeyVaultConfigurationProvider.cs @@ -29,7 +29,7 @@ internal class AzureKeyVaultConfigurationProvider : ConfigurationProvider, IDisp /// /// The to use for retrieving values. /// Azure KeyVault uri. - /// + /// The to use in managing values. /// The timespan to wait in between each attempt at polling the Azure KeyVault for changes. Default is null which indicates no reloading. public AzureKeyVaultConfigurationProvider(IKeyVaultClient client, string vault, IKeyVaultSecretManager manager, TimeSpan? reloadInterval = null) { @@ -38,7 +38,7 @@ public AzureKeyVaultConfigurationProvider(IKeyVaultClient client, string vault, _manager = manager ?? throw new ArgumentNullException(nameof(manager)); if (reloadInterval != null && reloadInterval.Value <= TimeSpan.Zero) { - throw new ArgumentOutOfRangeException (nameof(reloadInterval), reloadInterval, nameof(reloadInterval) + " must be positive."); + throw new ArgumentOutOfRangeException(nameof(reloadInterval), reloadInterval, nameof(reloadInterval) + " must be positive."); } _pollingTask = null; @@ -46,6 +46,9 @@ public AzureKeyVaultConfigurationProvider(IKeyVaultClient client, string vault, _reloadInterval = reloadInterval; } + /// + /// Load secrets into this provider. + /// public override void Load() => LoadAsync().ConfigureAwait(false).GetAwaiter().GetResult(); private async Task PollForSecretChangesAsync() @@ -145,6 +148,7 @@ private void SetData(Dictionary loadedSecrets, bool fireTo } } + /// public void Dispose() { _cancellationToken.Cancel(); diff --git a/src/Configuration/Config.Ini/src/IniStreamConfigurationProvider.cs b/src/Configuration/Config.Ini/src/IniStreamConfigurationProvider.cs index 28be7a900e5..b6f212ee91d 100644 --- a/src/Configuration/Config.Ini/src/IniStreamConfigurationProvider.cs +++ b/src/Configuration/Config.Ini/src/IniStreamConfigurationProvider.cs @@ -22,7 +22,7 @@ public IniStreamConfigurationProvider(IniStreamConfigurationSource source) : bas /// Read a stream of INI values into a key/value dictionary. /// /// The stream of INI data. - /// + /// The which was read from the stream. public static IDictionary Read(Stream stream) { var data = new Dictionary(StringComparer.OrdinalIgnoreCase); @@ -45,7 +45,7 @@ public static IDictionary Read(Stream stream) { continue; } - // [Section:header] + // [Section:header] if (line[0] == '[' && line[line.Length - 1] == ']') { // remove the brackets diff --git a/src/Configuration/Config.NewtonsoftJson/src/NewtonsoftJsonStreamConfigurationProvider.cs b/src/Configuration/Config.NewtonsoftJson/src/NewtonsoftJsonStreamConfigurationProvider.cs index a6dfd342bc4..b9bf456e705 100644 --- a/src/Configuration/Config.NewtonsoftJson/src/NewtonsoftJsonStreamConfigurationProvider.cs +++ b/src/Configuration/Config.NewtonsoftJson/src/NewtonsoftJsonStreamConfigurationProvider.cs @@ -13,7 +13,7 @@ public class NewtonsoftJsonStreamConfigurationProvider : StreamConfigurationProv /// /// Constructor. /// - /// + /// The source of configuration. public NewtonsoftJsonStreamConfigurationProvider(NewtonsoftJsonStreamConfigurationSource source) : base(source) { } /// diff --git a/src/Configuration/Config.Xml/src/XmlStreamConfigurationProvider.cs b/src/Configuration/Config.Xml/src/XmlStreamConfigurationProvider.cs index ca463084115..89ef8bf4059 100644 --- a/src/Configuration/Config.Xml/src/XmlStreamConfigurationProvider.cs +++ b/src/Configuration/Config.Xml/src/XmlStreamConfigurationProvider.cs @@ -27,7 +27,7 @@ public XmlStreamConfigurationProvider(XmlStreamConfigurationSource source) : bas /// /// The stream of INI data. /// The to use to decrypt. - /// + /// The which was read from the stream. public static IDictionary Read(Stream stream, XmlDocumentDecryptor decryptor) { var data = new Dictionary(StringComparer.OrdinalIgnoreCase); @@ -46,7 +46,7 @@ public static IDictionary Read(Stream stream, XmlDocumentDecrypt SkipUntilRootElement(reader); - // We process the root element individually since it doesn't contribute to prefix + // We process the root element individually since it doesn't contribute to prefix ProcessAttributes(reader, prefixStack, data, AddNamePrefix); ProcessAttributes(reader, prefixStack, data, AddAttributePair); diff --git a/src/Configuration/Config/src/ChainedConfigurationProvider.cs b/src/Configuration/Config/src/ChainedConfigurationProvider.cs index 5298f749545..8b0c43959a2 100644 --- a/src/Configuration/Config/src/ChainedConfigurationProvider.cs +++ b/src/Configuration/Config/src/ChainedConfigurationProvider.cs @@ -57,7 +57,7 @@ public bool TryGet(string key, out string value) /// /// Returns a change token if this provider supports change tracking, null otherwise. /// - /// + /// The change token. public IChangeToken GetReloadToken() => _config.GetReloadToken(); /// diff --git a/src/Configuration/Config/src/ConfigurationKeyComparer.cs b/src/Configuration/Config/src/ConfigurationKeyComparer.cs index 52fe7264025..9e03cb19c09 100644 --- a/src/Configuration/Config/src/ConfigurationKeyComparer.cs +++ b/src/Configuration/Config/src/ConfigurationKeyComparer.cs @@ -12,7 +12,7 @@ namespace Microsoft.Extensions.Configuration public class ConfigurationKeyComparer : IComparer { private static readonly string[] _keyDelimiterArray = new[] { ConfigurationPath.KeyDelimiter }; - + /// /// The default instance. /// @@ -23,7 +23,7 @@ public class ConfigurationKeyComparer : IComparer /// /// First string. /// Second string. - /// + /// Less than 0 if x is less than y, 0 if x is equal to y and greater than 0 if x is greater than y. public int Compare(string x, string y) { var xParts = x?.Split(_keyDelimiterArray, StringSplitOptions.RemoveEmptyEntries) ?? Array.Empty(); @@ -50,7 +50,7 @@ public int Compare(string x, string y) } else if (xIsInt && yIsInt) { - // Both are int + // Both are int result = value1 - value2; } else diff --git a/src/Configuration/Config/src/ConfigurationProvider.cs b/src/Configuration/Config/src/ConfigurationProvider.cs index 4e0d438f707..9e65de7180a 100644 --- a/src/Configuration/Config/src/ConfigurationProvider.cs +++ b/src/Configuration/Config/src/ConfigurationProvider.cs @@ -51,7 +51,7 @@ public virtual void Set(string key, string value) /// public virtual void Load() { } - + /// /// Returns the list of keys that this provider has. /// @@ -80,7 +80,7 @@ private static string Segment(string key, int prefixLength) /// /// Returns a that can be used to listen when this provider is reloaded. /// - /// + /// The . public IChangeToken GetReloadToken() { return _reloadToken; diff --git a/src/Configuration/Config/src/ConfigurationReloadToken.cs b/src/Configuration/Config/src/ConfigurationReloadToken.cs index 1027a887ccd..30832eb5c19 100644 --- a/src/Configuration/Config/src/ConfigurationReloadToken.cs +++ b/src/Configuration/Config/src/ConfigurationReloadToken.cs @@ -17,11 +17,13 @@ public class ConfigurationReloadToken : IChangeToken /// /// Indicates if this token will proactively raise callbacks. Callbacks are still guaranteed to be invoked, eventually. /// + /// True if the token will proactively raise callbacks. public bool ActiveChangeCallbacks => true; /// /// Gets a value that indicates if a change has occurred. /// + /// True if a change has occurred. public bool HasChanged => _cts.IsCancellationRequested; /// @@ -30,7 +32,7 @@ public class ConfigurationReloadToken : IChangeToken /// /// The callback to invoke. /// State to be passed into the callback. - /// + /// The registration. public IDisposable RegisterChangeCallback(Action callback, object state) => _cts.Token.Register(callback, state); /// diff --git a/src/Configuration/Config/src/ConfigurationRoot.cs b/src/Configuration/Config/src/ConfigurationRoot.cs index a8a0500328d..bd40d049bf0 100644 --- a/src/Configuration/Config/src/ConfigurationRoot.cs +++ b/src/Configuration/Config/src/ConfigurationRoot.cs @@ -81,13 +81,13 @@ public string this[string key] /// /// Gets the immediate children sub-sections. /// - /// + /// The children. public IEnumerable GetChildren() => this.GetChildrenImplementation(null); /// /// Returns a that can be used to observe when this configuration is reloaded. /// - /// + /// The . public IChangeToken GetReloadToken() => _changeToken; /// @@ -99,7 +99,7 @@ public string this[string key] /// This method will never return null. If no matching sub-section is found with the specified key, /// an empty will be returned. /// - public IConfigurationSection GetSection(string key) + public IConfigurationSection GetSection(string key) => new ConfigurationSection(this, key); /// diff --git a/src/Configuration/Config/src/ConfigurationSection.cs b/src/Configuration/Config/src/ConfigurationSection.cs index 6bb0515195a..1581c269d2c 100644 --- a/src/Configuration/Config/src/ConfigurationSection.cs +++ b/src/Configuration/Config/src/ConfigurationSection.cs @@ -111,7 +111,7 @@ public string this[string key] /// /// Returns a that can be used to observe when this configuration is reloaded. /// - /// + /// The . public IChangeToken GetReloadToken() => _root.GetReloadToken(); } } diff --git a/src/DependencyInjection/DI.Abstractions/src/Extensions/ServiceCollectionDescriptorExtensions.cs b/src/DependencyInjection/DI.Abstractions/src/Extensions/ServiceCollectionDescriptorExtensions.cs index fb6d0ac0b69..728cf5954e9 100644 --- a/src/DependencyInjection/DI.Abstractions/src/Extensions/ServiceCollectionDescriptorExtensions.cs +++ b/src/DependencyInjection/DI.Abstractions/src/Extensions/ServiceCollectionDescriptorExtensions.cs @@ -655,11 +655,11 @@ public static void TryAddEnumerable( /// /// Removes the first service in with the same service type - /// as and adds to the collection. + /// as and adds to the collection. /// /// The . /// The to replace with. - /// + /// The for chaining. public static IServiceCollection Replace( this IServiceCollection collection, ServiceDescriptor descriptor) @@ -685,21 +685,21 @@ public static IServiceCollection Replace( } /// - /// Removes all services of type in . + /// Removes all services of type in . /// /// The . - /// + /// The for chaining. public static IServiceCollection RemoveAll(this IServiceCollection collection) { return RemoveAll(collection, typeof(T)); } /// - /// Removes all services of type in . + /// Removes all services of type in . /// /// The . /// The service type to remove. - /// + /// The for chaining. public static IServiceCollection RemoveAll(this IServiceCollection collection, Type serviceType) { if (serviceType == null) diff --git a/src/DependencyInjection/DI/src/ServiceProvider.cs b/src/DependencyInjection/DI/src/ServiceProvider.cs index 56c1bab771a..e3d5bd709f3 100644 --- a/src/DependencyInjection/DI/src/ServiceProvider.cs +++ b/src/DependencyInjection/DI/src/ServiceProvider.cs @@ -91,8 +91,8 @@ internal ServiceProvider(IEnumerable serviceDescriptors, Serv /// /// Gets the service object of the specified type. /// - /// - /// + /// The type of the service to get. + /// The service that was produced. public object GetService(Type serviceType) => _engine.GetService(serviceType); /// diff --git a/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs b/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs index 4f625a326d9..4ffb0c6193c 100644 --- a/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs +++ b/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs @@ -22,7 +22,7 @@ public static IHost Start(this IHostBuilder hostBuilder) /// Builds and starts the host. /// /// The to start. - /// A that can be used to cancel the health check. + /// A that can be used to cancel the start. /// The started . public static async Task StartAsync(this IHostBuilder hostBuilder, CancellationToken cancellationToken = default) { diff --git a/src/Hosting/Abstractions/src/HostingAbstractionsHostExtensions.cs b/src/Hosting/Abstractions/src/HostingAbstractionsHostExtensions.cs index 854b63b3b8b..4747ed47f74 100644 --- a/src/Hosting/Abstractions/src/HostingAbstractionsHostExtensions.cs +++ b/src/Hosting/Abstractions/src/HostingAbstractionsHostExtensions.cs @@ -13,7 +13,7 @@ public static class HostingAbstractionsHostExtensions /// /// Starts the host synchronously. /// - /// + /// The to start. public static void Start(this IHost host) { host.StartAsync().GetAwaiter().GetResult(); @@ -22,10 +22,10 @@ public static void Start(this IHost host) /// /// Attempts to gracefully stop the host with the given timeout. /// - /// + /// The to stop. /// The timeout for stopping gracefully. Once expired the /// server may terminate any remaining active connections. - /// + /// The that represents the asynchronous operation. public static Task StopAsync(this IHost host, TimeSpan timeout) { return host.StopAsync(new CancellationTokenSource(timeout).Token); @@ -54,6 +54,7 @@ public static void Run(this IHost host) /// /// The to run. /// The token to trigger shutdown. + /// The that represents the asynchronous operation. public static async Task RunAsync(this IHost host, CancellationToken token = default) { try @@ -83,6 +84,7 @@ public static async Task RunAsync(this IHost host, CancellationToken token = def /// /// The running . /// The token to trigger shutdown. + /// The that represents the asynchronous operation. public static async Task WaitForShutdownAsync(this IHost host, CancellationToken token = default) { var applicationLifetime = host.Services.GetService(); diff --git a/src/Hosting/Abstractions/src/IHost.cs b/src/Hosting/Abstractions/src/IHost.cs index cd5a6b1c1d7..0a6d89294ec 100644 --- a/src/Hosting/Abstractions/src/IHost.cs +++ b/src/Hosting/Abstractions/src/IHost.cs @@ -21,14 +21,14 @@ public interface IHost : IDisposable /// Start the program. /// /// Used to abort program start. - /// + /// A that will be completed when the starts. Task StartAsync(CancellationToken cancellationToken = default); /// /// Attempts to gracefully stop the program. /// /// Used to indicate when stop should no longer be graceful. - /// + /// A that will be completed when the stops. Task StopAsync(CancellationToken cancellationToken = default); } } diff --git a/src/Hosting/Abstractions/src/IHostBuilder.cs b/src/Hosting/Abstractions/src/IHostBuilder.cs index 986ffcd891c..1550be0b894 100644 --- a/src/Hosting/Abstractions/src/IHostBuilder.cs +++ b/src/Hosting/Abstractions/src/IHostBuilder.cs @@ -49,7 +49,7 @@ public interface IHostBuilder /// Overrides the factory used to create the service provider. /// /// The type of builder. - /// The factory to register/ + /// The factory to register. /// The same instance of the for chaining. IHostBuilder UseServiceProviderFactory(IServiceProviderFactory factory); diff --git a/src/Hosting/Abstractions/src/IHostLifetime.cs b/src/Hosting/Abstractions/src/IHostLifetime.cs index ceb2a69810f..29563415315 100644 --- a/src/Hosting/Abstractions/src/IHostLifetime.cs +++ b/src/Hosting/Abstractions/src/IHostLifetime.cs @@ -12,13 +12,15 @@ public interface IHostLifetime /// Called at the start of which will wait until it's complete before /// continuing. This can be used to delay startup until signaled by an external event. /// + /// Used to indicate when stop should no longer be graceful. + /// A . Task WaitForStartAsync(CancellationToken cancellationToken); /// /// Called from to indicate that the host is stopping and it's time to shut down. /// /// Used to indicate when stop should no longer be graceful. - /// + /// A . Task StopAsync(CancellationToken cancellationToken); } } diff --git a/src/Hosting/Hosting/src/HostBuilder.cs b/src/Hosting/Hosting/src/HostBuilder.cs index f5e9aa63d2c..ed68d0171a6 100644 --- a/src/Hosting/Hosting/src/HostBuilder.cs +++ b/src/Hosting/Hosting/src/HostBuilder.cs @@ -38,7 +38,8 @@ public class HostBuilder : IHostBuilder /// Set up the configuration for the builder itself. This will be used to initialize the /// for use later in the build process. This can be called multiple times and the results will be additive. /// - /// + /// The delegate for configuring the that will be used + /// to construct the for the host. /// The same instance of the for chaining. public IHostBuilder ConfigureHostConfiguration(Action configureDelegate) { @@ -51,7 +52,8 @@ public IHostBuilder ConfigureHostConfiguration(Action con /// the results will be additive. The results will be available at for /// subsequent operations, as well as in . /// - /// + /// The delegate for configuring the that will be used + /// to construct the for the host. /// The same instance of the for chaining. public IHostBuilder ConfigureAppConfiguration(Action configureDelegate) { @@ -62,7 +64,8 @@ public IHostBuilder ConfigureAppConfiguration(Action /// Adds services to the container. This can be called multiple times and the results will be additive. /// - /// + /// The delegate for configuring the that will be used + /// to construct the for the host. /// The same instance of the for chaining. public IHostBuilder ConfigureServices(Action configureDelegate) { @@ -73,8 +76,8 @@ public IHostBuilder ConfigureServices(Action /// Overrides the factory used to create the service provider. /// - /// - /// + /// The type of the builder to create. + /// A factory used for creating service providers. /// The same instance of the for chaining. public IHostBuilder UseServiceProviderFactory(IServiceProviderFactory factory) { @@ -82,6 +85,12 @@ public IHostBuilder UseServiceProviderFactory(IServiceProvide return this; } + /// + /// Overrides the factory used to create the service provider. + /// + /// A factory used for creating service providers. + /// The type of the builder to create. + /// The same instance of the for chaining. public IHostBuilder UseServiceProviderFactory(Func> factory) { _serviceProviderFactory = new ServiceFactoryAdapter(() => _hostBuilderContext, factory ?? throw new ArgumentNullException(nameof(factory))); @@ -92,8 +101,9 @@ public IHostBuilder UseServiceProviderFactory(Func - /// - /// + /// The type of the builder to create. + /// The delegate for configuring the that will be used + /// to construct the for the host. /// The same instance of the for chaining. public IHostBuilder ConfigureContainer(Action configureDelegate) { @@ -207,7 +217,7 @@ private void CreateServiceProvider() services.AddSingleton(); services.AddOptions(); services.AddLogging(); - + foreach (var configureServicesAction in _configureServicesActions) { configureServicesAction(_hostBuilderContext, services); diff --git a/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs b/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs index 7996be2d88b..ef8543491f0 100644 --- a/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs +++ b/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs @@ -50,9 +50,21 @@ public static IHostBuilder UseContentRoot(this IHostBuilder hostBuilder, string }); } + /// + /// Specify the to be the default one. + /// + /// The to configure. + /// + /// The . public static IHostBuilder UseDefaultServiceProvider(this IHostBuilder hostBuilder, Action configure) => hostBuilder.UseDefaultServiceProvider((context, options) => configure(options)); + /// + /// Specify the to be the default one. + /// + /// The to configure. + /// The delegate that configures the . + /// The . public static IHostBuilder UseDefaultServiceProvider(this IHostBuilder hostBuilder, Action configure) { return hostBuilder.UseServiceProviderFactory(context => @@ -90,7 +102,8 @@ public static IHostBuilder ConfigureLogging(this IHostBuilder hostBuilder, Actio /// subsequent operations, as well as in . /// /// The to configure. - /// + /// The delegate for configuring the that will be used + /// to construct the for the host. /// The same instance of the for chaining. public static IHostBuilder ConfigureAppConfiguration(this IHostBuilder hostBuilder, Action configureDelegate) { @@ -101,7 +114,7 @@ public static IHostBuilder ConfigureAppConfiguration(this IHostBuilder hostBuild /// Adds services to the container. This can be called multiple times and the results will be additive. /// /// The to configure. - /// + /// The delegate for configuring the . /// The same instance of the for chaining. public static IHostBuilder ConfigureServices(this IHostBuilder hostBuilder, Action configureDelegate) { @@ -114,7 +127,7 @@ public static IHostBuilder ConfigureServices(this IHostBuilder hostBuilder, Acti /// /// /// The to configure. - /// + /// The delegate for configuring the . /// The same instance of the for chaining. public static IHostBuilder ConfigureContainer(this IHostBuilder hostBuilder, Action configureDelegate) { @@ -137,7 +150,7 @@ public static IHostBuilder UseConsoleLifetime(this IHostBuilder hostBuilder) /// This will unblock extensions like RunAsync and WaitForShutdownAsync. /// /// The to configure. - /// + /// The delegate for configuring the . /// The same instance of the for chaining. public static IHostBuilder UseConsoleLifetime(this IHostBuilder hostBuilder, Action configureOptions) { @@ -152,8 +165,8 @@ public static IHostBuilder UseConsoleLifetime(this IHostBuilder hostBuilder, Act /// Enables console support, builds and starts the host, and waits for Ctrl+C or SIGTERM to shut down. /// /// The to configure. - /// A that can be used to cancel the health check. - /// + /// A that can be used to cancel the console. + /// A that only completes when the token is triggeredor shutdown is triggered. public static Task RunConsoleAsync(this IHostBuilder hostBuilder, CancellationToken cancellationToken = default) { return hostBuilder.UseConsoleLifetime().Build().RunAsync(cancellationToken); @@ -163,9 +176,9 @@ public static Task RunConsoleAsync(this IHostBuilder hostBuilder, CancellationTo /// Enables console support, builds and starts the host, and waits for Ctrl+C or SIGTERM to shut down. /// /// The to configure. - /// - /// A that can be used to cancel the health check. - /// + /// The delegate for configuring the . + /// A that can be used to cancel the console. + /// A that only completes when the token is triggeredor shutdown is triggered. public static Task RunConsoleAsync(this IHostBuilder hostBuilder, Action configureOptions, CancellationToken cancellationToken = default) { return hostBuilder.UseConsoleLifetime(configureOptions).Build().RunAsync(cancellationToken); diff --git a/src/Hosting/IntegrationTesting/src/Deployers/ApplicationDeployerFactory.cs b/src/Hosting/IntegrationTesting/src/Deployers/ApplicationDeployerFactory.cs index 2b13376b802..bec3cad7d58 100644 --- a/src/Hosting/IntegrationTesting/src/Deployers/ApplicationDeployerFactory.cs +++ b/src/Hosting/IntegrationTesting/src/Deployers/ApplicationDeployerFactory.cs @@ -14,9 +14,9 @@ public class ApplicationDeployerFactory /// /// Creates a deployer instance based on settings in . /// - /// - /// - /// + /// The parameters to set on the deployer. + /// The factory used to create loggers. + /// The that was created. public static ApplicationDeployer Create(DeploymentParameters deploymentParameters, ILoggerFactory loggerFactory) { if (deploymentParameters == null) diff --git a/src/Hosting/Systemd/src/SystemdHostBuilderExtensions.cs b/src/Hosting/Systemd/src/SystemdHostBuilderExtensions.cs index 66e69ff063f..c19177f2cb6 100644 --- a/src/Hosting/Systemd/src/SystemdHostBuilderExtensions.cs +++ b/src/Hosting/Systemd/src/SystemdHostBuilderExtensions.cs @@ -27,7 +27,7 @@ public static class SystemdHostBuilderExtensions /// notifications. See https://www.freedesktop.org/software/systemd/man/systemd.service.html. /// /// - /// + /// The to use. /// public static IHostBuilder UseSystemd(this IHostBuilder hostBuilder) { diff --git a/src/Logging/Logging.Abstractions/src/EventId.cs b/src/Logging/Logging.Abstractions/src/EventId.cs index 9a1c9cda897..f4a5be0a8c8 100644 --- a/src/Logging/Logging.Abstractions/src/EventId.cs +++ b/src/Logging/Logging.Abstractions/src/EventId.cs @@ -67,7 +67,7 @@ public override string ToString() } /// - /// Indicates whether the current object is equal to another object of the same type. + /// Indicates whether the current object is equal to another object of the same type. Two events are equal if they the same Id. /// /// An object to compare with this object. /// true if the current object is equal to the other parameter; otherwise, false. diff --git a/src/Logging/Logging.Abstractions/src/NullLogger.cs b/src/Logging/Logging.Abstractions/src/NullLogger.cs index 9d3cba4dca6..fe15c9179e6 100644 --- a/src/Logging/Logging.Abstractions/src/NullLogger.cs +++ b/src/Logging/Logging.Abstractions/src/NullLogger.cs @@ -11,7 +11,7 @@ namespace Microsoft.Extensions.Logging.Abstractions public class NullLogger : ILogger { /// - /// Returns an instance of . + /// Returns the shared instance of . /// public static NullLogger Instance { get; } = new NullLogger(); diff --git a/src/Logging/Logging.Abstractions/src/NullLoggerFactory.cs b/src/Logging/Logging.Abstractions/src/NullLoggerFactory.cs index ac7e67f6343..e9aae09161e 100644 --- a/src/Logging/Logging.Abstractions/src/NullLoggerFactory.cs +++ b/src/Logging/Logging.Abstractions/src/NullLoggerFactory.cs @@ -15,7 +15,7 @@ public class NullLoggerFactory : ILoggerFactory public NullLoggerFactory() { } /// - /// Returns an instance of . + /// Returns the shared instance of . /// public static readonly NullLoggerFactory Instance = new NullLoggerFactory(); diff --git a/src/Logging/Logging/src/LoggerFactory.cs b/src/Logging/Logging/src/LoggerFactory.cs index 0ab6b40ad8f..60b58d56e10 100644 --- a/src/Logging/Logging/src/LoggerFactory.cs +++ b/src/Logging/Logging/src/LoggerFactory.cs @@ -94,7 +94,7 @@ private void RefreshFilters(LoggerFilterOptions filterOptions) /// /// Creates an with the given . /// - /// The categoryName for messages produced by the logger. + /// The category name for messages produced by the logger. /// The that was created. public ILogger CreateLogger(string categoryName) { diff --git a/src/Logging/Logging/src/LoggingBuilderExtensions.cs b/src/Logging/Logging/src/LoggingBuilderExtensions.cs index 8e441820f06..cf80b740ed8 100644 --- a/src/Logging/Logging/src/LoggingBuilderExtensions.cs +++ b/src/Logging/Logging/src/LoggingBuilderExtensions.cs @@ -13,7 +13,7 @@ namespace Microsoft.Extensions.Logging public static class LoggingBuilderExtensions { /// - /// Sets a minimum requirement for log messages. + /// Sets a minimum requirement for log messages to be logged. /// /// The to set the minimum level on. /// The to set as the minimum. diff --git a/src/ObjectPool/src/ObjectPool.cs b/src/ObjectPool/src/ObjectPool.cs index 9dfe1ca55a2..bfc495528ad 100644 --- a/src/ObjectPool/src/ObjectPool.cs +++ b/src/ObjectPool/src/ObjectPool.cs @@ -10,9 +10,9 @@ namespace Microsoft.Extensions.ObjectPool public abstract class ObjectPool where T : class { /// - /// Returns an object from the pool. + /// Gets an object from the pool is one is available, otherwise creates one. /// - /// An object from the pool. + /// A . public abstract T Get(); /// diff --git a/src/Shared/src/CommandLineUtils/Utilities/ArgumentEscaper.cs b/src/Shared/src/CommandLineUtils/Utilities/ArgumentEscaper.cs index 7b696c5175d..92543e7f237 100644 --- a/src/Shared/src/CommandLineUtils/Utilities/ArgumentEscaper.cs +++ b/src/Shared/src/CommandLineUtils/Utilities/ArgumentEscaper.cs @@ -19,8 +19,8 @@ internal static class ArgumentEscaper /// /// See https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/ /// - /// - /// + /// The arguments to concatenate. + /// The escaped arguments, concatenated. public static string EscapeAndConcatenate(IEnumerable args) => string.Join(" ", args.Select(EscapeSingleArg)); @@ -104,6 +104,6 @@ private static bool IsSurroundedWithQuotes(string argument) } private static bool ContainsWhitespace(string argument) - => argument.IndexOfAny(new [] { ' ', '\t', '\n' }) >= 0; + => argument.IndexOfAny(new[] { ' ', '\t', '\n' }) >= 0; } }