Added additional XML documentation

Fauna/Client/IConnection.cs

@@ -1,7 +1,17 @@
 namespace Fauna;
 
+/// <summary>
+/// Represents an interface for connections to a Fauna database.
+/// </summary>
 public interface IConnection
 {
+    /// <summary>
+    /// Asynchronously sends a POST request to the specified path with the provided body and headers.
+    /// </summary>
+    /// <param name="path">The path of the resource to send the request to.</param>
+    /// <param name="body">The stream containing the request body.</param>
+    /// <param name="headers">A dictionary of headers to be included in the request.</param>
+    /// <returns>A Task representing the asynchronous operation, which upon completion contains the response from the server as <see cref="HttpResponseMessage"/>.</returns>
     Task<HttpResponseMessage> DoPostAsync(
         string path,
         Stream body,

Fauna/Client/QueryOptions.cs

@@ -1,13 +1,42 @@
 namespace Fauna;
 
+/// <summary>
+/// Represents the options for customizing Fauna queries.
+/// </summary>
 public class QueryOptions
 {
+    /// <summary>
+    /// Gets or sets a value indicating whether the query runs as strictly serialized, affecting read-only transactions.
+    /// </summary>
     public bool? Linearized { get; set; } = null;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether type checking of the query is enabled or disabled before evaluation.
+    /// </summary>
     public bool? TypeCheck { get; set; } = null;
+
+    /// <summary>
+    /// Gets or sets the query timeout. It defines how long the client waits for a query to complete.
+    /// </summary>
     public TimeSpan? QueryTimeout { get; set; } = null;
+
+    /// <summary>
+    /// Gets or sets a string-encoded set of caller-defined tags for identifying the request in logs and response bodies. 
+    /// Format is a list of key:value pairs, each key and value limited to [a-zA-Z0-9_].
+    /// </summary>
     public Dictionary<string, string>? QueryTags { get; set; } = null;
+
+    /// <summary>
+    /// Gets or sets the trace parent identifier for distributed tracing systems.
+    /// </summary>
     public string? TraceParent { get; set; } = null;
 
+    /// <summary>
+    /// Combines default query options with overrides from the client configuration.
+    /// </summary>
+    /// <param name="defaultQueryOptions">The default query options.</param>
+    /// <param name="queryOptionOverrides">The query options provided for a specific query, overriding the defaults.</param>
+    /// <returns>A <see cref="QueryOptions"/> object representing the final combined set of query options.</returns>
     internal static QueryOptions? GetFinalQueryOptions(QueryOptions? defaultQueryOptions, QueryOptions? queryOptionOverrides)
     {
 

Fauna/Constants/Endpoints.cs

@@ -1,7 +1,17 @@
 namespace Fauna.Constants;
 
+/// <summary>
+/// Represents the endpoints used for accessing Fauna.
+/// </summary>
 public readonly struct Endpoints
 {
+    /// <summary>
+    /// The default URI for Fauna, used for production.
+    /// </summary>
     public static readonly Uri Default = new("https://db.fauna.com");
+
+    /// <summary>
+    /// The local development URI for Fauna, used for testing or local development.
+    /// </summary>
     public static readonly Uri Local = new("http://localhost:8443");
 }

Fauna/Constants/Headers.cs

@@ -1,16 +1,63 @@
 namespace Fauna.Constants;
 
+/// <summary>
+/// Contains constant values for HTTP header names used in Fauna API requests.
+/// </summary>
 internal readonly struct Headers
 {
+    /// <summary>
+    /// Header for the authorization token in API requests.
+    /// </summary>
     public const string Authorization = "Authorization";
+
+    /// <summary>
+    /// Header indicating the minimum snapshot time for the query execution based on the highest transaction timestamp observed by the client.
+    /// </summary>
     public const string LastTxnTs = "X-Last-Txn-Ts";
+
+    /// <summary>
+    /// Header to enforce strictly serialized execution of the query, affecting read-only transactions.
+    /// </summary>
     public const string Linearized = "X-Linearized";
+
+    /// <summary>
+    /// Header indicating the maximum number of retries for a transaction due to contention failure before returning an error.
+    /// </summary>
     public const string MaxContentionRetries = "X-Max-Contention-Retries";
+
+    /// <summary>
+    /// Header specifying the query timeout in milliseconds.
+    /// </summary>
     public const string QueryTimeoutMs = "X-Query-Timeout-Ms";
+
+    /// <summary>
+    /// Header to enable or disable type checking of the query before evaluation.
+    /// </summary>
     public const string TypeCheck = "X-Typecheck";
+
+    /// <summary>
+    /// Header for passing custom, string-encoded tags for request identification in logs and responses.
+    /// </summary>
     public const string QueryTags = "X-Query-Tags";
+
+    /// <summary>
+    /// Header for the trace parent identifier in distributed tracing systems.
+    /// </summary>
     public const string TraceParent = "Traceparent";
+
+    /// <summary>
+    /// Header indicating the driver used for the API request.
+    /// </summary>
     public const string Driver = "X-Driver";
+
+    /// <summary>
+    /// Header for specifying the environment of the driver used in the API request.
+    /// </summary>
     public const string DriverEnv = "X-Driver-Env";
+
+    /// <summary>
+    /// Header for specifying the encoded format for query arguments and response data.
+    /// Options are 'simple' and 'tagged'. 'Simple' is the default format.
+    /// </summary>
     public const string Format = "X-Format";
 }

Fauna/Constants/ResponseFields.cs

@@ -1,30 +1,119 @@
 namespace Fauna.Constants;
 
+/// <summary>
+/// Contains constant values for the response field names returned by Fauna API queries.
+/// </summary>
 internal readonly struct ResponseFields
 {
-    // Top-level fields
+    #region Top-level fields
+
+    /// <summary>
+    /// Field name for the main data content of the response.
+    /// </summary>
     public const string DataFieldName = "data";
+
+    /// <summary>
+    /// Field name for the transaction timestamp of the last transaction seen by the request.
+    /// </summary>
     public const string LastSeenTxnFieldName = "txn_ts";
+
+    /// <summary>
+    /// Field name for static type information in the response.
+    /// </summary>
     public const string StaticTypeFieldName = "static_type";
+
+    /// <summary>
+    /// Field name for statistical information about the query execution.
+    /// </summary>
     public const string StatsFieldName = "stats";
+
+    /// <summary>
+    /// Field name for the schema version of the database at the time of query execution.
+    /// </summary>
     public const string SchemaVersionFieldName = "schema_version";
+
+    /// <summary>
+    /// Field name for the summary information about the query execution.
+    /// </summary>
     public const string SummaryFieldName = "summary";
+
+    /// <summary>
+    /// Field name for query tags associated with the request, used in logging and monitoring.
+    /// </summary>
     public const string QueryTagsFieldName = "query_tags";
+
+    /// <summary>
+    /// Field name for error information if the query fails.
+    /// </summary>
     public const string ErrorFieldName = "error";
 
-    // "stats" block
+    #endregion
+
+    #region "stats" block
+
+    /// <summary>
+    /// Field name for the number of compute operations consumed by the query.
+    /// </summary>
     public const string Stats_ComputeOpsFieldName = "compute_ops";
+
+    /// <summary>
+    /// Field name for the number of read operations consumed by the query.
+    /// </summary>
     public const string Stats_ReadOps = "read_ops";
+
+    /// <summary>
+    /// Field name for the number of write operations consumed by the query.
+    /// </summary>
     public const string Stats_WriteOps = "write_ops";
+
+    /// <summary>
+    /// Field name for the query processing time in milliseconds.
+    /// </summary>
     public const string Stats_QueryTimeMs = "query_time_ms";
+
+    /// <summary>
+    /// Field name for the write contention retry count.
+    /// </summary>
     public const string Stats_ContentionRetries = "contention_retries";
+
+    /// <summary>
+    /// Field name for the amount of data read from storage, in bytes.
+    /// </summary>
     public const string Stats_StorageBytesRead = "storage_bytes_read";
+
+    /// <summary>
+    /// Field name for the amount of data written to storage, in bytes.
+    /// </summary>
     public const string Stats_StorageBytesWrite = "storage_bytes_write";
+
+    /// <summary>
+    /// Field name for the types of operations that were limited or approaching rate limits.
+    /// </summary>
     public const string Stats_RateLimitsHit = "rate_limits_hit";
 
-    // "error" block
+    #endregion
+
+    #region "error" block
+
+    /// <summary>
+    /// Field name for the error code when a query fails.
+    /// </summary>
     public const string Error_CodeFieldName = "code";
+
+    /// <summary>
+    /// Field name for the detailed message describing the cause of the error.
+    /// </summary>
     public const string Error_MessageFieldName = "message";
+
+    /// <summary>
+    /// Field name for constraint failures that occurred during the query.
+    /// </summary>
     public const string Error_ConstraintFailuresFieldName = "constraint_failures";
+
+    /// <summary>
+    /// Field name for information about an abort operation within a transaction.
+    /// </summary>
     public const string Error_AbortFieldName = "abort";
+
+    #endregion
 }

Fauna/Exceptions/AuthenticationException.cs

@@ -1,5 +1,9 @@
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// Represents an exception thrown when there is an authentication error in Fauna.
+/// Corresponds to the 'unauthorized' error code in Fauna.
+/// </summary>
 public class AuthenticationException : ServiceException
 {
     public AuthenticationException(QueryFailure queryFailure, string message)

Fauna/Exceptions/AuthorizationException.cs

@@ -1,5 +1,9 @@
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// Represents an exception thrown when there is an authorization error in Fauna.
+/// Corresponds to the 'forbidden' error code in Fauna.
+/// </summary>
 public class AuthorizationException : ServiceException
 {
     public AuthorizationException(QueryFailure queryFailure, string message)

Fauna/Exceptions/QueryCheckException.cs

@@ -1,5 +1,8 @@
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// Represents exceptions thrown when the query has syntax errors.
+/// </summary>
 public class QueryCheckException : ServiceException
 {
     public QueryCheckException(QueryFailure queryFailure, string message)

Fauna/Exceptions/QueryTimeoutException.cs

@@ -1,5 +1,8 @@
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// Represents exceptions thrown when the query execution time exceeds the specified or default timeout period.
+/// </summary>
 public class QueryTimeoutException : ServiceException
 {
     public QueryTimeoutException(QueryFailure queryFailure, string message)

Fauna/Exceptions/WriteConstraintException.cs

@@ -1,5 +1,8 @@
 namespace Fauna.Exceptions;
 
+/// <summary>
+/// Represents exceptions thrown due to constraint violations on write operations.
+/// </summary>
 public class WriteConstraintException : QueryRuntimeException
 {
     public WriteConstraintException(QueryFailure queryFailure, string message)

Fauna/Query/QueryExpr.cs

@@ -31,8 +31,16 @@ public QueryExpr(params IQueryFragment[] fragments)
     /// </summary>
     public ReadOnlyCollection<IQueryFragment> Unwrap { get; }
 
+    /// <summary>
+    /// Gets the readonly collection of query fragments.
+    /// </summary>
     public ReadOnlyCollection<IQueryFragment> Fragments => Unwrap;
 
+    /// <summary>
+    /// Serializes the query expression.
+    /// </summary>
+    /// <param name="ctx">The serialization context.</param>
+    /// <param name="writer">The writer to serialize the query expression to.</param>
     public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer)
     {
         writer.WriteStartObject();
@@ -46,8 +54,18 @@ public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer)
         writer.WriteEndObject();
     }
 
+    /// <summary>
+    /// Determines whether the specified QueryExpr is equal to the current QueryExpr.
+    /// </summary>
+    /// <param name="o">The QueryExpr to compare with the current QueryExpr.</param>
+    /// <returns>true if the specified QueryExpr is equal to the current QueryExpr; otherwise, false.</returns>
     public override bool Equals(Query? o) => IsEqual(o as QueryExpr);
 
+    /// <summary>
+    /// Determines whether the specified object is equal to the current QueryExpr.
+    /// </summary>
+    /// <param name="o">The object to compare with the current QueryExpr.</param>
+    /// <returns>true if the specified object is equal to the current QueryExpr; otherwise, false.</returns>
     public override bool Equals(object? o)
     {
         if (ReferenceEquals(this, o))
@@ -58,8 +76,16 @@ public override bool Equals(object? o)
         return o is QueryExpr expr && IsEqual(expr);
     }
 
+    /// <summary>
+    /// The default hash function.
+    /// </summary>
+    /// <returns>A hash code for the current QueryExpr.</returns>
     public override int GetHashCode() => Fragments.GetHashCode();
 
+    /// <summary>
+    /// Returns a string that represents the current QueryExpr.
+    /// </summary>
+    /// <returns>A string that represents the current QueryExpr.</returns>
     public override string ToString() => $"QueryExpr({string.Join(",", Fragments)})";
 
     private bool IsEqual(QueryExpr? o)
@@ -77,6 +103,12 @@ private bool IsEqual(QueryExpr? o)
         return Fragments.SequenceEqual(o.Fragments);
     }
 
+    /// <summary>
+    /// Determines whether two specified instances of QueryExpr are equal.
+    /// </summary>
+    /// <param name="left">The first QueryExpr to compare.</param>
+    /// <param name="right">The second QueryExpr to compare.</param>
+    /// <returns>true if left and right are equal; otherwise, false.</returns>
     public static bool operator ==(QueryExpr left, QueryExpr right)
     {
         if (ReferenceEquals(left, right))
@@ -92,6 +124,12 @@ private bool IsEqual(QueryExpr? o)
         return left.Equals(right);
     }
 
+    /// <summary>
+    /// Determines whether two specified instances of QueryExpr are not equal.
+    /// </summary>
+    /// <param name="left">The first QueryExpr to compare.</param>
+    /// <param name="right">The second QueryExpr to compare.</param>
+    /// <returns>true if left and right are not equal; otherwise, false.</returns>
     public static bool operator !=(QueryExpr left, QueryExpr right)
     {
         return !(left == right);