Merge github.com:grpc/grpc into thread_pool

1 files changed, 27 insertions, 18 deletions

diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h
index 2185b283ac..f8b6d03e35 100644
--- a/include/grpc++/server_builder.h
+++ b/include/grpc++/server_builder.h
@@ -71,7 +71,13 @@ class ServerBuilder {
   ServerBuilder();
   ~ServerBuilder();
 
-  enum SyncServerOption { NUM_CQS, MIN_POLLERS, MAX_POLLERS, CQ_TIMEOUT_MSEC };
+  /// Options for synchronous servers.
+  enum SyncServerOption {
+    NUM_CQS,         ///< Number of completion queues.
+    MIN_POLLERS,     ///< Minimum number of polling threads.
+    MAX_POLLERS,     ///< Maximum number of polling threads.
+    CQ_TIMEOUT_MSEC  ///< Completion queue timeout in milliseconds.
+  };
 
   /// Register a service. This call does not take ownership of the service.
   /// The service must exist for the lifetime of the \a Server instance returned
@@ -85,7 +91,7 @@ class ServerBuilder {
 
   /// Register a service. This call does not take ownership of the service.
   /// The service must exist for the lifetime of the \a Server instance returned
-  /// by BuildAndStart().
+  /// by \a BuildAndStart().
   /// Only matches requests with :authority \a host
   ServerBuilder& RegisterService(const grpc::string& host, Service* service);
 
@@ -110,7 +116,7 @@ class ServerBuilder {
   /// enabled by default.
   ///
   /// Incoming calls compressed with an unsupported algorithm will fail with
-  /// GRPC_STATUS_UNIMPLEMENTED.
+  /// \a GRPC_STATUS_UNIMPLEMENTED.
   ServerBuilder& SetCompressionAlgorithmSupportStatus(
       grpc_compression_algorithm algorithm, bool enabled);
 
@@ -139,15 +145,17 @@ class ServerBuilder {
     return SetOption(MakeChannelArgumentOption(arg, value));
   }
 
-  /// Tries to bind \a server to the given \a addr.
+  /// Enlists an endpoint \a addr (port with an optional IP address) to
+  /// bind the \a grpc::Server object to be created to.
   ///
   /// It can be invoked multiple times.
   ///
   /// \param addr The address to try to bind to the server (eg, localhost:1234,
   /// 192.168.1.1:31416, [::1]:27182, etc.).
   /// \params creds The credentials associated with the server.
-  /// \param selected_port[out] Upon success, updated to contain the port
-  /// number. \a nullptr otherwise.
+  /// \param selected_port[out] If not `nullptr`, gets populated with the port
+  /// number bound to the \a grpc::Server for the corresponding endpoint after
+  /// it is successfully bound, 0 otherwise.
   ///
   // TODO(dgq): the "port" part seems to be a misnomer.
   ServerBuilder& AddListeningPort(const grpc::string& addr,
@@ -169,12 +177,13 @@ class ServerBuilder {
   /// server_->Shutdown();
   /// cq_->Shutdown();  // Always *after* the associated server's Shutdown()!
   ///
-  /// \param is_frequently_polled This is an optional parameter to inform GRPC
+  /// \param is_frequently_polled This is an optional parameter to inform gRPC
   /// library about whether this completion queue would be frequently polled
-  /// (i.e by calling Next() or AsyncNext()). The default value is 'true' and is
-  /// the recommended setting. Setting this to 'false' (i.e not polling the
-  /// completion queue frequently) will have a significantly negative
-  /// performance impact and hence should not be used in production use cases.
+  /// (i.e. by calling \a Next() or \a AsyncNext()). The default value is
+  /// 'true' and is the recommended setting. Setting this to 'false' (i.e.
+  /// not polling the completion queue frequently) will have a significantly
+  /// negative performance impact and hence should not be used in production
+  /// use cases.
   std::unique_ptr<ServerCompletionQueue> AddCompletionQueue(
       bool is_frequently_polled = true);
 
@@ -206,18 +215,18 @@ class ServerBuilder {
           max_pollers(2),
           cq_timeout_msec(10000) {}
 
-    // Number of server completion queues to create to listen to incoming RPCs.
+    /// Number of server completion queues to create to listen to incoming RPCs.
     int num_cqs;
 
-    // Minimum number of threads per completion queue that should be listening
-    // to incoming RPCs.
+    /// Minimum number of threads per completion queue that should be listening
+    /// to incoming RPCs.
     int min_pollers;
 
-    // Maximum number of threads per completion queue that can be listening to
-    // incoming RPCs.
+    /// Maximum number of threads per completion queue that can be listening to
+    /// incoming RPCs.
     int max_pollers;
 
-    // The timeout for server completion queue's AsyncNext call.
+    /// The timeout for server completion queue's AsyncNext call.
     int cq_timeout_msec;
   };
 
@@ -238,7 +247,7 @@ class ServerBuilder {
 
   SyncServerSettings sync_server_settings_;
 
-  // List of completion queues added via AddCompletionQueue() method
+  /// List of completion queues added via \a AddCompletionQueue method.
   std::vector<ServerCompletionQueue*> cqs_;
 
   std::shared_ptr<ServerCredentials> creds_;