Add (almost) all missing XML docs (#208)

Co-authored-by: James Rodewig <[email protected]>

Fauna.Test/Serialization/TestClasses.cs

@@ -220,7 +220,7 @@ class ClassWithLotsOfFields
 
 public class IntToStringSerializer : BaseSerializer<int>
 {
-    public override int Deserialize(MappingContext context, ref Utf8FaunaReader reader)
+    public override int Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
     {
         return reader.CurrentTokenType switch
         {

Fauna/Client.cs

@@ -94,7 +94,11 @@ public void Dispose()
         GC.SuppressFinalize(this);
     }
 
-    // A finalizer: https://stackoverflow.com/questions/151051/when-should-i-use-gc-suppressfinalize
+    /// <inheritdoc />
+    /// <remarks>
+    /// https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/finalizers
+    /// https://stackoverflow.com/questions/151051/when-should-i-use-gc-suppressfinalize
+    /// </remarks>
     ~Client()
     {
         Dispose(false);

Fauna/Configuration.cs

@@ -56,8 +56,9 @@ public record class Configuration
     /// <summary>
     /// Initializes a new instance of the <see cref="Configuration"/> record with the specified secret key.
     /// </summary>
-    /// <param name="secret">The secret key used for authentication.</param>
-    /// <param name="httpClient">The <see cref="HttpClient"/> to use.</param>
+    /// <param name="secret">The secret used for authentication. If null or empty, attempt to use the FAUNA_SECRET env var.</param>
+    /// <param name="httpClient">The <see cref="HttpClient"/> to use. If null, a default HttpClient is used.</param>
+    /// <param name="logger">A logger. If null, a default logger is used.</param>
     public Configuration(string secret = "", HttpClient? httpClient = null, ILogger? logger = null)
     {
         if (string.IsNullOrEmpty(secret) && string.IsNullOrEmpty(Secret))

Fauna/Core/QueryResponse.cs

@@ -12,6 +12,9 @@ namespace Fauna.Core;
 /// </summary>
 public abstract class QueryResponse
 {
+    /// <summary>
+    /// The raw JSON of the query response.
+    /// </summary>
     public JsonElement RawJson { get; init; }
 
     /// <summary>
@@ -159,10 +162,25 @@ public QuerySuccess(
 /// </summary>
 public sealed class QueryFailure : QueryResponse
 {
+    /// <summary>
+    /// The HTTP status code.
+    /// </summary>
     public HttpStatusCode StatusCode { get; init; }
+    /// <summary>
+    /// The Fauna error code.
+    /// </summary>
     public string ErrorCode { get; init; } = "";
+    /// <summary>
+    /// The query failure message.
+    /// </summary>
     public string Message { get; init; } = "";
+    /// <summary>
+    /// The constraint failures, if any. Only present for the  constraint_failure error code.
+    /// </summary>
     public ConstraintFailure[]? ConstraintFailures { get; init; }
+    /// <summary>
+    /// The abort object, if any. Only present for the abort error code.
+    /// </summary>
     public object? Abort { get; init; }
 
     /// <summary>

Fauna/Core/StatsCollector.cs

@@ -1,22 +1,61 @@
 namespace Fauna.Core;
 
 
+/// <summary>
+/// A struct representing stats aggregated across queries.
+/// </summary>
 public readonly struct Stats
 {
+    /// <summary>
+    /// The aggregate read ops.
+    /// </summary>
     public long ReadOps { get; init; }
+    /// <summary>
+    /// The aggregate compute ops.
+    /// </summary>
     public long ComputeOps { get; init; }
+    /// <summary>
+    /// The aggregate write ops.
+    /// </summary>
     public long WriteOps { get; init; }
+    /// <summary>
+    /// The aggregate query time in milliseconds.
+    /// </summary>
     public long QueryTimeMs { get; init; }
+    /// <summary>
+    /// The aggregate number of retries due to transaction contention.
+    /// </summary>
     public int ContentionRetries { get; init; }
+    /// <summary>
+    /// The aggregate number of storage bytes read.
+    /// </summary>
     public long StorageBytesRead { get; init; }
+    /// <summary>
+    /// The aggregate number of storage bytes written.
+    /// </summary>
     public long StorageBytesWrite { get; init; }
+    /// <summary>
+    /// The aggregate number of queries summarized.
+    /// </summary>
     public int QueryCount { get; init; }
 
+    /// <summary>
+    /// The aggregate count of rate limited queries due to read limits.
+    /// </summary>
     public int RateLimitedReadQueryCount { get; init; }
+    /// <summary>
+    /// The aggregate count of rate limited queries due to compute limits.
+    /// </summary>
     public int RateLimitedComputeQueryCount { get; init; }
+    /// <summary>
+    /// The aggregate count of rate limited queries due to write limits.
+    /// </summary>
     public int RateLimitedWriteQueryCount { get; init; }
 }
 
+/// <summary>
+/// An interface used by a client instance for aggregating stats across all queries.
+/// </summary>
 public interface IStatsCollector
 {
     /// <summary>
@@ -36,6 +75,9 @@ public interface IStatsCollector
     public Stats ReadAndReset();
 }
 
+/// <summary>
+/// The default implementation of <see cref="IStatsCollector"/>.
+/// </summary>
 public class StatsCollector : IStatsCollector
 {
     private const string RateLimitReadOps = "read";
@@ -54,7 +96,7 @@ public class StatsCollector : IStatsCollector
     private int _rateLimitedComputeQueryCount;
     private int _rateLimitedWriteQueryCount;
 
-
+    /// <inheritdoc />
     public void Add(QueryStats stats)
     {
         Interlocked.Exchange(ref _readOps, _readOps + stats.ReadOps);
@@ -84,6 +126,7 @@ public void Add(QueryStats stats)
         Interlocked.Increment(ref _queryCount);
     }
 
+    /// <inheritdoc />
     public Stats Read()
     {
         return new Stats
@@ -102,6 +145,7 @@ public Stats Read()
         };
     }
 
+    /// <inheritdoc />
     public Stats ReadAndReset()
     {
         var beforeReset = new Stats

Fauna/Core/StreamEnumerable.cs

@@ -2,12 +2,19 @@
 
 namespace Fauna.Core;
 
+/// <summary>
+/// A class representing a Fauna Event Stream. Additional queries will be made during enumeration.
+/// </summary>
+/// <typeparam name="T">The return type of the stream.</typeparam>
 public class StreamEnumerable<T> where T : notnull
 {
     private readonly BaseClient _client;
     private readonly EventSource _eventSource;
     private readonly CancellationToken _cancel;
 
+    /// <summary>
+    /// The token for the event source.
+    /// </summary>
     public string Token => _eventSource.Token;
 
     internal StreamEnumerable(
@@ -20,6 +27,10 @@ internal StreamEnumerable(
         _cancel = cancel;
     }
 
+    /// <summary>
+    /// Gets an async enumerator for the stream.
+    /// </summary>
+    /// <returns>An async enumerator that yields <see cref="Event{T}"/>.</returns>
     public async IAsyncEnumerator<Event<T>> GetAsyncEnumerator()
     {
         await using var subscribeStream = _client.SubscribeStream<T>(

Fauna/Exceptions/AuthenticationException.cs

@@ -8,6 +8,11 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class AuthenticationException : ServiceException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AuthenticationException"/> class with a specified error message and query failure details.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
     public AuthenticationException(string message, QueryFailure failure) : base(message, failure)
     {
     }

Fauna/Exceptions/AuthorizationException.cs

@@ -8,6 +8,11 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class AuthorizationException : ServiceException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AuthorizationException"/> class with a specified error message and query failure details.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="failure">A <see cref="QueryFailure"/></param>
     public AuthorizationException(string message, QueryFailure failure) : base(message, failure)
     {
     }

Fauna/Exceptions/BadGatewayException.cs

@@ -8,6 +8,11 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class BadGatewayException : ServiceException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BadGatewayException"/> class with a specified error message and query failure details.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="failure">A <see cref="QueryFailure"/></param>
     public BadGatewayException(string message, QueryFailure failure) : base(message, failure)
     {
     }

Fauna/Exceptions/ConstraintFailure.cs

@@ -3,21 +3,39 @@
 
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// A class representing a <a href="https://docs.fauna.com/fauna/current/reference/fsl/check/">constraint failure</a> from Fauna.
+/// </summary>
 public class ConstraintFailure
 {
+    /// <summary>
+    /// Initializes a new <see cref="ConstraintFailure"/>.
+    /// </summary>
+    /// <param name="message">The message describing the constraint failure.</param>
+    /// <param name="name">The name of the constraint failure.</param>
+    /// <param name="paths">The paths for the constraint failure.</param>
     public ConstraintFailure(string message, string name, object[][]? paths)
     {
         Message = message;
         Name = name;
         Paths = paths;
     }
 
+    /// <summary>
+    /// The constraint failure message describing the specific check that failed.
+    /// </summary>
     [JsonPropertyName(Error_ConstraintFailuresMessageFieldName)]
     public string Message { get; set; }
 
+    /// <summary>
+    /// The constraint failure name.
+    /// </summary>
     [JsonPropertyName(Error_ConstraintFailuresNameFieldName)]
     public string Name { get; set; }
 
+    /// <summary>
+    /// The constraint failure paths.
+    /// </summary>
     [JsonPropertyName(Error_ConstraintFailuresPathsFieldName)]
     public object[][]? Paths { get; set; }
 

Fauna/Exceptions/ConstraintFailureException.cs

@@ -9,6 +9,9 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class ConstraintFailureException : ServiceException
 {
+    /// <summary>
+    /// The constraint failures related to the exception.
+    /// </summary>
     public ConstraintFailure[]? ConstraintFailures { get; }
 
     /// <summary>

Fauna/Exceptions/ContendedTransactionException.cs

@@ -8,6 +8,11 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class ContendedTransactionException : ServiceException, IRetryableException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContendedTransactionException"/> class with a specified error message and query failure details.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
     public ContendedTransactionException(string message, QueryFailure failure) : base(message, failure)
     {
     }

Fauna/Exceptions/ExceptionHandler.cs

@@ -4,8 +4,17 @@
 
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// A utility class for generating an appropriate <see cref="FaunaException"/> from a <see cref="QueryFailure"/>.
+/// </summary>
 public static class ExceptionHandler
 {
+    /// <summary>
+    /// Creates an exception from a <see cref="QueryFailure"/>
+    /// </summary>
+    /// <param name="ctx">A <see cref="MappingContext"/> used for exceptions that require additional deserialization, such as <see cref="AbortException"/>.</param>
+    /// <param name="f">The <see cref="QueryFailure"/>.</param>
+    /// <returns></returns>
     public static Exception FromQueryFailure(MappingContext ctx, QueryFailure f)
     {
         var msg =
@@ -31,6 +40,12 @@ public static Exception FromQueryFailure(MappingContext ctx, QueryFailure f)
     }
 
 
+    /// <summary>
+    /// Creates an exception from a body and an already consumed <see cref="HttpResponseMessage"/>
+    /// </summary>
+    /// <param name="body">The response body.</param>
+    /// <param name="r">The <see cref="HttpResponseMessage"/> with consumed body.</param>
+    /// <returns></returns>
     public static Exception FromRawResponse(string body, HttpResponseMessage r)
     {
         if (r.StatusCode is >= HttpStatusCode.OK and <= (HttpStatusCode)299)

Fauna/Exceptions/FaunaException.cs

@@ -7,13 +7,24 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class FaunaException : Exception
 {
-    public FaunaException() { }
-
+    /// <summary>
+    /// Initializes a FaunaException with a message.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
     public FaunaException(string message) : base(message) { }
 
+    /// <summary>
+    /// Initializes a FaunaException with a message and inner exception.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The inner exception.</param>
     public FaunaException(string message, Exception innerException)
     : base(message, innerException) { }
 
+    /// <summary>
+    /// Initializes a FaunaException from an <see cref="ErrorInfo"/> instance.
+    /// </summary>
+    /// <param name="err">The <see cref="ErrorInfo"/> from which to extract a message.</param>
     public FaunaException(ErrorInfo err) : base(message: err.Message) { }
 }
 

Fauna/Exceptions/InvalidRequestException.cs

@@ -7,6 +7,11 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class InvalidRequestException : ServiceException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InvalidRequestException"/> class with a specified error message and query failure details.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
     public InvalidRequestException(string message, QueryFailure failure) : base(message, failure)
     {
     }

Fauna/Exceptions/NetworkException.cs

@@ -7,10 +7,22 @@ namespace Fauna.Exceptions;
 /// </summary>
 public class NetworkException : FaunaException
 {
+    /// <summary>
+    /// The response body that caused the <see cref="ProtocolException"/> to be thrown.
+    /// </summary>
     public string ResponseBody { get; init; }
 
+    /// <summary>
+    /// The HTTP status code associated with the <see cref="ProtocolException"/>.
+    /// </summary>
     public HttpStatusCode StatusCode { get; init; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NetworkException"/> class.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="statusCode">The HTTP status code from the related HTTP request.</param>
+    /// <param name="body">The HTTP response body that was out of protocol.</param>
     public NetworkException(string message, HttpStatusCode statusCode, string body)
         : base(message)
     {