stub: update docs about Call lifetime + minor cleanups

* Reflowed some method parameters to be on the same line, else one
  parameter per line
* Used `@link` where appropriate
* Made some parameters non-final where it had no effect
* Renamed some parameters to be consistent

2 files changed, 64 insertions, 51 deletions

diff --git a/stub/src/main/java/io/grpc/stub/ClientCalls.java b/stub/src/main/java/io/grpc/stub/ClientCalls.java
index 8bf3ff018..db2440381 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCalls.java
@@ -55,27 +55,29 @@ public final class ClientCalls {
   private ClientCalls() {}
 
   /**
-   * Executes a unary call with a response {@link StreamObserver}.
+   * Executes a unary call with a response {@link StreamObserver}.  The {@code call} should not be
+   * already started.  After calling this method, {@code call} should no longer be used.
    */
   public static <ReqT, RespT> void asyncUnaryCall(
-      ClientCall<ReqT, RespT> call,
-      ReqT param,
-      StreamObserver<RespT> observer) {
-    asyncUnaryRequestCall(call, param, observer, false);
+      ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
+    asyncUnaryRequestCall(call, req, responseObserver, false);
   }
 
   /**
-   * Executes a server-streaming call with a response {@link StreamObserver}.
+   * Executes a server-streaming call with a response {@link StreamObserver}.  The {@code call}
+   * should not be already started.  After calling this method, {@code call} should no longer be
+   * used.
    */
   public static <ReqT, RespT> void asyncServerStreamingCall(
-      ClientCall<ReqT, RespT> call,
-      ReqT param,
-      StreamObserver<RespT> responseObserver) {
-    asyncUnaryRequestCall(call, param, responseObserver, true);
+      ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
+    asyncUnaryRequestCall(call, req, responseObserver, true);
   }
 
   /**
    * Executes a client-streaming call returning a {@link StreamObserver} for the request messages.
+   * The {@code call} should not be already started.  After calling this method, {@code call}
+   * should no longer be used.
+   *
    * @return request stream observer.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
@@ -85,7 +87,9 @@ public final class ClientCalls {
   }
 
   /**
-   * Executes a bidi-streaming call.
+   * Executes a bidirectional-streaming call.  The {@code call} should not be already started.
+   * After calling this method, {@code call} should no longer be used.
+   *
    * @return request stream observer.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
@@ -94,12 +98,14 @@ public final class ClientCalls {
   }
 
   /**
-   * Executes a unary call and blocks on the response.
+   * 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.
+   *
    * @return the single response message.
    */
-  public static <ReqT, RespT> RespT blockingUnaryCall(ClientCall<ReqT, RespT> call, ReqT param) {
+  public static <ReqT, RespT> RespT blockingUnaryCall(ClientCall<ReqT, RespT> call, ReqT req) {
     try {
-      return getUnchecked(futureUnaryCall(call, param));
+      return getUnchecked(futureUnaryCall(call, req));
     } catch (RuntimeException e) {
       throw cancelThrow(call, e);
     } catch (Error e) {
@@ -108,16 +114,17 @@ public final class ClientCalls {
   }
 
   /**
-   * Executes a unary call and blocks on the response.
+   * 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.
    *
    * @return the single response message.
    */
   public static <ReqT, RespT> RespT blockingUnaryCall(
-      Channel channel, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, ReqT param) {
+      Channel channel, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, ReqT req) {
     ThreadlessExecutor executor = new ThreadlessExecutor();
     ClientCall<ReqT, RespT> call = channel.newCall(method, callOptions.withExecutor(executor));
     try {
-      ListenableFuture<RespT> responseFuture = futureUnaryCall(call, param);
+      ListenableFuture<RespT> responseFuture = futureUnaryCall(call, req);
       while (!responseFuture.isDone()) {
         try {
           executor.waitAndDrain();
@@ -139,43 +146,47 @@ public final class ClientCalls {
 
   /**
    * Executes a server-streaming call returning a blocking {@link Iterator} over the
-   * response stream.
+   * response stream.  The {@code call} should not be already started.  After calling this method,
+   * {@code call} should no longer be used.
+   *
    * @return an iterator over the response stream.
    */
   // TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs.
   public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
-      ClientCall<ReqT, RespT> call, ReqT param) {
+      ClientCall<ReqT, RespT> call, ReqT req) {
     BlockingResponseStream<RespT> result = new BlockingResponseStream<RespT>(call);
-    asyncUnaryRequestCall(call, param, result.listener(), true);
+    asyncUnaryRequestCall(call, req, result.listener(), true);
     return result;
   }
 
   /**
    * Executes a server-streaming call returning a blocking {@link Iterator} over the
-   * response stream.
+   * response stream.  The {@code call} should not be already started.  After calling this method,
+   * {@code call} should no longer be used.
    *
    * @return an iterator over the response stream.
    */
   // TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs.
   public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
-      Channel channel, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, ReqT param) {
+      Channel channel, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, ReqT req) {
     ThreadlessExecutor executor = new ThreadlessExecutor();
     ClientCall<ReqT, RespT> call = channel.newCall(method, callOptions.withExecutor(executor));
     BlockingResponseStream<RespT> result = new BlockingResponseStream<RespT>(call, executor);
-    asyncUnaryRequestCall(call, param, result.listener(), true);
+    asyncUnaryRequestCall(call, req, result.listener(), true);
     return result;
   }
 
   /**
-   * Executes a unary call and returns a {@link ListenableFuture} to the response.
+   * Executes a unary call and returns a {@link ListenableFuture} to the response.  The
+   * {@code call} should not be already started.  After calling this method, {@code call} should no
+   * longer be used.
    *
    * @return a future for the single response message.
    */
   public static <ReqT, RespT> ListenableFuture<RespT> futureUnaryCall(
-      ClientCall<ReqT, RespT> call,
-      ReqT param) {
+      ClientCall<ReqT, RespT> call, ReqT req) {
     GrpcFuture<RespT> responseFuture = new GrpcFuture<RespT>(call);
-    asyncUnaryRequestCall(call, param, new UnaryStreamToFuture<RespT>(responseFuture), false);
+    asyncUnaryRequestCall(call, req, new UnaryStreamToFuture<RespT>(responseFuture), false);
     return responseFuture;
   }
 
@@ -249,11 +260,11 @@ public final class ClientCalls {
   }
 
   private static <ReqT, RespT> void asyncUnaryRequestCall(
-      ClientCall<ReqT, RespT> call, ReqT param, StreamObserver<RespT> responseObserver,
+      ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver,
       boolean streamingResponse) {
     asyncUnaryRequestCall(
         call,
-        param,
+        req,
         new StreamObserverToCallListenerAdapter<ReqT, RespT>(
             responseObserver,
             new CallToStreamObserverAdapter<ReqT>(call),
@@ -263,12 +274,12 @@ public final class ClientCalls {
 
   private static <ReqT, RespT> void asyncUnaryRequestCall(
       ClientCall<ReqT, RespT> call,
-      ReqT param,
+      ReqT req,
       ClientCall.Listener<RespT> responseListener,
       boolean streamingResponse) {
     startCall(call, responseListener, streamingResponse);
     try {
-      call.sendMessage(param);
+      call.sendMessage(req);
       call.halfClose();
     } catch (RuntimeException e) {
       throw cancelThrow(call, e);
@@ -278,7 +289,8 @@ public final class ClientCalls {
   }
 
   private static <ReqT, RespT> StreamObserver<ReqT> asyncStreamingRequestCall(
-      ClientCall<ReqT, RespT> call, StreamObserver<RespT> responseObserver,
+      ClientCall<ReqT, RespT> call,
+      StreamObserver<RespT> responseObserver,
       boolean streamingResponse) {
     CallToStreamObserverAdapter<ReqT> adapter = new CallToStreamObserverAdapter<ReqT>(call);
     startCall(
@@ -289,8 +301,10 @@ public final class ClientCalls {
     return adapter;
   }
 
-  private static <ReqT, RespT> void startCall(ClientCall<ReqT, RespT> call,
-      ClientCall.Listener<RespT> responseListener, boolean streamingResponse) {
+  private static <ReqT, RespT> void startCall(
+      ClientCall<ReqT, RespT> call,
+      ClientCall.Listener<RespT> responseListener,
+      boolean streamingResponse) {
     call.start(responseListener, new Metadata());
     if (streamingResponse) {
       call.request(1);
@@ -430,7 +444,7 @@ public final class ClientCalls {
   }
 
   /**
-   * Complete a GrpcFuture using {@link StreamObserver} events.
+   * Completes a {@link GrpcFuture} using {@link StreamObserver} events.
    */
   private static final class UnaryStreamToFuture<RespT> extends ClientCall.Listener<RespT> {
     private final GrpcFuture<RespT> responseFuture;
@@ -500,11 +514,10 @@ public final class ClientCalls {
   }
 
   /**
-   * Convert events on a {@link io.grpc.ClientCall.Listener} into a blocking
-   * {@link Iterator}.
+   * Convert events on a {@link io.grpc.ClientCall.Listener} into a blocking {@link Iterator}.
    *
    * <p>The class is not thread-safe, but it does permit {@link ClientCall.Listener} calls in a
-   * separate thread from {@code Iterator} calls.
+   * separate thread from {@link Iterator} calls.
    */
   // TODO(ejona86): determine how to allow ClientCall.cancel() in case of application error.
   private static final class BlockingResponseStream<T> implements Iterator<T> {
diff --git a/stub/src/main/java/io/grpc/stub/ServerCalls.java b/stub/src/main/java/io/grpc/stub/ServerCalls.java
index 5b043701a..aac13a5f8 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCalls.java
@@ -42,42 +42,42 @@ public final class ServerCalls {
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a unary call method of the service.
+   * Creates a {@link ServerCallHandler} for a unary call method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncUnaryCall(
-      final UnaryMethod<ReqT, RespT> method) {
+      UnaryMethod<ReqT, RespT> method) {
     return asyncUnaryRequestCall(method);
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a server streaming method of the service.
+   * Creates a {@link ServerCallHandler} for a server streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncServerStreamingCall(
-      final ServerStreamingMethod<ReqT, RespT> method) {
+      ServerStreamingMethod<ReqT, RespT> method) {
     return asyncUnaryRequestCall(method);
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a client streaming method of the service.
+   * Creates a {@link ServerCallHandler} for a client streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncClientStreamingCall(
-      final ClientStreamingMethod<ReqT, RespT> method) {
+      ClientStreamingMethod<ReqT, RespT> method) {
     return asyncStreamingRequestCall(method);
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a bidi streaming method of the service.
+   * Creates a {@link ServerCallHandler} for a bidi streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncBidiStreamingCall(
-      final BidiStreamingMethod<ReqT, RespT> method) {
+      BidiStreamingMethod<ReqT, RespT> method) {
     return asyncStreamingRequestCall(method);
   }
 
@@ -97,7 +97,7 @@ public final class ServerCalls {
   public interface ClientStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {}
 
   /**
-   * Adaptor to a bi-directional streaming method.
+   * Adaptor to a bidirectional streaming method.
    */
   public interface BidiStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {}
 
@@ -195,7 +195,7 @@ public final class ServerCalls {
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a unary request call method of the service.
+   * Creates a {@link ServerCallHandler} for a unary request call method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
@@ -283,7 +283,7 @@ public final class ServerCalls {
   }
 
   /**
-   * Creates a {@code ServerCallHandler} for a streaming request call method of the service.
+   * Creates a {@link ServerCallHandler} for a streaming request call method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
    */
@@ -399,8 +399,8 @@ public final class ServerCalls {
    * @param methodDescriptor of method for which error will be thrown.
    * @param responseObserver on which error will be set.
    */
-  public static void asyncUnimplementedUnaryCall(MethodDescriptor<?, ?> methodDescriptor,
-      StreamObserver<?> responseObserver) {
+  public static void asyncUnimplementedUnaryCall(
+      MethodDescriptor<?, ?> methodDescriptor, StreamObserver<?> responseObserver) {
     checkNotNull(methodDescriptor, "methodDescriptor");
     checkNotNull(responseObserver, "responseObserver");
     responseObserver.onError(Status.UNIMPLEMENTED