Merge pull request #18 from Leefrost/docs

Internal documentations

Author: Leefrost

src/HttpClient.Cache/ICacheEntry.cs

@@ -1,18 +1,44 @@
 namespace HttpClient.Cache;
 
+/// <summary>
+/// Cache value holder
+/// </summary>
 public interface ICacheEntry: IDisposable
 {
+    /// <summary>
+    /// Cache value
+    /// </summary>
     object Value { get; set; }
 
+    /// <summary>
+    /// Cache entry priority
+    /// </summary>
+    CacheEntryPriority Priority { get; set; }
+    
+    /// <summary>
+    /// Entry absolute expiration. The entry will be expired after a set amount of time
+    /// </summary>
     DateTimeOffset? AbsoluteExpiration { get; set; }
 
+    /// <summary>
+    /// Entry absolute expiration relative to created time. The entry will be expired a set amount of time from now
+    /// </summary>
     TimeSpan? AbsoluteExpirationRelativeToNow { get; set; }
 
+    /// <summary>
+    /// Entry sliding expiration. Entry will be expired if it hasn't been accessed in a set amount of time. 
+    /// </summary>
     TimeSpan? SlidingExpiration { get; set; }
 
+    /// <summary>
+    /// Collection of <see cref="IChangeToken"/> tokens.
+    /// Any lifecycle changes will appear here
+    /// </summary>
     IList<IChangeToken> ExpirationTokens { get; }
 
+    /// <summary>
+    /// Collection of <see cref="PostEvictionCallbackRegistration"/> callbacks.
+    /// Will be executed on entry eviction
+    /// </summary>
     IList<PostEvictionCallbackRegistration> PostEvictionCallbacks { get; }
-    
-    CacheEntryPriority Priority { get; set; }
 }

src/HttpClient.Cache/ICacheKeysProvider.cs

@@ -1,6 +1,14 @@
 namespace HttpClient.Cache;
 
+/// <summary>
+/// Cache keys generator
+/// </summary>
 public interface ICacheKeysProvider
 {
+    /// <summary>
+    /// Generate a cache key for <see cref="HttpRequestMessage"/> http request
+    /// </summary>
+    /// <param name="request">Http request</param>
+    /// <returns>Cache key</returns>
     string GetKey(HttpRequestMessage request);
 }

src/HttpClient.Cache/IChangeToken.cs

@@ -1,10 +1,25 @@
 namespace HttpClient.Cache;
 
+/// <summary>
+/// Defines the mechanism for checking the changes over the cache entry
+/// </summary>
 public interface IChangeToken
 {
+    /// <summary>
+    /// Cache entry is changed
+    /// </summary>
     bool HasChanged { get; }
 
+    /// <summary>
+    /// Call the callback on change
+    /// </summary>
     bool ActiveChangeCallbacks { get; }
 
+    /// <summary>
+    /// Register a callback to call on change
+    /// </summary>
+    /// <param name="callback">Callback to call</param>
+    /// <param name="state">Current state</param>
+    /// <returns><see cref="IDisposable"/> callback handler</returns>
     IDisposable RegisterChangeCallback(Action<object> callback, object state);
 }

src/HttpClient.Cache/InMemory/Clock/ISystemClock.cs

@@ -1,6 +1,12 @@
 namespace HttpClient.Cache.InMemory.Clock;
 
+/// <summary>
+/// Defines cache clock
+/// </summary>
 public interface ISystemClock
 {
+    /// <summary>
+    /// Current time
+    /// </summary>
     DateTimeOffset UtcNow { get; }
 }

src/HttpClient.Cache/InMemory/IMemoryCache.cs

@@ -1,12 +1,33 @@
 namespace HttpClient.Cache.InMemory;
 
+/// <summary>
+/// Describes the API for InMemory cache
+/// </summary>
 public interface IMemoryCache: IDisposable
 {
+    /// <summary>
+    /// Getting the cache value by key
+    /// </summary>
+    /// <param name="key">Entry key</param>
+    /// <param name="value">Cache value</param>
+    /// <returns>True if entry exist and returned, otherwise - false</returns>
     bool TryGetValue(object key, out object? value);
 
+    /// <summary>
+    /// Create empty cache entry
+    /// </summary>
+    /// <param name="key">Entry key</param>
+    /// <returns><see cref="ICacheEntry"/> cache entry</returns>
     ICacheEntry CreateEntry(object key);
 
+    /// <summary>
+    /// Remove entry by key
+    /// </summary>
+    /// <param name="key">Entry key</param>
     void Remove(object key);
 
+    /// <summary>
+    /// Clean the cache
+    /// </summary>
     void Clear();
 }

src/HttpClient.Cache/Stats/ICacheStatsProvider.cs

@@ -2,11 +2,26 @@
 
 namespace HttpClient.Cache.Stats;
 
+/// <summary>
+/// Defines a mechanism to report cache hit/miss and generate on this info a cache report
+/// </summary>
 public interface ICacheStatsProvider
 {
+    /// <summary>
+    /// Mark a cache hit
+    /// </summary>
+    /// <param name="code">Target code</param>
     void ReportHit(HttpStatusCode code);
 
+    /// <summary>
+    /// Mark a cache miss
+    /// </summary>
+    /// <param name="code">Target code</param>
     void ReportMiss(HttpStatusCode code);
 
+    /// <summary>
+    /// Gets stored cache report
+    /// </summary>
+    /// <returns><see cref="CacheStatsReport"/> report</returns>
     CacheStatsReport GetReport();
 }