api,stub: Improve waitForReady documentation
diff --git a/api/src/main/java/io/grpc/CallOptions.java b/api/src/main/java/io/grpc/CallOptions.java
index 17b065e..2c9b1c5 100644
--- a/api/src/main/java/io/grpc/CallOptions.java
+++ b/api/src/main/java/io/grpc/CallOptions.java
@@ -150,8 +150,10 @@
/**
* 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 bafd5ea..2a74aa2 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 @@
}
/**
- * 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
*/
