From 9b2508cce325ae9bc22984cad73d8117bd18272a Mon Sep 17 00:00:00 2001
From: Mattie Fu <mattiefu@google.com>
Date: Fri, 25 Jun 2021 15:34:46 +0000
Subject: [PATCH] add comments

---
 .../data/v2/stub/EnhancedBigtableStub.java    | 21 +++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/stub/EnhancedBigtableStub.java b/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/stub/EnhancedBigtableStub.java
index d8b3eda0a8..08eeb4c49c 100644
--- a/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/stub/EnhancedBigtableStub.java
+++ b/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/stub/EnhancedBigtableStub.java
@@ -395,9 +395,20 @@ public Map<String, String> extract(ReadRowsRequest readRowsRequest) {
   }
 
   /**
-   * @param rowAdapter
-   * @param <RowT>
-   * @return
+   * Creates a callable chain to handle bulk ReadRows RPCs. This is meant to be used in ReadRows
+   * batcher. The chain will:
+   *
+   * <ul>
+   *   <li>Convert a {@link Query} into a {@link com.google.bigtable.v2.ReadRowsRequest}.
+   *   <li>Upon receiving the response stream, it will merge the {@link
+   *       com.google.bigtable.v2.ReadRowsResponse.CellChunk}s in logical rows. The actual row
+   *       implementation can be configured in by the {@code rowAdapter} parameter.
+   *   <li>Retry/resume on failure.
+   *   <li>Filter out marker rows.
+   *   <li>Construct a {@link UnaryCallable} that will buffer the entire stream into memory before
+   *       completing. If the stream is empty, then the list will be empty.
+   *   <li>Add tracing & metrics.
+   * </ul>
    */
   private <RowT> UnaryCallable<Query, List<RowT>> createBulkReadRowsCallable(
       RowAdapter<RowT> rowAdapter) {
@@ -409,6 +420,8 @@ private <RowT> UnaryCallable<Query, List<RowT>> createBulkReadRowsCallable(
 
     SpanName span = getSpanName("ReadRows");
 
+    // TracedBatchingContextCallable needs to be the last in the callable chain so Batcher can pass
+    // a BatchedCallContext to add batching metrics to ApiTracer.
     UnaryCallable<Query, List<RowT>> traced =
         new TracedBatchedContextCallable<>(
             readRowsUserCallable.all(),
@@ -540,7 +553,7 @@ private UnaryCallable<BulkMutation, Void> createBulkMutateRowsCallable() {
             userFacing, settings.getHeaderTracer(), spanName.toString());
 
     // TracedBatchingContextCallable needs to be the last in the callable chain so Batcher can pass
-    // batchingCallContext to add batching metrics to ApiTracer.
+    // a BatchedCallContext to add batching metrics to ApiTracer.
     UnaryCallable<BulkMutation, Void> batchingContextCallable =
         new TracedBatchedContextCallable<>(
             withHeaderTracer,