From 257bb546fd54d1a16b81dba632632d786070ec35 Mon Sep 17 00:00:00 2001
From: Eric Anderson <ejona@google.com>
Date: Fri, 3 May 2019 09:36:15 -0700
Subject: [PATCH] api: Discourage using ClientInterceptor for credentials

---
 api/src/main/java/io/grpc/ClientInterceptor.java | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/api/src/main/java/io/grpc/ClientInterceptor.java b/api/src/main/java/io/grpc/ClientInterceptor.java
index b01133a952..6cb0c2420f 100644
--- a/api/src/main/java/io/grpc/ClientInterceptor.java
+++ b/api/src/main/java/io/grpc/ClientInterceptor.java
@@ -24,10 +24,14 @@ import javax.annotation.concurrent.ThreadSafe;
  * <p>Implementers use this mechanism to add cross-cutting behavior to {@link Channel} and
  * stub implementations. Common examples of such behavior include:
  * <ul>
- * <li>Adding credentials to header metadata</li>
  * <li>Logging and monitoring call behavior</li>
+ * <li>Adding metadata for proxies to observe</li>
  * <li>Request and response rewriting</li>
  * </ul>
+ *
+ * <p>Providing authentication credentials is better served by {@link
+ * CallCredentials}. But a {@code ClientInterceptor} could set the {@code
+ * CallCredentials} within the {@link CallOptions}.
  */
 @ThreadSafe
 public interface ClientInterceptor {