Add more XML comments (#134)

src/Knet.Kudu.Client/ExternalConsistencyMode.cs

@@ -3,62 +3,69 @@
 namespace Knet.Kudu.Client
 {
     /// <summary>
+    /// <para>
     /// The external consistency mode for client requests.
     /// This defines how transactions and/or sequences of operations that touch
     /// several TabletServers, in different machines, can be observed by external
     /// clients.
-    ///
+    /// </para>
+    /// 
+    /// <para>
     /// Note that ExternalConsistencyMode makes no guarantee on atomicity, i.e.
     /// no sequence of operations is made atomic (or transactional) just because
     /// an external consistency mode is set.
     /// Note also that ExternalConsistencyMode has no implication on the
     /// consistency between replicas of the same tablet.
+    /// </para>
     /// </summary>
     public enum ExternalConsistencyMode
     {
         /// <summary>
-        /// The response to any write will contain a timestamp.
-        /// Any further calls from the same client to other servers will update
-        /// those servers with that timestamp. The user will make sure that the
-        /// timestamp is propagated through back-channels to other
-        /// KuduClient's.
-        ///
-        /// WARNING: Failure to propagate timestamp information through
-        /// back-channels will negate any external consistency guarantee under this
-        /// mode.
-        ///
-        /// Example:
-        /// 1 - Client A executes operation X in Tablet A
-        /// 2 - Afterwards, Client A executes operation Y in Tablet B
-        ///
-        ///
-        /// Client B may observe the following operation sequences:
-        /// {}, {X}, {X Y}
-        ///
-        /// This is the default mode.
+        /// <para>
+        /// The response to any write will contain a timestamp. Any further calls
+        /// from the same client to other servers will update those servers
+        /// with that timestamp. Following write operations from the same client
+        /// will be assigned timestamps that are strictly higher, enforcing external
+        /// consistency without having to wait or incur any latency penalties.
+        /// </para>
+        /// 
+        /// <para>
+        /// In order to maintain external consistency for writes between
+        /// two different clients in this mode, the user must forward the timestamp
+        /// from the first client to the second by using
+        /// <see cref="KuduClient.LastPropagatedTimestamp"/>.
+        /// </para>
+        /// 
+        /// <para>
+        /// This is the default external consistency mode.
+        /// </para>
+        /// 
+        /// <para>
+        /// Failure to propagate timestamp information through back-channels
+        /// between two different clients will negate any external consistency
+        /// guarantee under this mode.
+        /// </para>
         /// </summary>
         ClientPropagated = ExternalConsistencyModePB.ClientPropagated,
 
         /// <summary>
-        /// The server will guarantee that each transaction is externally
-        /// consistent by making sure that none of its results are visible
-        /// until every Kudu server agrees that the transaction is in the past.
-        /// The client is not obligated to forward timestamp information
-        /// through back-channels.
-        ///
-        /// WARNING: Depending on the clock synchronization state of TabletServers
-        /// this may imply considerable latency. Moreover operations with
-        /// COMMIT_WAIT requested external consistency will outright fail if
-        /// TabletServer clocks are either unsynchronized or synchronized but
-        /// with a maximum error which surpasses a pre-configured one.
-        ///
-        /// Example:
-        /// - Client A executes operation X in Tablet A
-        /// - Afterwards, Client A executes operation Y in Tablet B
-        ///
-        ///
-        /// Client B may observe the following operation sequences:
-        /// {}, {X}, {X Y}
+        /// <para>
+        /// The server will guarantee that write operations from the same or from
+        /// other client are externally consistent, without the need to propagate
+        /// timestamps across clients. This is done by making write operations
+        /// wait until there is certainty that all follow up write operations
+        /// (operations that start after the previous one finishes)
+        /// will be assigned a timestamp that is strictly higher, enforcing external
+        /// consistency.
+        /// </para>
+        /// 
+        /// <para>
+        /// Depending on the clock synchronization state of TabletServers this may
+        /// imply considerable latency. Moreover operations in COMMIT_WAIT
+        /// external consistency mode will outright fail if TabletServer clocks
+        /// are either unsynchronized or synchronized but with a maximum error
+        /// which surpasses a pre-configured threshold.
+        /// </para>
         /// </summary>
         CommitWait = ExternalConsistencyModePB.CommitWait
     }

src/Knet.Kudu.Client/Internal/ISystemClock.cs

@@ -2,6 +2,11 @@
 {
     public interface ISystemClock
     {
+        /// <summary>
+        /// Retrieve the current milliseconds. This value should only
+        /// be used to measure how much time has passed relative to
+        /// another call to this property.
+        /// </summary>
         long CurrentMilliseconds { get; }
     }
 }

src/Knet.Kudu.Client/Internal/SystemClock.cs

@@ -6,10 +6,12 @@ namespace Knet.Kudu.Client.Internal
     public sealed class SystemClock : ISystemClock
     {
 #if NETCOREAPP3_0
+        /// <inheritdoc/>
         public long CurrentMilliseconds => Environment.TickCount64;
 #else
         private readonly Stopwatch _stopwatch = Stopwatch.StartNew();
 
+        /// <inheritdoc/>
         public long CurrentMilliseconds => _stopwatch.ElapsedMilliseconds;
 #endif
     }

src/Knet.Kudu.Client/KuduClient.cs

@@ -168,17 +168,23 @@ public void ImportAuthenticationCredentials(ReadOnlyMemory<byte> token)
             _securityContext.ImportAuthenticationCredentials(token);
         }
 
+        /// <summary>
+        /// Create a table on the cluster with the specified name, schema, and
+        /// table configurations.
+        /// </summary>
+        /// <param name="builder">The create table options.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public async Task<KuduTable> CreateTableAsync(
-            TableBuilder tableBuilder, CancellationToken cancellationToken = default)
+            TableBuilder builder, CancellationToken cancellationToken = default)
         {
-            var rpc = new CreateTableRequest(tableBuilder.Build());
+            var rpc = new CreateTableRequest(builder.Build());
 
             var response = await SendRpcAsync(rpc, cancellationToken)
                 .ConfigureAwait(false);
 
             var tableId = new TableIdentifierPB { TableId = response.TableId };
 
-            if (tableBuilder.Wait)
+            if (builder.Wait)
             {
                 await WaitForCreateTableDoneAsync(
                     tableId, cancellationToken).ConfigureAwait(false);
@@ -190,11 +196,16 @@ await WaitForCreateTableDoneAsync(
             return null;
         }
 
+        /// <summary>
+        /// Alter a table on the cluster as specified by the builder.
+        /// </summary>
+        /// <param name="builder">The alter table options.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public async Task<AlterTableResponse> AlterTableAsync(
-            AlterTableBuilder alterTable,
+            AlterTableBuilder builder,
             CancellationToken cancellationToken = default)
         {
-            var rpc = new AlterTableRequest(alterTable);
+            var rpc = new AlterTableRequest(builder);
             AlterTableResponse response;
 
             try
@@ -204,19 +215,19 @@ public async Task<AlterTableResponse> AlterTableAsync(
             }
             finally
             {
-                if (alterTable.HasAddDropRangePartitions)
+                if (builder.HasAddDropRangePartitions)
                 {
                     // Clear the table locations cache so the new partition is
                     // immediately visible. We clear the cache even on failure,
                     // just in case the alter table operation actually succeeded.
-                    _tableLocations.TryRemove(alterTable.TableId, out _);
+                    _tableLocations.TryRemove(builder.TableId, out _);
                 }
             }
 
-            if (alterTable.Wait)
+            if (builder.Wait)
             {
                 var isDoneResponse = await WaitForAlterTableDoneAsync(
-                    alterTable.TableIdPb, cancellationToken).ConfigureAwait(false);
+                    builder.TableIdPb, cancellationToken).ConfigureAwait(false);
 
                 response = new AlterTableResponse(
                     response.TableId,
@@ -286,6 +297,13 @@ public async Task DeleteTableAsync(
             await SendRpcAsync(rpc, cancellationToken).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Get a list of table names. Passing a null filter returns all the tables.
+        /// When a filter is specified, it only returns tables that satisfy a substring
+        /// match.
+        /// </summary>
+        /// <param name="nameFilter">An optional table name filter.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public async Task<List<TableInfo>> GetTablesAsync(
             string nameFilter = null, CancellationToken cancellationToken = default)
         {
@@ -381,6 +399,11 @@ internal async Task<List<RemoteTablet>> GetTableLocationsAsync(
             return tableLocations;
         }
 
+        /// <summary>
+        /// Open the table with the given name.
+        /// </summary>
+        /// <param name="tableName">The table to open.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public async Task<KuduTable> OpenTableAsync(
             string tableName, CancellationToken cancellationToken = default)
         {
@@ -532,6 +555,23 @@ public IKuduSession NewSession(KuduSessionOptions options)
             return new KuduSession(this, options, _loggerFactory);
         }
 
+        /// <summary>
+        /// <para>
+        /// Create a <see cref="KuduPartitioner"/> that allows clients to determine
+        /// the target partition of a row without actually performing a write. The
+        /// set of partitions is eagerly fetched when the KuduPartitioner is constructed
+        /// so that the actual partitioning step can be performed synchronously
+        /// without any network trips.
+        /// </para>
+        /// 
+        /// <para>
+        /// NOTE: Because this operates on a metadata snapshot retrieved at
+        /// construction time, it will not reflect any metadata changes to the
+        /// table that have occurred since its creation.
+        /// </para>
+        /// </summary>
+        /// <param name="table">The table to operate on.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public async ValueTask<KuduPartitioner> CreatePartitionerAsync(
             KuduTable table, CancellationToken cancellationToken = default)
         {
@@ -736,7 +776,7 @@ private TableLocationsCache GetTableLocationsCache(string tableId)
 #endif
         }
 
-        public async ValueTask<List<RemoteTablet>> LoopLocateTableAsync(
+        private async ValueTask<List<RemoteTablet>> LoopLocateTableAsync(
             string tableId,
             byte[] startPartitionKey,
             byte[] endPartitionKey,

src/Knet.Kudu.Client/KuduScanEnumerator.cs

@@ -131,7 +131,6 @@ public KuduScanEnumerator(
             _lastPrimaryKey = Array.Empty<byte>();
             _cancellationToken = cancellationToken;
             ResourceMetrics = new ResourceMetrics();
-            // TODO: Register cancellation callback and cancel the scan.
 
             // Map the column names to actual columns in the table schema.
             // If the user set this to 'null', we scan all columns.
@@ -436,7 +435,6 @@ private async ValueTask<bool> ScanNextRowsAsync()
 
         private ScanRequest<T> GetOpenRequest()
         {
-            //checkScanningNotStarted();
             var request = new ScanRequestPB();
 
             var newRequest = request.NewScanRequest = new NewScanRequestPB
@@ -499,7 +497,6 @@ private ScanRequest<T> GetOpenRequest()
 
         private ScanRequest<T> GetNextRowsRequest()
         {
-            //checkScanningNotStarted();
             var request = new ScanRequestPB
             {
                 ScannerId = _scannerId,