Add comments

gax-grpc/src/main/java/com/google/api/gax/grpc/RefreshingManagedChannel.java

@@ -44,7 +44,8 @@
 import org.threeten.bp.Duration;
 
 /**
- * A {@link ManagedChannel} that will self refresh the underlying channel so the server
+ * A {@link ManagedChannel} that will refresh the underlying channel by swapping the underlying
+ * channel with a new one periodically
  *
  * <p>Package-private for internal use.
  */

gax-grpc/src/main/java/com/google/api/gax/grpc/SafeShutdownManagedChannel.java

@@ -42,7 +42,10 @@
 
 /**
  * A {@link ManagedChannel} that will complete all calls started on the underlying channel before
- * shutting down
+ * shutting down.
+ *
+ * This class is not thread-safe. Caller must synchronize in order to ensure no new calls if safe
+ * shutdown has started.
  *
  * <p>Package-private for internal use.
  */
@@ -56,8 +59,8 @@ class SafeShutdownManagedChannel extends ManagedChannel {
   }
 
   /**
-   * Safely shutdown channel by checking that there are no more outstanding calls If there are
-   * outstanding calls, the calls will call this function again when they complete
+   * Safely shutdown channel by checking that there are no more outstanding calls. If there are
+   * outstanding calls, the last call will invoke this method again when it complete
    */
   void shutdownSafely() {
     isShutdownSafely = true;