Merge pull request #10991 from mehrdada/cpp-doc-fixes

C++ Documentation Audit Fixes 

18 files changed, 89 insertions, 74 deletions

diff --git a/include/grpc++/create_channel.h b/include/grpc++/create_channel.h
index 0537695ed2..669711531f 100644
--- a/include/grpc++/create_channel.h
+++ b/include/grpc++/create_channel.h
@@ -43,7 +43,7 @@
 
 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
@@ -52,7 +52,7 @@ 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.
diff --git a/include/grpc++/create_channel_posix.h b/include/grpc++/create_channel_posix.h
index 2af12e6c36..cb323a2f24 100644
--- a/include/grpc++/create_channel_posix.h
+++ b/include/grpc++/create_channel_posix.h
@@ -44,7 +44,7 @@ namespace grpc {
 
 #ifdef GPR_SUPPORT_CHANNELS_FROM_FD
 
-/// Create a new \a Channel communicating over given file descriptor
+/// Create a new \a Channel communicating over the given file descriptor.
 ///
 /// \param target The name of the target.
 /// \param fd The file descriptor representing a socket.
@@ -52,7 +52,7 @@ std::shared_ptr<Channel> CreateInsecureChannelFromFd(const grpc::string& target,
                                                      int fd);
 
 /// Create a new \a Channel communicating over given file descriptor with custom
-/// channel arguments
+/// channel arguments.
 ///
 /// \param target The name of the target.
 /// \param fd The file descriptor representing a socket.
diff --git a/include/grpc++/ext/health_check_service_server_builder_option.h b/include/grpc++/ext/health_check_service_server_builder_option.h
index a27841af01..9da8e91cd5 100644
--- a/include/grpc++/ext/health_check_service_server_builder_option.h
+++ b/include/grpc++/ext/health_check_service_server_builder_option.h
@@ -44,7 +44,7 @@ namespace grpc {
 
 class HealthCheckServiceServerBuilderOption : public ServerBuilderOption {
  public:
-  /// The ownership of hc will be taken and transferred to the grpc server.
+  /// The ownership of \a hc will be taken and transferred to the grpc server.
   /// To explicitly disable default service, pass in a nullptr.
   explicit HealthCheckServiceServerBuilderOption(
       std::unique_ptr<HealthCheckServiceInterface> hc);
diff --git a/include/grpc++/ext/proto_server_reflection_plugin.h b/include/grpc++/ext/proto_server_reflection_plugin.h
index 6497bba905..f4a0eec986 100644
--- a/include/grpc++/ext/proto_server_reflection_plugin.h
+++ b/include/grpc++/ext/proto_server_reflection_plugin.h
@@ -59,8 +59,8 @@ class ProtoServerReflectionPlugin : public ::grpc::ServerBuilderPlugin {
   std::shared_ptr<grpc::ProtoServerReflection> reflection_service_;
 };
 
-/// Add proto reflection plugin to ServerBuilder. This function should be called
-/// at the static initialization time.
+/// Add proto reflection plugin to \a ServerBuilder.
+/// This function should be called at the static initialization time.
 void InitProtoReflectionServerBuilderPlugin();
 
 }  // namespace reflection
diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h
index 978b172346..d6c3e2e768 100644
--- a/include/grpc++/grpc++.h
+++ b/include/grpc++/grpc++.h
@@ -76,6 +76,7 @@
 // IWYU pragma: end_exports
 
 namespace grpc {
+/// Return gRPC library version.
 grpc::string Version();
 }  // namespace grpc
 
diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h
index c1b43199a6..bdc4ed76ef 100644
--- a/include/grpc++/health_check_service_interface.h
+++ b/include/grpc++/health_check_service_interface.h
@@ -47,7 +47,7 @@ class HealthCheckServiceInterface {
  public:
   virtual ~HealthCheckServiceInterface() {}
 
-  /// Set or change the serving status of the given service_name.
+  /// Set or change the serving status of the given \a service_name.
   virtual void SetServingStatus(const grpc::string& service_name,
                                 bool serving) = 0;
   /// Apply to all registered service names.
diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h
index b1b9be0fe2..b03715e70c 100644
--- a/include/grpc++/impl/codegen/client_context.h
+++ b/include/grpc++/impl/codegen/client_context.h
@@ -307,7 +307,7 @@ class ClientContext {
 
   /// Flag whether the initial metadata should be \a corked
   ///
-  /// If \a corked is true, then the initial metadata will be colasced with the
+  /// If \a corked is true, then the initial metadata will be coalesced with the
   /// write of first message in the stream.
   ///
   /// \param corked The flag indicating whether the initial metadata is to be
diff --git a/include/grpc++/resource_quota.h b/include/grpc++/resource_quota.h
index 1199ae9381..fab2b4c6e4 100644
--- a/include/grpc++/resource_quota.h
+++ b/include/grpc++/resource_quota.h
@@ -42,9 +42,10 @@ struct grpc_resource_quota;
 namespace grpc {
 
 /// ResourceQuota represents a bound on memory usage by the gRPC library.
-/// A ResourceQuota can be attached to a server (via ServerBuilder), or a client
-/// channel (via ChannelArguments). gRPC will attempt to keep memory used by
-/// all attached entities below the ResourceQuota bound.
+/// A ResourceQuota can be attached to a server (via \a ServerBuilder),
+/// or a client channel (via \a ChannelArguments).
+/// gRPC will attempt to keep memory used by all attached entities
+/// below the ResourceQuota bound.
 class ResourceQuota final : private GrpcLibraryCodegen {
  public:
   /// \param name - a unique name for this ResourceQuota.
@@ -52,10 +53,10 @@ class ResourceQuota final : private GrpcLibraryCodegen {
   ResourceQuota();
   ~ResourceQuota();
 
-  /// Resize this ResourceQuota to a new size. If new_size is smaller than the
-  /// current size of the pool, memory usage will be monotonically decreased
-  /// until it falls under new_size. No time bound is given for this to occur
-  /// however.
+  /// Resize this \a ResourceQuota to a new size. If \a new_size is smaller
+  /// than the current size of the pool, memory usage will be monotonically
+  /// decreased until it falls under \a new_size.
+  /// No time bound is given for this to occur however.
   ResourceQuota& Resize(size_t new_size);
 
   grpc_resource_quota* c_resource_quota() const { return impl_; }
diff --git a/include/grpc++/security/auth_metadata_processor.h b/include/grpc++/security/auth_metadata_processor.h
index 3536923146..18e8a47515 100644
--- a/include/grpc++/security/auth_metadata_processor.h
+++ b/include/grpc++/security/auth_metadata_processor.h
@@ -49,7 +49,7 @@ class AuthMetadataProcessor {
 
   virtual ~AuthMetadataProcessor() {}
 
-  /// If this method returns true, the Process function will be scheduled in
+  /// If this method returns true, the \a Process function will be scheduled in
   /// a different thread from the one processing the call.
   virtual bool IsBlocking() const { return true; }
 
diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h
index 8d9d181fde..46cc96eca3 100644
--- a/include/grpc++/security/credentials.h
+++ b/include/grpc++/security/credentials.h
@@ -151,7 +151,7 @@ std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
 /// json_key is the JSON key string containing the client's private key.
 /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
 /// (JWT) created with this credentials. It should not exceed
-/// grpc_max_auth_token_lifetime or will be cropped to this value.
+/// \a grpc_max_auth_token_lifetime or will be cropped to this value.
 std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
     const grpc::string& json_key, long token_lifetime_seconds);
 
diff --git a/include/grpc++/security/server_credentials.h b/include/grpc++/security/server_credentials.h
index 4676b04c5d..d7720e41e5 100644
--- a/include/grpc++/security/server_credentials.h
+++ b/include/grpc++/security/server_credentials.h
@@ -70,7 +70,7 @@ class ServerCredentials {
 
 /// Options to create ServerCredentials with SSL
 struct SslServerCredentialsOptions {
-  /// Deprecated
+  /// \warning Deprecated
   SslServerCredentialsOptions()
       : force_client_auth(false),
         client_certificate_request(GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE) {}
@@ -84,12 +84,13 @@ struct SslServerCredentialsOptions {
   };
   grpc::string pem_root_certs;
   std::vector<PemKeyCertPair> pem_key_cert_pairs;
-  /// Deprecated
+  /// \warning Deprecated
   bool force_client_auth;
 
-  /// If both force_client_auth and client_certificate_request fields are set,
-  /// force_client_auth takes effect i.e
-  /// REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY will be enforced.
+  /// If both \a force_client_auth and \a client_certificate_request
+  /// fields are set, \a force_client_auth takes effect, i.e.
+  /// \a REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY
+  /// will be enforced.
   grpc_ssl_client_certificate_request_type client_certificate_request;
 };
 
diff --git a/include/grpc++/server.h b/include/grpc++/server.h
index 2f7018e95b..85a7300820 100644
--- a/include/grpc++/server.h
+++ b/include/grpc++/server.h
@@ -60,9 +60,10 @@ class HealthCheckServiceInterface;
 class ServerContext;
 class ServerInitializer;
 
-/// Models a gRPC server.
+/// Represents a gRPC server.
 ///
-/// Servers are configured and started via \a grpc::ServerBuilder.
+/// Use a \a grpc::ServerBuilder to create, configure, and start
+/// \a Server instances.
 class Server final : public ServerInterface, private GrpcLibraryCodegen {
  public:
   ~Server();
@@ -73,10 +74,12 @@ class Server final : public ServerInterface, private GrpcLibraryCodegen {
   /// call \a Shutdown for this function to ever return.
   void Wait() override;
 
-  /// Global Callbacks
-  ///
-  /// Can be set exactly once per application to install hooks whenever
-  /// a server event occurs
+  /// Global callbacks are a set of hooks that are called when server
+  /// events occur.  \a SetGlobalCallbacks method is used to register
+  /// the hooks with gRPC.  Note that
+  /// the \a GlobalCallbacks instance will be shared among all
+  /// \a Server instances in an application and can be set exactly
+  /// once per application.
   class GlobalCallbacks {
    public:
     virtual ~GlobalCallbacks() {}
@@ -92,12 +95,14 @@ class Server final : public ServerInterface, private GrpcLibraryCodegen {
     virtual void AddPort(Server* server, const grpc::string& addr,
                          ServerCredentials* creds, int port) {}
   };
-  /// Set the global callback object. Can only be called once. Does not take
-  /// ownership of callbacks, and expects the pointed to object to be alive
-  /// until all server objects in the process have been destroyed.
+  /// Set the global callback object. Can only be called once per application.
+  /// Does not take ownership of callbacks, and expects the pointed to object
+  /// to be alive until all server objects in the process have been destroyed.
+  /// The same \a GlobalCallbacks object will be used throughout the
+  /// application and is shared among all \a Server objects.
   static void SetGlobalCallbacks(GlobalCallbacks* callbacks);
 
-  // Returns a \em raw pointer to the underlying grpc_server instance.
+  // Returns a \em raw pointer to the underlying \a grpc_server instance.
   grpc_server* c_server();
 
   /// Returns the health check service.
@@ -158,17 +163,19 @@ class Server final : public ServerInterface, private GrpcLibraryCodegen {
   /// service. The service must exist for the lifetime of the Server instance.
   void RegisterAsyncGenericService(AsyncGenericService* service) override;
 
-  /// Tries to bind \a server to the given \a addr.
+  /// Try binding the server to the given \a addr endpoint
+  /// (port, and optionally including IP address to bind to).
   ///
-  /// It can be invoked multiple times.
+  /// It can be invoked multiple times. Should be used before
+  /// starting the server.
   ///
   /// \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.
+  /// \return bound port number on success, 0 on failure.
   ///
-  /// \warning It's an error to call this method on an already started server.
+  /// \warning It is an error to call this method on an already started server.
   int AddListeningPort(const grpc::string& addr,
                        ServerCredentials* creds) override;
 
@@ -194,13 +201,14 @@ class Server final : public ServerInterface, private GrpcLibraryCodegen {
 
   const int max_receive_message_size_;
 
-  /// The following completion queues are ONLY used in case of Sync API i.e if
-  /// the server has any services with sync methods. The server uses these
-  /// completion queues to poll for new RPCs
+  /// The following completion queues are ONLY used in case of Sync API
+  /// i.e. if the server has any services with sync methods. The server uses
+  /// these completion queues to poll for new RPCs
   std::shared_ptr<std::vector<std::unique_ptr<ServerCompletionQueue>>>
       sync_server_cqs_;
 
-  /// List of ThreadManager instances (one for each cq in the sync_server_cqs)
+  /// List of \a ThreadManager instances (one for each cq in
+  /// the \a sync_server_cqs)
   std::vector<std::unique_ptr<SyncRequestThreadManager>> sync_req_mgrs_;
 
   // Sever status
diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h
index 2185b283ac..8bedef5899 100644
--- a/include/grpc++/server_builder.h
+++ b/include/grpc++/server_builder.h
@@ -85,7 +85,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 +110,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 +139,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 +171,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 +209,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 +241,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_;
diff --git a/include/grpc++/server_posix.h b/include/grpc++/server_posix.h
index e6066d4eaa..a8fe8cb3d1 100644
--- a/include/grpc++/server_posix.h
+++ b/include/grpc++/server_posix.h
@@ -43,9 +43,10 @@ namespace grpc {
 
 #ifdef GPR_SUPPORT_CHANNELS_FROM_FD
 
-/// Adds new client to a \a Server communicating over given file descriptor
+/// Add a new client to a \a Server communicating over the given
+/// file descriptor.
 ///
-/// \param server The server to add a client to.
+/// \param server The server to add the client to.
 /// \param fd The file descriptor representing a socket.
 void AddInsecureChannelFromFd(Server* server, int fd);
 
diff --git a/include/grpc++/support/channel_arguments.h b/include/grpc++/support/channel_arguments.h
index 61307d6194..061ab55138 100644
--- a/include/grpc++/support/channel_arguments.h
+++ b/include/grpc++/support/channel_arguments.h
@@ -49,7 +49,7 @@ class ChannelArgumentsTest;
 class ResourceQuota;
 
 /// Options for channel creation. The user can use generic setters to pass
-/// key value pairs down to c channel creation code. For grpc related options,
+/// key value pairs down to C channel creation code. For gRPC related options,
 /// concrete setters are provided.
 class ChannelArguments {
  public:
@@ -82,13 +82,13 @@ class ChannelArguments {
   /// Set the socket mutator for the channel.
   void SetSocketMutator(grpc_socket_mutator* mutator);
 
-  /// The given string will be sent at the front of the user agent string.
+  /// Set the string to prepend to the user agent.
   void SetUserAgentPrefix(const grpc::string& user_agent_prefix);
 
-  /// The given buffer pool will be attached to the constructed channel
+  /// Set the buffer pool to be attached to the constructed channel.
   void SetResourceQuota(const ResourceQuota& resource_quota);
 
-  /// Sets the max receive and send message sizes.
+  /// Set the max receive and send message sizes.
   void SetMaxReceiveMessageSize(int size);
   void SetMaxSendMessageSize(int size);
 
@@ -115,8 +115,8 @@ class ChannelArguments {
   /// Set a textual argument \a value under \a key.
   void SetString(const grpc::string& key, const grpc::string& value);
 
-  /// Return (by value) a c grpc_channel_args structure which points to
-  /// arguments owned by this ChannelArguments instance
+  /// Return (by value) a C \a grpc_channel_args structure which points to
+  /// arguments owned by this \a ChannelArguments instance
   grpc_channel_args c_channel_args() const {
     grpc_channel_args out;
     out.num_args = args_.size();
diff --git a/include/grpc++/support/error_details.h b/include/grpc++/support/error_details.h
index d4324d35cf..4f5176228c 100644
--- a/include/grpc++/support/error_details.h
+++ b/include/grpc++/support/error_details.h
@@ -44,16 +44,16 @@ class Status;
 
 namespace grpc {
 
-/// Maps a grpc::Status to a google::rpc::Status.
+/// Map a \a grpc::Status to a \a google::rpc::Status.
 /// The given \a to object will be cleared.
 /// On success, returns status with OK.
-/// Returns status with INVALID_ARGUMENT, if failed to deserialize.
-/// Returns status with FAILED_PRECONDITION, if \a to is nullptr.
+/// Returns status with \a INVALID_ARGUMENT, if failed to deserialize.
+/// Returns status with \a FAILED_PRECONDITION, if \a to is nullptr.
 Status ExtractErrorDetails(const Status& from, ::google::rpc::Status* to);
 
-/// Maps google::rpc::Status to a grpc::Status.
+/// Map \a google::rpc::Status to a \a grpc::Status.
 /// Returns OK on success.
-/// Returns status with FAILED_PRECONDITION if \a to is nullptr.
+/// Returns status with \a FAILED_PRECONDITION if \a to is nullptr.
 Status SetErrorDetails(const ::google::rpc::Status& from, Status* to);
 
 }  // namespace grpc
diff --git a/include/grpc++/support/slice.h b/include/grpc++/support/slice.h
index 3ec0d1af80..e2bd211413 100644
--- a/include/grpc++/support/slice.h
+++ b/include/grpc++/support/slice.h
@@ -48,7 +48,7 @@ class Slice final {
  public:
   /// Construct an empty slice.
   Slice();
-  // Destructor - drops one reference.
+  /// Destructor - drops one reference.
   ~Slice();
 
   enum AddRef { ADD_REF };
diff --git a/include/grpc++/test/server_context_test_spouse.h b/include/grpc++/test/server_context_test_spouse.h
index 5bd07e7aec..80edd5622b 100644
--- a/include/grpc++/test/server_context_test_spouse.h
+++ b/include/grpc++/test/server_context_test_spouse.h
@@ -47,7 +47,7 @@ class ServerContextTestSpouse {
   explicit ServerContextTestSpouse(ServerContext* ctx) : ctx_(ctx) {}
 
   /// Inject client metadata to the ServerContext for the test. The test spouse
-  /// must be alive when ServerContext::client_metadata is called.
+  /// must be alive when \a ServerContext::client_metadata is called.
   void AddClientMetadata(const grpc::string& key, const grpc::string& value) {
     client_metadata_storage_.insert(
         std::pair<grpc::string, grpc::string>(key, value));
@@ -70,7 +70,7 @@ class ServerContextTestSpouse {
   }
 
  private:
-  ServerContext* ctx_;  /// not owned
+  ServerContext* ctx_;  // not owned
   std::multimap<grpc::string, grpc::string> client_metadata_storage_;
 };