More Doxygen comment improvements.

include/grpc++/create_channel.h

@@ -43,23 +43,25 @@
 
 namespace grpc {
 
-/// Create a new \a Channel pointing to \a target
+/// Create a new \a Channel pointing to \a target.
 ///
 /// \param target The URI of the endpoint to connect to.
-/// \param creds Credentials to use for the created channel. If it does not hold
-/// an object or is invalid, a lame channel is returned.
+/// \param creds Credentials to use for the created channel. If it does not
+/// hold an object or is invalid, a lame channel (one on which all operations
+/// fail) is returned.
 std::shared_ptr<Channel> CreateChannel(
     const grpc::string& target,
     const std::shared_ptr<ChannelCredentials>& creds);
 
-/// Create a new \em custom \a Channel pointing to \a target
+/// Create a new \em custom \a Channel pointing to \a target.
 ///
 /// \warning For advanced use and testing ONLY. Override default channel
 /// arguments only if necessary.
 ///
 /// \param target The URI of the endpoint to connect to.
-/// \param creds Credentials to use for the created channel. If it does not hold
-/// an object or is invalid, a lame channel is returned.
+/// \param creds Credentials to use for the created channel. If it does not
+/// hold an object or is invalid, a lame channel (one on which all operations
+/// fail) is returned.
 /// \param args Options for channel creation.
 std::shared_ptr<Channel> CreateCustomChannel(
     const grpc::string& target,

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

@@ -331,8 +331,9 @@ class ClientContext {
     return census_context_;
   }
 
-  /// Send a best-effort out-of-band cancel. The call could be in any stage.
-  /// e.g. if it is already finished, it may still return success.
+  /// Send a best-effort out-of-band cancel on the call associated with
+  /// this client context.  The call could be in any stage; e.g., if it is
+  /// already finished, it may still return success.
   ///
   /// There is no guarantee the call will be cancelled.
   void TryCancel();

include/grpc++/security/auth_metadata_processor.h

@@ -42,6 +42,9 @@
 
 namespace grpc {
 
+/// Interface allowing custom server-side authorization based on credentials
+/// encoded in metadata.  Objects of this type can be passed to
+/// \a ServerCredentials::SetAuthMetadataProcessor().
 class AuthMetadataProcessor {
  public:
   typedef std::multimap<grpc::string_ref, grpc::string_ref> InputMetadata;

include/grpc++/server.h

@@ -67,7 +67,7 @@ class Server final : public ServerInterface, private GrpcLibraryCodegen {
  public:
   ~Server();
 
-  /// Block waiting for all work to complete.
+  /// Block until the server shuts down.
   ///
   /// \warning The server must be either shutting down or some other thread must
   /// call \a Shutdown for this function to ever return.

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