Address review comments.

Author: kannanjgithub

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

@@ -72,11 +72,10 @@ private ClientCalls() {}
    * {@code beforeStart()} will be called.
    *
    * <h3>Server errors</h3>
-   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
-   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
-   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
-   * description will be encoded to the stream trailer, but the cause (which may contain server
-   * application's information) will not.
+   * If the server completes the RPC with status code OK, then {@code
+   * responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
+   * trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
+   * Status#fromThrowable} and {@link Status#trailersFromThrowable}.
    */
   public static <ReqT, RespT> void asyncUnaryCall(
       ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -93,11 +92,10 @@ public static <ReqT, RespT> void asyncUnaryCall(
    * {@code beforeStart()} will be called.
    *
    * <h3>Server errors</h3>
-   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
-   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
-   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
-   * description will be encoded to the stream trailer, but the cause (which may contain server
-   * application's information) will not.
+   * If the server completes the RPC with status code OK, then {@code
+   * responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
+   * trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
+   * Status#fromThrowable} and {@link Status#trailersFromThrowable}.
    */
   public static <ReqT, RespT> void asyncServerStreamingCall(
       ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -113,24 +111,26 @@ public static <ReqT, RespT> void asyncServerStreamingCall(
    * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
    * {@code beforeStart()} will be called.
    *
-   * @return request stream observer. It will extend {@link ClientCallStreamObserver}
-   *
    * <h3>Client errors</h3>
-   * onError called on the request stream observer will result in stream cancellation. The response
+   * {@link StreamObserver#onError} called on the request stream observer will result in stream
+   * cancellation. The response
    * {@link StreamObserver} will be immediately notified of the cancellation with a
    * {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
    * and the stream is considered closed. The server's request stream observer will receive an
-   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
-   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * {@link StreamObserver#onError} callback with a throwable which when converted to a status
+   * with
+   * Status.fromThrowable(), always has the status code CANCELLED and exception cause set to
+   * null because the actual exception
    * passed by the client to onError is never actually transmitted to the server and the server
    * just receives a RST_STREAM frame indicating cancellation by the client.
    *
    * <h3>Server errors</h3>
-   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
-   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
-   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
-   * description will be encoded to the stream trailer, but the cause (which may contain server
-   * application's information) will not.
+   * If the server completes the RPC with status code OK, then {@code
+   * responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
+   * trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
+   * Status#fromThrowable} and {@link Status#trailersFromThrowable}.
+   *
+   * @return request stream observer. It will extend {@link ClientCallStreamObserver}
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
       ClientCall<ReqT, RespT> call,
@@ -146,24 +146,26 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
    * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
    * {@code beforeStart()} will be called.
    *
-   * @return request stream observer. It will extend {@link ClientCallStreamObserver}
-   *
    * <h3>Client errors</h3>
-   * onError called on the request stream observer will result in stream cancellation. The response
+   * {@link StreamObserver#onError} called on the request stream observer will result in stream
+   * cancellation. The response
    * {@link StreamObserver} will be immediately notified of the cancellation with a
    * {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
    * and the stream is considered closed. The server's request stream observer will receive an
-   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
-   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * {@link StreamObserver#onError} callback with a throwable which when converted to a status
+   * with
+   * Status.fromThrowable(), always has the status code CANCELLED and exception cause set to
+   * null because the actual exception
    * passed by the client to onError is never actually transmitted to the server and the server
    * just receives a RST_STREAM frame indicating cancellation by the client.
    *
    * <h3>Server errors</h3>
-   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
-   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
-   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
-   * description will be encoded to the stream trailer, but the cause (which may contain server
-   * application's information) will not.
+   * If the server completes the RPC with status code OK, then {@code
+   * responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
+   * trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
+   * Status#fromThrowable} and {@link Status#trailersFromThrowable}.
+   *
+   * @return request stream observer. It will extend {@link ClientCallStreamObserver}
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
       ClientCall<ReqT, RespT> call, StreamObserver<RespT> responseObserver) {
@@ -175,6 +177,10 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
    * Executes a unary call and blocks on the response.  The {@code call} should not be already
    * started.  After calling this method, {@code call} should no longer be used.
    *
+   * <h3>Server errors</h3>
+   * If the server completes the RPC with a non-OK status, a {@link StatusRuntimeException}
+   * is thrown. The status code and trailers can be accessed from the exception.
+   *
    * @return the single response message.
    * @throws StatusRuntimeException on error
    */
@@ -190,6 +196,10 @@ public static <ReqT, RespT> RespT blockingUnaryCall(ClientCall<ReqT, RespT> call
    * Executes a unary call and blocks on the response.  The {@code call} should not be already
    * started.  After calling this method, {@code call} should no longer be used.
    *
+   * <h3>Server errors</h3>
+   * If the server completes the RPC with a non-OK status, a {@link StatusRuntimeException}
+   * is thrown. The status code and trailers can be accessed from the exception.
+   *
    * @return the single response message.
    * @throws StatusRuntimeException on error
    */
@@ -228,7 +238,11 @@ public static <ReqT, RespT> RespT blockingUnaryCall(
    * response stream.  The {@code call} should not be already started.  After calling this method,
    * {@code call} should no longer be used.
    *
-   * <p>The returned iterator may throw {@link StatusRuntimeException} on error.
+   * <h3>Server errors</h3>
+   * If the server completes the RPC with a non-OK status, the returned iterator will throw
+   * a {@link StatusRuntimeException} when attempting to read the error response (e.g. in
+   * {@link Iterator#hasNext} or {@link Iterator#next}). The status code and trailers can be
+   * accessed from the exception.
    *
    * @return an iterator over the response stream.
    */
@@ -245,7 +259,11 @@ public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
    * response stream.  The {@code call} should not be already started.  After calling this method,
    * {@code call} should no longer be used.
    *
-   * <p>The returned iterator may throw {@link StatusRuntimeException} on error.
+   * <h3>Server errors</h3>
+   * If the server completes the RPC with a non-OK status, the returned iterator will throw
+   * a {@link StatusRuntimeException} when attempting to read the error response (e.g. in
+   * {@link Iterator#hasNext} or {@link Iterator#next}). The status code and trailers can be
+   * accessed from the exception.
    *
    * @return an iterator over the response stream.
    */
@@ -264,6 +282,11 @@ public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
    * {@code call} should not be already started.  After calling this method, {@code call} should no
    * longer be used.
    *
+   * <h3>Server errors</h3>
+   * If the server completes the RPC with a non-OK status, the returned future will fail with
+   * a {@link StatusRuntimeException}. The status code and trailers can be accessed from the
+   * exception.
+   *
    * @return a future for the single response message.
    */
   public static <ReqT, RespT> ListenableFuture<RespT> futureUnaryCall(