Improve docs to describe close as being last method called

ejona86 · ejona86 · commit d27cbc8aa3e8 · 2015-07-08T15:08:26.000-07:00
This isn't changing any of the semantics we already had, but more
informing users of the guarantees we provide.
diff --git a/core/src/main/java/io/grpc/ClientCall.java b/core/src/main/java/io/grpc/ClientCall.java
@@ -80,10 +80,13 @@ public abstract static class Listener<T> {
     public abstract void onPayload(T payload);
 
     /**
-     * The ClientCall has been closed. No further sending or receiving can occur. If {@code status}
-     * is not equal to {@link Status#OK}, then the call failed. An additional block of trailer
-     * metadata may be received at the end of the call from the server. An empty {@link Metadata}
-     * object is passed if no trailers are received.
+     * The ClientCall has been closed. Any additional calls to the {@code ClientCall} will not be
+     * processed by the server. No further receiving will occur and no further notifications will be
+     * made.
+     *
+     * <p>If {@code status} is not equal to {@link Status#OK}, then the call failed. An additional
+     * block of trailer metadata may be received at the end of the call from the server. An empty
+     * {@link Metadata} object is passed if no trailers are received.
      *
      * @param status the result of the remote call.
      * @param trailers metadata provided at call completion.
diff --git a/stub/src/main/java/io/grpc/stub/StreamObserver.java b/stub/src/main/java/io/grpc/stub/StreamObserver.java
@@ -60,9 +60,9 @@ public interface StreamObserver<V>  {
   /**
    * Receives a terminating error from the stream.
    *
-   * <p>May only be called once and is never called after {@link #onCompleted()}. In particular if
-   * an exception is thrown by an implementation of {@code onError} no further calls to any
-   * method are allowed.
+   * <p>May only be called once and if called it must be the last method called. In particular if an
+   * exception is thrown by an implementation of {@code onError} no further calls to any method are
+   * allowed.
    *
    * @param t the error occurred on the stream
    */
@@ -71,9 +71,9 @@ public interface StreamObserver<V>  {
   /**
    * Receives a notification of successful stream completion.
    *
-   * <p>May only be called once and is never called after {@link #onError(Throwable)}. In particular
-   * if an exception is thrown by an implementation of {@code onCompleted} no further calls to
-   * any method are allowed.
+   * <p>May only be called once and if called it must be the last method called. In particular if an
+   * exception is thrown by an implementation of {@code onCompleted} no further calls to any method
+   * are allowed.
    */
   public void onCompleted();
 }
