refactor: improve XML documentation for Buffer and IBuffer interfaces

Author: RaphDal

src/net-questdb-client/Buffers/Buffer.cs

@@ -31,14 +31,6 @@ namespace QuestDB.Buffers;
 /// </summary>
 public static class Buffer
 {
-    /// <summary>
-    ///     Creates an IBuffer instance, based on the provided protocol version.
-    /// </summary>
-    /// <param name="bufferSize"></param>
-    /// <param name="maxNameLen"></param>
-    /// <param name="maxBufSize"></param>
-    /// <param name="version"></param>
-    /// <returns></returns>
     /// <summary>
     /// Creates a concrete IBuffer implementation configured for the specified protocol version.
     /// </summary>

src/net-questdb-client/Buffers/IBuffer.cs

@@ -229,29 +229,29 @@ public interface IBuffer
     public IBuffer Column<T>(ReadOnlySpan<char> name, ReadOnlySpan<T> value) where T : struct;
 
     /// <summary>
-/// Writes an array column value for the current row.
-/// </summary>
-/// <param name="name">The column name.</param>
-/// <param name="value">The array to write as the column value, or null to record a NULL value.</param>
-/// <returns>The same buffer instance for fluent chaining.</returns>
+    /// Writes an array column value for the current row.
+    /// </summary>
+    /// <param name="name">The column name.</param>
+    /// <param name="value">The array to write as the column value, or null to record a NULL value.</param>
+    /// <returns>The same buffer instance for fluent chaining.</returns>
     public IBuffer Column(ReadOnlySpan<char> name, Array? value);
 
     /// <summary>
-/// Writes a column with the specified name using the provided enumerable of values and shape information.
-/// </summary>
-/// <param name="name">The column name.</param>
-/// <param name="value">An enumerable of values for the column; elements are of the value type `T`.</param>
-/// <param name="shape">An enumerable of integers describing the multidimensional shape/length(s) for the values.</param>
-/// <returns>The same <see cref="IBuffer"/> instance for call chaining.</returns>
+    /// Writes a column with the specified name using the provided enumerable of values and shape information.
+    /// </summary>
+    /// <param name="name">The column name.</param>
+    /// <param name="value">An enumerable of values for the column; elements are of the value type `T`.</param>
+    /// <param name="shape">An enumerable of integers describing the multidimensional shape/length(s) for the values.</param>
+    /// <returns>The same <see cref="IBuffer"/> instance for call chaining.</returns>
     public IBuffer Column<T>(ReadOnlySpan<char> name, IEnumerable<T> value, IEnumerable<int> shape) where T : struct;
 
     /// <summary>
     ///     Records a DECIMAL column value using the ILP binary decimal layout.
     /// <summary>
-/// Writes a DECIMAL column with the specified name using the ILP binary decimal layout.
-/// </summary>
-/// <param name="name">The column name.</param>
-/// <param name="value">The decimal value to write, or `null` to write a NULL column.</param>
-/// <returns>The buffer instance for method chaining.</returns>
+    /// Writes a DECIMAL column with the specified name using the ILP binary decimal layout.
+    /// </summary>
+    /// <param name="name">The column name.</param>
+    /// <param name="value">The decimal value to write, or `null` to write a NULL column.</param>
+    /// <returns>The buffer instance for method chaining.</returns>
     public IBuffer Column(ReadOnlySpan<char> name, decimal? value);
 }

src/net-questdb-client/Senders/HttpSender.cs

@@ -149,9 +149,9 @@ private void Build()
         {
             _client.DefaultRequestHeaders.Authorization
                 = new AuthenticationHeaderValue("Basic",
-                                                Convert.ToBase64String(
-                                                    Encoding.ASCII.GetBytes(
-                                                        $"{Options.username}:{Options.password}")));
+                    Convert.ToBase64String(
+                        Encoding.ASCII.GetBytes(
+                            $"{Options.username}:{Options.password}")));
         }
         else if (!string.IsNullOrEmpty(Options.token))
         {
@@ -223,17 +223,14 @@ private CancellationTokenSource GenerateRequestCts(CancellationToken ct = defaul
         return cts;
     }
 
-    /// <summary>
-    ///     Creates a new HTTP request with appropriate encoding.
-    /// </summary>
     /// <summary>
     /// Create an HTTP POST request targeting "/write" with the sender's buffer as the request body.
     /// </summary>
     /// <returns>An <see cref="HttpRequestMessage"/> configured with the buffer as the request body, Content-Type set to "text/plain" with charset "utf-8", and Content-Length set to the buffer length.</returns>
     private HttpRequestMessage GenerateRequest()
     {
         var request = new HttpRequestMessage(HttpMethod.Post, "/write")
-        { Content = new BufferStreamContent(Buffer), };
+            { Content = new BufferStreamContent(Buffer), };
         request.Content.Headers.ContentType = new MediaTypeHeaderValue("text/plain") { CharSet = "utf-8", };
         request.Content.Headers.ContentLength = Buffer.Length;
         return request;
@@ -260,21 +257,20 @@ public override ISender Transaction(ReadOnlySpan<char> tableName)
         if (WithinTransaction)
         {
             throw new IngressError(ErrorCode.InvalidApiCall,
-                                   "Cannot start another transaction - only one allowed at a time.");
+                "Cannot start another transaction - only one allowed at a time.");
         }
 
         if (Length > 0)
         {
             throw new IngressError(ErrorCode.InvalidApiCall,
-                                   "Buffer must be clear before you can start a transaction.");
+                "Buffer must be clear before you can start a transaction.");
         }
 
         Buffer.Transaction(tableName);
         return this;
     }
 
     /// <inheritdoc cref="CommitAsync" />
-    /// />
     public override void Commit(CancellationToken ct = default)
     {
         try
@@ -396,7 +392,8 @@ public override void Send(CancellationToken ct = default)
     /// <returns>The final <see cref="HttpResponseMessage"/> returned by the server for a successful request.</returns>
     /// <exception cref="IngressError">Thrown with <see cref="ErrorCode.ServerFlushError"/> when a connection could not be established within the allowed retries.</exception>
     /// <remarks>The caller is responsible for disposing the returned <see cref="HttpResponseMessage"/>./// </remarks>
-    private HttpResponseMessage SendWithRetries(CancellationToken ct, Func<HttpRequestMessage> requestFactory, TimeSpan retryTimeout)
+    private HttpResponseMessage SendWithRetries(CancellationToken ct, Func<HttpRequestMessage> requestFactory,
+        TimeSpan retryTimeout)
     {
         HttpResponseMessage? response = null;
         CancellationTokenSource cts = GenerateRequestCts(ct);
@@ -414,9 +411,9 @@ private HttpResponseMessage SendWithRetries(CancellationToken ct, Func<HttpReque
             }
 
             if (retryTimeout > TimeSpan.Zero)
-            // retry if appropriate - error that's retriable, and retries are enabled
+                // retry if appropriate - error that's retriable, and retries are enabled
             {
-                if (response == null                  // if it was a cannot correct error
+                if (response == null // if it was a cannot correct error
                     || (!response.IsSuccessStatusCode // or some other http error
                         && IsRetriableError(response.StatusCode)))
                 {
@@ -426,9 +423,9 @@ private HttpResponseMessage SendWithRetries(CancellationToken ct, Func<HttpReque
 
                     while (retryTimer.Elapsed < retryTimeout // whilst we can still retry
                            && (
-                                  response == null ||               // either we can't connect
-                                  (!response.IsSuccessStatusCode && // or we have another http error
-                                   IsRetriableError(response.StatusCode)))
+                               response == null || // either we can't connect
+                               (!response.IsSuccessStatusCode && // or we have another http error
+                                IsRetriableError(response.StatusCode)))
                           )
                     {
                         retryInterval = TimeSpan.FromMilliseconds(Math.Min(retryInterval.TotalMilliseconds * 2, 1000));
@@ -460,7 +457,7 @@ private HttpResponseMessage SendWithRetries(CancellationToken ct, Func<HttpReque
             if (response == null)
             {
                 throw new IngressError(ErrorCode.ServerFlushError,
-                                       $"Cannot connect to `{Options.Host}:{Options.Port}`");
+                    $"Cannot connect to `{Options.Host}:{Options.Port}`");
             }
 
             return response;
@@ -542,7 +539,7 @@ public override async Task SendAsync(CancellationToken ct = default)
             // retry if appropriate - error that's retriable, and retries are enabled
             if (Options.retry_timeout > TimeSpan.Zero)
             {
-                if (response == null                  // if it was a cannot correct error
+                if (response == null // if it was a cannot correct error
                     || (!response.IsSuccessStatusCode // or some other http error
                         && IsRetriableError(response.StatusCode)))
                 {
@@ -552,9 +549,9 @@ public override async Task SendAsync(CancellationToken ct = default)
 
                     while (retryTimer.Elapsed < Options.retry_timeout // whilst we can still retry
                            && (
-                                  response == null ||               // either we can't connect
-                                  (!response.IsSuccessStatusCode && // or we have another http error
-                                   IsRetriableError(response.StatusCode)))
+                               response == null || // either we can't connect
+                               (!response.IsSuccessStatusCode && // or we have another http error
+                                IsRetriableError(response.StatusCode)))
                           )
                     {
                         retryInterval = TimeSpan.FromMilliseconds(Math.Min(retryInterval.TotalMilliseconds * 2, 1000));
@@ -574,7 +571,7 @@ public override async Task SendAsync(CancellationToken ct = default)
                         try
                         {
                             response = await _client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead,
-                                                               cts.Token);
+                                cts.Token);
                         }
                         catch (HttpRequestException)
                         {
@@ -588,7 +585,7 @@ public override async Task SendAsync(CancellationToken ct = default)
             if (response == null)
             {
                 throw new IngressError(ErrorCode.ServerFlushError,
-                                       $"Cannot connect to `{Options.Host}:{Options.Port}`");
+                    $"Cannot connect to `{Options.Host}:{Options.Port}`");
             }
 
             // return if ok