stub: Clarify flow control javadoc (grpc#12977)

Remove vestigial references to credit-based flow control and the
suggestion that a request() for messages directly corresponds to the
number of messages a peer could subsequently send before its end of the
stream went !isReady(). In fact, okhttp, netty and binder transports all
buffer messages meaning the outbound stream can be isReady() even when
the receiver has no outstanding request()s for messages. Furthermore, those
buffers are sized in bytes and not all messages are the same size. So
consuming an inbound's next message may not cause a non-ready outbound
to become ready again.

Replace this with a short discussion of what is actually guaranteed by
every transport.

Author: jdcormie

stub/src/main/java/io/grpc/stub/CallStreamObserver.java

@@ -47,6 +47,14 @@
  * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple
  * threads will be writing to an instance concurrently, the application must synchronize its calls.
  *
+ * <p>On flow control: {@link #isReady} returns whether an observer can accept more messages without
+ * excessive buffering. Readiness is affected by the volume of messages previously sent and how much
+ * of that data has been requested by the peer application. But this effect may not be immediate and
+ * may not be message-for-message. All that's guaranteed is this: if an outbound is being fed
+ * messages but the peer is not requesting them, the outbound's {@link #isReady} will eventually
+ * return false. If, later, the peer does ask for enough of those messages, the outbound observer
+ * will eventually become ready again.
+ *
  * <p>DO NOT MOCK: The API is too complex to reliably mock. Use InProcessChannelBuilder to create
  * "real" RPCs suitable for testing.
  *
@@ -87,9 +95,10 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Disables automatic flow control where a token is returned to the peer after a call
-   * to the 'inbound' {@link io.grpc.stub.StreamObserver#onNext(Object)} has completed. If disabled
-   * an application must make explicit calls to {@link #request} to receive messages.
+   * Disables automatic flow control, a mode where another message is implicitly {@link #request}ed
+   * after each call to the inbound's {@link StreamObserver#onNext(Object)} returns.
+   *
+   * <p>If disabled an application must make explicit calls to {@link #request} to receive messages.
    *
    * <p>On client-side this method may only be called during {@link
    * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial
@@ -108,16 +117,15 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    *   </li>
    * </ul>
    * </p>
-   * 
+   *
    * <p>This API is being replaced, but is not yet deprecated. On server-side it being replaced
    * with {@link ServerCallStreamObserver#disableAutoRequest}. On client-side {@link
    * ClientCallStreamObserver#disableAutoRequestWithInitial disableAutoRequestWithInitial(1)}.
    */
   public abstract void disableAutoInboundFlowControl();
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *

stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java

@@ -92,8 +92,7 @@ public void disableAutoRequestWithInitial(int request) {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *

stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java

@@ -147,8 +147,7 @@ public void disableAutoRequest() {
   public abstract void setOnReadyHandler(Runnable onReadyHandler);
 
   /**
-   * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
-   * {@link StreamObserver}.
+   * Requests that {@code count} more messages be delivered to the 'inbound' {@link StreamObserver}.
    *
    * <p>This method is safe to call from multiple threads without external synchronization.
    *