core: add clarification to ClientCall javadoc

* Improve ClientCall documentation. Clarify that some methods of ClientCall may be invoked from any thread. Adds @throws clauses to request().

core/src/main/java/io/grpc/ClientCall.java

@@ -38,7 +38,8 @@ import javax.annotation.Nullable;
  * Applications are expected to utilize normal payload messages for such signals, as a response
  * naturally acknowledges its request.
  *
- * <p>Methods are guaranteed to be non-blocking. Implementations are not required to be thread-safe.
+ * <p>Methods are guaranteed to be non-blocking. Not thread-safe except for {@link #request}, which
+ * may be called from any thread.
  *
  * <p>There is no interaction between the states on the {@link Listener Listener} and {@link
  * ClientCall}, i.e., if {@link Listener#onClose Listener.onClose()} is called, it has no bearing on
@@ -190,6 +191,8 @@ public abstract class ClientCall<ReqT, RespT> {
    *
    * @param numMessages the requested number of messages to be delivered to the listener. Must be
    *                    non-negative.
+   * @throws IllegalStateException if call is not {@code start()}ed
+   * @throws IllegalArgumentException if numMessages is negative
    */
   public abstract void request(int numMessages);