1 files changed, 53 insertions, 12 deletions

diff --git a/include/grpc++/server.h b/include/grpc++/server.h
index 22d14ee652..18a8017880 100644
--- a/include/grpc++/server.h
+++ b/include/grpc++/server.h
@@ -57,24 +57,30 @@ class RpcServiceMethod;
 class ServerAsyncStreamingInterface;
 class ThreadPoolInterface;
 
-// Currently it only supports handling rpcs in a single thread.
+/// Models a gRPC server.
+///
+/// Servers are configured and started via \a grpc::ServerBuilder.
 class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
  public:
   ~Server();
 
-  // Shutdown the server, block until all rpc processing finishes.
-  // Forcefully terminate pending calls after deadline expires.
+  /// Shutdown the server, blocking until all rpc processing finishes.
+  /// Forcefully terminate pending calls after \a deadline expires.
+  ///
+  /// \param deadline How long to wait until pending rpcs are forcefully
+  /// terminated.
   template <class T>
   void Shutdown(const T& deadline) {
     ShutdownInternal(TimePoint<T>(deadline).raw_time());
   }
 
-  // Shutdown the server, waiting for all rpc processing to finish.
+  /// Shutdown the server, waiting for all rpc processing to finish.
   void Shutdown() { ShutdownInternal(gpr_inf_future(GPR_CLOCK_MONOTONIC)); }
 
-  // Block waiting for all work to complete (the server must either
-  // be shutting down or some other thread must call Shutdown for this
-  // function to ever return)
+  /// Block waiting for all work to complete.
+  ///
+  /// \warning The server must be either shutting down or some other thread must
+  /// call \a Shutdown for this function to ever return.
   void Wait();
 
  private:
@@ -86,22 +92,57 @@ class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
   class AsyncRequest;
   class ShutdownRequest;
 
-  // ServerBuilder use only
+  /// Server constructors. To be used by \a ServerBuilder only.
+  ///
+  /// \param thread_pool The threadpool instance to use for call processing.
+  /// \param thread_pool_owned Does the server own the \a thread_pool instance?
+  /// \param max_message_size Maximum message length that the channel can
+  /// receive.
   Server(ThreadPoolInterface* thread_pool, bool thread_pool_owned,
          int max_message_size);
-  // Register a service. This call does not take ownership of the service.
-  // The service must exist for the lifetime of the Server instance.
+
+  /// Register a service. This call does not take ownership of the service.
+  /// The service must exist for the lifetime of the Server instance.
   bool RegisterService(const grpc::string* host, RpcService* service);
+
+  /// Register an asynchronous service. This call does not take ownership of the
+  /// service. The service must exist for the lifetime of the Server instance.
   bool RegisterAsyncService(const grpc::string* host,
                             AsynchronousService* service);
+
+  /// Register a generic service. This call does not take ownership of the
+  /// service. The service must exist for the lifetime of the Server instance.
   void RegisterAsyncGenericService(AsyncGenericService* service);
-  // Add a listening port. Can be called multiple times.
+
+  /// Tries to bind \a server to the given \a addr.
+  ///
+  /// 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.
+  ///
+  /// \return bound port number on sucess, 0 on failure.
+  ///
+  /// \warning It's an error to call this method on an already started server.
   int AddListeningPort(const grpc::string& addr, ServerCredentials* creds);
-  // Start the server.
+
+  /// Start the server.
+  ///
+  /// \param cqs Completion queues for handling asynchronous services. The
+  /// caller is required to keep all completion queues live until the server is
+  /// destroyed.
+  /// \param num_cqs How many completion queues does \a cqs hold.
+  ///
+  /// \return true on a successful shutdown.
   bool Start(ServerCompletionQueue** cqs, size_t num_cqs);
 
   void HandleQueueClosed();
+
+  /// Process one or more incoming calls.
   void RunRpc();
+
+  /// Schedule \a RunRpc to run in the threadpool.
   void ScheduleCallback();
 
   void PerformOpsOnCall(CallOpSetInterface* ops, Call* call) GRPC_OVERRIDE;