From 2ce5a2fdb0347045af6550e998e053e17d159e21 Mon Sep 17 00:00:00 2001
From: Vadym Matsishevskyi <25311427+vam-google@users.noreply.github.com>
Date: Mon, 7 Jan 2019 14:44:58 -0800
Subject: [PATCH] Document default values for BatchingSettings (#639)

"Fixes" https://github.com/googleapis/gax-java/issues/543
---
 .../google/api/gax/batching/BatchingSettings.java    | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java b/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java
index a1585f4e9..8982c46ff 100644
--- a/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java
+++ b/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java
@@ -38,6 +38,11 @@
 /**
  * Represents the batching settings to use for an API method that is capable of batching.
  *
+ * <p>By default the settings are configured to <b>not</b> use batching (i.e. the batch size
+ * threshold is 1). This is the safest default behavior, which has meaning in all possible
+ * scenarios. Users are expected to configure actual batching thresholds explicitly: the element
+ * count, the request bytes count and the delay.
+ *
  * <p>Warning: With the wrong settings, it is possible to cause long periods of dead waiting time.
  *
  * <p>When batching is turned on for an API method, a call to that method will result in the request
@@ -50,12 +55,13 @@
  *
  * <ul>
  *   <li><b>Delay Threshold</b>: Counting from the time that the first message is queued, once this
- *       delay has passed, then send the batch.
+ *       delay has passed, then send the batch. The default value is 1 millisecond.
  *   <li><b>Message Count Threshold</b>: Once this many messages are queued, send all of the
- *       messages in a single call, even if the delay threshold hasn't elapsed yet.
+ *       messages in a single call, even if the delay threshold hasn't elapsed yet. The default
+ *       value is 1 message.
  *   <li><b>Request Byte Threshold</b>: Once the number of bytes in the batched request reaches this
  *       threshold, send all of the messages in a single call, even if neither the delay or message
- *       count thresholds have been exceeded yet.
+ *       count thresholds have been exceeded yet. The default value is 1 byte.
  * </ul>
  *
  * <p>These thresholds are treated as triggers, not as limits. Thus, if a request is made with 2x