Improve documentation

1 files changed, 11 insertions, 5 deletions

diff --git a/include/grpcpp/impl/codegen/client_interceptor.h b/include/grpcpp/impl/codegen/client_interceptor.h
index f44a7c469c..bc62bb4a7b 100644
--- a/include/grpcpp/impl/codegen/client_interceptor.h
+++ b/include/grpcpp/impl/codegen/client_interceptor.h
@@ -108,11 +108,17 @@ class ClientRpcInfo {
   friend class grpc::ClientContext;
 };
 
-// DO NOT USE THIS
-// Registers a global client interceptor factory object. This should be
-// registered before any channels are created. The application is responsible
-// for maintaining the life of the object while gRPC is used. It is unsafe to
-// try to register if gRPC operations have already started.
+// PLEASE DO NOT USE THIS. ALWAYS PREFER PER CHANNEL INTERCEPTORS OVER A GLOBAL
+// INTERCEPTOR. IF USAGE IS ABSOLUTELY NECESSARY, PLEASE READ THE SAFETY NOTES.
+// Registers a global client interceptor factory object, which is used for all
+// RPCs made in this process.  If the argument is nullptr, the global
+// interceptor factory is deregistered. The application is responsible for
+// maintaining the life of the object while gRPC operations are in progress. It
+// is unsafe to try to register/deregister if any gRPC operation is in progress.
+// For safety, it is in the best interests of the developer to register the
+// global interceptor factory once at the start of the process before any gRPC
+// operations have begun. Deregistration is optional since gRPC does not
+// maintain any references to the object.
 void RegisterGlobalClientInterceptorFactory(
     ClientInterceptorFactoryInterface* factory);