Enhance documentation across various interfaces

- Added XML documentation comments to IMemoryCacheClient, IJob, IQueueJob, ILockProvider, IMessagePublisher, IMessageSubscriber, Message, IQueue, IQueueActivity, IQueueEntry, ICircuitBreaker, IHaveSerializer, IFileStorage, DataDictionary, IAsyncLifetime, IHaveLogger, IHaveResiliencePolicyProvider, and IHaveTimeProvider interfaces.
- Improved clarity and detail in method descriptions, parameters, and return values to facilitate better understanding and usage of the APIs.

Author: niemyjski

src/Foundatio/Caching/IMemoryCacheClient.cs

@@ -1,5 +1,9 @@
-namespace Foundatio.Caching;
+namespace Foundatio.Caching;
 
+/// <summary>
+/// Marker interface for in-memory cache implementations.
+/// Used to identify caches that store data in process memory rather than external stores.
+/// </summary>
 public interface IMemoryCacheClient : ICacheClient
 {
 }

src/Foundatio/Jobs/IJob.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -7,13 +7,28 @@
 
 namespace Foundatio.Jobs;
 
+/// <summary>
+/// Represents a unit of background work that can be executed once or continuously.
+/// Implement this interface to create custom jobs for scheduled tasks, queue processing, or maintenance operations.
+/// </summary>
 public interface IJob
 {
+    /// <summary>
+    /// Executes the job's work.
+    /// </summary>
+    /// <param name="cancellationToken">Token to signal that the job should stop.</param>
+    /// <returns>A result indicating success, failure, or cancellation.</returns>
     Task<JobResult> RunAsync(CancellationToken cancellationToken = default);
 }
 
+/// <summary>
+/// A job that exposes configurable options for execution behavior.
+/// </summary>
 public interface IJobWithOptions : IJob
 {
+    /// <summary>
+    /// Gets or sets the options controlling job execution (name, interval, iteration limit).
+    /// </summary>
     JobOptions Options { get; set; }
 }
 

src/Foundatio/Jobs/IQueueJob.cs

@@ -7,13 +7,25 @@
 
 namespace Foundatio.Jobs;
 
+/// <summary>
+/// A job that processes items from a queue. Each invocation of <see cref="IJob.RunAsync"/>
+/// dequeues and processes a single item.
+/// </summary>
+/// <typeparam name="T">The type of message payload in the queue.</typeparam>
 public interface IQueueJob<T> : IJob where T : class
 {
     /// <summary>
-    /// Processes a queue entry and returns the result. This method is typically called from RunAsync()
-    /// but can also be called from a function passing in the queue entry.
+    /// Processes a single queue entry. Called by <see cref="IJob.RunAsync"/> after dequeuing an item.
+    /// Can also be called directly when the queue entry is obtained externally.
     /// </summary>
+    /// <param name="queueEntry">The queue entry to process.</param>
+    /// <param name="cancellationToken">Token to signal that processing should stop.</param>
+    /// <returns>A result indicating success or failure of processing.</returns>
     Task<JobResult> ProcessAsync(IQueueEntry<T> queueEntry, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets the queue this job processes items from.
+    /// </summary>
     IQueue<T> Queue { get; }
 }
 

src/Foundatio/Lock/ILockProvider.cs

@@ -9,23 +9,93 @@
 
 namespace Foundatio.Lock;
 
+/// <summary>
+/// Provides distributed locking to coordinate access to shared resources across processes.
+/// </summary>
 public interface ILockProvider
 {
+    /// <summary>
+    /// Acquires a lock on the specified resource, waiting until available or cancellation.
+    /// </summary>
+    /// <param name="resource">The resource identifier to lock. Use consistent naming across processes.</param>
+    /// <param name="timeUntilExpires">
+    /// How long the lock is held before automatic release. Defaults to 20 minutes.
+    /// For long-running operations, call <see cref="ILock.RenewAsync"/> periodically.
+    /// </param>
+    /// <param name="releaseOnDispose">If true, the lock is released when disposed.</param>
+    /// <param name="cancellationToken">Token to cancel the acquisition attempt.</param>
+    /// <returns>An <see cref="ILock"/> representing the acquired lock, or null if acquisition was cancelled.</returns>
     Task<ILock> AcquireAsync(string resource, TimeSpan? timeUntilExpires = null, bool releaseOnDispose = true, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks whether a resource is currently locked.
+    /// </summary>
+    /// <param name="resource">The resource identifier to check.</param>
+    /// <returns>True if the resource is locked; otherwise, false.</returns>
     Task<bool> IsLockedAsync(string resource);
+
+    /// <summary>
+    /// Releases a specific lock on a resource.
+    /// </summary>
+    /// <param name="resource">The resource identifier.</param>
+    /// <param name="lockId">The unique identifier of the lock to release.</param>
     Task ReleaseAsync(string resource, string lockId);
+
+    /// <summary>
+    /// Releases any lock on a resource regardless of lock ID.
+    /// Use with caution as this may release locks held by other processes.
+    /// </summary>
+    /// <param name="resource">The resource identifier.</param>
     Task ReleaseAsync(string resource);
+
+    /// <summary>
+    /// Extends the expiration time of an existing lock.
+    /// </summary>
+    /// <param name="resource">The resource identifier.</param>
+    /// <param name="lockId">The unique identifier of the lock to renew.</param>
+    /// <param name="timeUntilExpires">The new expiration duration from now.</param>
     Task RenewAsync(string resource, string lockId, TimeSpan? timeUntilExpires = null);
 }
 
+/// <summary>
+/// Represents an acquired lock on a resource. Dispose to release the lock.
+/// </summary>
 public interface ILock : IAsyncDisposable
 {
+    /// <summary>
+    /// Extends the lock expiration to prevent automatic release during long-running operations.
+    /// </summary>
+    /// <param name="timeUntilExpires">The new expiration duration from now.</param>
     Task RenewAsync(TimeSpan? timeUntilExpires = null);
+
+    /// <summary>
+    /// Explicitly releases the lock, allowing other processes to acquire it.
+    /// </summary>
     Task ReleaseAsync();
+
+    /// <summary>
+    /// Gets the unique identifier for this lock instance.
+    /// </summary>
     string LockId { get; }
+
+    /// <summary>
+    /// Gets the resource identifier this lock is held on.
+    /// </summary>
     string Resource { get; }
+
+    /// <summary>
+    /// Gets the UTC time when this lock was acquired.
+    /// </summary>
     DateTime AcquiredTimeUtc { get; }
+
+    /// <summary>
+    /// Gets the duration spent waiting to acquire this lock.
+    /// </summary>
     TimeSpan TimeWaitedForLock { get; }
+
+    /// <summary>
+    /// Gets the number of times this lock has been renewed.
+    /// </summary>
     int RenewalCount { get; }
 }
 

src/Foundatio/Messaging/IMessagePublisher.cs

@@ -4,8 +4,18 @@
 
 namespace Foundatio.Messaging;
 
+/// <summary>
+/// Publishes messages to all subscribers listening for the message type.
+/// </summary>
 public interface IMessagePublisher
 {
+    /// <summary>
+    /// Publishes a message to all subscribers of the specified type.
+    /// </summary>
+    /// <param name="messageType">The type used to route the message to subscribers.</param>
+    /// <param name="message">The message payload to publish.</param>
+    /// <param name="options">Optional settings for delivery delay, correlation ID, and custom properties.</param>
+    /// <param name="cancellationToken">Token to cancel the publish operation.</param>
     Task PublishAsync(Type messageType, object message, MessageOptions options = null, CancellationToken cancellationToken = default);
 }
 

src/Foundatio/Messaging/IMessageSubscriber.cs

@@ -1,11 +1,25 @@
-using System;
+using System;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Foundatio.Messaging;
 
+/// <summary>
+/// Subscribes to messages published on the message bus.
+/// Handlers receive messages of the subscribed type and any derived types.
+/// </summary>
 public interface IMessageSubscriber
 {
+    /// <summary>
+    /// Registers a handler to receive messages of the specified type.
+    /// The subscription remains active until the cancellation token is triggered.
+    /// </summary>
+    /// <typeparam name="T">The message type to subscribe to. Also receives messages of derived types.</typeparam>
+    /// <param name="handler">
+    /// The async function invoked for each received message.
+    /// Exceptions thrown by the handler are logged but do not affect other subscribers.
+    /// </param>
+    /// <param name="cancellationToken">Token to cancel the subscription.</param>
     Task SubscribeAsync<T>(Func<T, CancellationToken, Task> handler, CancellationToken cancellationToken = default) where T : class;
 }
 

src/Foundatio/Messaging/Message.cs

@@ -1,22 +1,60 @@
-using System;
+using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 
 namespace Foundatio.Messaging;
 
+/// <summary>
+/// Represents a message received from the message bus with metadata and raw payload.
+/// Subscribe to <see cref="IMessage"/> to receive all message types.
+/// </summary>
 public interface IMessage
 {
+    /// <summary>
+    /// Gets the unique identifier for this message instance.
+    /// </summary>
     string UniqueId { get; }
+
+    /// <summary>
+    /// Gets the correlation identifier for distributed tracing.
+    /// </summary>
     string CorrelationId { get; }
+
+    /// <summary>
+    /// Gets the message type name used for routing.
+    /// </summary>
     string Type { get; }
+
+    /// <summary>
+    /// Gets the CLR type of the message payload, or null if the type cannot be resolved.
+    /// </summary>
     Type ClrType { get; }
+
+    /// <summary>
+    /// Gets the raw serialized message payload.
+    /// </summary>
     byte[] Data { get; }
+
+    /// <summary>
+    /// Deserializes and returns the message payload.
+    /// </summary>
     object GetBody();
+
+    /// <summary>
+    /// Gets custom properties attached to this message.
+    /// </summary>
     IDictionary<string, string> Properties { get; }
 }
 
+/// <summary>
+/// A typed message providing strongly-typed access to the message payload.
+/// </summary>
+/// <typeparam name="T">The type of message payload.</typeparam>
 public interface IMessage<T> : IMessage where T : class
 {
+    /// <summary>
+    /// Gets the deserialized message payload.
+    /// </summary>
     T Body { get; }
 }