stub: Document StreamObserver is an async API

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

@@ -20,7 +20,8 @@
 
 /**
  * A refinement of {@link CallStreamObserver} that allows for lower-level interaction with
- * client calls.
+ * client calls. An instance of this class is obtained via {@link ClientResponseObserver}, or by
+ * manually casting the {@code StreamObserver} returned by a stub.
  *
  * <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.

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

@@ -18,7 +18,8 @@
 
 /**
  * A refinement of {@link CallStreamObserver} to allows for interaction with call
- * cancellation events on the server side.
+ * cancellation events on the server side. An instance of this class is obtained by casting the
+ * {@code StreamObserver} passed as an argument to service implementations.
  *
  * <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.

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

@@ -31,6 +31,16 @@
  * not need to be synchronized together; incoming and outgoing directions are independent.
  * Since individual {@code StreamObserver}s are not thread-safe, if multiple threads will be
  * writing to a {@code StreamObserver} concurrently, the application must synchronize calls.
+ *
+ * <p>This API is asynchronous, so methods may return before the operation completes. The API
+ * provides no guarantees for how quickly an operation will complete, so utilizing flow control via
+ * {@link ClientCallStreamObserver} and {@link ServerCallStreamObserver} to avoid excessive
+ * buffering is recommended for streaming RPCs. gRPC's implementation of {@code onError()} on
+ * client-side causes the RPC to be cancelled and discards all messages, so completes quickly.
+ *
+ * <p>gRPC guarantees it does not block on I/O in its implementation, but applications are allowed
+ * to perform blocking operations in their implementations. However, doing so will delay other
+ * callbacks because the methods cannot be called concurrently.
  */
 public interface StreamObserver<V>  {
   /**