diff --git a/core/src/main/java/io/grpc/Metadata.java b/core/src/main/java/io/grpc/Metadata.java
index 41ad08e82c..23a77f1691 100644
--- a/core/src/main/java/io/grpc/Metadata.java
+++ b/core/src/main/java/io/grpc/Metadata.java
@@ -287,6 +287,15 @@ public abstract class Metadata {
       return authority;
     }
 
+    /**
+     * Override the HTTP/2 authority the channel claims to be connecting to. <em>This is not
+     * generally safe.</em> Overriding allows advanced users to re-use a single Channel for multiple
+     * services, even if those services are hosted on different domain names. That assumes the
+     * server is virtually hosting multiple domains and is guaranteed to continue doing so. It is
+     * rare for a service provider to make such a guarantee. <em>At this time, there is no security
+     * verification of the overridden value, such as making sure the authority matches the server's
+     * TLS certificate.</em>
+     */
     public void setAuthority(String authority) {
       this.authority = authority;
     }