stub: Clarify flow control javadoc

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

@@ -47,6 +47,17 @@
  * <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 delivered to the peer application. This library considers delivery complete
+ * when the {@link #onNext} callback returns. Other gRPC libraries define this differently.
+ *
+ * <p>The link between local readiness and peer message consumption may not be immediate and may not
+ * be reflected message-for-message. All that's guaranteed is this: if an outbound is accepting
+ * messages but the peer is not consuming them, the outbound's {@link #isReady} will eventually
+ * return false. If, later, the peer does consume 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 +98,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 +120,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.
    *