Javadoc improvements, especially to Context

2 files changed, 11 insertions, 5 deletions

diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java
index 8b8d33032..a1f575b5e 100644
--- a/stub/src/main/java/io/grpc/stub/AbstractStub.java
+++ b/stub/src/main/java/io/grpc/stub/AbstractStub.java
@@ -43,16 +43,20 @@ import io.grpc.ExperimentalApi;
 import io.grpc.ManagedChannelBuilder;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Nullable;
+import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * Common base type for stub implementations.
+ * Common base type for stub implementations. Stub configuration is immutable; changing the
+ * configuration returns a new stub with updated configuration. Changing the configuration is cheap
+ * and may be done before every RPC, such as would be common when using {@link #withDeadlineAfter}.
  *
- * <p>This is the base class of the stub classes from the generated code. It allows for
- * reconfiguration, e.g., attaching interceptors to the stub.
+ * <p>Configuration is stored in {@link CallOptions} and is passed to the {@link Channel} when
+ * performing an RPC.
  *
  * @since 1.0.0
  * @param <S> the concrete type of this stub.
  */
+@ThreadSafe
 public abstract class AbstractStub<S extends AbstractStub<S>> {
   private final Channel channel;
   private final CallOptions callOptions;
diff --git a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
index 67003181a..e92ef278d 100644
--- a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
@@ -54,8 +54,10 @@ import io.grpc.ExperimentalApi;
 public abstract class CallStreamObserver<V> implements StreamObserver<V> {
 
   /**
-   * If {@code true} indicates that a call to {@link #onNext(Object)} will not require the entire
-   * message to be buffered before it is sent to the peer.
+   * If {@code true}, indicates that the observer is capable of sending additional messages
+   * without requiring excessive buffering internally. This value is just a suggestion and the
+   * application is free to ignore it, however doing so may result in excessive buffering within the
+   * observer.
    */
   public abstract boolean isReady();