From 4674b27736c9d5265ea0501c61d9353225a04a42 Mon Sep 17 00:00:00 2001
From: Eric Anderson <ejona@google.com>
Date: Thu, 30 Apr 2020 15:30:24 -0700
Subject: [PATCH] api,stub: Improve waitForReady documentation

---
 api/src/main/java/io/grpc/CallOptions.java        | 6 ++++--
 stub/src/main/java/io/grpc/stub/AbstractStub.java | 7 ++++++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/api/src/main/java/io/grpc/CallOptions.java b/api/src/main/java/io/grpc/CallOptions.java
index 17b065ed22..2c9b1c5208 100644
--- a/api/src/main/java/io/grpc/CallOptions.java
+++ b/api/src/main/java/io/grpc/CallOptions.java
@@ -150,8 +150,10 @@ public final class CallOptions {
 
   /**
    * Enables <a href="https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md">
-   * 'wait for ready'</a> feature for the call. 'Fail fast' is the default option for gRPC calls
-   * and 'wait for ready' is the opposite to it.
+   * 'wait for ready'</a> for the call. Wait-for-ready queues the RPC until a connection is
+   * available. This may dramatically increase the latency of the RPC, but avoids failing
+   * "unnecessarily." The default queues the RPC until an attempt to connect has completed, but
+   * fails RPCs without sending them if unable to connect.
    */
   public CallOptions withWaitForReady() {
     CallOptions newOptions = new CallOptions(this);
diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java
index bafd5ea268..2a74aa2469 100644
--- a/stub/src/main/java/io/grpc/stub/AbstractStub.java
+++ b/stub/src/main/java/io/grpc/stub/AbstractStub.java
@@ -220,7 +220,12 @@ public abstract class AbstractStub<S extends AbstractStub<S>> {
   }
 
   /**
-   * Returns a new stub that uses the 'wait for ready' call option.
+   * Returns a new stub that uses
+   * <a href="https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md">'wait for ready'</a>
+   * for the call. Wait-for-ready queues the RPC until a connection is available. This may
+   * dramatically increase the latency of the RPC, but avoids failing "unnecessarily." The default
+   * queues the RPC until an attempt to connect has completed, but fails RPCs without sending them
+   * if unable to connect.
    *
    * @since 1.1.0
    */