chore: zero inbox on docstring warnings (#300)

This fills in the remaining docstrings to get rid all of the
remaining compiler warnings.

src/Momento.Sdk/Config/Configurations.cs

@@ -14,8 +14,8 @@ namespace Momento.Sdk.Config;
 public class Configurations
 {
     /// <summary>
-    /// Laptop config provides defaults suitable for a medium-to-high-latency dev environment.  Permissive timeouts, retries, potentially
-    /// a higher number of connections, etc.
+    /// Laptop config provides defaults suitable for a medium-to-high-latency dev environment.  Permissive timeouts, retries, and
+    /// relaxed latency and throughput targets.
     /// </summary>
     public class Laptop : Configuration
     {
@@ -25,11 +25,17 @@ private Laptop(ILoggerFactory loggerFactory, IRetryStrategy retryStrategy, ITran
 
         }
 
+        /// <summary>
+        /// Provides the latest recommended configuration for a Laptop environment.
+        /// </summary>
+        /// <param name="loggerFactory"></param>
+        /// <returns></returns>
         public static Laptop Latest(ILoggerFactory? loggerFactory = null)
         {
             var finalLoggerFactory = loggerFactory ?? NullLoggerFactory.Instance;
             IRetryStrategy retryStrategy = new FixedCountRetryStrategy(finalLoggerFactory, maxAttempts: 3);
             ITransportStrategy transportStrategy = new StaticTransportStrategy(
+                loggerFactory: finalLoggerFactory,
                 maxConcurrentRequests: 100,
                 grpcConfig: new StaticGrpcConfiguration(deadline: TimeSpan.FromMilliseconds(15000))
             );
@@ -54,11 +60,17 @@ private Default(ILoggerFactory loggerFactory, IRetryStrategy retryStrategy, ITra
 
             }
 
+            /// <summary>
+            /// Provides the latest recommended configuration for an InRegion environment.
+            /// </summary>
+            /// <param name="loggerFactory"></param>
+            /// <returns></returns>
             public static Default Latest(ILoggerFactory? loggerFactory = null)
             {
                 var finalLoggerFactory = loggerFactory ?? NullLoggerFactory.Instance;
                 IRetryStrategy retryStrategy = new FixedCountRetryStrategy(finalLoggerFactory, maxAttempts: 3);
                 ITransportStrategy transportStrategy = new StaticTransportStrategy(
+                    loggerFactory: finalLoggerFactory,
                     maxConcurrentRequests: 200,
                     grpcConfig: new StaticGrpcConfiguration(deadline: TimeSpan.FromMilliseconds(1100)));
                 return new Default(finalLoggerFactory, retryStrategy, transportStrategy);
@@ -78,11 +90,18 @@ private LowLatency(ILoggerFactory loggerFactory, IRetryStrategy retryStrategy, I
 
             }
 
+            /// <summary>
+            /// Provides the latest recommended configuration for a low-latency in-region
+            /// environment.
+            /// </summary>
+            /// <param name="loggerFactory"></param>
+            /// <returns></returns>
             public static LowLatency Latest(ILoggerFactory? loggerFactory = null)
             {
                 var finalLoggerFactory = loggerFactory ?? NullLoggerFactory.Instance;
                 IRetryStrategy retryStrategy = new FixedCountRetryStrategy(finalLoggerFactory, maxAttempts: 3);
                 ITransportStrategy transportStrategy = new StaticTransportStrategy(
+                    loggerFactory: finalLoggerFactory,
                     maxConcurrentRequests: 20,
                     grpcConfig: new StaticGrpcConfiguration(deadline: TimeSpan.FromMilliseconds(500))
                 );

src/Momento.Sdk/Config/Middleware/LoggingMiddleware.cs

@@ -14,11 +14,16 @@ public class LoggingMiddleware : IMiddleware
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="loggerFactory"></param>
         public LoggingMiddleware(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<LoggingMiddleware>();
         }
 
+        /// <inheritdoc/>
         public async Task<MiddlewareResponseState<TResponse>> WrapRequest<TRequest, TResponse>(
             TRequest request,
             CallOptions callOptions,

src/Momento.Sdk/Config/Middleware/PassThroughMiddleware.cs

@@ -7,15 +7,24 @@
 
 namespace Momento.Sdk.Config.Middleware;
 
+/// <summary>
+/// No-op middleware.  Provided only to illustrate the simplest possible example
+/// of a middleware implementation.
+/// </summary>
 public class PassThroughMiddleware : IMiddleware
 {
     private readonly ILogger _logger;
 
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="loggerFactory"></param>
     public PassThroughMiddleware(ILoggerFactory loggerFactory)
     {
         _logger = loggerFactory.CreateLogger<PassThroughMiddleware>();
     }
 
+    /// <inheritdoc/>
     public Task<MiddlewareResponseState<TResponse>> WrapRequest<TRequest, TResponse>(
         TRequest request,
         CallOptions callOptions,

src/Momento.Sdk/Config/Retry/FixedCountRetryStrategy.cs

@@ -6,14 +6,26 @@
 
 namespace Momento.Sdk.Config.Retry;
 
+/// <summary>
+/// The most basic retry strategy; simply retries an eligible failed request the specified number of times.
+/// </summary>
 public class FixedCountRetryStrategy : IRetryStrategy
 {
     private ILoggerFactory _loggerFactory;
     private ILogger _logger;
     private readonly IRetryEligibilityStrategy _eligibilityStrategy;
 
+    /// <summary>
+    /// The maximum number of attempts that should be made before giving up on an individual request.
+    /// </summary>
     public int MaxAttempts { get; }
 
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="loggerFactory"></param>
+    /// <param name="maxAttempts">The maximum number of attempts that should be made before giving up on an individual request.</param>
+    /// <param name="eligibilityStrategy">The strategy used to determine whether a particular failed request is eligible for retry.</param>
     public FixedCountRetryStrategy(ILoggerFactory loggerFactory, int maxAttempts, IRetryEligibilityStrategy? eligibilityStrategy = null)
     {
         _loggerFactory = loggerFactory;
@@ -22,11 +34,17 @@ public FixedCountRetryStrategy(ILoggerFactory loggerFactory, int maxAttempts, IR
         MaxAttempts = maxAttempts;
     }
 
+    /// <summary>
+    /// Copy constructor that updates maxAttempts
+    /// </summary>
+    /// <param name="maxAttempts"></param>
+    /// <returns>A new FixedCountRetryStrategy instance with updated maximum number of attempts</returns>
     public FixedCountRetryStrategy WithMaxAttempts(int maxAttempts)
     {
         return new(_loggerFactory, maxAttempts, _eligibilityStrategy);
     }
 
+    /// <inheritdoc/>
     public int? DetermineWhenToRetryRequest<TRequest>(Status grpcStatus, TRequest grpcRequest, int attemptNumber) where TRequest : class
     {
         _logger.LogDebug($"Determining whether request is eligible for retry; status code: {grpcStatus.StatusCode}, request type: {grpcRequest.GetType()}, attemptNumber: {attemptNumber}, maxAttempts: {MaxAttempts}");

src/Momento.Sdk/Config/Retry/IRetryEligibilityStrategy.cs

@@ -4,10 +4,20 @@
 
 namespace Momento.Sdk.Config.Retry
 {
+    /// <summary>
+    /// Used to determine whether a failed request is eligible for retry.
+    /// </summary>
     public interface IRetryEligibilityStrategy
     {
-        public ILoggerFactory? LoggerFactory { get; }
-        public IRetryEligibilityStrategy WithLoggerFactory(ILoggerFactory loggerFactory);
+        /// <summary>
+        /// Given the status code and request object for a failed request, returns
+        /// <code>true</code> if the request is eligible for retry, <code>false</code>
+        /// otherwise.
+        /// </summary>
+        /// <typeparam name="TRequest"></typeparam>
+        /// <param name="status">The gRPC status of the failed request</param>
+        /// <param name="request">The original gRPC request object</param>
+        /// <returns></returns>
         public bool IsEligibleForRetry<TRequest>(Status status, TRequest request) where TRequest : class;
     }
 }

src/Momento.Sdk/Config/Transport/IGrpcConfiguration.cs

@@ -20,6 +20,17 @@ public interface IGrpcConfiguration
     /// </summary>
     public GrpcChannelOptions GrpcChannelOptions { get; }
 
+    /// <summary>
+    /// Copy constructor to override the Deadline
+    /// </summary>
+    /// <param name="deadline"></param>
+    /// <returns>A new IGrpcConfiguration with the specified Deadline</returns>
     public IGrpcConfiguration WithDeadline(TimeSpan deadline);
+
+    /// <summary>
+    /// Copy constructor to override the channel options
+    /// </summary>
+    /// <param name="grpcChannelOptions"></param>
+    /// <returns>A new IGrpcConfiguration with the specified channel options</returns>
     public IGrpcConfiguration WithGrpcChannelOptions(GrpcChannelOptions grpcChannelOptions);
 }

src/Momento.Sdk/Config/Transport/ITransportStrategy.cs

@@ -8,11 +8,35 @@ namespace Momento.Sdk.Config.Transport;
 /// </summary>
 public interface ITransportStrategy
 {
+    /// <summary>
+    /// The maximum number of concurrent requests that the Momento client will
+    /// allow onto the wire at a given time.
+    /// </summary>
     public int MaxConcurrentRequests { get; }
+    /// <summary>
+    /// Configures the low-level gRPC settings for the Momento client's communication
+    /// with the Momento server.
+    /// </summary>
     public IGrpcConfiguration GrpcConfig { get; }
 
-    public ITransportStrategy WithLoggerFactory(ILoggerFactory loggerFactory);
+    /// <summary>
+    /// Copy constructor to update the maximum number of concurrent requests.
+    /// </summary>
+    /// <param name="maxConcurrentRequests"></param>
+    /// <returns>A new ITransportStrategy with the specified maxConccurrentRequests</returns>
     public ITransportStrategy WithMaxConcurrentRequests(int maxConcurrentRequests);
+
+    /// <summary>
+    /// Copy constructor to update the gRPC configuration
+    /// </summary>
+    /// <param name="grpcConfig"></param>
+    /// <returns>A new ITransportStrategy with the specified grpcConfig</returns>
     public ITransportStrategy WithGrpcConfig(IGrpcConfiguration grpcConfig);
+
+    /// <summary>
+    /// Copy constructor to update the client timeout
+    /// </summary>
+    /// <param name="clientTimeout"></param>
+    /// <returns>A new ITransportStrategy with the specified client timeout</returns>
     public ITransportStrategy WithClientTimeout(TimeSpan clientTimeout);
 }

src/Momento.Sdk/Config/Transport/StaticTransportStrategy.cs

@@ -5,65 +5,101 @@
 
 namespace Momento.Sdk.Config.Transport;
 
-
+/// <summary>
+/// The simplest way to configure gRPC for the Momento client; specifies static values for
+/// request deadline and channel options.
+/// </summary>
 public class StaticGrpcConfiguration : IGrpcConfiguration
 {
+    /// <summary>
+    /// Maximum amount of time before a request will timeout
+    /// </summary>
     public TimeSpan Deadline { get; }
+    /// <summary>
+    /// Customizations to low-level gRPC channel configuration
+    /// </summary>
     public GrpcChannelOptions GrpcChannelOptions { get; }
 
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="deadline">Maximum amount of time before a request will timeout</param>
+    /// <param name="grpcChannelOptions">Customizations to low-level gRPC channel configuration</param>
     public StaticGrpcConfiguration(TimeSpan deadline, GrpcChannelOptions? grpcChannelOptions = null)
     {
         Utils.ArgumentStrictlyPositive(deadline, nameof(deadline));
         this.Deadline = deadline;
         this.GrpcChannelOptions = grpcChannelOptions ?? new GrpcChannelOptions();
     }
 
+    /// <summary>
+    /// Copy constructor for overriding the deadline
+    /// </summary>
+    /// <param name="deadline"></param>
+    /// <returns>A new GrpcConfiguration with the updated deadline</returns>
     public IGrpcConfiguration WithDeadline(TimeSpan deadline)
     {
         return new StaticGrpcConfiguration(deadline, this.GrpcChannelOptions);
     }
 
+    /// <summary>
+    /// Copy constructor for overriding the gRPC channel options
+    /// </summary>
+    /// <param name="grpcChannelOptions"></param>
+    /// <returns>A new GrpcConfiguration with the specified channel options</returns>
     public IGrpcConfiguration WithGrpcChannelOptions(GrpcChannelOptions grpcChannelOptions)
     {
         return new StaticGrpcConfiguration(this.Deadline, grpcChannelOptions);
     }
 }
 
+/// <summary>
+/// The simplest way to configure the transport layer for the Momento client.
+/// Provides static values for the maximum number of concurrent requests and the
+/// gRPC configuration.
+/// </summary>
 public class StaticTransportStrategy : ITransportStrategy
 {
-    public ILoggerFactory? LoggerFactory { get; }
+    private readonly ILoggerFactory _loggerFactory;
+
+    /// <summary>
+    /// The maximum number of concurrent requests that the Momento client will
+    /// allow on the wire at one time.
+    /// </summary>
     public int MaxConcurrentRequests { get; }
+    /// <summary>
+    /// Configures how Momento client interacts with the Momento service via gRPC
+    /// </summary>
     public IGrpcConfiguration GrpcConfig { get; }
 
-    public StaticTransportStrategy(int maxConcurrentRequests, IGrpcConfiguration grpcConfig, ILoggerFactory? loggerFactory = null)
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="loggerFactory"></param>
+    /// <param name="maxConcurrentRequests">The maximum number of concurrent requests that the Momento client will allow on the wire at one time.</param>
+    /// <param name="grpcConfig">Configures how Momento client interacts with the Momento service via gRPC</param>
+    public StaticTransportStrategy(ILoggerFactory loggerFactory, int maxConcurrentRequests, IGrpcConfiguration grpcConfig)
     {
-        LoggerFactory = loggerFactory;
+        _loggerFactory = loggerFactory;
         MaxConcurrentRequests = maxConcurrentRequests;
         GrpcConfig = grpcConfig;
     }
 
-    public StaticTransportStrategy WithLoggerFactory(ILoggerFactory loggerFactory)
-    {
-        return new(MaxConcurrentRequests, GrpcConfig, loggerFactory);
-    }
-
-    ITransportStrategy ITransportStrategy.WithLoggerFactory(ILoggerFactory loggerFactory)
-    {
-        return WithLoggerFactory(loggerFactory);
-    }
-
+    /// <inheritdoc/>
     public ITransportStrategy WithMaxConcurrentRequests(int maxConcurrentRequests)
     {
-        return new StaticTransportStrategy(maxConcurrentRequests, GrpcConfig, LoggerFactory);
+        return new StaticTransportStrategy(_loggerFactory, maxConcurrentRequests, GrpcConfig);
     }
 
+    /// <inheritdoc/>
     public ITransportStrategy WithGrpcConfig(IGrpcConfiguration grpcConfig)
     {
-        return new StaticTransportStrategy(MaxConcurrentRequests, grpcConfig, LoggerFactory);
+        return new StaticTransportStrategy(_loggerFactory, MaxConcurrentRequests, grpcConfig);
     }
 
+    /// <inheritdoc/>
     public ITransportStrategy WithClientTimeout(TimeSpan clientTimeout)
     {
-        return new StaticTransportStrategy(MaxConcurrentRequests, GrpcConfig.WithDeadline(clientTimeout), LoggerFactory);
+        return new StaticTransportStrategy(_loggerFactory, MaxConcurrentRequests, GrpcConfig.WithDeadline(clientTimeout));
     }
 }

src/Momento.Sdk/Exceptions/AlreadyExistsException.cs

@@ -7,6 +7,7 @@
 /// </summary>
 public class AlreadyExistsException : SdkException
 {
+    /// <include file="../docs.xml" path='docs/class[@name="Error"]/constructor/*' />
     public AlreadyExistsException(string message, MomentoErrorTransportDetails transportDetails, Exception? e = null) : base(MomentoErrorCode.ALREADY_EXISTS_ERROR, message, transportDetails, e)
     {
         this.MessageWrapper = "A cache with the specified name already exists.  To resolve this error, either delete the existing cache and make a new one, or use a different name";

src/Momento.Sdk/Exceptions/AuthenticationException.cs

@@ -7,6 +7,7 @@
 /// </summary>
 public class AuthenticationException : SdkException
 {
+    /// <include file="../docs.xml" path='docs/class[@name="SdkException"]/constructor/*' />
     public AuthenticationException(string message, MomentoErrorTransportDetails transportDetails, Exception? e = null) : base(MomentoErrorCode.AUTHENTICATION_ERROR, message, transportDetails, e)
     {
         this.MessageWrapper = "Invalid authentication credentials to connect to cache service";

src/Momento.Sdk/Exceptions/BadRequestException.cs

@@ -7,6 +7,7 @@
 /// </summary>
 public class BadRequestException : SdkException
 {
+    /// <include file="../docs.xml" path='docs/class[@name="SdkException"]/constructor/*' />
     public BadRequestException(string message, MomentoErrorTransportDetails transportDetails, Exception? e = null) : base(MomentoErrorCode.BAD_REQUEST_ERROR, message, transportDetails, e)
     {
         this.MessageWrapper = "The request was invalid; please contact us at [email protected]";

src/Momento.Sdk/Exceptions/CancelledException.cs

@@ -2,6 +2,9 @@
 
 using System;
 
+/// <summary>
+/// Operation was cancelled.
+/// </summary>
 public class CancelledException : SdkException
 {
     /// <summary>

src/Momento.Sdk/Exceptions/FailedPreconditionException.cs

@@ -10,6 +10,7 @@ namespace Momento.Sdk.Exceptions;
 /// </summary>
 public class FailedPreconditionException : SdkException
 {
+    /// <include file="../docs.xml" path='docs/class[@name="SdkException"]/constructor/*' />
     public FailedPreconditionException(string message, MomentoErrorTransportDetails transportDetails, Exception? e = null) : base(MomentoErrorCode.FAILED_PRECONDITION_ERROR, message, transportDetails, e)
     {
         this.MessageWrapper = "System is not in a state required for the operation's execution";

src/Momento.Sdk/Exceptions/InternalServerException.cs

@@ -7,6 +7,7 @@ namespace Momento.Sdk.Exceptions;
 /// </summary>
 public class InternalServerException : SdkException
 {
+    /// <include file="../docs.xml" path='docs/class[@name="SdkException"]/constructor/*' />
     public InternalServerException(string message, MomentoErrorTransportDetails transportDetails, Exception? e = null) : base(MomentoErrorCode.INTERNAL_SERVER_ERROR, message, transportDetails, e)
     {
         this.MessageWrapper = "An unexpected error occurred while trying to fulfill the request; please contact us at [email protected]";