Merge pull request #6895 from dgquintas/async_docs_fixit

Added docs to server's shutdown docstrings

include/grpc++/impl/codegen/server_interface.h

@@ -62,6 +62,10 @@ class ServerInterface : public CallHook {
   /// Shutdown the server, blocking until all rpc processing finishes.
   /// Forcefully terminate pending calls after \a deadline expires.
   ///
+  /// All completion queue associated with the server (for example, for async
+  /// serving) must be shutdown *after* this method has returned:
+  /// See \a ServerBuilder::AddCompletionQueue for details.
+  ///
   /// \param deadline How long to wait until pending rpcs are forcefully
   /// terminated.
   template <class T>
@@ -70,6 +74,10 @@ class ServerInterface : public CallHook {
   }
 
   /// Shutdown the server, waiting for all rpc processing to finish.
+  ///
+  /// All completion queue associated with the server (for example, for async
+  /// serving) must be shutdown *after* this method has returned:
+  /// See \a ServerBuilder::AddCompletionQueue for details.
   void Shutdown() { ShutdownInternal(gpr_inf_future(GPR_CLOCK_MONOTONIC)); }
 
   /// Block waiting for all work to complete.

include/grpc++/server_builder.h

@@ -119,9 +119,20 @@ class ServerBuilder {
                                   std::shared_ptr<ServerCredentials> creds,
                                   int* selected_port = nullptr);
 
-  /// Add a completion queue for handling asynchronous services
+  /// Add a completion queue for handling asynchronous services.
-  /// Caller is required to keep this completion queue live until
+  ///
-  /// the server is destroyed.
+  /// Caller is required to shutdown the server prior to shutting down the
+  /// returned completion queue. A typical usage scenario:
+  ///
+  /// // While building the server:
+  /// ServerBuilder builder;
+  /// ...
+  /// cq_ = builder.AddCompletionQueue();
+  /// server_ = builder.BuildAndStart();
+  ///
+  /// // While shutting down the server;
+  /// server_->Shutdown();
+  /// cq_->Shutdown();  // Always *after* the associated server's Shutdown()!
   ///
   /// \param is_frequently_polled This is an optional parameter to inform GRPC
   /// library about whether this completion queue would be frequently polled