format changes, address comments

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

@@ -70,9 +70,8 @@ class ClientAsyncStreamingInterface {
   ///     \a ClientAsyncReaderWriterInterface::WritesDone).
   ///   * there are no more messages to be received from the server (this can
   ///     be known implicitly by the calling code, or explicitly from an
-  ///     earlier call to \a AsyncReaderInterface::Read that
-  ///     yielded a failed result
-  ///     , e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
+  ///     earlier call to \a AsyncReaderInterface::Read that yielded a failed
+  ///     result, e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
   ///
   /// This function will return when either:
   /// - all incoming messages have been read and the server has returned
@@ -814,9 +813,8 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface,
   ///   * it is desired to end the call early with some non-OK status code.
   ///
   /// This operation will end when the server has finished sending out initial
-  /// metadata
-  /// (if not sent already), response message, and status, or if some failure
-  /// occurred when trying to do so.
+  /// metadata (if not sent already), response message, and status, or if some
+  /// failure occurred when trying to do so.
   ///
   /// \param[in] tag Tag identifying this request.
   /// \param[in] status To be sent to the client as the result of this call.

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

@@ -47,6 +47,8 @@ namespace grpc {
 class CompletionQueue;
 extern CoreCodegenInterface* g_core_codegen_interface;
 
+/// An interface relevant for async client side unary RPCS (which send
+/// one request message to a server and receive one response message).
 template <class R>
 class ClientAsyncResponseReaderInterface {
  public:

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

@@ -192,8 +192,8 @@ class ClientContext {
   ///
   /// \param meta_key The metadata key. If \a meta_value is binary data, it must
   /// end in "-bin".
-  /// \param meta_value The metadata value. If its value is binary, it must be
-  /// end in "-bin".
+  /// \param meta_value The metadata value. If its value is binary, the key name
+  /// must end in "-bin".
   void AddMetadata(const grpc::string& meta_key,
                    const grpc::string& meta_value);
 
@@ -249,7 +249,7 @@ class ClientContext {
 
   /// EXPERIMENTAL: Trigger wait-for-ready or not on this request.
   /// See https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md.
-  /// If set, if an RPC made when a channel's connectivity state is
+  /// If set, if an RPC is made when a channel's connectivity state is
   /// TRANSIENT_FAILURE or CONNECTING, the call will not "fail fast",
   /// and the channel will wait until the channel is READY before making the
   /// call.

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

@@ -127,10 +127,10 @@ class ServerContext {
   /// to the client (which can happen explicitly, or implicitly when sending a
   /// a response message or status to the client).
   ///
-  /// \param meta_key The metadata key. If \a meta_value is binary data,
-  /// it must end in "-bin".
-  /// \param meta_value The metadata value. If its value is binary,
-  /// it must be must end in "-bin".
+  /// \param meta_key The metadata key. If \a meta_value is binary data, it must
+  /// end in "-bin".
+  /// \param meta_value The metadata value. If its value is binary, the key name
+  /// must end in "-bin".
   void AddInitialMetadata(const grpc::string& key, const grpc::string& value);
 
   /// Add the (\a meta_key, \a meta_value) pair to the initial metadata
@@ -143,8 +143,8 @@ class ServerContext {
   ///
   /// \param meta_key The metadata key. If \a meta_value is binary data,
   /// it must end in "-bin".
-  /// \param meta_value The metadata value. If its value is binary,
-  /// it must be end in "-bin".
+  /// \param meta_value The metadata value. If its value is binary, the key name
+  /// must end in "-bin".
   void AddTrailingMetadata(const grpc::string& key, const grpc::string& value);
 
   /// IsCancelled is always safe to call when using sync API.
@@ -153,7 +153,7 @@ class ServerContext {
   bool IsCancelled() const;
 
   /// Cancel the Call from the server. This is a best-effort API and
-  /// depending :on when it is called, the RPC may still appear successful to
+  /// depending on when it is called, the RPC may still appear successful to
   /// the client.
   /// For example, if TryCancel() is called on a separate thread, it might race
   /// with the server handler which might return success to the client before

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

@@ -136,7 +136,7 @@ enum StatusCode {
   /// The service is currently unavailable. This is a most likely a transient
   /// condition and may be corrected by retrying with a backoff.
   ///
-  /// \warning: Although data MIGHT not have been transmitted when this
+  /// \warning Although data MIGHT not have been transmitted when this
   /// status occurs, there is NOT A GUARANTEE that the server has not seen
   /// anything. So in general it is unsafe to retry on this status code
   /// if the call is non-idempotent.

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

@@ -222,8 +222,7 @@ class ClientReader final : public ClientReaderInterface<R> {
   /// Side effect:
   ///   This also receives initial metadata from the server, if not
   ///   already received (if initial metadata is received, it can be then
-  ///   accessed
-  ///   through the \a ClientContext associated with this call).
+  ///   accessed through the \a ClientContext associated with this call).
   bool Read(R* msg) override {
     CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops;
     if (!context_->initial_metadata_received_) {

include/grpc/impl/codegen/grpc_types.h

@@ -198,9 +198,8 @@ typedef struct {
 #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
   "grpc.http2.hpack_table_size.encoder"
 /** How big a frame are we willing to receive via HTTP2.
-    Min 16384, max 16777215.
-    Larger values give lower CPU usage for large messages, but more head of line
-    blocking for small messages. */
+    Min 16384, max 16777215. Larger values give lower CPU usage for large
+    messages, but more head of line blocking for small messages. */
 #define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size"
 /** Should BDP probing be performed? */
 #define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe"
@@ -210,15 +209,13 @@ typedef struct {
 /** Channel arg to override the http2 :scheme header */
 #define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
 /** How many pings can we send before needing to send a data frame or header
-    frame?
-    (0 indicates that an infinite number of pings can be sent without sending
-     a data frame or header frame) */
+    frame? (0 indicates that an infinite number of pings can be sent without
+    sending a data frame or header frame) */
 #define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
   "grpc.http2.max_pings_without_data"
 /** How many misbehaving pings the server can bear before sending goaway and
-    closing the transport?
-    (0 indicates that the server can bear an infinite number of misbehaving
-     pings) */
+    closing the transport? (0 indicates that the server can bear an infinite
+    number of misbehaving pings) */
 #define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes"
 /** Minimum allowed time between two pings without sending any data frame. Int
     valued, seconds */
@@ -260,21 +257,19 @@ typedef struct {
 /** This *should* be used for testing only.
     The caller of the secure_channel_create functions may override the target
     name used for SSL host name checking using this channel argument which is of
-    type \a GRPC_ARG_STRING.
-    If this argument is not specified, the name used for SSL host name checking
-    will be the target parameter (assuming that the secure channel is an SSL
-    channel). If this parameter is specified and the underlying is not an SSL
-    channel, it will just be ignored. */
+    type \a GRPC_ARG_STRING. If this argument is not specified, the name used
+    for SSL host name checking will be the target parameter (assuming that the
+    secure channel is an SSL channel). If this parameter is specified and the
+    underlying is not an SSL channel, it will just be ignored. */
 #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
 /** Maximum metadata size, in bytes. Note this limit applies to the max sum of
     all metadata key-value entries in a batch of headers. */
 #define GRPC_ARG_MAX_METADATA_SIZE "grpc.max_metadata_size"
 /** If non-zero, allow the use of SO_REUSEPORT if it's available (default 1) */
 #define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport"
-/** If non-zero, a pointer to a buffer pool
- * (a pointer of type grpc_resource_quota*).
-    (use grpc_resource_quota_arg_vtable() to fetch an
-    appropriate pointer arg vtable) */
+/** If non-zero, a pointer to a buffer pool (a pointer of type
+ * grpc_resource_quota*). (use grpc_resource_quota_arg_vtable() to fetch an
+ * appropriate pointer arg vtable) */
 #define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota"
 /** If non-zero, expand wildcard addresses to a list of local addresses. */
 #define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs"