From d3cad4c7872ea742be8299aa454ab15da6fb5623 Mon Sep 17 00:00:00 2001 From: Ryan Brandenburg Date: Thu, 27 Jun 2019 16:57:47 -0700 Subject: [PATCH] More doc comments --- .../src/MemoryCacheEntryExtensions.cs | 40 +++++++++++-------- src/Caching/Memory/src/MemoryCache.cs | 2 +- ...ostingAbstractionsHostBuilderExtensions.cs | 2 +- src/Hosting/Abstractions/src/IHostBuilder.cs | 12 +++--- .../src/HostingHostBuilderExtensions.cs | 4 +- ...owsServiceLifetimeHostBuilderExtensions.cs | 4 +- .../src/ResourceManagerStringLocalizer.cs | 2 +- .../Logging.Abstractions/src/ILogger.cs | 1 - .../src/BlobLoggerProvider.cs | 2 +- .../src/ConsoleLoggerFactoryExtensions.cs | 2 +- .../src/EventSourceLogger.cs | 4 +- .../src/LoggingEventSource.cs | 8 ++-- .../src/FilterLoggingBuilderExtensions.cs | 2 +- .../src/DataAnnotationValidateOptions.cs | 6 +-- .../Options/src/PostConfigureOptions.cs | 4 +- 15 files changed, 51 insertions(+), 44 deletions(-) diff --git a/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs b/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs index e9759b74958..8089182cfe3 100644 --- a/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs +++ b/src/Caching/Abstractions/src/MemoryCacheEntryExtensions.cs @@ -11,8 +11,9 @@ public static class MemoryCacheEntryExtensions /// /// Sets the priority for keeping the cache entry in the cache during a memory pressure tokened cleanup. /// - /// - /// + /// The option on which to set the priority. + /// The to set on the option. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetPriority( this MemoryCacheEntryOptions options, CacheItemPriority priority) @@ -24,8 +25,9 @@ public static MemoryCacheEntryOptions SetPriority( /// /// Sets the size of the cache entry value. /// - /// - /// + /// The option to set the size of. + /// The size to set on the . + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetSize( this MemoryCacheEntryOptions options, long size) @@ -44,6 +46,7 @@ public static MemoryCacheEntryOptions SetSize( /// /// The . /// The that causes the cache entry to expire. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions AddExpirationToken( this MemoryCacheEntryOptions options, IChangeToken expirationToken) @@ -60,8 +63,9 @@ public static MemoryCacheEntryOptions AddExpirationToken( /// /// Sets an absolute expiration time, relative to now. /// - /// - /// + /// The . + /// The expiration time, relative to now. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetAbsoluteExpiration( this MemoryCacheEntryOptions options, TimeSpan relative) @@ -73,8 +77,9 @@ public static MemoryCacheEntryOptions SetAbsoluteExpiration( /// /// Sets an absolute expiration date for the cache entry. /// - /// - /// + /// The . + /// The expiration time, in absolute terms. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetAbsoluteExpiration( this MemoryCacheEntryOptions options, DateTimeOffset absolute) @@ -87,8 +92,9 @@ public static MemoryCacheEntryOptions 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 . + /// The sliding expiration time. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions SetSlidingExpiration( this MemoryCacheEntryOptions options, TimeSpan offset) @@ -100,8 +106,9 @@ public static MemoryCacheEntryOptions SetSlidingExpiration( /// /// The given callback will be fired after the cache entry is evicted from the cache. /// - /// - /// + /// The . + /// The callback to register for calling after an entry is evicted. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions RegisterPostEvictionCallback( this MemoryCacheEntryOptions options, PostEvictionDelegate callback) @@ -117,9 +124,10 @@ public static MemoryCacheEntryOptions RegisterPostEvictionCallback( /// /// The given callback will be fired after the cache entry is evicted from the cache. /// - /// - /// - /// + /// The . + /// The callback to register for calling after an entry is evicted. + /// The state to pass to the callback. + /// The so that additional calls can be chained. public static MemoryCacheEntryOptions RegisterPostEvictionCallback( this MemoryCacheEntryOptions options, PostEvictionDelegate callback, @@ -138,4 +146,4 @@ public static MemoryCacheEntryOptions RegisterPostEvictionCallback( return options; } } -} \ No newline at end of file +} diff --git a/src/Caching/Memory/src/MemoryCache.cs b/src/Caching/Memory/src/MemoryCache.cs index e51c77df522..edbb6d79608 100644 --- a/src/Caching/Memory/src/MemoryCache.cs +++ b/src/Caching/Memory/src/MemoryCache.cs @@ -44,7 +44,7 @@ public MemoryCache(IOptions optionsAccessor) /// Creates a new instance. /// /// The options of the cache. - /// + /// The factory used to create loggers. public MemoryCache(IOptions optionsAccessor, ILoggerFactory loggerFactory) { if (optionsAccessor == null) diff --git a/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs b/src/Hosting/Abstractions/src/HostingAbstractionsHostBuilderExtensions.cs index b4753d72012..4f625a326d9 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. /// The started . public static async Task StartAsync(this IHostBuilder hostBuilder, CancellationToken cancellationToken = default) { diff --git a/src/Hosting/Abstractions/src/IHostBuilder.cs b/src/Hosting/Abstractions/src/IHostBuilder.cs index eecc6734338..986ffcd891c 100644 --- a/src/Hosting/Abstractions/src/IHostBuilder.cs +++ b/src/Hosting/Abstractions/src/IHostBuilder.cs @@ -48,15 +48,15 @@ public interface IHostBuilder /// /// Overrides the factory used to create the service provider. /// - /// - /// + /// The type of builder. + /// The factory to register/ /// The same instance of the for chaining. IHostBuilder UseServiceProviderFactory(IServiceProviderFactory factory); /// /// Overrides the factory used to create the service provider. /// - /// + /// The type of builder. /// The same instance of the for chaining. IHostBuilder UseServiceProviderFactory(Func> factory); @@ -64,15 +64,15 @@ public interface IHostBuilder /// Enables configuring the instantiated dependency container. This can be called multiple times and /// the results will be additive. /// - /// - /// + /// The type of builder. + /// The delegate which configures the builder. /// The same instance of the for chaining. IHostBuilder ConfigureContainer(Action configureDelegate); /// /// Run the given actions to initialize the host. This can only be called once. /// - /// An initialized + /// An initialized . IHost Build(); } } diff --git a/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs b/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs index a7cb9b372a8..7996be2d88b 100644 --- a/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs +++ b/src/Hosting/Hosting/src/HostingHostBuilderExtensions.cs @@ -152,7 +152,7 @@ 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. /// public static Task RunConsoleAsync(this IHostBuilder hostBuilder, CancellationToken cancellationToken = default) { @@ -164,7 +164,7 @@ public static Task RunConsoleAsync(this IHostBuilder hostBuilder, CancellationTo /// /// The to configure. /// - /// + /// A that can be used to cancel the health check. /// public static Task RunConsoleAsync(this IHostBuilder hostBuilder, Action configureOptions, CancellationToken cancellationToken = default) { diff --git a/src/Hosting/WindowsServices/src/WindowsServiceLifetimeHostBuilderExtensions.cs b/src/Hosting/WindowsServices/src/WindowsServiceLifetimeHostBuilderExtensions.cs index 555120b1a99..bdf147b12f7 100644 --- a/src/Hosting/WindowsServices/src/WindowsServiceLifetimeHostBuilderExtensions.cs +++ b/src/Hosting/WindowsServices/src/WindowsServiceLifetimeHostBuilderExtensions.cs @@ -23,8 +23,8 @@ public static class WindowsServiceLifetimeHostBuilderExtensions /// This is context aware and will only activate if it detects the process is running /// as a Windows Service. /// - /// - /// + /// The to operate on. + /// The same instance of the for chaining. public static IHostBuilder UseWindowsService(this IHostBuilder hostBuilder) { if (WindowsServiceHelpers.IsWindowsService()) diff --git a/src/Localization/Localization/src/ResourceManagerStringLocalizer.cs b/src/Localization/Localization/src/ResourceManagerStringLocalizer.cs index 90f8e077b42..a8321fca0ad 100644 --- a/src/Localization/Localization/src/ResourceManagerStringLocalizer.cs +++ b/src/Localization/Localization/src/ResourceManagerStringLocalizer.cs @@ -177,7 +177,7 @@ public virtual IEnumerable GetAllStrings(bool includeParentCult /// /// Returns all strings in the specified culture. /// - /// + /// Whether to include parent cultures in the search for a resource. /// The to get strings for. /// The strings. protected IEnumerable GetAllStrings(bool includeParentCultures, CultureInfo culture) diff --git a/src/Logging/Logging.Abstractions/src/ILogger.cs b/src/Logging/Logging.Abstractions/src/ILogger.cs index 2a1bb64df0a..cfa3b90071b 100644 --- a/src/Logging/Logging.Abstractions/src/ILogger.cs +++ b/src/Logging/Logging.Abstractions/src/ILogger.cs @@ -29,7 +29,6 @@ public interface ILogger /// true if enabled. bool IsEnabled(LogLevel logLevel); - /// /// Begins a logical operation scope. /// diff --git a/src/Logging/Logging.AzureAppServices/src/BlobLoggerProvider.cs b/src/Logging/Logging.AzureAppServices/src/BlobLoggerProvider.cs index 77182ea9338..e906c2746f9 100644 --- a/src/Logging/Logging.AzureAppServices/src/BlobLoggerProvider.cs +++ b/src/Logging/Logging.AzureAppServices/src/BlobLoggerProvider.cs @@ -41,7 +41,7 @@ public BlobLoggerProvider(IOptionsMonitor options) /// Creates a new instance of /// /// The container to store logs to. - /// + /// Options to be used in creating a logger. internal BlobLoggerProvider( IOptionsMonitor options, Func blobReferenceFactory) : diff --git a/src/Logging/Logging.Console/src/ConsoleLoggerFactoryExtensions.cs b/src/Logging/Logging.Console/src/ConsoleLoggerFactoryExtensions.cs index aae45a85e8e..ce9e24062b7 100644 --- a/src/Logging/Logging.Console/src/ConsoleLoggerFactoryExtensions.cs +++ b/src/Logging/Logging.Console/src/ConsoleLoggerFactoryExtensions.cs @@ -28,7 +28,7 @@ public static ILoggingBuilder AddConsole(this ILoggingBuilder builder) /// Adds a console logger named 'Console' to the factory. /// /// The to use. - /// + /// A delegate to configure the . public static ILoggingBuilder AddConsole(this ILoggingBuilder builder, Action configure) { if (configure == null) diff --git a/src/Logging/Logging.EventSource/src/EventSourceLogger.cs b/src/Logging/Logging.EventSource/src/EventSourceLogger.cs index 070a22c21ea..f3ed9ceae30 100644 --- a/src/Logging/Logging.EventSource/src/EventSourceLogger.cs +++ b/src/Logging/Logging.EventSource/src/EventSourceLogger.cs @@ -93,7 +93,7 @@ public void Log(LogLevel logLevel, EventId eventId, TState state, Except if (exception != null) { var exceptionInfo = GetExceptionInfo(exception); - var exceptionInfoData = new [] + var exceptionInfoData = new[] { new KeyValuePair("TypeName", exceptionInfo.TypeName), new KeyValuePair("Message", exceptionInfo.Message), @@ -179,7 +179,7 @@ public void Dispose() /// /// 'serializes' a given exception into an ExceptionInfo (that EventSource knows how to serialize) /// - /// + /// The exception to get information for. /// ExceptionInfo object represending a .NET Exception /// ETW does not support a concept of a null value. So we use an un-initialized object if there is no exception in the event data. private ExceptionInfo GetExceptionInfo(Exception exception) diff --git a/src/Logging/Logging.EventSource/src/LoggingEventSource.cs b/src/Logging/Logging.EventSource/src/LoggingEventSource.cs index 6521f1a4509..61338f50852 100644 --- a/src/Logging/Logging.EventSource/src/LoggingEventSource.cs +++ b/src/Logging/Logging.EventSource/src/LoggingEventSource.cs @@ -275,7 +275,7 @@ protected override void OnEventCommand(EventCommandEventArgs command) /// /// Set the filtering specification. null means turn off all loggers. Empty string is turn on all providers. /// - /// + /// The filter specification to set. [NonEvent] private void SetFilterSpec(string filterSpec) { @@ -298,7 +298,7 @@ private void FireChangeToken() tcs?.Cancel(); } - /// + /// /// Given a set of specifications Pat1:Level1;Pat1;Level2 ... Where /// Pat is a string pattern (a logger Name with a optional trailing wildcard * char) /// and Level is a number 0 (Trace) through 5 (Critical). @@ -314,7 +314,7 @@ private static LoggerFilterRule[] ParseFilterSpec(string filterSpec, LogLevel de { if (filterSpec == string.Empty) { - return new [] { new LoggerFilterRule(typeof(EventSourceLoggerProvider).FullName, null, defaultLevel, null) }; + return new[] { new LoggerFilterRule(typeof(EventSourceLoggerProvider).FullName, null, defaultLevel, null) }; } var rules = new List(); @@ -335,7 +335,7 @@ private static LoggerFilterRule[] ParseFilterSpec(string filterSpec, LogLevel de continue; } - if (loggerName[loggerName.Length-1] == '*') + if (loggerName[loggerName.Length - 1] == '*') { loggerName = loggerName.Substring(0, loggerName.Length - 1); } diff --git a/src/Logging/Logging/src/FilterLoggingBuilderExtensions.cs b/src/Logging/Logging/src/FilterLoggingBuilderExtensions.cs index d71994c29a6..fb428b6796d 100644 --- a/src/Logging/Logging/src/FilterLoggingBuilderExtensions.cs +++ b/src/Logging/Logging/src/FilterLoggingBuilderExtensions.cs @@ -23,7 +23,7 @@ public static ILoggingBuilder AddFilter(this ILoggingBuilder builder, Func /// Adds a log filter to the factory. /// - /// /// The to add the filter to. + /// The to add the filter to. /// The filter to be added. /// The so that additional calls can be chained. public static ILoggingBuilder AddFilter(this ILoggingBuilder builder, Func categoryLevelFilter) => diff --git a/src/Options/DataAnnotations/src/DataAnnotationValidateOptions.cs b/src/Options/DataAnnotations/src/DataAnnotationValidateOptions.cs index bfb0e5cae06..0aa565fe4fa 100644 --- a/src/Options/DataAnnotations/src/DataAnnotationValidateOptions.cs +++ b/src/Options/DataAnnotations/src/DataAnnotationValidateOptions.cs @@ -17,7 +17,7 @@ public class DataAnnotationValidateOptions : IValidateOptions /// Constructor. /// - /// + /// The name of the option. public DataAnnotationValidateOptions(string name) { Name = name; @@ -41,8 +41,8 @@ public ValidateOptionsResult Validate(string name, TOptions options) { var validationResults = new List(); if (Validator.TryValidateObject(options, - new ValidationContext(options, serviceProvider: null, items: null), - validationResults, + new ValidationContext(options, serviceProvider: null, items: null), + validationResults, validateAllProperties: true)) { return ValidateOptionsResult.Success; diff --git a/src/Options/Options/src/PostConfigureOptions.cs b/src/Options/Options/src/PostConfigureOptions.cs index 58d9c4569b5..42d8051c560 100644 --- a/src/Options/Options/src/PostConfigureOptions.cs +++ b/src/Options/Options/src/PostConfigureOptions.cs @@ -35,8 +35,8 @@ public PostConfigureOptions(string name, Action action) /// /// Invokes the registered initialization if the matches. /// - /// - /// + /// The name of the action to invoke. + /// The options to use in initialization. public virtual void PostConfigure(string name, TOptions options) { if (options == null)