Add documentation

Author: calledude

AsyncMemoryCache/AsyncMemoryCache.cs

@@ -1,4 +1,5 @@
-using Microsoft.Extensions.Logging;
+using AsyncMemoryCache.EvictionBehaviors;
+using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Nito.AsyncEx;
 using System;
@@ -10,16 +11,58 @@
 
 namespace AsyncMemoryCache;
 
+/// <summary>
+/// This interface exists mainly to avoid having concrete types as constructor arguments.
+/// An effect of this is enabling subsitution and as a result, easier testing, where an actual concrete instance is not required in each and every test that uses a class that looks like the following
+/// <para/>
+/// <code>
+/// public MyService(AsyncMemoryCache&lt;string, SomeCacheable&gt;) { }
+/// </code>
+/// </summary>
+/// <typeparam name="TKey">The type of the key for cache items represented by the cache.</typeparam>
+/// <typeparam name="TValue">The type of the value which each item in the cache will hold.</typeparam>
 public interface IAsyncMemoryCache<TKey, TValue>
 	where TKey : notnull
 	where TValue : IAsyncDisposable
 {
+	/// <summary>
+	/// Gets the cached item with the specified key.
+	/// </summary>
+	/// <param name="key">The key of the element to get.</param>
+	/// <returns>A <see cref="CacheEntityReference{TKey, TValue}"/> representing the lifetime of the underlying <see cref="CacheEntity{TKey, TValue}"/> until disposed.</returns>
 	CacheEntityReference<TKey, TValue> this[TKey key] { get; }
+
+	/// <summary>
+	/// Gets the value associated with this key if it exists, or generates a new entry using the provided key and a value from the given factory if the key is not found.<br/>
+	/// The <paramref name="objectFactory"/> is started in a non-blocking fashion, and the result from it will have to be <c>await</c>ed
+	/// </summary>
+	/// <param name="key">The cache item key.</param>
+	/// <param name="objectFactory">The object factory.</param>
+	/// <param name="lazyFlags">Optional <see cref="AsyncLazyFlags"/> to configure object factory behavior.</param>
+	/// <returns>A <see cref="CacheEntityReference{TKey, TValue}"/> representing the lifetime of the underlying <see cref="CacheEntity{TKey, TValue}"/> until disposed.</returns>
 	CacheEntityReference<TKey, TValue> GetOrCreate(TKey key, Func<Task<TValue>> objectFactory, AsyncLazyFlags lazyFlags = AsyncLazyFlags.None);
+
+	/// <summary>
+	/// Determines whether the <see cref="IAsyncMemoryCache{TKey, TValue}"/> contains an element with the specified key.
+	/// </summary>
+	/// <param name="key">The key to locate in the <see cref="IAsyncMemoryCache{TKey, TValue}"/>.</param>
+	/// <returns><see langword="true"/> if the <see cref="IAsyncMemoryCache{TKey, TValue}"/> contains a cache item with the key; otherwise, <see langword="false"/>.</returns>
 	bool ContainsKey(TKey key);
+
+	/// <summary>
+	/// Gets the value associated with the specified key.
+	/// </summary>
+	/// <param name="key">The key whose value to get.</param>
+	/// <param name="value">When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter.</param>
+	/// <returns><see langword="true"/> if a cache item with the specified key exists; otherwise <see langword="false"/>.</returns>
 	bool TryGetValue(TKey key, [NotNullWhen(true)] out CacheEntityReference<TKey, TValue>? value);
 }
 
+/// <summary>
+/// The default implementation of <see cref="IAsyncMemoryCache{TKey, TValue}"/>
+/// </summary>
+/// <typeparam name="TKey">The type of the key for cache items represented by the cache.</typeparam>
+/// <typeparam name="TValue">The type of the value which each item in the cache will hold.</typeparam>
 public sealed class AsyncMemoryCache<TKey, TValue> : IAsyncDisposable, IAsyncMemoryCache<TKey, TValue>
 	where TKey : notnull
 	where TValue : IAsyncDisposable
@@ -44,6 +87,7 @@ public AsyncMemoryCache(IAsyncMemoryCacheConfiguration<TKey, TValue> configurati
 		configuration.EvictionBehavior.Start(configuration, _logger);
 	}
 
+	/// <inheritdoc/>
 	public CacheEntityReference<TKey, TValue> this[TKey key]
 	{
 		get
@@ -54,6 +98,7 @@ public CacheEntityReference<TKey, TValue> this[TKey key]
 		}
 	}
 
+	/// <inheritdoc/>
 	public CacheEntityReference<TKey, TValue> GetOrCreate(TKey key, Func<Task<TValue>> objectFactory, AsyncLazyFlags lazyFlags = AsyncLazyFlags.None)
 	{
 		_logger.LogTrace("Adding item with key: {Key}", key);
@@ -69,9 +114,11 @@ public CacheEntityReference<TKey, TValue> GetOrCreate(TKey key, Func<Task<TValue
 		return new(cacheEntity);
 	}
 
+	/// <inheritdoc/>
 	public bool ContainsKey(TKey key)
 		=> _cache.ContainsKey(key);
 
+	/// <inheritdoc/>
 	public bool TryGetValue(TKey key, [NotNullWhen(true)] out CacheEntityReference<TKey, TValue>? value)
 	{
 		if (_cache.TryGetValue(key, out var entity))

AsyncMemoryCache/AsyncMemoryCacheConfiguration.cs

@@ -6,20 +6,43 @@
 
 namespace AsyncMemoryCache;
 
+/// <summary>
+/// An interface which configures the <see cref="AsyncMemoryCache{TKey, TValue}"/><br/>
+/// Can be used to extend the configuration for use in custom implementations of either <see cref="IAsyncMemoryCache{TKey, TValue}"/> or <see cref="IEvictionBehavior"/>
+/// </summary>
+/// <typeparam name="TKey">The type of the key for cache items represented by the cache.</typeparam>
+/// <typeparam name="TValue">The type of the value which each item in the cache will hold.</typeparam>
 public interface IAsyncMemoryCacheConfiguration<TKey, TValue>
 	where TKey : notnull
 	where TValue : IAsyncDisposable
 {
 	Action<TKey, TValue>? CacheItemExpired { get; init; }
+
+	/// <summary>
+	/// The eviction behavior. Default is <see cref="DefaultEvictionBehavior"/>
+	/// </summary>
 	IEvictionBehavior EvictionBehavior { get; init; }
+
+	/// <summary>
+	/// The cache backing store. Default is <see cref="ConcurrentDictionary{TKey, TValue}"/>.
+	/// </summary>
 	IDictionary<TKey, CacheEntity<TKey, TValue>> CacheBackingStore { get; init; }
 }
 
+/// <summary>
+/// The default implementation of <see cref="IAsyncMemoryCacheConfiguration{TKey, TValue}"/>
+/// </summary>
+/// <typeparam name="TKey">The type of the key for cache items represented by the cache.</typeparam>
+/// <typeparam name="TValue">The type of the value which each item in the cache will hold.</typeparam>
 public sealed class AsyncMemoryCacheConfiguration<TKey, TValue> : IAsyncMemoryCacheConfiguration<TKey, TValue>
 	where TKey : notnull
 	where TValue : IAsyncDisposable
 {
 	public Action<TKey, TValue>? CacheItemExpired { get; init; }
+
+	/// <inheritdoc/>
 	public IEvictionBehavior EvictionBehavior { get; init; } = Default;
+
+	/// <inheritdoc/>
 	public IDictionary<TKey, CacheEntity<TKey, TValue>> CacheBackingStore { get; init; } = new ConcurrentDictionary<TKey, CacheEntity<TKey, TValue>>();
 }

AsyncMemoryCache/CacheEntity.cs

@@ -5,6 +5,11 @@
 
 namespace AsyncMemoryCache;
 
+/// <summary>
+/// Wraps the cached object together with its configured expiration strategy and callbacks.
+/// </summary>
+/// <typeparam name="TKey">The type of the key used for the item.</typeparam>
+/// <typeparam name="TValue">The type of the value which the <see cref="CacheEntity{TKey, TValue}"/> wraps.</typeparam>
 public sealed class CacheEntity<TKey, TValue>
 	where TKey : notnull
 	where TValue : IAsyncDisposable
@@ -23,24 +28,48 @@ public CacheEntity(TKey key, Func<Task<TValue>> objectFactory, AsyncLazyFlags la
 	internal IExpirationStrategy? ExpirationStrategy { get; private set; }
 	internal Action<TKey, TValue>? ExpirationCallback { get; private set; }
 
+	/// <summary>
+	/// Sets the <see cref="ExpirationStrategy"/> to a new instance of <see cref="AbsoluteExpirationStrategy"/>.<br/>
+	/// This strategy takes an absolute date into account when evaluating whether or not it is expired.<br/>
+	/// Useful when more control over the lifetime of a <see cref="CacheEntity{TKey, TValue}"/> is desirable or when there are downsides to having the object alive for an indeterminate amount of time.<br/>
+	/// </summary>
+	/// <param name="expiryDate">The configurable exact date used when evaluating if the object should be expired.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public CacheEntity<TKey, TValue> WithAbsoluteExpiration(DateTimeOffset expiryDate)
 	{
 		ExpirationStrategy = new AbsoluteExpirationStrategy(expiryDate);
 		return this;
 	}
 
+	/// <summary>
+	/// Sets the <see cref="ExpirationStrategy"/> to a new instance of <see cref="SlidingExpirationStrategy"/>.<br/>
+	/// This strategy takes the last use of a <see cref="CacheEntity{TKey, TValue}"/> into account when evaluating whether or not it is expired.<br/>
+	/// Useful when a cached object is actively used and there is no apparent downside in keeping the cached object alive for an indeterminate amount of time.<br/>
+	/// </summary>
+	/// <param name="slidingExpirationWindow">The configurable window used when evaluating if the object should be expired.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public CacheEntity<TKey, TValue> WithSlidingExpiration(TimeSpan slidingExpirationWindow)
 	{
 		ExpirationStrategy = new SlidingExpirationStrategy(slidingExpirationWindow);
 		return this;
 	}
 
+	/// <summary>
+	/// Sets the <see cref="ExpirationStrategy"/> to the provided instance of a custom implementation of <see cref="IExpirationStrategy"/>.<br/>
+	/// </summary>
+	/// <param name="expirationStrategy">The custom implementation instance of <see cref="IExpirationStrategy"/></param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public CacheEntity<TKey, TValue> WithExpirationStrategy(IExpirationStrategy expirationStrategy)
 	{
 		ExpirationStrategy = expirationStrategy;
 		return this;
 	}
 
+	/// <summary>
+	/// Configures the <see cref="ExpirationCallback"/><br/>
+	/// </summary>
+	/// <param name="expirationCallback">The callback which will be invoked when this instance of <see cref="CacheEntity{TKey, TValue}"/> expires.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public CacheEntity<TKey, TValue> WithExpirationCallback(Action<TKey, TValue> expirationCallback)
 	{
 		ExpirationCallback = expirationCallback;

AsyncMemoryCache/CacheEntityReference.cs

@@ -1,9 +1,16 @@
-using System;
+using AsyncMemoryCache.EvictionBehaviors;
+using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Threading;
 
 namespace AsyncMemoryCache;
 
+/// <summary>
+/// A class representing the lifetime of the underlying cached object.<br/>
+/// As long as this object is referenced/not disposed the cached object will not be evicted or disposed if <see cref="DefaultEvictionBehavior"/> is used.<br/>
+/// </summary>
+/// <typeparam name="TKey">The type of the key for the cache item.</typeparam>
+/// <typeparam name="TValue">The type of the value which the referenced <see cref="CacheEntity{TKey, TValue}"/> wraps.</typeparam>
 public sealed class CacheEntityReference<TKey, TValue> : IDisposable
 	where TKey : notnull
 	where TValue : IAsyncDisposable

AsyncMemoryCache/EvictionBehaviors/DefaultEvictionBehavior.cs

@@ -6,6 +6,12 @@
 
 namespace AsyncMemoryCache.EvictionBehaviors;
 
+/// <summary>
+/// The default provided <see cref="IEvictionBehavior"/>.
+/// This class perodically checks for expired items and evicts them. Handling disposal and eviction callbacks as needed.
+/// <para/>
+/// If a cache entity is considered to be expired but still has a live reference via a <see cref="CacheEntityReference{TKey, TValue}"/> object the underlying cached item will not be evicted from the cache.
+/// </summary>
 public sealed class DefaultEvictionBehavior : IEvictionBehavior
 {
 	private readonly CancellationTokenSource _cts;

AsyncMemoryCache/EvictionBehaviors/EvictionBehavior.cs

@@ -5,16 +5,26 @@ namespace AsyncMemoryCache.EvictionBehaviors;
 
 public static class EvictionBehavior
 {
+	/// <inheritdoc cref="DefaultEvictionBehavior"/>
 #if NET8_0_OR_GREATER
 	public static readonly IEvictionBehavior Default = new DefaultEvictionBehavior(TimeProvider.System);
 #else
 	public static readonly IEvictionBehavior Default = new DefaultEvictionBehavior();
 #endif
+	/// <inheritdoc cref="NoOpEvictionBehavior"/>
 	public static readonly IEvictionBehavior Disabled = new NoOpEvictionBehavior();
 }
 
 public interface IEvictionBehavior : IAsyncDisposable
 {
+	/// <summary>
+	/// The method which starts the <see cref="IEvictionBehavior"/>.
+	/// Called automatically by <see cref="AsyncMemoryCache{TKey, TValue}"/>.
+	/// </summary>
+	/// <typeparam name="TKey">The type of the key of the <see cref="CacheEntity{TKey, TValue}"/></typeparam>
+	/// <typeparam name="TValue">The type of the value of the <see cref="CacheEntity{TKey, TValue}"/></typeparam>
+	/// <param name="configuration">The configuration object used in <see cref="AsyncMemoryCache{TKey, TValue}"/> which contains the backing store that holds all of the cached objects</param>
+	/// <param name="logger">The logger object</param>
 	void Start<TKey, TValue>(IAsyncMemoryCacheConfiguration<TKey, TValue> configuration, ILogger<AsyncMemoryCache<TKey, TValue>> logger)
 		where TKey : notnull
 		where TValue : IAsyncDisposable;

AsyncMemoryCache/EvictionBehaviors/NoOpEvictionBehavior.cs

@@ -5,6 +5,10 @@
 
 namespace AsyncMemoryCache.EvictionBehaviors;
 
+/// <summary>
+/// A no-op implementation of <see cref="IEvictionBehavior"/>.
+/// This class has no behavior. Use this to disable eviction functionality.
+/// </summary>
 #if NET8_0_OR_GREATER
 [ExcludeFromCodeCoverage(Justification = "Nothing to test")]
 #endif

AsyncMemoryCache/ExpirationStrategy/ExpirationStrategy.cs

@@ -1,7 +1,18 @@
 namespace AsyncMemoryCache.ExpirationStrategy;
 
+/// <summary>
+/// An interface used to provide custom implementations and rules surrounding the expiration of a <see cref="CacheEntity{TKey, TValue}"/> object.
+/// </summary>
 public interface IExpirationStrategy
 {
+	/// <summary>
+	/// A method that evaluates whether or not a <see cref="CacheEntity{TKey, TValue}"/> is expired.
+	/// </summary>
+	/// <returns>A <see cref="bool"/> that indicates whether or not the <see cref="CacheEntity{TKey, TValue}"/> being interrogated is expired.</returns>
 	bool IsExpired();
+
+	/// <summary>
+	/// A method that is called by the cache every time the <see cref="CacheEntity{TKey, TValue}"/> this expiration strategy belongs to is used.
+	/// </summary>
 	void CacheEntityAccessed();
 }

AsyncMemoryCache/Extensions/CacheEntityReferenceExtensions.cs

@@ -5,6 +5,15 @@ namespace AsyncMemoryCache.Extensions;
 
 public static class CacheEntityReferenceExtensions
 {
+	/// <summary>
+	/// Helper method that sets the <see cref="CacheEntity{TKey, TValue}.ExpirationStrategy"/> to a new instance of <see cref="AbsoluteExpirationStrategy"/>.<br/>
+	/// This strategy takes an absolute date into account when evaluating whether or not it is expired.<br/>
+	/// Useful when more control over the lifetime of a <see cref="CacheEntity{TKey, TValue}"/> is desirable or when there are downsides to having the object alive for an indeterminate amount of time.<para/>
+	/// This is a direct proxy to <see cref="CacheEntity{TKey, TValue}.WithAbsoluteExpiration(DateTimeOffset)"/>
+	/// </summary>
+	/// <param name="cacheEntityReference">The <see cref="CacheEntityReference{TKey, TValue}"/></param>
+	/// <param name="expiryDate">The configurable exact date used when evaluating if the object should be expired.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public static CacheEntityReference<TKey, TValue> WithAbsoluteExpiration<TKey, TValue>(this CacheEntityReference<TKey, TValue> cacheEntityReference, DateTimeOffset expiryDate)
 		where TKey : notnull
 		where TValue : IAsyncDisposable
@@ -13,6 +22,15 @@ public static CacheEntityReference<TKey, TValue> WithAbsoluteExpiration<TKey, TV
 		return cacheEntityReference;
 	}
 
+	/// <summary>
+	/// Helper method that sets the <see cref="CacheEntity{TKey, TValue}.ExpirationStrategy"/> to a new instance of <see cref="SlidingExpirationStrategy"/>.<br/>
+	/// This strategy takes the last use of a <see cref="CacheEntity{TKey, TValue}"/> into account when evaluating whether or not it is expired.<br/>
+	/// Useful when a cached object is actively used and there is no apparent downside in keeping the cached object alive for an indeterminate amount of time.<para/>
+	/// This is a direct proxy to <see cref="CacheEntity{TKey, TValue}.WithSlidingExpiration(TimeSpan)"/>
+	/// </summary>
+	/// <param name="cacheEntityReference">The <see cref="CacheEntityReference{TKey, TValue}"/></param>
+	/// <param name="slidingExpirationWindow">The configurable window used when evaluating if the object should be expired.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public static CacheEntityReference<TKey, TValue> WithSlidingExpiration<TKey, TValue>(this CacheEntityReference<TKey, TValue> cacheEntityReference, TimeSpan slidingExpirationWindow)
 		where TKey : notnull
 		where TValue : IAsyncDisposable
@@ -21,6 +39,13 @@ public static CacheEntityReference<TKey, TValue> WithSlidingExpiration<TKey, TVa
 		return cacheEntityReference;
 	}
 
+	/// <summary>
+	/// Helper method that sets the <see cref="CacheEntity{TKey, TValue}.ExpirationStrategy"/> to the provided instance of a custom implementation of <see cref="IExpirationStrategy"/>.<br/>
+	/// This is a direct proxy to <see cref="CacheEntity{TKey, TValue}.WithExpirationStrategy(IExpirationStrategy)"/>
+	/// </summary>
+	/// <param name="cacheEntityReference">The <see cref="CacheEntityReference{TKey, TValue}"/></param>
+	/// <param name="expirationStrategy">The custom implementation instance of <see cref="IExpirationStrategy"/></param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public static CacheEntityReference<TKey, TValue> WithExpirationStrategy<TKey, TValue>(this CacheEntityReference<TKey, TValue> cacheEntityReference, IExpirationStrategy expirationStrategy)
 		where TKey : notnull
 		where TValue : IAsyncDisposable
@@ -29,6 +54,13 @@ public static CacheEntityReference<TKey, TValue> WithExpirationStrategy<TKey, TV
 		return cacheEntityReference;
 	}
 
+	/// <summary>
+	/// Helper method that configures the <see cref="CacheEntity{TKey, TValue}.ExpirationCallback"/><br/>
+	/// This is a direct proxy to <see cref="CacheEntity{TKey, TValue}.WithExpirationCallback(Action{TKey, TValue})"/>
+	/// </summary>
+	/// <param name="cacheEntityReference">The <see cref="CacheEntityReference{TKey, TValue}"/></param>
+	/// <param name="expirationCallback">The callback which will be invoked when this instance of <see cref="CacheEntity{TKey, TValue}"/> expires.</param>
+	/// <returns><see langword="this"/> to enable chained calls</returns>
 	public static CacheEntityReference<TKey, TValue> WithExpirationCallback<TKey, TValue>(this CacheEntityReference<TKey, TValue> cacheEntityReference, Action<TKey, TValue> expirationCallback)
 		where TKey : notnull
 		where TValue : IAsyncDisposable