update xml docs

Author: pwelter34

.editorconfig

@@ -9,6 +9,8 @@ indent_style = space
 indent_size = 4
 insert_final_newline = true
 trim_trailing_whitespace = true
+vsspell_section_id = main
+vsspell_ignored_words_main = File:dictionary.dic
 
 # XML Configuration Files
 [*.{xml,config,props,targets,nuspec,resx,ruleset,vsixmanifest,vsct,refactorlog,runsettings}]

dictionary.dic

@@ -0,0 +1,20 @@
+accessor
+app
+awaitable
+cacheable
+clr
+csv
+deconstruct
+deserialization
+deserializer
+inline
+json
+linq
+middleware
+mvc
+nullable
+queryable
+serialization
+serializer
+upsert
+validator

src/AspNetCore.SecurityKey/ApplicationBuilderExtensions.cs

@@ -3,18 +3,21 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// Extension methods for the <see cref="SecurityKeyMiddleware"/>.
+/// Provides extension methods for integrating <see cref="SecurityKeyMiddleware"/> into the ASP.NET Core request pipeline.
 /// </summary>
 public static class ApplicationBuilderExtensions
 {
     /// <summary>
-    /// Adds middleware for requiring security API key for all requests.
+    /// Registers the <see cref="SecurityKeyMiddleware"/> in the application's request pipeline.
+    /// This middleware enforces the presence of a valid security API key for all incoming HTTP requests.
     /// </summary>
-    /// <param name="builder">The <see cref="IApplicationBuilder" /> instance this method extends</param>
+    /// <param name="builder">The <see cref="IApplicationBuilder"/> to configure.</param>
     /// <returns>
-    /// The <see cref="IApplicationBuilder" /> for requiring security API keys
+    /// The <see cref="IApplicationBuilder"/> instance for chaining further middleware registrations.
     /// </returns>
-    /// <exception cref="System.ArgumentNullException">builder is null</exception>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="builder"/> is <c>null</c>.
+    /// </exception>
     public static IApplicationBuilder UseSecurityKey(this IApplicationBuilder builder)
     {
         ArgumentNullException.ThrowIfNull(builder);

src/AspNetCore.SecurityKey/AspNetCore.SecurityKey.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFrameworks>net6.0;net7.0;net8.0;net9.0</TargetFrameworks>
+    <TargetFrameworks>net6.0;net8.0;net9.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
   </PropertyGroup>

src/AspNetCore.SecurityKey/AuthenticationBuilderExtensions.cs

@@ -4,56 +4,69 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-///  Extension methods to configure security API key authentication.
+/// Provides extension methods for configuring security API key authentication in ASP.NET Core applications.
 /// </summary>
 public static class AuthenticationBuilderExtensions
 {
     /// <summary>
-    /// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
-    /// The default scheme is specified by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
+    /// Registers security API key authentication using the default scheme.
+    /// The default scheme is defined by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
     /// </summary>
-    /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-    /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
+    /// <param name="builder">The <see cref="AuthenticationBuilder"/> to configure.</param>
+    /// <returns>
+    /// The <see cref="AuthenticationBuilder"/> instance for chaining further authentication configuration.
+    /// </returns>
     public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder)
         => builder.AddSecurityKey(SecurityKeyAuthenticationDefaults.AuthenticationScheme);
 
     /// <summary>
-    /// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
+    /// Registers security API key authentication using a specified scheme.
     /// </summary>
-    /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-    /// <param name="authenticationScheme">The authentication scheme.</param>
-    /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
+    /// <param name="builder">The <see cref="AuthenticationBuilder"/> to configure.</param>
+    /// <param name="authenticationScheme">The name of the authentication scheme to use.</param>
+    /// <returns>
+    /// The <see cref="AuthenticationBuilder"/> instance for chaining further authentication configuration.
+    /// </returns>
     public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme)
         => builder.AddSecurityKey(authenticationScheme, configureOptions: null);
 
     /// <summary>
-    /// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
-    /// The default scheme is specified by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
+    /// Registers security API key authentication using the default scheme and allows configuration of options.
+    /// The default scheme is defined by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
     /// </summary>
-    /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+    /// <param name="builder">The <see cref="AuthenticationBuilder"/> to configure.</param>
     /// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
-    /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
+    /// <returns>
+    /// The <see cref="AuthenticationBuilder"/> instance for chaining further authentication configuration.
+    /// </returns>
     public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, Action<SecurityKeyAuthenticationSchemeOptions>? configureOptions)
         => builder.AddSecurityKey(SecurityKeyAuthenticationDefaults.AuthenticationScheme, configureOptions);
 
     /// <summary>
-    /// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
+    /// Registers security API key authentication using a specified scheme and allows configuration of options.
     /// </summary>
-    /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-    /// <param name="authenticationScheme">The authentication scheme.</param>
+    /// <param name="builder">The <see cref="AuthenticationBuilder"/> to configure.</param>
+    /// <param name="authenticationScheme">The name of the authentication scheme to use.</param>
     /// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
-    /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
+    /// <returns>
+    /// The <see cref="AuthenticationBuilder"/> instance for chaining further authentication configuration.
+    /// </returns>
     public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme, Action<SecurityKeyAuthenticationSchemeOptions>? configureOptions)
         => builder.AddSecurityKey(authenticationScheme, displayName: null, configureOptions: configureOptions);
 
     /// <summary>
-    /// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
+    /// Registers security API key authentication using a specified scheme, display name, and configuration options.
     /// </summary>
-    /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-    /// <param name="authenticationScheme">The authentication scheme.</param>
-    /// <param name="displayName">A display name for the authentication handler.</param>
+    /// <param name="builder">The <see cref="AuthenticationBuilder"/> to configure.</param>
+    /// <param name="authenticationScheme">The name of the authentication scheme to use.</param>
+    /// <param name="displayName">A display name for the authentication handler, used for UI or logging purposes.</param>
     /// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
-    /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
+    /// <returns>
+    /// The <see cref="AuthenticationBuilder"/> instance for chaining further authentication configuration.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="builder"/> is <c>null</c>.
+    /// </exception>
     public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme, string? displayName, Action<SecurityKeyAuthenticationSchemeOptions>? configureOptions)
     {
         ArgumentNullException.ThrowIfNull(builder);

src/AspNetCore.SecurityKey/DependencyInjectionExtensions.cs

@@ -5,44 +5,49 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// Extension methods for setting up security API key services
+/// Provides extension methods for registering security API key services in an ASP.NET Core application.
 /// </summary>
 public static class DependencyInjectionExtensions
 {
     /// <summary>
-    /// Adds the security API key services to the specified <see cref="IServiceCollection"/>.
+    /// Registers the default security API key services and configuration in the specified <see cref="IServiceCollection"/>.
+    /// Uses <see cref="SecurityKeyValidator"/> for validation and <see cref="SecurityKeyExtractor"/> for extraction.
     /// </summary>
-    /// <param name="services">The <see cref="IServiceCollection"/> to add services.</param>
-    /// <param name="configure">An action delegate to configure the provided <see cref="SecurityKeyOptions"/>.</param>
+    /// <param name="services">The <see cref="IServiceCollection"/> to which the services are added.</param>
+    /// <param name="configure">An optional delegate to configure <see cref="SecurityKeyOptions"/>.</param>
     /// <returns>
-    /// The <see cref="IServiceCollection"/> so that additional calls can be chained.
+    /// The same <see cref="IServiceCollection"/> instance for chaining further service registrations.
     /// </returns>
     public static IServiceCollection AddSecurityKey(this IServiceCollection services, Action<SecurityKeyOptions>? configure = null)
         => AddSecurityKey<SecurityKeyValidator, SecurityKeyExtractor>(services, configure);
 
     /// <summary>
-    /// Adds the security API key services to the specified <see cref="IServiceCollection" />.
+    /// Registers security API key services with a custom validator in the specified <see cref="IServiceCollection"/>.
+    /// Uses <see cref="SecurityKeyExtractor"/> for extraction.
     /// </summary>
-    /// <typeparam name="TValidator">The type for validating the security API key.</typeparam>
-    /// <param name="services">The <see cref="IServiceCollection" /> to add services.</param>
-    /// <param name="configure">An action delegate to configure the provided <see cref="SecurityKeyOptions" />.</param>
+    /// <typeparam name="TValidator">The type implementing <see cref="ISecurityKeyValidator"/> for validating the security API key.</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection"/> to which the services are added.</param>
+    /// <param name="configure">An optional delegate to configure <see cref="SecurityKeyOptions"/>.</param>
     /// <returns>
-    /// The <see cref="IServiceCollection" /> so that additional calls can be chained.
+    /// The same <see cref="IServiceCollection"/> instance for chaining further service registrations.
     /// </returns>
     public static IServiceCollection AddSecurityKey<TValidator>(this IServiceCollection services, Action<SecurityKeyOptions>? configure = null)
         where TValidator : class, ISecurityKeyValidator
         => AddSecurityKey<TValidator, SecurityKeyExtractor>(services, configure);
 
     /// <summary>
-    /// Adds the security API key services to the specified <see cref="IServiceCollection" />.
+    /// Registers security API key services with custom validator and extractor types in the specified <see cref="IServiceCollection"/>.
     /// </summary>
-    /// <typeparam name="TValidator">The type for validating the security API key.</typeparam>
-    /// <typeparam name="TExtractor">The type for extracting the security API key.</typeparam>
-    /// <param name="services">The <see cref="IServiceCollection" /> to add services.</param>
-    /// <param name="configure">An action delegate to configure the provided <see cref="SecurityKeyOptions" />.</param>
+    /// <typeparam name="TValidator">The type implementing <see cref="ISecurityKeyValidator"/> for validating the security API key.</typeparam>
+    /// <typeparam name="TExtractor">The type implementing <see cref="ISecurityKeyExtractor"/> for extracting the security API key.</typeparam>
+    /// <param name="services">The <see cref="IServiceCollection"/> to which the services are added.</param>
+    /// <param name="configure">An optional delegate to configure <see cref="SecurityKeyOptions"/>.</param>
     /// <returns>
-    /// The <see cref="IServiceCollection" /> so that additional calls can be chained.
+    /// The same <see cref="IServiceCollection"/> instance for chaining further service registrations.
     /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="services"/> is <c>null</c>.
+    /// </exception>
     public static IServiceCollection AddSecurityKey<TValidator, TExtractor>(this IServiceCollection services, Action<SecurityKeyOptions>? configure = null)
         where TValidator : class, ISecurityKeyValidator
         where TExtractor : class, ISecurityKeyExtractor

src/AspNetCore.SecurityKey/EndpointFilterExtensions.cs

@@ -5,17 +5,21 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// Extension methods for adding <see cref="IEndpointFilter" /> to a route handler.
+/// Provides extension methods for attaching <see cref="IEndpointFilter"/> implementations to route handlers.
 /// </summary>
 public static class EndpointFilterExtensions
 {
     /// <summary>
-    /// Registers an endpoint filter requiring security API key for the specified route handler.
+    /// Adds an endpoint filter to the specified <see cref="RouteHandlerBuilder"/> that enforces a security API key requirement.
+    /// The filter uses <see cref="SecurityKeyEndpointFilter"/> to validate requests for the presence of a valid API key.
     /// </summary>
-    /// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
+    /// <param name="builder">The <see cref="RouteHandlerBuilder"/> to configure.</param>
     /// <returns>
-    /// A <see cref="RouteHandlerBuilder"/> that can be used to further customize the route handler.
+    /// The same <see cref="RouteHandlerBuilder"/> instance for further route customization.
     /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="builder"/> is <c>null</c>.
+    /// </exception>
     public static RouteHandlerBuilder RequireSecurityKey(this RouteHandlerBuilder builder)
     {
         ArgumentNullException.ThrowIfNull(builder);

src/AspNetCore.SecurityKey/ISecurityKeyExtractor.cs

@@ -3,14 +3,18 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// An interface for extracting the security API key
+/// Defines a contract for extracting a security API key from an HTTP request context.
+/// Implementations should provide logic to retrieve the API key from headers, query parameters, or other request data.
 /// </summary>
 public interface ISecurityKeyExtractor
 {
     /// <summary>
-    /// Gets the security API key from the specified <see cref="HttpContent"/>.
+    /// Attempts to extract the security API key from the specified <see cref="HttpContext"/>.
+    /// Implementations may inspect headers, query parameters, or other request properties to locate the key.
     /// </summary>
-    /// <param name="context">The <see cref="HttpContent"/> to get security key from.</param>
-    /// <returns>The security API key if found; otherwise null</returns>
+    /// <param name="context">The <see cref="HttpContext"/> representing the current HTTP request.</param>
+    /// <returns>
+    /// The extracted security API key if found; otherwise, <c>null</c>.
+    /// </returns>
     string? GetKey(HttpContext? context);
 }

src/AspNetCore.SecurityKey/ISecurityKeyValidator.cs

@@ -3,27 +3,29 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// An interface for validating the security API key
+/// Defines a contract for validating and authenticating security API keys in an HTTP request context.
+/// Implementations should provide logic to verify the key's validity and produce authentication identities.
 /// </summary>
 public interface ISecurityKeyValidator
 {
     /// <summary>
-    /// Validates the specified security API key.
+    /// Asynchronously validates the specified security API key.
     /// </summary>
-    /// <param name="value">The security API key to validate.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="value">The security API key to validate. May be <c>null</c> if not provided in the request.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
     /// <returns>
-    /// true if security API key is valid; otherwise false
+    /// A <see cref="ValueTask{Boolean}"/> that resolves to <c>true</c> if the security API key is valid; otherwise, <c>false</c>.
     /// </returns>
     ValueTask<bool> Validate(string? value, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Authenticate the specified security API key.
+    /// Asynchronously authenticates the specified security API key and produces a <see cref="ClaimsIdentity"/> if valid.
     /// </summary>
-    /// <param name="value">The security API key to validate.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="value">The security API key to authenticate. May be <c>null</c> if not provided in the request.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
     /// <returns>
-    ///   <see cref="ClaimsIdentity" /> result of the authentication
+    /// A <see cref="ValueTask{ClaimsIdentity}"/> representing the result of the authentication.
+    /// The returned <see cref="ClaimsIdentity"/> should reflect the authenticated principal if the key is valid.
     /// </returns>
     ValueTask<ClaimsIdentity> Authenticate(string? value, CancellationToken cancellationToken = default);
 }

src/AspNetCore.SecurityKey/SecurityKeyAttribute.cs

@@ -3,13 +3,16 @@
 namespace AspNetCore.SecurityKey;
 
 /// <summary>
-/// Specifies that the class or method that this attribute is applied to requires security API key authorization.
+/// Indicates that the decorated controller or action requires security API key authorization.
+/// When applied, requests must provide a valid API key to access the resource.
+/// This attribute uses <see cref="SecurityKeyAuthorizationFilter"/> to enforce authorization.
 /// </summary>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
 public class SecurityKeyAttribute : ServiceFilterAttribute
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="SecurityKeyAttribute"/> class.
+    /// Initializes a new instance of the <see cref="SecurityKeyAttribute"/> class,
+    /// configuring it to use <see cref="SecurityKeyAuthorizationFilter"/> for API key validation.
     /// </summary>
     public SecurityKeyAttribute() : base(typeof(SecurityKeyAuthorizationFilter))
     {