Add XML documentation to all public APIs

src/AzureCosmos/AzureCosmosActionCacheFactory.cs

@@ -14,7 +14,7 @@ namespace ActionCache.AzureCosmos;
 public class AzureCosmosActionCacheFactory : ActionCacheFactoryBase
 {
     /// <summary>
-    /// An Azure Cosmos Db client implementation.
+    /// The Azure Cosmos DB container used as the backing store for created cache instances.
     /// </summary>
     protected readonly Container Cache;
 

src/AzureCosmos/AzureCosmosCacheOptions.cs

@@ -8,11 +8,8 @@ namespace ActionCache.AzureCosmos;
 public class AzureCosmosCacheOptions
 {
     /// <summary>
-    /// Gets or sets the connection string for the Azure Cosmos cache.
+    /// Gets or sets the connection string used to connect to the Azure Cosmos DB account.
     /// </summary>
-    /// <remarks>
-    /// The <see cref="ConnectionString"/> is required to establish a connection to the Cosmos database.
-    /// </remarks>
     public string? ConnectionString { get; set; }
 
     /// <summary>

src/AzureCosmos/AzureCosmosEntry.cs

@@ -37,23 +37,23 @@ public class AzureCosmosEntry
     public required string Value { get; set; }
 
     /// <summary>
-    /// Gets or sets the absolute expiration associated with the entry.
+    /// Gets or sets the absolute expiration of the entry as a Unix timestamp in milliseconds.
     /// </summary>
     [JsonPropertyName("absoluteExpiration")]
-    [JsonProperty(PropertyName = "absoluteExpiration")]  
+    [JsonProperty(PropertyName = "absoluteExpiration")]
     public long AbsoluteExpiration { get; set; }
 
     /// <summary>
-    /// Gets or sets the sliding expiration associated with the entry.
+    /// Gets or sets the sliding expiration of the entry in milliseconds.
     /// </summary>
     [JsonPropertyName("slidingExpiration")]
-    [JsonProperty(PropertyName = "slidingExpiration")]  
+    [JsonProperty(PropertyName = "slidingExpiration")]
     public long SlidingExpiration { get; set; }
 
     /// <summary>
-    /// Gets or sets the TTL associated with the entry.
+    /// Gets or sets the Cosmos DB TTL for the entry in seconds; <c>-1</c> disables TTL-based expiration.
     /// </summary>
     [JsonPropertyName("ttl")]
-    [JsonProperty(PropertyName = "ttl")]  
+    [JsonProperty(PropertyName = "ttl")]
     public long TTL { get; set; }
 }

src/AzureCosmos/Exceptions/AzureCosmosContainerNotFoundOrCreated.cs

@@ -9,10 +9,10 @@ namespace ActionCache.AzureCosmos.Exceptions;
 public class AzureCosmosContainerNotFoundOrCreated : Exception
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="AzureCosmosContainerNotFoundOrCreated"/> class
-    /// with the default error message.
+    /// Initializes a new instance of the <see cref="AzureCosmosContainerNotFoundOrCreated"/> class with an error message containing the HTTP status code from <paramref name="response"/>.
     /// </summary>
-    public AzureCosmosContainerNotFoundOrCreated(ContainerResponse response) 
+    /// <param name="response">The Cosmos DB container response whose status code is included in the exception message.</param>
+    public AzureCosmosContainerNotFoundOrCreated(ContainerResponse response)
         : base($"An error occurred fetching or creating Azure Cosmos container ({response.StatusCode}).")
     {
     }

src/AzureCosmos/Exceptions/AzureCosmosDatabaseNotFoundOrCreated.cs

@@ -9,10 +9,10 @@ namespace ActionCache.AzureCosmos.Exceptions;
 public class AzureCosmosDatabaseNotFoundOrCreated : Exception
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="AzureCosmosDatabaseNotFoundOrCreated"/> class
-    /// with the default error message.
+    /// Initializes a new instance of the <see cref="AzureCosmosDatabaseNotFoundOrCreated"/> class with an error message containing the HTTP status code from <paramref name="response"/>.
     /// </summary>
-    public AzureCosmosDatabaseNotFoundOrCreated(DatabaseResponse response) 
+    /// <param name="response">The Cosmos DB database response whose status code is included in the exception message.</param>
+    public AzureCosmosDatabaseNotFoundOrCreated(DatabaseResponse response)
         : base($"An error occurred fetching or creating Azure Cosmos database ({response.StatusCode}).")
     {
     }

src/Common/Caching/ActionCacheFactoryBase.cs

@@ -19,10 +19,10 @@ public abstract class ActionCacheFactoryBase : IActionCacheFactory
     protected readonly IActionCacheRefreshProvider RefreshProvider;
 
     /// <summary>
-    /// The base constructor.
+    /// Initializes a new instance of the <see cref="ActionCacheFactoryBase"/> class.
     /// </summary>
-    /// <param name="entryOptionsAccessor">entryOptionsAccessor global entry options accessor.</param>
-    /// <param name="refreshProvider">The refresh provider.</param>
+    /// <param name="entryOptionsAccessor">Accessor for the globally configured <see cref="ActionCacheEntryOptions"/>.</param>
+    /// <param name="refreshProvider">The provider used to refresh stale cache entries by re-invoking their originating actions.</param>
     public ActionCacheFactoryBase(
         IOptions<ActionCacheEntryOptions> entryOptionsAccessor,
         IActionCacheRefreshProvider refreshProvider

src/Common/Caching/ActionCacheOptionsBuilder.cs

@@ -65,7 +65,7 @@ public ActionCacheOptionsBuilder UseSqlServerCache(Action<SqlServerCacheOptions>
     }
 
     /// <summary>
-    /// Enables the use of SQL Server cache.
+    /// Enables the use of Azure Cosmos DB as a cache backend.
     /// </summary>
     /// <returns>Returns this instance of <see cref="ActionCacheOptionsBuilder"/>.</returns>
     public ActionCacheOptionsBuilder UseAzureCosmosCache(Action<AzureCosmosCacheOptions> configureOptions)

src/Common/Caching/ActionCacheRefreshProvider.cs

@@ -5,7 +5,7 @@
 namespace ActionCache.Common.Caching;
 
 /// <summary>
-/// A class responsible for executing controller actions for cache keys
+/// Re-invokes cached controller actions to produce up-to-date values for each cache key.
 /// </summary>
 public class ActionCacheRefreshProvider : IActionCacheRefreshProvider
 {

src/Common/Concurrency/CacheLockerBase.cs

@@ -76,10 +76,7 @@ public virtual Task WaitForLockThenAsync(string resource, Action thenFunc) =>
     /// <param name="resource">The resource to acquire the lock for.</param>
     /// <param name="thenFunc">The action to execute once the lock is acquired.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
-    /// <remarks>
-    /// The action will be executed after the lock is acquired and released once the action completes.
-    /// If the lock acquisition fails, no action is executed.
-    /// </remarks>
+    /// <exception cref="InvalidOperationException">Thrown when the lock cannot be acquired within the configured timeout.</exception>
     public virtual async Task WaitForLockThenAsync(string resource, Func<Task> thenFunc)
     {
         var cacheLock = await WaitForLockAsync(resource);
@@ -107,10 +104,7 @@ public virtual async Task WaitForLockThenAsync(string resource, Func<Task> thenF
     /// <param name="resource">The resource to acquire the lock for.</param>
     /// <param name="resultAccessor">The function that will be executed once the lock is acquired, which returns a result.</param>
     /// <returns>A task representing the asynchronous operation, with the result of the function.</returns>
-    /// <remarks>
-    /// The result will be returned after the lock is acquired and released once the function completes.
-    /// If the lock acquisition fails, the result will be null.
-    /// </remarks>
+    /// <exception cref="InvalidOperationException">Thrown when the lock cannot be acquired within the configured timeout.</exception>
     public virtual async Task<TResult?> WaitForLockThenAsync<TResult>(string resource, Func<Task<TResult>> resultAccessor)
     {
         TResult? result = default;

src/Common/Concurrency/Interfaces/ICacheLockerHandler.cs

@@ -28,10 +28,7 @@ public interface ICacheLockerHandler
     /// <param name="resource">The resource to acquire the lock for.</param>
     /// <param name="thenFunc">The action to execute once the lock is acquired.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
-    /// <remarks>
-    /// The action will be executed after the lock is acquired and released once the action completes.
-    /// If the lock acquisition fails, no action is executed.
-    /// </remarks>
+    /// <exception cref="InvalidOperationException">Thrown when the lock cannot be acquired within the configured timeout.</exception>
     Task WaitForLockThenAsync(string resource, Func<Task> thenFunc);
 
     /// <summary>
@@ -41,9 +38,6 @@ public interface ICacheLockerHandler
     /// <param name="resource">The resource to acquire the lock for.</param>
     /// <param name="resultAccessor">The function that will be executed once the lock is acquired, which returns a result.</param>
     /// <returns>A task representing the asynchronous operation, with the result of the function.</returns>
-    /// <remarks>
-    /// The result will be returned after the lock is acquired and released once the function completes.
-    /// If the lock acquisition fails, the result will be null.
-    /// </remarks>
+    /// <exception cref="InvalidOperationException">Thrown when the lock cannot be acquired within the configured timeout.</exception>
     Task<TResult?> WaitForLockThenAsync<TResult>(string resource, Func<Task<TResult>> resultAccessor);
 }

src/Common/Concurrency/Locks/CacheLock.cs

@@ -15,7 +15,7 @@ public CacheLock(string resource)
     }
 
     /// <summary>
-    /// Gets or sets the unique resource identifier associated with the lock.
+    /// Gets the unique resource identifier associated with the lock.
     /// </summary>
     public readonly string Resource;
 
@@ -35,7 +35,7 @@ public CacheLock(string resource)
     public TimeSpan Timeout { get; set; } = TimeSpan.FromMilliseconds(150);
 
     /// <summary>
-    /// Gets the timestamp when the lock request was initiated.
+    /// Gets the UTC timestamp when the lock request was initiated.
     /// </summary>
     public DateTime DateRequested { get; } = DateTime.UtcNow;
 }

src/Common/Concurrency/Locks/NullCacheLock.cs

@@ -1,8 +1,7 @@
 namespace ActionCache.Common.Concurrency.Locks;
 
 /// <summary>
-/// Represents a no-operation cache lock that does not perform any locking mechanism.
-/// This is useful as a fallback when no actual locking is required.
+/// Represents a no-operation cache lock that always reports itself as acquired without performing any locking.
 /// </summary>
 public class NullCacheLock : CacheLock
 {

src/Common/Concurrency/NullCacheLocker.cs

@@ -3,8 +3,7 @@
 namespace ActionCache.Common.Concurrency;
 
 /// <summary>
-/// Represents a no-operation cache locker that does not perform any actual locking mechanism.
-/// It serves as a fallback implementation where a locking system is required but not enforced.
+/// A no-operation <see cref="CacheLockerBase{TLock}"/> that immediately grants every lock request without any blocking or synchronization.
 /// </summary>
 public class NullCacheLocker : CacheLockerBase<NullCacheLock>
 {
@@ -16,25 +15,22 @@ public NullCacheLocker() : base(TimeSpan.Zero, TimeSpan.Zero)
     }
 
     /// <summary>
-    /// Releases the specified lock asynchronously. Since this is a no-operation implementation, 
-    /// the method completes immediately.
+    /// Releases the specified lock asynchronously as a no-operation and returns a completed task immediately.
     /// </summary>
     /// <param name="cacheLock">The lock to be released.</param>
     /// <returns>A completed task.</returns>
     public override Task ReleaseLockAsync(NullCacheLock cacheLock) => Task.CompletedTask;
 
     /// <summary>
-    /// Attempts to acquire a lock for the specified resource asynchronously.
-    /// Since this is a no-operation implementation, it always returns a new lock immediately.
+    /// Returns a pre-acquired <see cref="NullCacheLock"/> for the specified resource without any blocking.
     /// </summary>
     /// <param name="resource">The resource to lock.</param>
     /// <returns>A completed task containing the acquired lock.</returns>
     public override Task<NullCacheLock> TryAcquireLockAsync(string resource) => 
         Task.FromResult(new NullCacheLock(resource));
 
     /// <summary>
-    /// Waits for a lock on the specified resource asynchronously.
-    /// Since this is a no-operation implementation, it immediately returns a new lock.
+    /// Returns a pre-acquired <see cref="NullCacheLock"/> for the specified resource without any waiting.
     /// </summary>
     /// <param name="resource">The resource to lock.</param>
     /// <returns>A completed task containing the acquired lock.</returns>

src/Common/EndpointFilters/ActionCacheEndpointEvictionFilterFactory.cs

@@ -5,7 +5,7 @@
 namespace ActionCache.Filters;
 
 /// <summary>
-/// Provides a custom filter factory for caching action results based on the configuration.
+/// A filter factory attribute that creates an <see cref="ActionCache.EndpointFilters.ActionCacheEndpointEvictionFilter"/> to evict cached entries for the configured namespace.
 /// </summary>
 [AttributeUsage(AttributeTargets.Method)]
 public class ActionCacheEndpointEvictionFilterFactory : ActionCacheEndpointFilterFactoryBase

src/Common/EndpointFilters/ActionCacheEndpointFilterAbstractFactory.cs

@@ -26,7 +26,7 @@ public class ActionCacheEndpointFilterAbstractFactory : IActionCacheFilterAbstra
     protected readonly TemplateBinderFactory BinderFactory;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ActionCacheEvictionFilter"/> class.
+    /// Initializes a new instance of the <see cref="ActionCacheEndpointFilterAbstractFactory"/> class.
     /// </summary>
     /// <param name="cacheFactories">The cache factories used to create caches.</param>
     /// <param name="binderFactory">The template binder for parsing route parameters for templated namespaces.</param>
@@ -40,14 +40,14 @@ TemplateBinderFactory binderFactory
     }
 
     /// <inheritdoc/>
-    /// <exception cref="InvalidCacheInstanceException"></exception> 
-    /// <exception cref="FilterTypeNotSupportedException"></exception>
-    public IEndpointFilter CreateInstance(Namespace @namespace, FilterType type) => 
+    /// <exception cref="InvalidCacheInstanceException">Thrown if no cache instances could be created for the namespace.</exception>
+    /// <exception cref="FilterTypeNotSupportedException">Thrown if the specified filter type is not supported.</exception>
+    public IEndpointFilter CreateInstance(Namespace @namespace, FilterType type) =>
         CreateInstance(@namespace, absoluteExpiration: null, slidingExpiration: null, type);
 
     /// <inheritdoc/>
-    /// <exception cref="InvalidCacheInstanceException"></exception> 
-    /// <exception cref="FilterTypeNotSupportedException"></exception>
+    /// <exception cref="InvalidCacheInstanceException">Thrown if no cache instances could be created for the namespace.</exception>
+    /// <exception cref="FilterTypeNotSupportedException">Thrown if the specified filter type is not supported.</exception>
     public IEndpointFilter CreateInstance(Namespace @namespace, TimeSpan? absoluteExpiration, TimeSpan? slidingExpiration, FilterType type)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(@namespace, nameof(@namespace));

src/Common/EndpointFilters/ActionCacheEndpointFilterFactoryBase.cs

@@ -8,7 +8,7 @@
 namespace ActionCache.Filters;
 
 /// <summary>
-/// Provides a base factory for creating instances of action cache filters.
+/// Provides a base factory for creating instances of Minimal API endpoint cache filters.
 /// </summary>
 public abstract class ActionCacheEndpointFilterFactoryBase : Attribute
 {
@@ -27,13 +27,13 @@ public abstract class ActionCacheEndpointFilterFactoryBase : Attribute
     public abstract IEndpointFilter CreateInstance(IServiceProvider serviceProvider);
 
     /// <summary>
-    /// 
+    /// Resolves and creates an <see cref="IEndpointFilter"/> of the specified type with optional expiration settings.
     /// </summary>
-    /// <param name="serviceProvider">The service provider.</param>
+    /// <param name="serviceProvider">The service provider used to resolve the abstract filter factory.</param>
     /// <param name="type">The type of filter to be created.</param>
-    /// <param name="absoluteExpiration">The absolute expiration in milliseconds for a cache entry.</param>
-    /// <param name="slidingExpiration">The sliding expiration in milliseconds for a cache entry.</param>
-    /// <returns>An instance of a cache filter.</returns>
+    /// <param name="absoluteExpiration">The absolute expiration duration for a cache entry, or <see langword="null"/> for no absolute expiration.</param>
+    /// <param name="slidingExpiration">The sliding expiration duration for a cache entry, or <see langword="null"/> for no sliding expiration.</param>
+    /// <returns>An <see cref="IEndpointFilter"/> instance representing the resolved cache filter.</returns>
     protected IEndpointFilter CreateInstance(IServiceProvider serviceProvider, 
         FilterType type,
         TimeSpan? absoluteExpiration = null, 

src/Common/Filters/ActionCacheFilterAbstractFactory.cs

@@ -25,7 +25,7 @@ public class ActionCacheFilterAbstractFactory : IActionCacheFilterAbstractFactor
     protected readonly TemplateBinderFactory BinderFactory;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ActionCacheEvictionFilter"/> class.
+    /// Initializes a new instance of the <see cref="ActionCacheFilterAbstractFactory"/> class.
     /// </summary>
     /// <param name="cacheFactories">The cache factories used to create caches.</param>
     /// <param name="binderFactory">The template binder for parsing route parameters for templated namespaces.</param>
@@ -39,14 +39,14 @@ TemplateBinderFactory binderFactory
     }
 
     /// <inheritdoc/>
-    /// <exception cref="InvalidCacheInstanceException"></exception> 
-    /// <exception cref="FilterTypeNotSupportedException"></exception>
-    public IFilterMetadata CreateInstance(Namespace @namespace, FilterType type) => 
+    /// <exception cref="InvalidCacheInstanceException">Thrown if no cache instances could be created for the namespace.</exception>
+    /// <exception cref="FilterTypeNotSupportedException">Thrown if the specified filter type is not supported.</exception>
+    public IFilterMetadata CreateInstance(Namespace @namespace, FilterType type) =>
         CreateInstance(@namespace, absoluteExpiration: null, slidingExpiration: null, type);
 
     /// <inheritdoc/>
-    /// <exception cref="InvalidCacheInstanceException"></exception> 
-    /// <exception cref="FilterTypeNotSupportedException"></exception>
+    /// <exception cref="InvalidCacheInstanceException">Thrown if no cache instances could be created for the namespace.</exception>
+    /// <exception cref="FilterTypeNotSupportedException">Thrown if the specified filter type is not supported.</exception>
     public IFilterMetadata CreateInstance(Namespace @namespace, TimeSpan? absoluteExpiration, TimeSpan? slidingExpiration, FilterType type)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(@namespace, nameof(@namespace));

src/Common/Filters/ActionCacheFilterFactoryBase.cs

@@ -27,14 +27,14 @@ public abstract class ActionCacheFilterFactoryBase : Attribute, IFilterFactory
     public abstract IFilterMetadata CreateInstance(IServiceProvider serviceProvider);
 
     /// <summary>
-    /// 
+    /// Resolves and creates an <see cref="IFilterMetadata"/> of the specified type with optional expiration settings.
     /// </summary>
-    /// <param name="serviceProvider">The service provider.</param>
+    /// <param name="serviceProvider">The service provider used to resolve the abstract filter factory.</param>
     /// <param name="type">The type of filter to be created.</param>
-    /// <param name="absoluteExpiration">The absolute expiration in milliseconds for a cache entry.</param>
-    /// <param name="slidingExpiration">The sliding expiration in milliseconds for a cache entry.</param>
-    /// <returns>An instance of a cache filter.</returns>
-    protected IFilterMetadata CreateInstance(IServiceProvider serviceProvider, 
+    /// <param name="absoluteExpiration">The absolute expiration duration for a cache entry, or <see langword="null"/> for no absolute expiration.</param>
+    /// <param name="slidingExpiration">The sliding expiration duration for a cache entry, or <see langword="null"/> for no sliding expiration.</param>
+    /// <returns>An <see cref="IFilterMetadata"/> instance representing the resolved cache filter.</returns>
+    protected IFilterMetadata CreateInstance(IServiceProvider serviceProvider,
         FilterType type,
         TimeSpan? absoluteExpiration = null, 
         TimeSpan? slidingExpiration = null