cpp doc nits

72 files changed, 508 insertions, 479 deletions

diff --git a/doc/PROTOCOL-WEB.md b/doc/PROTOCOL-WEB.md
index 6bb280894a..5f37df9b0f 100644
--- a/doc/PROTOCOL-WEB.md
+++ b/doc/PROTOCOL-WEB.md
@@ -1,4 +1,4 @@
-# Overview
+# gRPC Web
 
 gRPC-Web provides a JS client library that supports the same API
 as gRPC-Node to access a gRPC service. Due to browser limitation,
diff --git a/doc/compression.md b/doc/compression.md
index de245d90fe..ee22bc3f12 100644
--- a/doc/compression.md
+++ b/doc/compression.md
@@ -1,4 +1,4 @@
-## **gRPC Compression**
+## gRPC Compression
 
 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be
@@ -112,7 +112,7 @@ unsupported condition as well as the supported ones. The returned
 1. An ill-constructed message with its [Compressed-Flag
 bit](PROTOCOL-HTTP2.md#compressed-flag)
 set but lacking a
-"[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)"
+[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)
 entry different from _identity_ in its metadata MUST fail with `INTERNAL`
 status, its associated description indicating the invalid Compressed-Flag
 condition.
diff --git a/doc/cpp-style-guide.md b/doc/cpp-style-guide.md
index a1f91353fe..8211703d02 100644
--- a/doc/cpp-style-guide.md
+++ b/doc/cpp-style-guide.md
@@ -5,5 +5,4 @@ The majority of gRPC's C++ requirements are drawn from the [Google C++ style
 guide] (https://google.github.io/styleguide/cppguide.html). Additionally,
 as in C, layout rules are defined by clang-format, and all code
 should be passed through clang-format. A (docker-based) script to do
-so is included in [tools/distrib/clang\_format\_code.sh]
-(../tools/distrib/clang_format_code.sh).
+so is included in [tools/distrib/clang_format_code.sh](../tools/distrib/clang_format_code.sh).
diff --git a/doc/fail_fast.md b/doc/fail_fast.md
index 2dd5561fc6..ff3d235397 100644
--- a/doc/fail_fast.md
+++ b/doc/fail_fast.md
@@ -1 +1 @@
-Moved to wait-for-ready.md
+Moved to [wait-for-ready.md](wait-for-ready.md)
diff --git a/doc/service_config.md b/doc/service_config.md
index 8039fcad09..e790180f35 100644
--- a/doc/service_config.md
+++ b/doc/service_config.md
@@ -131,8 +131,8 @@ functionality is introduced.
 
 # Architecture
 
-A service config is associated with a server name.  The [name
-resolver](naming.md) plugin, when asked to resolve a particular server
+A service config is associated with a server name.  The [nameresolver](naming.md)
+plugin, when asked to resolve a particular server
 name, will return both the resolved addresses and the service config.
 
 TODO(roth): Design how the service config will be encoded in DNS.
diff --git a/doc/stress_test_framework.md b/doc/stress_test_framework.md
index 18f545e090..2212d9842c 100644
--- a/doc/stress_test_framework.md
+++ b/doc/stress_test_framework.md
@@ -2,7 +2,7 @@
 
 (Sree Kuchibhotla - sreek@)
 
-> Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
+Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
 
 
 **I. GOALS**
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 4861daacd4..a27841af01 100644
--- a/include/grpc++/ext/health_check_service_server_builder_option.h
+++ b/include/grpc++/ext/health_check_service_server_builder_option.h
@@ -44,8 +44,8 @@ namespace grpc {
 
 class HealthCheckServiceServerBuilderOption : public ServerBuilderOption {
  public:
-  // The ownership of hc will be taken and transferred to the grpc server.
-  // To explicitly disable default service, pass in a nullptr.
+  /// The ownership of 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);
   ~HealthCheckServiceServerBuilderOption() override {}
diff --git a/include/grpc++/ext/proto_server_reflection_plugin.h b/include/grpc++/ext/proto_server_reflection_plugin.h
index 66f39eb876..6497bba905 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 ServerBuilder. This function should be called
+/// at the static initialization time.
 void InitProtoReflectionServerBuilderPlugin();
 
 }  // namespace reflection
diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h
index 02c00d0d45..3c11e55001 100644
--- a/include/grpc++/generic/generic_stub.h
+++ b/include/grpc++/generic/generic_stub.h
@@ -43,14 +43,14 @@ class CompletionQueue;
 typedef ClientAsyncReaderWriter<ByteBuffer, ByteBuffer>
     GenericClientAsyncReaderWriter;
 
-// Generic stubs provide a type-unsafe interface to call gRPC methods
-// by name.
+/// Generic stubs provide a type-unsafe interface to call gRPC methods
+/// by name.
 class GenericStub final {
  public:
   explicit GenericStub(std::shared_ptr<ChannelInterface> channel)
       : channel_(channel) {}
 
-  // begin a call to a named method
+  /// begin a call to a named method
   std::unique_ptr<GenericClientAsyncReaderWriter> Call(
       ClientContext* context, const grpc::string& method, CompletionQueue* cq,
       void* tag);
diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h
index 0eed702683..8323e9e554 100644
--- a/include/grpc++/health_check_service_interface.h
+++ b/include/grpc++/health_check_service_interface.h
@@ -41,26 +41,26 @@ namespace grpc {
 const char kHealthCheckServiceInterfaceArg[] =
     "grpc.health_check_service_interface";
 
-// The gRPC server uses this interface to expose the health checking service
-// without depending on protobuf.
+/// The gRPC server uses this interface to expose the health checking service
+/// without depending on protobuf.
 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 service_name.
   virtual void SetServingStatus(const grpc::string& service_name,
                                 bool serving) = 0;
-  // Apply to all registered service names.
+  /// Apply to all registered service names.
   virtual void SetServingStatus(bool serving) = 0;
 };
 
-// Enable/disable the default health checking service. This applies to all C++
-// servers created afterwards. For each server, user can override the default
-// with a HealthCheckServiceServerBuilderOption.
-// NOT thread safe.
+/// Enable/disable the default health checking service. This applies to all C++
+/// servers created afterwards. For each server, user can override the default
+/// with a HealthCheckServiceServerBuilderOption.
+/// NOT thread safe.
 void EnableDefaultHealthCheckService(bool enable);
 
-// NOT thread safe.
+/// NOT thread safe.
 bool DefaultHealthCheckServiceEnabled();
 
 }  // namespace grpc
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h
index f97d824baf..39f0ebd86f 100644
--- a/include/grpc++/impl/codegen/async_stream.h
+++ b/include/grpc++/impl/codegen/async_stream.h
@@ -155,7 +155,7 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> {
         ClientAsyncReader(call, context, request, tag);
   }
 
-  // always allocated against a call arena, no memory free required
+  /// always allocated against a call arena, no memory free required
   static void operator delete(void* ptr, std::size_t size) {
     assert(size == sizeof(ClientAsyncReader));
   }
@@ -235,7 +235,7 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
         ClientAsyncWriter(call, context, response, tag);
   }
 
-  // always allocated against a call arena, no memory free required
+  /// always allocated against a call arena, no memory free required
   static void operator delete(void* ptr, std::size_t size) {
     assert(size == sizeof(ClientAsyncWriter));
   }
@@ -338,7 +338,7 @@ class ClientAsyncReaderWriter final
         ClientAsyncReaderWriter(call, context, tag);
   }
 
-  // always allocated against a call arena, no memory free required
+  /// always allocated against a call arena, no memory free required
   static void operator delete(void* ptr, std::size_t size) {
     assert(size == sizeof(ClientAsyncReaderWriter));
   }
diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h
index a147a6acbf..ea2da42198 100644
--- a/include/grpc++/impl/codegen/async_unary_call.h
+++ b/include/grpc++/impl/codegen/async_unary_call.h
@@ -71,7 +71,7 @@ class ClientAsyncResponseReader final
         ClientAsyncResponseReader(call, context, request);
   }
 
-  // always allocated against a call arena, no memory free required
+  /// always allocated against a call arena, no memory free required
   static void operator delete(void* ptr, std::size_t size) {
     assert(size == sizeof(ClientAsyncResponseReader));
   }
diff --git a/include/grpc++/impl/codegen/call.h b/include/grpc++/impl/codegen/call.h
index 9fe2bbb75e..bbd0fc2dc8 100644
--- a/include/grpc++/impl/codegen/call.h
+++ b/include/grpc++/impl/codegen/call.h
@@ -634,10 +634,10 @@ class SneakyCallOpSet : public CallOpSet<Op1, Op2, Op3, Op4, Op5, Op6> {
   }
 };
 
-// Straightforward wrapping of the C call object
+/// Straightforward wrapping of the C call object
 class Call final {
  public:
-  /* call is owned by the caller */
+  /** call is owned by the caller */
   Call(grpc_call* call, CallHook* call_hook, CompletionQueue* cq)
       : call_hook_(call_hook),
         cq_(cq),
diff --git a/include/grpc++/impl/codegen/call_hook.h b/include/grpc++/impl/codegen/call_hook.h
index 6a8258233d..812c4a91e7 100644
--- a/include/grpc++/impl/codegen/call_hook.h
+++ b/include/grpc++/impl/codegen/call_hook.h
@@ -39,7 +39,8 @@ namespace grpc {
 class CallOpSetInterface;
 class Call;
 
-/// Channel and Server implement this to allow them to hook performing ops
+/// An interface that Channel and Server implement to allow them to hook
+/// performing ops
 class CallHook {
  public:
   virtual ~CallHook() {}
diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h
index 3c50e6ba9d..c17ce20186 100644
--- a/include/grpc++/impl/codegen/client_context.h
+++ b/include/grpc++/impl/codegen/client_context.h
@@ -151,6 +151,7 @@ namespace testing {
 class InteropClientContextInspector;
 }  // namespace testing
 
+/// Gives access to client side RPC configuration.
 class ClientContext {
  public:
   ClientContext();
@@ -325,8 +326,8 @@ class ClientContext {
   };
   static void SetGlobalCallbacks(GlobalCallbacks* callbacks);
 
-  // Should be used for framework-level extensions only.
-  // Applications never need to call this method.
+  /// Should be used for framework-level extensions only.
+  /// Applications never need to call this method.
   grpc_call* c_call() { return call_; }
 
  private:
diff --git a/include/grpc++/impl/codegen/client_unary_call.h b/include/grpc++/impl/codegen/client_unary_call.h
index 4bf35ae778..b923498db8 100644
--- a/include/grpc++/impl/codegen/client_unary_call.h
+++ b/include/grpc++/impl/codegen/client_unary_call.h
@@ -47,7 +47,7 @@ class ClientContext;
 class CompletionQueue;
 class RpcMethod;
 
-// Wrapper that performs a blocking unary call
+/// Wrapper that performs a blocking unary call
 template <class InputMessage, class OutputMessage>
 Status BlockingUnaryCall(ChannelInterface* channel, const RpcMethod& method,
                          ClientContext* context, const InputMessage& request,
diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h
index c8ab726b0f..57333d7158 100644
--- a/include/grpc++/impl/codegen/completion_queue.h
+++ b/include/grpc++/impl/codegen/completion_queue.h
@@ -159,7 +159,8 @@ class CompletionQueue : private GrpcLibraryCodegen {
   /// will start to return false and \a AsyncNext will return \a
   /// NextStatus::SHUTDOWN. Only once either one of these methods does that
   /// (that is, once the queue has been \em drained) can an instance of this
-  /// class be destroyed.
+  /// class be destroyed. Also note that applications must ensure that
+  /// no work is enqueued on this completion queue after this method is called.
   void Shutdown();
 
   /// Returns a \em raw pointer to the underlying \a grpc_completion_queue
diff --git a/include/grpc++/impl/codegen/completion_queue_tag.h b/include/grpc++/impl/codegen/completion_queue_tag.h
index 19a08500cf..0affc818e8 100644
--- a/include/grpc++/impl/codegen/completion_queue_tag.h
+++ b/include/grpc++/impl/codegen/completion_queue_tag.h
@@ -40,10 +40,10 @@ namespace grpc {
 class CompletionQueueTag {
  public:
   virtual ~CompletionQueueTag() {}
-  // Called prior to returning from Next(), return value is the status of the
-  // operation (return status is the default thing to do). If this function
-  // returns false, the tag is dropped and not returned from the completion
-  // queue
+  /// Called prior to returning from Next(), return value is the status of the
+  /// operation (return status is the default thing to do). If this function
+  /// returns false, the tag is dropped and not returned from the completion
+  /// queue
   virtual bool FinalizeResult(void** tag, bool* status) = 0;
 };
 
diff --git a/include/grpc++/impl/codegen/config.h b/include/grpc++/impl/codegen/config.h
index a43bf65f91..79352eee3c 100644
--- a/include/grpc++/impl/codegen/config.h
+++ b/include/grpc++/impl/codegen/config.h
@@ -39,9 +39,9 @@
 #define GRPC_CUSTOM_STRING std::string
 #endif
 
-// The following macros are deprecated and appear only for users
-// with PB files generated using gRPC 1.0.x plugins. They should
-// not be used in new code
+/// The following macros are deprecated and appear only for users
+/// with PB files generated using gRPC 1.0.x plugins. They should
+/// not be used in new code
 #define GRPC_OVERRIDE override  // deprecated
 #define GRPC_FINAL final        // deprecated
 
diff --git a/include/grpc++/impl/codegen/method_handler_impl.h b/include/grpc++/impl/codegen/method_handler_impl.h
index 83b569ce74..8dfaf5883c 100644
--- a/include/grpc++/impl/codegen/method_handler_impl.h
+++ b/include/grpc++/impl/codegen/method_handler_impl.h
@@ -40,7 +40,7 @@
 
 namespace grpc {
 
-// A wrapper class of an application provided rpc method handler.
+/// A wrapper class of an application provided rpc method handler.
 template <class ServiceType, class RequestType, class ResponseType>
 class RpcMethodHandler : public MethodHandler {
  public:
@@ -77,7 +77,7 @@ class RpcMethodHandler : public MethodHandler {
   }
 
  private:
-  // Application provided rpc handler function.
+  /// Application provided rpc handler function.
   std::function<Status(ServiceType*, ServerContext*, const RequestType*,
                        ResponseType*)>
       func_;
@@ -85,7 +85,7 @@ class RpcMethodHandler : public MethodHandler {
   ServiceType* service_;
 };
 
-// A wrapper class of an application provided client streaming handler.
+/// A wrapper class of an application provided client streaming handler.
 template <class ServiceType, class RequestType, class ResponseType>
 class ClientStreamingHandler : public MethodHandler {
  public:
@@ -125,7 +125,7 @@ class ClientStreamingHandler : public MethodHandler {
   ServiceType* service_;
 };
 
-// A wrapper class of an application provided server streaming handler.
+/// A wrapper class of an application provided server streaming handler.
 template <class ServiceType, class RequestType, class ResponseType>
 class ServerStreamingHandler : public MethodHandler {
  public:
@@ -166,13 +166,13 @@ class ServerStreamingHandler : public MethodHandler {
   ServiceType* service_;
 };
 
-// A wrapper class of an application provided bidi-streaming handler.
-// This also applies to server-streamed implementation of a unary method
-// with the additional requirement that such methods must have done a
-// write for status to be ok
-// Since this is used by more than 1 class, the service is not passed in.
-// Instead, it is expected to be an implicitly-captured argument of func
-// (through bind or something along those lines)
+/// A wrapper class of an application provided bidi-streaming handler.
+/// This also applies to server-streamed implementation of a unary method
+/// with the additional requirement that such methods must have done a
+/// write for status to be ok
+/// Since this is used by more than 1 class, the service is not passed in.
+/// Instead, it is expected to be an implicitly-captured argument of func
+/// (through bind or something along those lines)
 template <class Streamer, bool WriteNeeded>
 class TemplatedBidiStreamingHandler : public MethodHandler {
  public:
@@ -249,7 +249,7 @@ class SplitServerStreamingHandler
             ServerSplitStreamer<RequestType, ResponseType>, false>(func) {}
 };
 
-// Handle unknown method by returning UNIMPLEMENTED error.
+/// Handle unknown method by returning UNIMPLEMENTED error.
 class UnknownMethodHandler : public MethodHandler {
  public:
   template <class T>
diff --git a/include/grpc++/impl/codegen/rpc_method.h b/include/grpc++/impl/codegen/rpc_method.h
index 4897428074..ca7527507c 100644
--- a/include/grpc++/impl/codegen/rpc_method.h
+++ b/include/grpc++/impl/codegen/rpc_method.h
@@ -40,6 +40,7 @@
 
 namespace grpc {
 
+/// Descriptor of an RPC method
 class RpcMethod {
  public:
   enum RpcType {
diff --git a/include/grpc++/impl/codegen/rpc_service_method.h b/include/grpc++/impl/codegen/rpc_service_method.h
index eb8f9a1096..96bb739c99 100644
--- a/include/grpc++/impl/codegen/rpc_service_method.h
+++ b/include/grpc++/impl/codegen/rpc_service_method.h
@@ -52,7 +52,7 @@ namespace grpc {
 class ServerContext;
 class StreamContextInterface;
 
-// Base class for running an RPC handler.
+/// Base class for running an RPC handler.
 class MethodHandler {
  public:
   virtual ~MethodHandler() {}
@@ -67,17 +67,17 @@ class MethodHandler {
   virtual void RunHandler(const HandlerParameter& param) = 0;
 };
 
-// Server side rpc method class
+/// Server side rpc method class
 class RpcServiceMethod : public RpcMethod {
  public:
-  // Takes ownership of the handler
+  /// Takes ownership of the handler
   RpcServiceMethod(const char* name, RpcMethod::RpcType type,
                    MethodHandler* handler)
       : RpcMethod(name, type), server_tag_(nullptr), handler_(handler) {}
 
   void set_server_tag(void* tag) { server_tag_ = tag; }
   void* server_tag() const { return server_tag_; }
-  // if MethodHandler is nullptr, then this is an async method
+  /// if MethodHandler is nullptr, then this is an async method
   MethodHandler* handler() const { return handler_.get(); }
   void ResetHandler() { handler_.reset(); }
   void SetHandler(MethodHandler* handler) { handler_.reset(handler); }
diff --git a/include/grpc++/impl/codegen/security/auth_context.h b/include/grpc++/impl/codegen/security/auth_context.h
index 75f2482346..e83877bcaf 100644
--- a/include/grpc++/impl/codegen/security/auth_context.h
+++ b/include/grpc++/impl/codegen/security/auth_context.h
@@ -99,7 +99,7 @@ class AuthContext {
   virtual AuthPropertyIterator begin() const = 0;
   virtual AuthPropertyIterator end() const = 0;
 
-  // Mutation functions: should only be used by an AuthMetadataProcessor.
+  /// Mutation functions: should only be used by an AuthMetadataProcessor.
   virtual void AddProperty(const grpc::string& key,
                            const grpc::string_ref& value) = 0;
   virtual bool SetPeerIdentityPropertyName(const grpc::string& name) = 0;
diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h
index ada304d571..07e3710b4b 100644
--- a/include/grpc++/impl/codegen/server_context.h
+++ b/include/grpc++/impl/codegen/server_context.h
@@ -91,7 +91,7 @@ class InteropServerContextInspector;
 class ServerContextTestSpouse;
 }  // namespace testing
 
-// Interface of server side rpc context.
+/// Interface of server side rpc context.
 class ServerContext {
  public:
   ServerContext();  // for async calls
@@ -106,9 +106,9 @@ class ServerContext {
   void AddInitialMetadata(const grpc::string& key, const grpc::string& value);
   void AddTrailingMetadata(const grpc::string& key, const grpc::string& value);
 
-  // IsCancelled is always safe to call when using sync API
-  // When using async API, it is only safe to call IsCancelled after
-  // the AsyncNotifyWhenDone tag has been delivered
+  /// IsCancelled is always safe to call when using sync API
+  /// When using async API, it is only safe to call IsCancelled after
+  /// the AsyncNotifyWhenDone tag has been delivered
   bool IsCancelled() const;
 
   // Cancel the Call from the server. This is a best-effort API and depending on
diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h
index bd65ea009e..0df90678b1 100644
--- a/include/grpc++/impl/codegen/service_type.h
+++ b/include/grpc++/impl/codegen/service_type.h
@@ -61,6 +61,7 @@ class ServerAsyncStreamingInterface {
   virtual void BindCall(Call* call) = 0;
 };
 
+/// Desriptor of an RPC service and its various RPC methods
 class Service {
  public:
   Service() : server_(nullptr) {}
diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h
index 9a90a18e2a..2eb97e83c1 100644
--- a/include/grpc++/impl/codegen/status_code_enum.h
+++ b/include/grpc++/impl/codegen/status_code_enum.h
@@ -136,6 +136,12 @@ 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
+  /// 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.
+  ///
+  ///
   /// See litmus test above for deciding between FAILED_PRECONDITION, ABORTED,
   /// and UNAVAILABLE.
   UNAVAILABLE = 14,
diff --git a/include/grpc++/impl/codegen/string_ref.h b/include/grpc++/impl/codegen/string_ref.h
index 003793823c..4ed11b1b6c 100644
--- a/include/grpc++/impl/codegen/string_ref.h
+++ b/include/grpc++/impl/codegen/string_ref.h
@@ -55,14 +55,14 @@ namespace grpc {
 /// compatibility.
 class string_ref {
  public:
-  // types
+  /// types
   typedef const char* const_iterator;
   typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 
-  // constants
+  /// constants
   const static size_t npos;
 
-  // construct/copy.
+  /// construct/copy.
   string_ref() : data_(nullptr), length_(0) {}
   string_ref(const string_ref& other)
       : data_(other.data_), length_(other.length_) {}
@@ -76,7 +76,7 @@ class string_ref {
   string_ref(const char* s, size_t l) : data_(s), length_(l) {}
   string_ref(const grpc::string& s) : data_(s.data()), length_(s.length()) {}
 
-  // iterators
+  /// iterators
   const_iterator begin() const { return data_; }
   const_iterator end() const { return data_ + length_; }
   const_iterator cbegin() const { return data_; }
@@ -94,16 +94,16 @@ class string_ref {
     return const_reverse_iterator(begin());
   }
 
-  // capacity
+  /// capacity
   size_t size() const { return length_; }
   size_t length() const { return length_; }
   size_t max_size() const { return length_; }
   bool empty() const { return length_ == 0; }
 
-  // element access
+  /// element access
   const char* data() const { return data_; }
 
-  // string operations
+  /// string operations
   int compare(string_ref x) const {
     size_t min_size = length_ < x.length_ ? length_ : x.length_;
     int r = memcmp(data_, x.data_, min_size);
@@ -144,7 +144,7 @@ class string_ref {
   size_t length_;
 };
 
-// Comparison operators
+/// Comparison operators
 inline bool operator==(string_ref x, string_ref y) { return x.compare(y) == 0; }
 inline bool operator!=(string_ref x, string_ref y) { return x.compare(y) != 0; }
 inline bool operator<(string_ref x, string_ref y) { return x.compare(y) < 0; }
diff --git a/include/grpc++/impl/codegen/stub_options.h b/include/grpc++/impl/codegen/stub_options.h
index 8e966a8dbf..41aef19ab0 100644
--- a/include/grpc++/impl/codegen/stub_options.h
+++ b/include/grpc++/impl/codegen/stub_options.h
@@ -36,6 +36,7 @@
 
 namespace grpc {
 
+/// Useful interface for generated stubs
 class StubOptions {};
 
 }  // namespace grpc
diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h
index a010924cef..34b814e9e3 100644
--- a/include/grpc++/impl/codegen/sync_stream.h
+++ b/include/grpc++/impl/codegen/sync_stream.h
@@ -516,7 +516,7 @@ class ServerReaderWriterInterface : public ServerStreamingInterface,
                                     public WriterInterface<W>,
                                     public ReaderInterface<R> {};
 
-// Actual implementation of bi-directional streaming
+/// Actual implementation of bi-directional streaming
 namespace internal {
 template <class W, class R>
 class ServerReaderWriterBody final {
@@ -576,7 +576,7 @@ class ServerReaderWriterBody final {
 };
 }  // namespace internal
 
-// class to represent the user API for a bidirectional streaming call
+/// class to represent the user API for a bidirectional streaming call
 template <class W, class R>
 class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> {
  public:
diff --git a/include/grpc++/impl/codegen/time.h b/include/grpc++/impl/codegen/time.h
index e090ece756..81ca7bb3de 100644
--- a/include/grpc++/impl/codegen/time.h
+++ b/include/grpc++/impl/codegen/time.h
@@ -39,17 +39,16 @@
 
 namespace grpc {
 
-/* If you are trying to use CompletionQueue::AsyncNext with a time class that
-   isn't either gpr_timespec or std::chrono::system_clock::time_point, you
-   will most likely be looking at this comment as your compiler will have
-   fired an error below. In order to fix this issue, you have two potential
-   solutions:
-
-     1. Use gpr_timespec or std::chrono::system_clock::time_point instead
-     2. Specialize the TimePoint class with whichever time class that you
-        want to use here. See below for two examples of how to do this.
+/** If you are trying to use CompletionQueue::AsyncNext with a time class that
+    isn't either gpr_timespec or std::chrono::system_clock::time_point, you
+    will most likely be looking at this comment as your compiler will have
+    fired an error below. In order to fix this issue, you have two potential
+    solutions:
+
+      1. Use gpr_timespec or std::chrono::system_clock::time_point instead
+      2. Specialize the TimePoint class with whichever time class that you
+         want to use here. See below for two examples of how to do this.
  */
-
 template <typename T>
 class TimePoint {
  public:
diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h
index 61632e32fa..7697232807 100644
--- a/include/grpc++/impl/server_builder_plugin.h
+++ b/include/grpc++/impl/server_builder_plugin.h
@@ -48,19 +48,19 @@ class ServerBuilderPlugin {
   virtual ~ServerBuilderPlugin() {}
   virtual grpc::string name() = 0;
 
-  // InitServer will be called in ServerBuilder::BuildAndStart(), after the
-  // Server instance is created.
+  /// InitServer will be called in ServerBuilder::BuildAndStart(), after the
+  /// Server instance is created.
   virtual void InitServer(ServerInitializer* si) = 0;
 
-  // Finish will be called at the end of ServerBuilder::BuildAndStart().
+  /// Finish will be called at the end of ServerBuilder::BuildAndStart().
   virtual void Finish(ServerInitializer* si) = 0;
 
-  // ChangeArguments is an interface that can be used in
-  // ServerBuilderOption::UpdatePlugins
+  /// ChangeArguments is an interface that can be used in
+  /// ServerBuilderOption::UpdatePlugins
   virtual void ChangeArguments(const grpc::string& name, void* value) = 0;
 
-  // UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(),
-  // before the Server instance is created.
+  /// UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(),
+  /// before the Server instance is created.
   virtual void UpdateChannelArguments(ChannelArguments* args) {}
 
   virtual bool has_sync_methods() const { return false; }
diff --git a/include/grpc++/resource_quota.h b/include/grpc++/resource_quota.h
index 68a514658d..da14088ebb 100644
--- a/include/grpc++/resource_quota.h
+++ b/include/grpc++/resource_quota.h
@@ -47,6 +47,7 @@ namespace grpc {
 /// all attached entities below the ResourceQuota bound.
 class ResourceQuota final : private GrpcLibraryCodegen {
  public:
+  // \param name - a unique name for this ResourceQuota.
   explicit ResourceQuota(const grpc::string& name);
   ResourceQuota();
   ~ResourceQuota();
diff --git a/include/grpc++/security/auth_metadata_processor.h b/include/grpc++/security/auth_metadata_processor.h
index 1ae32d0f6c..3536923146 100644
--- a/include/grpc++/security/auth_metadata_processor.h
+++ b/include/grpc++/security/auth_metadata_processor.h
@@ -49,19 +49,19 @@ class AuthMetadataProcessor {
 
   virtual ~AuthMetadataProcessor() {}
 
-  // If this method returns true, the Process function will be scheduled in
-  // a different thread from the one processing the call.
+  /// If this method returns true, the Process function will be scheduled in
+  /// a different thread from the one processing the call.
   virtual bool IsBlocking() const { return true; }
 
-  // context is read/write: it contains the properties of the channel peer and
-  // it is the job of the Process method to augment it with properties derived
-  // from the passed-in auth_metadata.
-  // consumed_auth_metadata needs to be filled with metadata that has been
-  // consumed by the processor and will be removed from the call.
-  // response_metadata is the metadata that will be sent as part of the
-  // response.
-  // If the return value is not Status::OK, the rpc call will be aborted with
-  // the error code and error message sent back to the client.
+  /// context is read/write: it contains the properties of the channel peer and
+  /// it is the job of the Process method to augment it with properties derived
+  /// from the passed-in auth_metadata.
+  /// consumed_auth_metadata needs to be filled with metadata that has been
+  /// consumed by the processor and will be removed from the call.
+  /// response_metadata is the metadata that will be sent as part of the
+  /// response.
+  /// If the return value is not Status::OK, the rpc call will be aborted with
+  /// the error code and error message sent back to the client.
   virtual Status Process(const InputMetadata& auth_metadata,
                          AuthContext* context,
                          OutputMetadata* consumed_auth_metadata,
diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h
index 59861b78d8..8d9d181fde 100644
--- a/include/grpc++/security/credentials.h
+++ b/include/grpc++/security/credentials.h
@@ -204,23 +204,23 @@ std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
 /// Credentials for a channel using Cronet.
 std::shared_ptr<ChannelCredentials> CronetChannelCredentials(void* engine);
 
-// User defined metadata credentials.
+/// User defined metadata credentials.
 class MetadataCredentialsPlugin {
  public:
   virtual ~MetadataCredentialsPlugin() {}
 
-  // If this method returns true, the Process function will be scheduled in
-  // a different thread from the one processing the call.
+  /// If this method returns true, the Process function will be scheduled in
+  /// a different thread from the one processing the call.
   virtual bool IsBlocking() const { return true; }
 
-  // Type of credentials this plugin is implementing.
+  /// Type of credentials this plugin is implementing.
   virtual const char* GetType() const { return ""; }
 
-  // Gets the auth metatada produced by this plugin.
-  // The fully qualified method name is:
-  // service_url + "/" + method_name.
-  // The channel_auth_context contains (among other things), the identity of
-  // the server.
+  /// Gets the auth metatada produced by this plugin.
+  /// The fully qualified method name is:
+  /// service_url + "/" + method_name.
+  /// The channel_auth_context contains (among other things), the identity of
+  /// the server.
   virtual Status GetMetadata(
       grpc::string_ref service_url, grpc::string_ref method_name,
       const AuthContext& channel_auth_context,
diff --git a/include/grpc++/security/server_credentials.h b/include/grpc++/security/server_credentials.h
index 229bab8d84..4676b04c5d 100644
--- a/include/grpc++/security/server_credentials.h
+++ b/include/grpc++/security/server_credentials.h
@@ -46,13 +46,13 @@ struct grpc_server;
 namespace grpc {
 class Server;
 
-// Wrapper around \a grpc_server_credentials, a way to authenticate a server.
+/// Wrapper around \a grpc_server_credentials, a way to authenticate a server.
 class ServerCredentials {
  public:
   virtual ~ServerCredentials();
 
-  // This method is not thread-safe and has to be called before the server is
-  // started. The last call to this function wins.
+  /// This method is not thread-safe and has to be called before the server is
+  /// started. The last call to this function wins.
   virtual void SetAuthMetadataProcessor(
       const std::shared_ptr<AuthMetadataProcessor>& processor) = 0;
 
@@ -70,7 +70,7 @@ class ServerCredentials {
 
 /// Options to create ServerCredentials with SSL
 struct SslServerCredentialsOptions {
-  // Deprecated
+  /// Deprecated
   SslServerCredentialsOptions()
       : force_client_auth(false),
         client_certificate_request(GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE) {}
@@ -84,12 +84,12 @@ struct SslServerCredentialsOptions {
   };
   grpc::string pem_root_certs;
   std::vector<PemKeyCertPair> pem_key_cert_pairs;
-  // Deprecated
+  /// 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 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.
   grpc_ssl_client_certificate_request_type client_certificate_request;
 };
 
diff --git a/include/grpc++/support/error_details.h b/include/grpc++/support/error_details.h
index 411175fb46..d4324d35cf 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.
-// 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.
+/// Maps a grpc::Status to 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.
 Status ExtractErrorDetails(const Status& from, ::google::rpc::Status* to);
 
-// Maps google::rpc::Status to a grpc::Status.
-// Returns OK on success.
-// Returns status with FAILED_PRECONDITION if \a to is nullptr.
+/// Maps google::rpc::Status to a grpc::Status.
+/// Returns OK on success.
+/// Returns status with FAILED_PRECONDITION if \a to is nullptr.
 Status SetErrorDetails(const ::google::rpc::Status& from, Status* to);
 
 }  // namespace grpc
diff --git a/include/grpc++/test/mock_stream.h b/include/grpc++/test/mock_stream.h
index f2de9472d6..f6e94a48b3 100644
--- a/include/grpc++/test/mock_stream.h
+++ b/include/grpc++/test/mock_stream.h
@@ -50,14 +50,14 @@ class MockClientReader : public ClientReaderInterface<R> {
  public:
   MockClientReader() = default;
 
-  // ClientStreamingInterface
+  /// ClientStreamingInterface
   MOCK_METHOD0_T(Finish, Status());
 
-  // ReaderInterface
+  /// ReaderInterface
   MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*));
   MOCK_METHOD1_T(Read, bool(R*));
 
-  // ClientReaderInterface
+  /// ClientReaderInterface
   MOCK_METHOD0_T(WaitForInitialMetadata, void());
 };
 
@@ -66,13 +66,13 @@ class MockClientWriter : public ClientWriterInterface<W> {
  public:
   MockClientWriter() = default;
 
-  // ClientStreamingInterface
+  /// ClientStreamingInterface
   MOCK_METHOD0_T(Finish, Status());
 
-  // WriterInterface
+  /// WriterInterface
   MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions));
 
-  // ClientWriterInterface
+  /// ClientWriterInterface
   MOCK_METHOD0_T(WritesDone, bool());
 };
 
@@ -81,22 +81,22 @@ class MockClientReaderWriter : public ClientReaderWriterInterface<W, R> {
  public:
   MockClientReaderWriter() = default;
 
-  // ClientStreamingInterface
+  /// ClientStreamingInterface
   MOCK_METHOD0_T(Finish, Status());
 
-  // ReaderInterface
+  /// ReaderInterface
   MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*));
   MOCK_METHOD1_T(Read, bool(R*));
 
-  // WriterInterface
+  /// WriterInterface
   MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions));
 
-  // ClientReaderWriterInterface
+  /// ClientReaderWriterInterface
   MOCK_METHOD0_T(WaitForInitialMetadata, void());
   MOCK_METHOD0_T(WritesDone, bool());
 };
 
-// TODO: We do not support mocking an async RPC for now.
+/// TODO: We do not support mocking an async RPC for now.
 
 template <class R>
 class MockClientAsyncResponseReader
@@ -113,11 +113,11 @@ class MockClientAsyncReader : public ClientAsyncReaderInterface<R> {
  public:
   MockClientAsyncReader() = default;
 
-  // ClientAsyncStreamingInterface
+  /// ClientAsyncStreamingInterface
   MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
   MOCK_METHOD2_T(Finish, void(Status*, void*));
 
-  // AsyncReaderInterface
+  /// AsyncReaderInterface
   MOCK_METHOD2_T(Read, void(R*, void*));
 };
 
@@ -126,14 +126,14 @@ class MockClientAsyncWriter : public ClientAsyncWriterInterface<W> {
  public:
   MockClientAsyncWriter() = default;
 
-  // ClientAsyncStreamingInterface
+  /// ClientAsyncStreamingInterface
   MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
   MOCK_METHOD2_T(Finish, void(Status*, void*));
 
-  // AsyncWriterInterface
+  /// AsyncWriterInterface
   MOCK_METHOD2_T(Write, void(const W&, void*));
 
-  // ClientAsyncWriterInterface
+  /// ClientAsyncWriterInterface
   MOCK_METHOD1_T(WritesDone, void(void*));
 };
 
@@ -143,17 +143,17 @@ class MockClientAsyncReaderWriter
  public:
   MockClientAsyncReaderWriter() = default;
 
-  // ClientAsyncStreamingInterface
+  /// ClientAsyncStreamingInterface
   MOCK_METHOD1_T(ReadInitialMetadata, void(void*));
   MOCK_METHOD2_T(Finish, void(Status*, void*));
 
-  // AsyncWriterInterface
+  /// AsyncWriterInterface
   MOCK_METHOD2_T(Write, void(const W&, void*));
 
-  // AsyncReaderInterface
+  /// AsyncReaderInterface
   MOCK_METHOD2_T(Read, void(R*, void*));
 
-  // ClientAsyncReaderWriterInterface
+  /// ClientAsyncReaderWriterInterface
   MOCK_METHOD1_T(WritesDone, void(void*));
 };
 
diff --git a/include/grpc++/test/server_context_test_spouse.h b/include/grpc++/test/server_context_test_spouse.h
index bac0db7bdc..5bd07e7aec 100644
--- a/include/grpc++/test/server_context_test_spouse.h
+++ b/include/grpc++/test/server_context_test_spouse.h
@@ -41,13 +41,13 @@
 namespace grpc {
 namespace testing {
 
-// A test-only class to access private members and methods of ServerContext.
+/// A test-only class to access private members and methods of ServerContext.
 class ServerContextTestSpouse {
  public:
   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.
+  /// Inject client metadata to the ServerContext for the test. The test spouse
+  /// must be alive when 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_;
 };
 
diff --git a/include/grpc/census.h b/include/grpc/census.h
index 822c42c0a4..68cefd86a1 100644
--- a/include/grpc/census.h
+++ b/include/grpc/census.h
@@ -31,7 +31,7 @@
  *
  */
 
-/* RPC-internal Census API's. These are designed to be generic enough that
+/** RPC-internal Census API's. These are designed to be generic enough that
  * they can (ultimately) be used in many different RPC systems (with differing
  * implementations). */
 
@@ -44,12 +44,12 @@
 extern "C" {
 #endif
 
-/* Identify census features that can be enabled via census_initialize(). */
+/** Identify census features that can be enabled via census_initialize(). */
 enum census_features {
-  CENSUS_FEATURE_NONE = 0,    /* Do not enable census. */
-  CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */
-  CENSUS_FEATURE_STATS = 2,   /* Enable Census stats collection. */
-  CENSUS_FEATURE_CPU = 4,     /* Enable Census CPU usage collection. */
+  CENSUS_FEATURE_NONE = 0,    /** Do not enable census. */
+  CENSUS_FEATURE_TRACING = 1, /** Enable census tracing. */
+  CENSUS_FEATURE_STATS = 2,   /** Enable Census stats collection. */
+  CENSUS_FEATURE_CPU = 4,     /** Enable Census CPU usage collection. */
   CENSUS_FEATURE_ALL =
       CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU
 };
@@ -82,7 +82,7 @@ CENSUSAPI int census_enabled(void);
   metrics will be recorded. Keys are unique within a context. */
 typedef struct census_context census_context;
 
-/* A tag is a key:value pair. Both keys and values are nil-terminated strings,
+/** A tag is a key:value pair. Both keys and values are nil-terminated strings,
    containing printable ASCII characters (decimal 32-126). Keys must be at
    least one character in length. Both keys and values can have at most
    CENSUS_MAX_TAG_KB_LEN characters (including the terminating nil). The
@@ -97,36 +97,36 @@ typedef struct {
   uint8_t flags;
 } census_tag;
 
-/* Maximum length of a tag's key or value. */
+/** Maximum length of a tag's key or value. */
 #define CENSUS_MAX_TAG_KV_LEN 255
-/* Maximum number of propagatable tags. */
+/** Maximum number of propagatable tags. */
 #define CENSUS_MAX_PROPAGATED_TAGS 255
 
-/* Tag flags. */
-#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */
-#define CENSUS_TAG_STATS 2     /* Tag will be used for statistics aggregation */
-#define CENSUS_TAG_RESERVED 4  /* Reserved for internal use. */
-/* Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients
+/** Tag flags. */
+#define CENSUS_TAG_PROPAGATE 1 /** Tag should be propagated over RPC */
+#define CENSUS_TAG_STATS 2    /** Tag will be used for statistics aggregation */
+#define CENSUS_TAG_RESERVED 4 /** Reserved for internal use. */
+/** Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients
    should not use or rely on their values. */
 
 #define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
 #define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)
 
-/* An instance of this structure is kept by every context, and records the
+/** An instance of this structure is kept by every context, and records the
    basic information associated with the creation of that context. */
 typedef struct {
-  int n_propagated_tags; /* number of propagated tags */
-  int n_local_tags;      /* number of non-propagated (local) tags */
-  int n_deleted_tags;    /* number of tags that were deleted */
-  int n_added_tags;      /* number of tags that were added */
-  int n_modified_tags;   /* number of tags that were modified */
-  int n_invalid_tags;    /* number of tags with bad keys or values (e.g.
+  int n_propagated_tags; /** number of propagated tags */
+  int n_local_tags;      /** number of non-propagated (local) tags */
+  int n_deleted_tags;    /** number of tags that were deleted */
+  int n_added_tags;      /** number of tags that were added */
+  int n_modified_tags;   /** number of tags that were modified */
+  int n_invalid_tags;    /** number of tags with bad keys or values (e.g.
                             longer than CENSUS_MAX_TAG_KV_LEN) */
-  int n_ignored_tags;    /* number of tags ignored because of
+  int n_ignored_tags;    /** number of tags ignored because of
                             CENSUS_MAX_PROPAGATED_TAGS limit. */
 } census_context_status;
 
-/* Create a new context, adding and removing tags from an existing context.
+/** Create a new context, adding and removing tags from an existing context.
    This will copy all tags from the 'tags' input, so it is recommended
    to add as many tags in a single operation as is practical for the client.
    @param base Base context to build upon. Can be NULL.
@@ -148,15 +148,15 @@ CENSUSAPI census_context *census_context_create(
     const census_context *base, const census_tag *tags, int ntags,
     census_context_status const **status);
 
-/* Destroy a context. Once this function has been called, the context cannot
+/** Destroy a context. Once this function has been called, the context cannot
    be reused. */
 CENSUSAPI void census_context_destroy(census_context *context);
 
-/* Get a pointer to the original status from the context creation. */
+/** Get a pointer to the original status from the context creation. */
 CENSUSAPI const census_context_status *census_context_get_status(
     const census_context *context);
 
-/* Structure used for iterating over the tags in a context. API clients should
+/** Structure used for iterating over the tags in a context. API clients should
    not use or reference internal fields - neither their contents or
    presence/absence are guaranteed. */
 typedef struct {
@@ -166,25 +166,25 @@ typedef struct {
   char *kvm;
 } census_context_iterator;
 
-/* Initialize a census_tag_iterator. Must be called before first use. */
+/** Initialize a census_tag_iterator. Must be called before first use. */
 CENSUSAPI void census_context_initialize_iterator(
     const census_context *context, census_context_iterator *iterator);
 
-/* Get the contents of the "next" tag in the context. If there are no more
+/** Get the contents of the "next" tag in the context. If there are no more
    tags, returns 0 (and 'tag' contents will be unchanged), otherwise returns 1.
    */
 CENSUSAPI int census_context_next_tag(census_context_iterator *iterator,
                                       census_tag *tag);
 
-/* Get a context tag by key. Returns 0 if the key is not present. */
+/** Get a context tag by key. Returns 0 if the key is not present. */
 CENSUSAPI int census_context_get_tag(const census_context *context,
                                      const char *key, census_tag *tag);
 
-/* Tag set encode/decode functionality. These functions are intended
+/** Tag set encode/decode functionality. These functions are intended
    for use by RPC systems only, for purposes of transmitting/receiving contexts.
    */
 
-/* Encode a context into a buffer.
+/** Encode a context into a buffer.
    @param context context to be encoded
    @param buffer buffer into which the context will be encoded.
    @param buf_size number of available bytes in buffer.
@@ -193,15 +193,15 @@ CENSUSAPI int census_context_get_tag(const census_context *context,
 CENSUSAPI size_t census_context_encode(const census_context *context,
                                        char *buffer, size_t buf_size);
 
-/* Decode context buffer encoded with census_context_encode(). Returns NULL
+/** Decode context buffer encoded with census_context_encode(). Returns NULL
    if there is an error in parsing either buffer. */
 CENSUSAPI census_context *census_context_decode(const char *buffer,
                                                 size_t size);
 
-/* Distributed traces can have a number of options. */
+/** Distributed traces can have a number of options. */
 enum census_trace_mask_values {
-  CENSUS_TRACE_MASK_NONE = 0,      /* Default, empty flags */
-  CENSUS_TRACE_MASK_IS_SAMPLED = 1 /* RPC tracing enabled for this context. */
+  CENSUS_TRACE_MASK_NONE = 0,      /** Default, empty flags */
+  CENSUS_TRACE_MASK_IS_SAMPLED = 1 /** RPC tracing enabled for this context. */
 };
 
 /** Get the current trace mask associated with this context. The value returned
@@ -211,7 +211,7 @@ CENSUSAPI int census_trace_mask(const census_context *context);
 /** Set the trace mask associated with a context. */
 CENSUSAPI void census_set_trace_mask(int trace_mask);
 
-/* The concept of "operation" is a fundamental concept for Census. In an RPC
+/** The concept of "operation" is a fundamental concept for Census. In an RPC
    system, an operation typically represents a single RPC, or a significant
    sub-part thereof (e.g. a single logical "read" RPC to a distributed storage
    system might do several other actions in parallel, from looking up metadata
@@ -238,7 +238,7 @@ CENSUSAPI void census_set_trace_mask(int trace_mask);
   at which an operation begins.
 */
 typedef struct {
-  /* Use gpr_timespec for default implementation. High performance
+  /** Use gpr_timespec for default implementation. High performance
    * implementations should use a cycle-counter based timestamp. */
   gpr_timespec ts;
 } census_timestamp;
@@ -398,12 +398,12 @@ CENSUSAPI void census_trace_print(census_context *context, uint32_t type,
 
 /** Trace record. */
 typedef struct {
-  census_timestamp timestamp; /* Time of record creation */
-  uint64_t trace_id;          /* Trace ID associated with record */
-  uint64_t op_id;             /* Operation ID associated with record */
-  uint32_t type;              /* Type (as used in census_trace_print() */
-  const char *buffer;         /* Buffer (from census_trace_print() */
-  size_t buf_size;            /* Number of bytes inside buffer */
+  census_timestamp timestamp; /** Time of record creation */
+  uint64_t trace_id;          /** Trace ID associated with record */
+  uint64_t op_id;             /** Operation ID associated with record */
+  uint32_t type;              /** Type (as used in census_trace_print() */
+  const char *buffer;         /** Buffer (from census_trace_print() */
+  size_t buf_size;            /** Number of bytes inside buffer */
 } census_trace_record;
 
 /** Start a scan of existing trace records. While a scan is ongoing, addition
@@ -431,7 +431,7 @@ CENSUSAPI int census_get_trace_record(census_trace_record *trace_record);
 /** End a scan previously started by census_trace_scan_start() */
 CENSUSAPI void census_trace_scan_end();
 
-/* Core stats collection API's. The following concepts are used:
+/** Core stats collection API's. The following concepts are used:
    * Resource: Users record measurements for a single resource. Examples
      include RPC latency, CPU seconds consumed, and bytes transmitted.
    * Aggregation: An aggregation of a set of measurements. Census supports the
@@ -450,7 +450,7 @@ CENSUSAPI void census_trace_scan_end();
   implementations. The proto definitions can be found in src/proto/census.
 */
 
-/* Define a new resource. `resource_pb` should contain an encoded Resource
+/** Define a new resource. `resource_pb` should contain an encoded Resource
    protobuf, `resource_pb_size` being the size of the buffer. Returns a -ve
    value on error, or a positive (>= 0) resource id (for use in
    census_delete_resource() and census_record_values()). In order to be valid, a
@@ -459,21 +459,21 @@ CENSUSAPI void census_trace_scan_end();
 CENSUSAPI int32_t census_define_resource(const uint8_t *resource_pb,
                                          size_t resource_pb_size);
 
-/* Delete a resource created by census_define_resource(). */
+/** Delete a resource created by census_define_resource(). */
 CENSUSAPI void census_delete_resource(int32_t resource_id);
 
-/* Determine the id of a resource, given its name. returns -1 if the resource
+/** Determine the id of a resource, given its name. returns -1 if the resource
    does not exist. */
 CENSUSAPI int32_t census_resource_id(const char *name);
 
-/* A single value to be recorded comprises two parts: an ID for the particular
+/** A single value to be recorded comprises two parts: an ID for the particular
  * resource and the value to be recorded against it. */
 typedef struct {
   int32_t resource_id;
   double value;
 } census_value;
 
-/* Record new usage values against the given context. */
+/** Record new usage values against the given context. */
 CENSUSAPI void census_record_values(census_context *context,
                                     census_value *values, size_t nvalues);
 
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h
index 1eeb075927..a36367fa8f 100644
--- a/include/grpc/grpc.h
+++ b/include/grpc/grpc.h
@@ -287,7 +287,7 @@ GRPCAPI grpc_channel *grpc_lame_client_channel_create(
 /** Close and destroy a grpc channel */
 GRPCAPI void grpc_channel_destroy(grpc_channel *channel);
 
-/* Error handling for grpc_call
+/** Error handling for grpc_call
    Most grpc_call functions return a grpc_error. If the error is not GRPC_OK
    then the operation failed due to some unsatisfied precondition.
    If a grpc_call fails, it's guaranteed that no change to the call state
diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h
index 5d3cc4fd67..4f35506882 100644
--- a/include/grpc/grpc_security.h
+++ b/include/grpc/grpc_security.h
@@ -42,7 +42,7 @@
 extern "C" {
 #endif
 
-/* --- Authentication Context. --- */
+/** --- Authentication Context. --- */
 
 typedef struct grpc_auth_context grpc_auth_context;
 
@@ -52,84 +52,84 @@ typedef struct grpc_auth_property_iterator {
   const char *name;
 } grpc_auth_property_iterator;
 
-/* value, if not NULL, is guaranteed to be NULL terminated. */
+/** value, if not NULL, is guaranteed to be NULL terminated. */
 typedef struct grpc_auth_property {
   char *name;
   char *value;
   size_t value_length;
 } grpc_auth_property;
 
-/* Returns NULL when the iterator is at the end. */
+/** Returns NULL when the iterator is at the end. */
 GRPCAPI const grpc_auth_property *grpc_auth_property_iterator_next(
     grpc_auth_property_iterator *it);
 
-/* Iterates over the auth context. */
+/** Iterates over the auth context. */
 GRPCAPI grpc_auth_property_iterator
 grpc_auth_context_property_iterator(const grpc_auth_context *ctx);
 
-/* Gets the peer identity. Returns an empty iterator (first _next will return
+/** Gets the peer identity. Returns an empty iterator (first _next will return
    NULL) if the peer is not authenticated. */
 GRPCAPI grpc_auth_property_iterator
 grpc_auth_context_peer_identity(const grpc_auth_context *ctx);
 
-/* Finds a property in the context. May return an empty iterator (first _next
+/** Finds a property in the context. May return an empty iterator (first _next
    will return NULL) if no property with this name was found in the context. */
 GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
     const grpc_auth_context *ctx, const char *name);
 
-/* Gets the name of the property that indicates the peer identity. Will return
+/** Gets the name of the property that indicates the peer identity. Will return
    NULL if the peer is not authenticated. */
 GRPCAPI const char *grpc_auth_context_peer_identity_property_name(
     const grpc_auth_context *ctx);
 
-/* Returns 1 if the peer is authenticated, 0 otherwise. */
+/** Returns 1 if the peer is authenticated, 0 otherwise. */
 GRPCAPI int grpc_auth_context_peer_is_authenticated(
     const grpc_auth_context *ctx);
 
-/* Gets the auth context from the call. Caller needs to call
+/** Gets the auth context from the call. Caller needs to call
    grpc_auth_context_release on the returned context. */
 GRPCAPI grpc_auth_context *grpc_call_auth_context(grpc_call *call);
 
-/* Releases the auth context returned from grpc_call_auth_context. */
+/** Releases the auth context returned from grpc_call_auth_context. */
 GRPCAPI void grpc_auth_context_release(grpc_auth_context *context);
 
-/* --
+/** --
    The following auth context methods should only be called by a server metadata
    processor to set properties extracted from auth metadata.
    -- */
 
-/* Add a property. */
+/** Add a property. */
 GRPCAPI void grpc_auth_context_add_property(grpc_auth_context *ctx,
                                             const char *name, const char *value,
                                             size_t value_length);
 
-/* Add a C string property. */
+/** Add a C string property. */
 GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx,
                                                     const char *name,
                                                     const char *value);
 
-/* Sets the property name. Returns 1 if successful or 0 in case of failure
+/** Sets the property name. Returns 1 if successful or 0 in case of failure
    (which means that no property with this name exists). */
 GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
     grpc_auth_context *ctx, const char *name);
 
-/* --- grpc_channel_credentials object. ---
+/** --- grpc_channel_credentials object. ---
 
    A channel credentials object represents a way to authenticate a client on a
    channel.  */
 
 typedef struct grpc_channel_credentials grpc_channel_credentials;
 
-/* Releases a channel credentials object.
+/** Releases a channel credentials object.
    The creator of the credentials object is responsible for its release. */
 GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials *creds);
 
-/* Creates default credentials to connect to a google gRPC service.
+/** Creates default credentials to connect to a google gRPC service.
    WARNING: Do NOT use this credentials to connect to a non-google service as
    this could result in an oauth2 token leak. */
 GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void);
 
-/* Callback for getting the SSL roots override from the application.
+/** Callback for getting the SSL roots override from the application.
    In case of success, *pem_roots_certs must be set to a NULL terminated string
    containing the list of PEM encoded root certificates. The ownership is passed
    to the core and freed (laster by the core) with gpr_free.
@@ -138,7 +138,7 @@ GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void);
 typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
     char **pem_root_certs);
 
-/* Setup a callback to override the default TLS/SSL roots.
+/** Setup a callback to override the default TLS/SSL roots.
    This function is not thread-safe and must be called at initialization time
    before any ssl credentials are created to have the desired side effect.
    If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
@@ -146,18 +146,18 @@ typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
 GRPCAPI void grpc_set_ssl_roots_override_callback(
     grpc_ssl_roots_override_callback cb);
 
-/* Object that holds a private key / certificate chain pair in PEM format. */
+/** Object that holds a private key / certificate chain pair in PEM format. */
 typedef struct {
-  /* private_key is the NULL-terminated string containing the PEM encoding of
+  /** private_key is the NULL-terminated string containing the PEM encoding of
      the client's private key. */
   const char *private_key;
 
-  /* cert_chain is the NULL-terminated string containing the PEM encoding of
+  /** cert_chain is the NULL-terminated string containing the PEM encoding of
      the client's certificate chain. */
   const char *cert_chain;
 } grpc_ssl_pem_key_cert_pair;
 
-/* Creates an SSL credentials object.
+/** Creates an SSL credentials object.
    - pem_root_certs is the NULL-terminated string containing the PEM encoding
      of the server root certificates. If this parameter is NULL, the
      implementation will first try to dereference the file pointed by the
@@ -172,7 +172,7 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create(
     const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair,
     void *reserved);
 
-/* --- grpc_call_credentials object.
+/** --- grpc_call_credentials object.
 
    A call credentials object represents a way to authenticate on a particular
    call. These credentials can be composed with a channel credentials object
@@ -180,21 +180,21 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create(
 
 typedef struct grpc_call_credentials grpc_call_credentials;
 
-/* Releases a call credentials object.
+/** Releases a call credentials object.
    The creator of the credentials object is responsible for its release. */
 GRPCAPI void grpc_call_credentials_release(grpc_call_credentials *creds);
 
-/* Creates a composite channel credentials object. */
+/** Creates a composite channel credentials object. */
 GRPCAPI grpc_channel_credentials *grpc_composite_channel_credentials_create(
     grpc_channel_credentials *channel_creds, grpc_call_credentials *call_creds,
     void *reserved);
 
-/* Creates a composite call credentials object. */
+/** Creates a composite call credentials object. */
 GRPCAPI grpc_call_credentials *grpc_composite_call_credentials_create(
     grpc_call_credentials *creds1, grpc_call_credentials *creds2,
     void *reserved);
 
-/* Creates a compute engine credentials object for connecting to Google.
+/** Creates a compute engine credentials object for connecting to Google.
    WARNING: Do NOT use this credentials to connect to a non-google service as
    this could result in an oauth2 token leak. */
 GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create(
@@ -202,7 +202,7 @@ GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create(
 
 GRPCAPI gpr_timespec grpc_max_auth_token_lifetime();
 
-/* Creates a JWT credentials object. May return NULL if the input is invalid.
+/** Creates a JWT credentials object. May return NULL if the input is invalid.
    - json_key is the JSON key string containing the client's private key.
    - token_lifetime is the lifetime of each Json Web Token (JWT) created with
      this credentials.  It should not exceed grpc_max_auth_token_lifetime or
@@ -212,7 +212,7 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key,
                                                    gpr_timespec token_lifetime,
                                                    void *reserved);
 
-/* Creates an Oauth2 Refresh Token credentials object for connecting to Google.
+/** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
    May return NULL if the input is invalid.
    WARNING: Do NOT use this credentials to connect to a non-google service as
    this could result in an oauth2 token leak.
@@ -221,17 +221,17 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key,
 GRPCAPI grpc_call_credentials *grpc_google_refresh_token_credentials_create(
     const char *json_refresh_token, void *reserved);
 
-/* Creates an Oauth2 Access Token credentials with an access token that was
+/** Creates an Oauth2 Access Token credentials with an access token that was
    aquired by an out of band mechanism. */
 GRPCAPI grpc_call_credentials *grpc_access_token_credentials_create(
     const char *access_token, void *reserved);
 
-/* Creates an IAM credentials object for connecting to Google. */
+/** Creates an IAM credentials object for connecting to Google. */
 GRPCAPI grpc_call_credentials *grpc_google_iam_credentials_create(
     const char *authorization_token, const char *authority_selector,
     void *reserved);
 
-/* Callback function to be called by the metadata credentials plugin
+/** Callback function to be called by the metadata credentials plugin
    implementation when the metadata is ready.
    - user_data is the opaque pointer that was passed in the get_metadata method
      of the grpc_metadata_credentials_plugin (see below).
@@ -246,31 +246,31 @@ typedef void (*grpc_credentials_plugin_metadata_cb)(
     void *user_data, const grpc_metadata *creds_md, size_t num_creds_md,
     grpc_status_code status, const char *error_details);
 
-/* Context that can be used by metadata credentials plugin in order to create
+/** Context that can be used by metadata credentials plugin in order to create
    auth related metadata. */
 typedef struct {
-  /* The fully qualifed service url. */
+  /** The fully qualifed service url. */
   const char *service_url;
 
-  /* The method name of the RPC being called (not fully qualified).
+  /** The method name of the RPC being called (not fully qualified).
      The fully qualified method name can be built from the service_url:
      full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */
   const char *method_name;
 
-  /* The auth_context of the channel which gives the server's identity. */
+  /** The auth_context of the channel which gives the server's identity. */
   const grpc_auth_context *channel_auth_context;
 
-  /* Reserved for future use. */
+  /** Reserved for future use. */
   void *reserved;
 } grpc_auth_metadata_context;
 
-/* grpc_metadata_credentials plugin is an API user provided structure used to
+/** grpc_metadata_credentials plugin is an API user provided structure used to
    create grpc_credentials objects that can be set on a channel (composed) or
    a call. See grpc_credentials_metadata_create_from_plugin below.
    The grpc client stack will call the get_metadata method of the plugin for
    every call in scope for the credentials created from it. */
 typedef struct {
-  /* The implementation of this method has to be non-blocking.
+  /** The implementation of this method has to be non-blocking.
      - context is the information that can be used by the plugin to create auth
        metadata.
      - cb is the callback that needs to be called when the metadata is ready.
@@ -278,39 +278,39 @@ typedef struct {
   void (*get_metadata)(void *state, grpc_auth_metadata_context context,
                        grpc_credentials_plugin_metadata_cb cb, void *user_data);
 
-  /* Destroys the plugin state. */
+  /** Destroys the plugin state. */
   void (*destroy)(void *state);
 
-  /* State that will be set as the first parameter of the methods above. */
+  /** State that will be set as the first parameter of the methods above. */
   void *state;
 
-  /* Type of credentials that this plugin is implementing. */
+  /** Type of credentials that this plugin is implementing. */
   const char *type;
 } grpc_metadata_credentials_plugin;
 
-/* Creates a credentials object from a plugin. */
+/** Creates a credentials object from a plugin. */
 GRPCAPI grpc_call_credentials *grpc_metadata_credentials_create_from_plugin(
     grpc_metadata_credentials_plugin plugin, void *reserved);
 
-/* --- Secure channel creation. --- */
+/** --- Secure channel creation. --- */
 
-/* Creates a secure channel using the passed-in credentials. */
+/** Creates a secure channel using the passed-in credentials. */
 GRPCAPI grpc_channel *grpc_secure_channel_create(
     grpc_channel_credentials *creds, const char *target,
     const grpc_channel_args *args, void *reserved);
 
-/* --- grpc_server_credentials object. ---
+/** --- grpc_server_credentials object. ---
 
    A server credentials object represents a way to authenticate a server.  */
 
 typedef struct grpc_server_credentials grpc_server_credentials;
 
-/* Releases a server_credentials object.
+/** Releases a server_credentials object.
    The creator of the server_credentials object is responsible for its release.
    */
 GRPCAPI void grpc_server_credentials_release(grpc_server_credentials *creds);
 
-/* Deprecated in favor of grpc_ssl_server_credentials_create_ex.
+/** Deprecated in favor of grpc_ssl_server_credentials_create_ex.
    Creates an SSL server_credentials object.
    - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
      the client root certificates. This parameter may be NULL if the server does
@@ -326,7 +326,7 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create(
     const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs,
     size_t num_key_cert_pairs, int force_client_auth, void *reserved);
 
-/* Same as grpc_ssl_server_credentials_create method except uses
+/** Same as grpc_ssl_server_credentials_create method except uses
    grpc_ssl_client_certificate_request_type enum to support more ways to
    authenticate client cerificates.*/
 GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex(
@@ -335,25 +335,25 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex(
     grpc_ssl_client_certificate_request_type client_certificate_request,
     void *reserved);
 
-/* --- Server-side secure ports. --- */
+/** --- Server-side secure ports. --- */
 
-/* Add a HTTP2 over an encrypted link over tcp listener.
+/** Add a HTTP2 over an encrypted link over tcp listener.
    Returns bound port number on success, 0 on failure.
    REQUIRES: server not started */
 GRPCAPI int grpc_server_add_secure_http2_port(grpc_server *server,
                                               const char *addr,
                                               grpc_server_credentials *creds);
 
-/* --- Call specific credentials. --- */
+/** --- Call specific credentials. --- */
 
-/* Sets a credentials to a call. Can only be called on the client side before
+/** Sets a credentials to a call. Can only be called on the client side before
    grpc_call_start_batch. */
 GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call *call,
                                                   grpc_call_credentials *creds);
 
-/* --- Auth Metadata Processing --- */
+/** --- Auth Metadata Processing --- */
 
-/* Callback function that is called when the metadata processing is done.
+/** Callback function that is called when the metadata processing is done.
    - Consumed metadata will be removed from the set of metadata available on the
      call. consumed_md may be NULL if no metadata has been consumed.
    - Response metadata will be set on the response. response_md may be NULL.
@@ -367,9 +367,9 @@ typedef void (*grpc_process_auth_metadata_done_cb)(
     const grpc_metadata *response_md, size_t num_response_md,
     grpc_status_code status, const char *error_details);
 
-/* Pluggable server-side metadata processor object. */
+/** Pluggable server-side metadata processor object. */
 typedef struct {
-  /* The context object is read/write: it contains the properties of the
+  /** The context object is read/write: it contains the properties of the
      channel peer and it is the job of the process function to augment it with
      properties derived from the passed-in metadata.
      The lifetime of these objects is guaranteed until cb is invoked. */
diff --git a/include/grpc/grpc_security_constants.h b/include/grpc/grpc_security_constants.h
index da05c5a97b..d7ac0b2745 100644
--- a/include/grpc/grpc_security_constants.h
+++ b/include/grpc/grpc_security_constants.h
@@ -45,30 +45,30 @@ extern "C" {
 #define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name"
 #define GRPC_X509_PEM_CERT_PROPERTY_NAME "x509_pem_cert"
 
-/* Environment variable that points to the default SSL roots file. This file
+/** Environment variable that points to the default SSL roots file. This file
    must be a PEM encoded file with all the roots such as the one that can be
    downloaded from https://pki.google.com/roots.pem.  */
 #define GRPC_DEFAULT_SSL_ROOTS_FILE_PATH_ENV_VAR \
   "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"
 
-/* Environment variable that points to the google default application
+/** Environment variable that points to the google default application
    credentials json key or refresh token. Used in the
    grpc_google_default_credentials_create function. */
 #define GRPC_GOOGLE_CREDENTIALS_ENV_VAR "GOOGLE_APPLICATION_CREDENTIALS"
 
-/* Results for the SSL roots override callback. */
+/** Results for the SSL roots override callback. */
 typedef enum {
   GRPC_SSL_ROOTS_OVERRIDE_OK,
-  GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /* Do not try fallback options. */
+  GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /** Do not try fallback options. */
   GRPC_SSL_ROOTS_OVERRIDE_FAIL
 } grpc_ssl_roots_override_result;
 
 typedef enum {
-  /* Server does not request client certificate. A client can present a self
+  /** Server does not request client certificate. A client can present a self
      signed or signed certificates if it wishes to do so and they would be
      accepted. */
   GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE,
-  /* Server requests client certificate but does not enforce that the client
+  /** Server requests client certificate but does not enforce that the client
      presents a certificate.
 
      If the client presents a certificate, the client authentication is left to
@@ -77,7 +77,7 @@ typedef enum {
      The key cert pair should still be valid for the SSL connection to be
      established. */
   GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
-  /* Server requests client certificate but does not enforce that the client
+  /** Server requests client certificate but does not enforce that the client
      presents a certificate.
 
      If the client presents a certificate, the client authentication is done by
@@ -87,7 +87,7 @@ typedef enum {
      The key cert pair should still be valid for the SSL connection to be
      established. */
   GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_AND_VERIFY,
-  /* Server requests client certificate but enforces that the client presents a
+  /** Server requests client certificate but enforces that the client presents a
      certificate.
 
      If the client presents a certificate, the client authentication is left to
@@ -96,7 +96,7 @@ typedef enum {
      The key cert pair should still be valid for the SSL connection to be
      established. */
   GRPC_SSL_REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY,
-  /* Server requests client certificate but enforces that the client presents a
+  /** Server requests client certificate but enforces that the client presents a
      certificate.
 
      The cerificate presented by the client is verified by grpc framework (The
diff --git a/include/grpc/impl/codegen/atm.h b/include/grpc/impl/codegen/atm.h
index 4bd572d6d1..d348f32f67 100644
--- a/include/grpc/impl/codegen/atm.h
+++ b/include/grpc/impl/codegen/atm.h
@@ -34,7 +34,7 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_H
 #define GRPC_IMPL_CODEGEN_ATM_H
 
-/* This interface provides atomic operations and barriers.
+/** This interface provides atomic operations and barriers.
    It is internal to gpr support code and should not be used outside it.
 
    If an operation with acquire semantics precedes another memory access by the
diff --git a/include/grpc/impl/codegen/atm_windows.h b/include/grpc/impl/codegen/atm_windows.h
index a533651f6f..fa842a3048 100644
--- a/include/grpc/impl/codegen/atm_windows.h
+++ b/include/grpc/impl/codegen/atm_windows.h
@@ -34,7 +34,7 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
 #define GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
 
-/* Win32 variant of atm_platform.h */
+/** Win32 variant of atm_platform.h */
 #include <grpc/impl/codegen/port_platform.h>
 
 typedef intptr_t gpr_atm;
@@ -64,7 +64,7 @@ static __inline void gpr_atm_no_barrier_store(gpr_atm *p, gpr_atm value) {
 }
 
 static __inline int gpr_atm_no_barrier_cas(gpr_atm *p, gpr_atm o, gpr_atm n) {
-/* InterlockedCompareExchangePointerNoFence() not available on vista or
+/** InterlockedCompareExchangePointerNoFence() not available on vista or
    windows7 */
 #ifdef GPR_ARCH_64
   return o == (gpr_atm)InterlockedCompareExchangeAcquire64(
@@ -107,7 +107,7 @@ static __inline int gpr_atm_full_cas(gpr_atm *p, gpr_atm o, gpr_atm n) {
 
 static __inline gpr_atm gpr_atm_no_barrier_fetch_add(gpr_atm *p,
                                                      gpr_atm delta) {
-  /* Use the CAS operation to get pointer-sized fetch and add */
+  /** Use the CAS operation to get pointer-sized fetch and add */
   gpr_atm old;
   do {
     old = *p;
@@ -116,7 +116,7 @@ static __inline gpr_atm gpr_atm_no_barrier_fetch_add(gpr_atm *p,
 }
 
 static __inline gpr_atm gpr_atm_full_fetch_add(gpr_atm *p, gpr_atm delta) {
-  /* Use a CAS operation to get pointer-sized fetch and add */
+  /** Use a CAS operation to get pointer-sized fetch and add */
   gpr_atm old;
 #ifdef GPR_ARCH_64
   do {
diff --git a/include/grpc/impl/codegen/byte_buffer_reader.h b/include/grpc/impl/codegen/byte_buffer_reader.h
index 85a4864140..354a28a14e 100644
--- a/include/grpc/impl/codegen/byte_buffer_reader.h
+++ b/include/grpc/impl/codegen/byte_buffer_reader.h
@@ -43,9 +43,9 @@ struct grpc_byte_buffer;
 struct grpc_byte_buffer_reader {
   struct grpc_byte_buffer *buffer_in;
   struct grpc_byte_buffer *buffer_out;
-  /* Different current objects correspond to different types of byte buffers */
+  /** Different current objects correspond to different types of byte buffers */
   union {
-    /* Index into a slice buffer's array of slices */
+    /** Index into a slice buffer's array of slices */
     unsigned index;
   } current;
 };
diff --git a/include/grpc/impl/codegen/compression_types.h b/include/grpc/impl/codegen/compression_types.h
index a563711e32..953b51d9c4 100644
--- a/include/grpc/impl/codegen/compression_types.h
+++ b/include/grpc/impl/codegen/compression_types.h
@@ -67,7 +67,7 @@ extern "C" {
   "grpc.compression_enabled_algorithms_bitset"
 /** \} */
 
-/* The various compression algorithms supported by gRPC */
+/** The various compression algorithms supported by gRPC */
 typedef enum {
   GRPC_COMPRESS_NONE = 0,
   GRPC_COMPRESS_DEFLATE,
diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h
index c62e976b8f..3797645442 100644
--- a/include/grpc/impl/codegen/gpr_slice.h
+++ b/include/grpc/impl/codegen/gpr_slice.h
@@ -33,7 +33,8 @@
 #ifndef GRPC_IMPL_CODEGEN_GPR_SLICE_H
 #define GRPC_IMPL_CODEGEN_GPR_SLICE_H
 
-/* WARNING: Please do not use this header. This was added as a temporary measure
+/** WARNING: Please do not use this header. This was added as a temporary
+ * measure
  * to not break some of the external projects that depend on gpr_slice_*
  * functions. We are actively working on moving all the gpr_slice_* references
  * to grpc_slice_* and this file will be removed
diff --git a/include/grpc/impl/codegen/gpr_types.h b/include/grpc/impl/codegen/gpr_types.h
index 34d8156b61..ee4425233d 100644
--- a/include/grpc/impl/codegen/gpr_types.h
+++ b/include/grpc/impl/codegen/gpr_types.h
@@ -42,22 +42,22 @@
 extern "C" {
 #endif
 
-/* The clocks we support. */
+/** The clocks we support. */
 typedef enum {
-  /* Monotonic clock. Epoch undefined. Always moves forwards. */
+  /** Monotonic clock. Epoch undefined. Always moves forwards. */
   GPR_CLOCK_MONOTONIC = 0,
-  /* Realtime clock. May jump forwards or backwards. Settable by
+  /** Realtime clock. May jump forwards or backwards. Settable by
      the system administrator. Has its epoch at 0:00:00 UTC 1 Jan 1970. */
   GPR_CLOCK_REALTIME,
-  /* CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch
+  /** CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch
      undefined. Degrades to GPR_CLOCK_REALTIME on other platforms. */
   GPR_CLOCK_PRECISE,
-  /* Unmeasurable clock type: no base, created by taking the difference
+  /** Unmeasurable clock type: no base, created by taking the difference
      between two times */
   GPR_TIMESPAN
 } gpr_clock_type;
 
-/* Analogous to struct timespec. On some machines, absolute times may be in
+/** Analogous to struct timespec. On some machines, absolute times may be in
  * local time. */
 typedef struct gpr_timespec {
   int64_t tv_sec;
diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h
index b2c38b2c92..dccbd6dbd6 100644
--- a/include/grpc/impl/codegen/grpc_types.h
+++ b/include/grpc/impl/codegen/grpc_types.h
@@ -50,7 +50,7 @@ extern "C" {
 
 typedef enum {
   GRPC_BB_RAW
-  /* Future types may include GRPC_BB_PROTOBUF, etc. */
+  /** Future types may include GRPC_BB_PROTOBUF, etc. */
 } grpc_byte_buffer_type;
 
 typedef struct grpc_byte_buffer {
@@ -162,7 +162,9 @@ typedef struct {
 /** Maximum message length that the channel can receive. Int valued, bytes.
     -1 means unlimited. */
 #define GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH "grpc.max_receive_message_length"
-/** \deprecated For backward compatibility. */
+/** \deprecated For backward compatibility. Use
+   GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH
+    instead. */
 #define GRPC_ARG_MAX_MESSAGE_LENGTH GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH
 /** Maximum message length that the channel can send. Int valued, bytes.
     -1 means unlimited. */
@@ -182,7 +184,7 @@ typedef struct {
 /** Enable/disable support for deadline checking. Defaults to 1, unless
     GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0 */
 #define GRPC_ARG_ENABLE_DEADLINE_CHECKS "grpc.enable_deadline_checking"
-/** Initial sequence number for http2 transports. Int valued. */
+/** Initial stream ID for http2 transports. Int valued. */
 #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
   "grpc.http2.initial_sequence_number"
 /** Amount to read ahead on individual streams. Defaults to 64kb, larger
@@ -206,7 +208,7 @@ typedef struct {
 /** Minimum time (in milliseconds) between successive ping frames being sent */
 #define GRPC_ARG_HTTP2_MIN_TIME_BETWEEN_PINGS_MS \
   "grpc.http2.min_time_between_pings_ms"
-/* Channel arg to override the http2 :scheme header */
+/** 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?
@@ -256,20 +258,24 @@ typedef struct {
 /** The time between the first and second connection attempts, in ms */
 #define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \
   "grpc.initial_reconnect_backoff_ms"
-/* 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. This *should* be used for testing only.
-   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. */
+/** 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. */
 #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
-/* Maximum metadata size, in bytes. */
+/** 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 (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"
@@ -285,9 +291,13 @@ typedef struct {
  * possible. */
 #define GRPC_ARG_USE_CRONET_PACKET_COALESCING \
   "grpc.use_cronet_packet_coalescing"
-/* Channel arg (integer) setting how large a slice to try and read from the wire
-each time recvmsg (or equivalent) is called */
+/** Channel arg (integer) setting how large a slice to try and read from the
+wire
+each time recvmsg (or equivalent) is called **/
 #define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size"
+/** Note this is not a "channel arg" key. This is the default slice size to use
+ * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE
+ * channel arg is unspecified. */
 #define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192
 #define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \
   "grpc.experimental.tcp_min_read_chunk_size"
@@ -334,12 +344,12 @@ typedef enum grpc_call_error {
   GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH
 } grpc_call_error;
 
-/* Default send/receive message size limits in bytes. -1 for unlimited. */
-/* TODO(roth) Make this match the default receive limit after next release */
+/** Default send/receive message size limits in bytes. -1 for unlimited. */
+/** TODO(roth) Make this match the default receive limit after next release */
 #define GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH -1
 #define GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH (4 * 1024 * 1024)
 
-/* Write Flags: */
+/** Write Flags: */
 /** Hint that the write may be buffered and need not go out on the wire
     immediately. GRPC is free to buffer the message until the next non-buffered
     write, or until writes_done, but it need not buffer completely or at all. */
@@ -350,7 +360,7 @@ typedef enum grpc_call_error {
 /** Mask of all valid flags. */
 #define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS)
 
-/* Initial metadata flags */
+/** Initial metadata flags */
 /** Signal that the call is idempotent */
 #define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u)
 /** Signal that the call should not return UNAVAILABLE before it has started */
@@ -373,7 +383,8 @@ typedef enum grpc_call_error {
 
 /** A single metadata element */
 typedef struct grpc_metadata {
-  /* the key, value values are expected to line up with grpc_mdelem: if changing
+  /** the key, value values are expected to line up with grpc_mdelem: if
+     changing
      them, update metadata.h at the same time. */
   grpc_slice key;
   grpc_slice value;
@@ -507,7 +518,7 @@ typedef struct grpc_op {
       size_t trailing_metadata_count;
       grpc_metadata *trailing_metadata;
       grpc_status_code status;
-      /* optional: set to NULL if no details need sending, non-NULL if they do
+      /** optional: set to NULL if no details need sending, non-NULL if they do
        * pointer will not be retained past the start_batch call
        */
       grpc_slice *status_details;
@@ -547,10 +558,10 @@ typedef struct grpc_op {
 
 /** Information requested from the channel. */
 typedef struct {
-  /* If non-NULL, will be set to point to a string indicating the LB
+  /** If non-NULL, will be set to point to a string indicating the LB
    * policy name.  Caller takes ownership. */
   char **lb_policy_name;
-  /* If non-NULL, will be set to point to a string containing the
+  /** If non-NULL, will be set to point to a string containing the
    * service config used by the channel in JSON form. */
   char **service_config_json;
 } grpc_channel_info;
@@ -594,9 +605,9 @@ typedef enum {
 
 #define GRPC_CQ_CURRENT_VERSION 1
 typedef struct grpc_completion_queue_attributes {
-  /* The version number of this structure. More fields might be added to this
+  /** The version number of this structure. More fields might be added to this
      structure in future. */
-  int version; /* Set to GRPC_CQ_CURRENT_VERSION */
+  int version; /** Set to GRPC_CQ_CURRENT_VERSION */
 
   grpc_cq_completion_type cq_completion_type;
 
diff --git a/include/grpc/impl/codegen/propagation_bits.h b/include/grpc/impl/codegen/propagation_bits.h
index 4b64558764..f58edb0e8b 100644
--- a/include/grpc/impl/codegen/propagation_bits.h
+++ b/include/grpc/impl/codegen/propagation_bits.h
@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Propagation bits: this can be bitwise or-ed to form propagation_mask for
+/** Propagation bits: this can be bitwise or-ed to form propagation_mask for
  * grpc_call */
 /** Propagate deadline */
 #define GRPC_PROPAGATE_DEADLINE ((uint32_t)1)
@@ -50,7 +50,7 @@ extern "C" {
 /** Propagate cancellation */
 #define GRPC_PROPAGATE_CANCELLATION ((uint32_t)8)
 
-/* Default propagation mask: clients of the core API are encouraged to encode
+/** Default propagation mask: clients of the core API are encouraged to encode
    deltas from this in their implementations... ie write:
    GRPC_PROPAGATE_DEFAULTS & ~GRPC_PROPAGATE_DEADLINE to disable deadline
    propagation. Doing so gives flexibility in the future to define new
diff --git a/include/grpc/impl/codegen/slice.h b/include/grpc/impl/codegen/slice.h
index b89a3f7910..5c01c87cb8 100644
--- a/include/grpc/impl/codegen/slice.h
+++ b/include/grpc/impl/codegen/slice.h
@@ -43,7 +43,7 @@
 
 typedef struct grpc_slice grpc_slice;
 
-/* Slice API
+/** Slice API
 
    A slice represents a contiguous reference counted array of bytes.
    It is cheap to take references to a slice, and it is cheap to create a
@@ -63,14 +63,14 @@ typedef struct grpc_slice_refcount_vtable {
   uint32_t (*hash)(grpc_slice slice);
 } grpc_slice_refcount_vtable;
 
-/* Reference count container for grpc_slice. Contains function pointers to
+/** Reference count container for grpc_slice. Contains function pointers to
    increment and decrement reference counts. Implementations should cleanup
    when the reference count drops to zero.
    Typically client code should not touch this, and use grpc_slice_malloc,
    grpc_slice_new, or grpc_slice_new_with_len instead. */
 typedef struct grpc_slice_refcount {
   const grpc_slice_refcount_vtable *vtable;
-  /* If a subset of this slice is taken, use this pointer for the refcount.
+  /** If a subset of this slice is taken, use this pointer for the refcount.
      Typically points back to the refcount itself, however iterning
      implementations can use this to avoid a verification step on each hash
      or equality check */
@@ -79,7 +79,7 @@ typedef struct grpc_slice_refcount {
 
 #define GRPC_SLICE_INLINED_SIZE (sizeof(size_t) + sizeof(uint8_t *) - 1)
 
-/* A grpc_slice s, if initialized, represents the byte range
+/** A grpc_slice s, if initialized, represents the byte range
    s.bytes[0..s.length-1].
 
    It can have an associated ref count which has a destruction routine to be run
@@ -104,23 +104,23 @@ struct grpc_slice {
 
 #define GRPC_SLICE_BUFFER_INLINE_ELEMENTS 8
 
-/* Represents an expandable array of slices, to be interpreted as a
+/** Represents an expandable array of slices, to be interpreted as a
    single item. */
 typedef struct {
-  /* This is for internal use only. External users (i.e any code outside grpc
+  /** This is for internal use only. External users (i.e any code outside grpc
    * core) MUST NOT use this field */
   grpc_slice *base_slices;
 
-  /* slices in the array (Points to the first valid grpc_slice in the array) */
+  /** slices in the array (Points to the first valid grpc_slice in the array) */
   grpc_slice *slices;
-  /* the number of slices in the array */
+  /** the number of slices in the array */
   size_t count;
-  /* the number of slices allocated in the array. External users (i.e any code
+  /** the number of slices allocated in the array. External users (i.e any code
    * outside grpc core) MUST NOT use this field */
   size_t capacity;
-  /* the combined length of all slices in the array */
+  /** the combined length of all slices in the array */
   size_t length;
-  /* inlined elements to avoid allocations */
+  /** inlined elements to avoid allocations */
   grpc_slice inlined[GRPC_SLICE_BUFFER_INLINE_ELEMENTS];
 } grpc_slice_buffer;
 
diff --git a/include/grpc/impl/codegen/status.h b/include/grpc/impl/codegen/status.h
index 29e4570f7c..a2ad6b19e6 100644
--- a/include/grpc/impl/codegen/status.h
+++ b/include/grpc/impl/codegen/status.h
@@ -39,40 +39,40 @@ extern "C" {
 #endif
 
 typedef enum {
-  /* Not an error; returned on success */
+  /** Not an error; returned on success */
   GRPC_STATUS_OK = 0,
 
-  /* The operation was cancelled (typically by the caller). */
+  /** The operation was cancelled (typically by the caller). */
   GRPC_STATUS_CANCELLED = 1,
 
-  /* Unknown error.  An example of where this error may be returned is
+  /** Unknown error.  An example of where this error may be returned is
      if a Status value received from another address space belongs to
      an error-space that is not known in this address space.  Also
      errors raised by APIs that do not return enough error information
      may be converted to this error. */
   GRPC_STATUS_UNKNOWN = 2,
 
-  /* Client specified an invalid argument.  Note that this differs
+  /** Client specified an invalid argument.  Note that this differs
      from FAILED_PRECONDITION.  INVALID_ARGUMENT indicates arguments
      that are problematic regardless of the state of the system
      (e.g., a malformed file name). */
   GRPC_STATUS_INVALID_ARGUMENT = 3,
 
-  /* Deadline expired before operation could complete.  For operations
+  /** Deadline expired before operation could complete.  For operations
      that change the state of the system, this error may be returned
      even if the operation has completed successfully.  For example, a
      successful response from a server could have been delayed long
      enough for the deadline to expire. */
   GRPC_STATUS_DEADLINE_EXCEEDED = 4,
 
-  /* Some requested entity (e.g., file or directory) was not found. */
+  /** Some requested entity (e.g., file or directory) was not found. */
   GRPC_STATUS_NOT_FOUND = 5,
 
-  /* Some entity that we attempted to create (e.g., file or directory)
+  /** Some entity that we attempted to create (e.g., file or directory)
      already exists. */
   GRPC_STATUS_ALREADY_EXISTS = 6,
 
-  /* The caller does not have permission to execute the specified
+  /** The caller does not have permission to execute the specified
      operation.  PERMISSION_DENIED must not be used for rejections
      caused by exhausting some resource (use RESOURCE_EXHAUSTED
      instead for those errors).  PERMISSION_DENIED must not be
@@ -80,15 +80,15 @@ typedef enum {
      instead for those errors). */
   GRPC_STATUS_PERMISSION_DENIED = 7,
 
-  /* The request does not have valid authentication credentials for the
+  /** The request does not have valid authentication credentials for the
      operation. */
   GRPC_STATUS_UNAUTHENTICATED = 16,
 
-  /* Some resource has been exhausted, perhaps a per-user quota, or
+  /** Some resource has been exhausted, perhaps a per-user quota, or
      perhaps the entire file system is out of space. */
   GRPC_STATUS_RESOURCE_EXHAUSTED = 8,
 
-  /* Operation was rejected because the system is not in a state
+  /** Operation was rejected because the system is not in a state
      required for the operation's execution.  For example, directory
      to be deleted may be non-empty, an rmdir operation is applied to
      a non-directory, etc.
@@ -109,14 +109,14 @@ typedef enum {
           read-modify-write on the same resource. */
   GRPC_STATUS_FAILED_PRECONDITION = 9,
 
-  /* The operation was aborted, typically due to a concurrency issue
+  /** The operation was aborted, typically due to a concurrency issue
      like sequencer check failures, transaction aborts, etc.
 
      See litmus test above for deciding between FAILED_PRECONDITION,
      ABORTED, and UNAVAILABLE. */
   GRPC_STATUS_ABORTED = 10,
 
-  /* Operation was attempted past the valid range.  E.g., seeking or
+  /** Operation was attempted past the valid range.  E.g., seeking or
      reading past end of file.
 
      Unlike INVALID_ARGUMENT, this error indicates a problem that may
@@ -133,26 +133,31 @@ typedef enum {
      they are done. */
   GRPC_STATUS_OUT_OF_RANGE = 11,
 
-  /* Operation is not implemented or not supported/enabled in this service. */
+  /** Operation is not implemented or not supported/enabled in this service. */
   GRPC_STATUS_UNIMPLEMENTED = 12,
 
-  /* Internal errors.  Means some invariants expected by underlying
+  /** Internal errors.  Means some invariants expected by underlying
      system has been broken.  If you see one of these errors,
      something is very broken. */
   GRPC_STATUS_INTERNAL = 13,
 
-  /* The service is currently unavailable.  This is a most likely a
+  /** 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
+     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.
+
      See litmus test above for deciding between FAILED_PRECONDITION,
      ABORTED, and UNAVAILABLE. */
   GRPC_STATUS_UNAVAILABLE = 14,
 
-  /* Unrecoverable data loss or corruption. */
+  /** Unrecoverable data loss or corruption. */
   GRPC_STATUS_DATA_LOSS = 15,
 
-  /* Force users to include a default branch: */
+  /** Force users to include a default branch: */
   GRPC_STATUS__DO_NOT_USE = -1
 } grpc_status_code;
 
diff --git a/include/grpc/impl/codegen/sync.h b/include/grpc/impl/codegen/sync.h
index 6a8e8a644f..5a135fab4c 100644
--- a/include/grpc/impl/codegen/sync.h
+++ b/include/grpc/impl/codegen/sync.h
@@ -33,7 +33,7 @@
 
 #ifndef GRPC_IMPL_CODEGEN_SYNC_H
 #define GRPC_IMPL_CODEGEN_SYNC_H
-/* Synchronization primitives for GPR.
+/** Synchronization primitives for GPR.
 
    The type  gpr_mu              provides a non-reentrant mutex (lock).
 
diff --git a/include/grpc/slice.h b/include/grpc/slice.h
index 9c4b158ae8..bd54bc8150 100644
--- a/include/grpc/slice.h
+++ b/include/grpc/slice.h
@@ -41,11 +41,11 @@
 extern "C" {
 #endif
 
-/* Increment the refcount of s. Requires slice is initialized.
+/** Increment the refcount of s. Requires slice is initialized.
    Returns s. */
 GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
 
-/* Decrement the ref count of s.  If the ref count of s reaches zero, all
+/** Decrement the ref count of s.  If the ref count of s reaches zero, all
    slices sharing the ref count are destroyed, and considered no longer
    initialized.  If s is ultimately derived from a call to grpc_slice_new(start,
    len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is
@@ -53,15 +53,15 @@ GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
    where dest!=NULL , then (*dest)(start, len).  Requires s initialized.  */
 GPRAPI void grpc_slice_unref(grpc_slice s);
 
-/* Copy slice - create a new slice that contains the same data as s */
+/** Copy slice - create a new slice that contains the same data as s */
 GPRAPI grpc_slice grpc_slice_copy(grpc_slice s);
 
-/* Create a slice pointing at some data. Calls malloc to allocate a refcount
+/** Create a slice pointing at some data. Calls malloc to allocate a refcount
    for the object, and arranges that destroy will be called with the pointer
    passed in at destruction. */
 GPRAPI grpc_slice grpc_slice_new(void *p, size_t len, void (*destroy)(void *));
 
-/* Equivalent to grpc_slice_new, but with a separate pointer that is
+/** Equivalent to grpc_slice_new, but with a separate pointer that is
    passed to the destroy function.  This function can be useful when
    the data is part of a larger structure that must be destroyed when
    the data is no longer needed. */
@@ -69,12 +69,12 @@ GPRAPI grpc_slice grpc_slice_new_with_user_data(void *p, size_t len,
                                                 void (*destroy)(void *),
                                                 void *user_data);
 
-/* Equivalent to grpc_slice_new, but with a two argument destroy function that
+/** Equivalent to grpc_slice_new, but with a two argument destroy function that
    also takes the slice length. */
 GPRAPI grpc_slice grpc_slice_new_with_len(void *p, size_t len,
                                           void (*destroy)(void *, size_t));
 
-/* Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
+/** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
    call.
    Aborts if malloc() fails. */
 GPRAPI grpc_slice grpc_slice_malloc(size_t length);
@@ -86,13 +86,13 @@ GPRAPI grpc_slice grpc_slice_malloc_large(size_t length);
                       .data.inlined = {.length = (uint8_t)(len)}} \
        : grpc_slice_malloc_large((len)))
 
-/* Intern a slice:
+/** Intern a slice:
 
    The return value for two invocations of this function with  the same sequence
    of bytes is a slice which points to the same memory. */
 GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
 
-/* Create a slice by copying a string.
+/** Create a slice by copying a string.
    Does not preserve null terminators.
    Equivalent to:
      size_t len = strlen(source);
@@ -100,29 +100,29 @@ GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
      memcpy(slice->data, source, len); */
 GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source);
 
-/* Create a slice by copying a buffer.
+/** Create a slice by copying a buffer.
    Equivalent to:
      grpc_slice slice = grpc_slice_malloc(len);
      memcpy(slice->data, source, len); */
 GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char *source, size_t len);
 
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
 GPRAPI grpc_slice grpc_slice_from_static_string(const char *source);
 
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
 GPRAPI grpc_slice grpc_slice_from_static_buffer(const void *source, size_t len);
 
-/* Return a result slice derived from s, which shares a ref count with \a s,
+/** Return a result slice derived from s, which shares a ref count with \a s,
    where result.data==s.data+begin, and result.length==end-begin. The ref count
    of \a s is increased by one. Do not assign result back to \a s.
    Requires s initialized, begin <= end, begin <= s.length, and
    end <= source->length. */
 GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end);
 
-/* The same as grpc_slice_sub, but without altering the ref count */
+/** The same as grpc_slice_sub, but without altering the ref count */
 GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end);
 
-/* Splits s into two: modifies s to be s[0:split], and returns a new slice,
+/** Splits s into two: modifies s to be s[0:split], and returns a new slice,
    sharing a refcount with s, that contains s[split:s.length].
    Requires s intialized, split <= s.length */
 GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice *s, size_t split);
@@ -133,13 +133,13 @@ typedef enum {
   GRPC_SLICE_REF_BOTH = 1 + 2
 } grpc_slice_ref_whom;
 
-/* The same as grpc_slice_split_tail, but with an option to skip altering
+/** The same as grpc_slice_split_tail, but with an option to skip altering
  * refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to
  * grpc_slice_split_tail(...)) */
 GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice *s, size_t split,
                                                   grpc_slice_ref_whom ref_whom);
 
-/* Splits s into two: modifies s to be s[split:s.length], and returns a new
+/** Splits s into two: modifies s to be s[split:s.length], and returns a new
    slice, sharing a refcount with s, that contains s[0:split].
    Requires s intialized, split <= s.length */
 GPRAPI grpc_slice grpc_slice_split_head(grpc_slice *s, size_t split);
@@ -151,35 +151,36 @@ GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b);
 
 GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b);
 
-/* Returns <0 if a < b, ==0 if a == b, >0 if a > b
+/** Returns <0 if a < b, ==0 if a == b, >0 if a > b
    The order is arbitrary, and is not guaranteed to be stable across different
    versions of the API. */
 GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b);
 GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char *b);
 GPRAPI int grpc_slice_buf_cmp(grpc_slice a, const void *b, size_t blen);
 
-/* return non-zero if the first blen bytes of a are equal to b */
+/** return non-zero if the first blen bytes of a are equal to b */
 GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void *b, size_t blen);
 
-/* return the index of the last instance of \a c in \a s, or -1 if not found */
+/** return the index of the last instance of \a c in \a s, or -1 if not found */
 GPRAPI int grpc_slice_rchr(grpc_slice s, char c);
 GPRAPI int grpc_slice_chr(grpc_slice s, char c);
 
-/* return the index of the first occurance of \a needle in \a haystack, or -1 if
+/** return the index of the first occurance of \a needle in \a haystack, or -1
+ * if
  * it's not found */
 GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle);
 
 GPRAPI uint32_t grpc_slice_hash(grpc_slice s);
 
-/* Do two slices point at the same memory, with the same length
+/** Do two slices point at the same memory, with the same length
    If a or b is inlined, actually compares data */
 GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b);
 
-/* Return a slice pointing to newly allocated memory that has the same contents
+/** Return a slice pointing to newly allocated memory that has the same contents
  * as \a s */
 GPRAPI grpc_slice grpc_slice_dup(grpc_slice a);
 
-/* Return a copy of slice as a C string. Offers no protection against embedded
+/** Return a copy of slice as a C string. Offers no protection against embedded
    NULL's. Returned string must be freed with gpr_free. */
 GPRAPI char *grpc_slice_to_c_string(grpc_slice s);
 
diff --git a/include/grpc/slice_buffer.h b/include/grpc/slice_buffer.h
index cdbd74776c..0d593954dc 100644
--- a/include/grpc/slice_buffer.h
+++ b/include/grpc/slice_buffer.h
@@ -40,15 +40,15 @@
 extern "C" {
 #endif
 
-/* initialize a slice buffer */
+/** initialize a slice buffer */
 GPRAPI void grpc_slice_buffer_init(grpc_slice_buffer *sb);
-/* destroy a slice buffer - unrefs any held elements */
+/** destroy a slice buffer - unrefs any held elements */
 GPRAPI void grpc_slice_buffer_destroy(grpc_slice_buffer *sb);
-/* Add an element to a slice buffer - takes ownership of the slice.
+/** Add an element to a slice buffer - takes ownership of the slice.
    This function is allowed to concatenate the passed in slice to the end of
    some other slice if desired by the slice buffer. */
 GPRAPI void grpc_slice_buffer_add(grpc_slice_buffer *sb, grpc_slice slice);
-/* add an element to a slice buffer - takes ownership of the slice and returns
+/** add an element to a slice buffer - takes ownership of the slice and returns
    the index of the slice.
    Guarantees that the slice will not be concatenated at the end of another
    slice (i.e. the data for this slice will begin at the first byte of the
@@ -59,35 +59,35 @@ GPRAPI size_t grpc_slice_buffer_add_indexed(grpc_slice_buffer *sb,
                                             grpc_slice slice);
 GPRAPI void grpc_slice_buffer_addn(grpc_slice_buffer *sb, grpc_slice *slices,
                                    size_t n);
-/* add a very small (less than 8 bytes) amount of data to the end of a slice
+/** add a very small (less than 8 bytes) amount of data to the end of a slice
    buffer: returns a pointer into which to add the data */
 GPRAPI uint8_t *grpc_slice_buffer_tiny_add(grpc_slice_buffer *sb, size_t len);
-/* pop the last buffer, but don't unref it */
+/** pop the last buffer, but don't unref it */
 GPRAPI void grpc_slice_buffer_pop(grpc_slice_buffer *sb);
-/* clear a slice buffer, unref all elements */
+/** clear a slice buffer, unref all elements */
 GPRAPI void grpc_slice_buffer_reset_and_unref(grpc_slice_buffer *sb);
-/* swap the contents of two slice buffers */
+/** swap the contents of two slice buffers */
 GPRAPI void grpc_slice_buffer_swap(grpc_slice_buffer *a, grpc_slice_buffer *b);
-/* move all of the elements of src into dst */
+/** move all of the elements of src into dst */
 GPRAPI void grpc_slice_buffer_move_into(grpc_slice_buffer *src,
                                         grpc_slice_buffer *dst);
-/* remove n bytes from the end of a slice buffer */
+/** remove n bytes from the end of a slice buffer */
 GPRAPI void grpc_slice_buffer_trim_end(grpc_slice_buffer *src, size_t n,
                                        grpc_slice_buffer *garbage);
-/* move the first n bytes of src into dst */
+/** move the first n bytes of src into dst */
 GPRAPI void grpc_slice_buffer_move_first(grpc_slice_buffer *src, size_t n,
                                          grpc_slice_buffer *dst);
-/* move the first n bytes of src into dst without adding references */
+/** move the first n bytes of src into dst without adding references */
 GPRAPI void grpc_slice_buffer_move_first_no_ref(grpc_slice_buffer *src,
                                                 size_t n,
                                                 grpc_slice_buffer *dst);
-/* move the first n bytes of src into dst (copying them) */
+/** move the first n bytes of src into dst (copying them) */
 GPRAPI void grpc_slice_buffer_move_first_into_buffer(grpc_exec_ctx *exec_ctx,
                                                      grpc_slice_buffer *src,
                                                      size_t n, void *dst);
-/* take the first slice in the slice buffer */
+/** take the first slice in the slice buffer */
 GPRAPI grpc_slice grpc_slice_buffer_take_first(grpc_slice_buffer *src);
-/* undo the above with (a possibly different) \a slice */
+/** undo the above with (a possibly different) \a slice */
 GPRAPI void grpc_slice_buffer_undo_take_first(grpc_slice_buffer *src,
                                               grpc_slice slice);
 
diff --git a/include/grpc/support/alloc.h b/include/grpc/support/alloc.h
index 017d75a3d0..99be2d161a 100644
--- a/include/grpc/support/alloc.h
+++ b/include/grpc/support/alloc.h
@@ -44,26 +44,26 @@ extern "C" {
 
 typedef struct gpr_allocation_functions {
   void *(*malloc_fn)(size_t size);
-  void *(*zalloc_fn)(size_t size); /* if NULL, uses malloc_fn then memset */
+  void *(*zalloc_fn)(size_t size); /** if NULL, uses malloc_fn then memset */
   void *(*realloc_fn)(void *ptr, size_t size);
   void (*free_fn)(void *ptr);
 } gpr_allocation_functions;
 
-/* malloc.
+/** malloc.
  * If size==0, always returns NULL. Otherwise this function never returns NULL.
  * The pointer returned is suitably aligned for any kind of variable it could
  * contain.
  */
 GPRAPI void *gpr_malloc(size_t size);
-/* like malloc, but zero all bytes before returning them */
+/** like malloc, but zero all bytes before returning them */
 GPRAPI void *gpr_zalloc(size_t size);
-/* free */
+/** free */
 GPRAPI void gpr_free(void *ptr);
-/* realloc, never returns NULL */
+/** realloc, never returns NULL */
 GPRAPI void *gpr_realloc(void *p, size_t size);
-/* aligned malloc, never returns NULL, will align to 1 << alignment_log */
+/** aligned malloc, never returns NULL, will align to 1 << alignment_log */
 GPRAPI void *gpr_malloc_aligned(size_t size, size_t alignment_log);
-/* free memory allocated by gpr_malloc_aligned */
+/** free memory allocated by gpr_malloc_aligned */
 GPRAPI void gpr_free_aligned(void *ptr);
 
 /** Request the family of allocation functions in \a functions be used. NOTE
diff --git a/include/grpc/support/cmdline.h b/include/grpc/support/cmdline.h
index 5b7bc82594..5a83afb464 100644
--- a/include/grpc/support/cmdline.h
+++ b/include/grpc/support/cmdline.h
@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Simple command line parser.
+/** Simple command line parser.
 
    Supports flags that can be specified as -foo, --foo, --no-foo, -no-foo, etc
    And integers, strings that can be specified as -foo=4, -foo blah, etc
@@ -68,32 +68,32 @@ extern "C" {
 
 typedef struct gpr_cmdline gpr_cmdline;
 
-/* Construct a command line parser: takes a short description of the tool
+/** Construct a command line parser: takes a short description of the tool
    doing the parsing */
 GPRAPI gpr_cmdline *gpr_cmdline_create(const char *description);
-/* Add an integer parameter, with a name (used on the command line) and some
+/** Add an integer parameter, with a name (used on the command line) and some
    helpful text (used in the command usage) */
 GPRAPI void gpr_cmdline_add_int(gpr_cmdline *cl, const char *name,
                                 const char *help, int *value);
-/* The same, for a boolean flag */
+/** The same, for a boolean flag */
 GPRAPI void gpr_cmdline_add_flag(gpr_cmdline *cl, const char *name,
                                  const char *help, int *value);
-/* And for a string */
+/** And for a string */
 GPRAPI void gpr_cmdline_add_string(gpr_cmdline *cl, const char *name,
                                    const char *help, char **value);
-/* Set a callback for non-named arguments */
+/** Set a callback for non-named arguments */
 GPRAPI void gpr_cmdline_on_extra_arg(
     gpr_cmdline *cl, const char *name, const char *help,
     void (*on_extra_arg)(void *user_data, const char *arg), void *user_data);
-/* Enable surviving failure: default behavior is to exit the process */
+/** Enable surviving failure: default behavior is to exit the process */
 GPRAPI void gpr_cmdline_set_survive_failure(gpr_cmdline *cl);
-/* Parse the command line; returns 1 on success, on failure either dies
+/** Parse the command line; returns 1 on success, on failure either dies
    (by default) or returns 0 if gpr_cmdline_set_survive_failure() has been
    called */
 GPRAPI int gpr_cmdline_parse(gpr_cmdline *cl, int argc, char **argv);
-/* Destroy the parser */
+/** Destroy the parser */
 GPRAPI void gpr_cmdline_destroy(gpr_cmdline *cl);
-/* Get a string describing usage */
+/** Get a string describing usage */
 GPRAPI char *gpr_cmdline_usage_string(gpr_cmdline *cl, const char *argv0);
 
 #ifdef __cplusplus
diff --git a/include/grpc/support/cpu.h b/include/grpc/support/cpu.h
index 6734feb391..0da02ada22 100644
--- a/include/grpc/support/cpu.h
+++ b/include/grpc/support/cpu.h
@@ -40,13 +40,13 @@
 extern "C" {
 #endif
 
-/* Interface providing CPU information for currently running system */
+/** Interface providing CPU information for currently running system */
 
-/* Return the number of CPU cores on the current system. Will return 0 if
+/** Return the number of CPU cores on the current system. Will return 0 if
    the information is not available. */
 GPRAPI unsigned gpr_cpu_num_cores(void);
 
-/* Return the CPU on which the current thread is executing; N.B. This should
+/** Return the CPU on which the current thread is executing; N.B. This should
    be considered advisory only - it is possible that the thread is switched
    to a different CPU at any time. Returns a value in range
    [0, gpr_cpu_num_cores() - 1] */
diff --git a/include/grpc/support/histogram.h b/include/grpc/support/histogram.h
index c545038528..96db758878 100644
--- a/include/grpc/support/histogram.h
+++ b/include/grpc/support/histogram.h
@@ -48,7 +48,7 @@ GPRAPI gpr_histogram *gpr_histogram_create(double resolution,
 GPRAPI void gpr_histogram_destroy(gpr_histogram *h);
 GPRAPI void gpr_histogram_add(gpr_histogram *h, double x);
 
-/* The following merges the second histogram into the first. It only works
+/** The following merges the second histogram into the first. It only works
    if they have the same buckets and resolution. Returns 0 on failure, 1
    on success */
 GPRAPI int gpr_histogram_merge(gpr_histogram *dst, const gpr_histogram *src);
diff --git a/include/grpc/support/host_port.h b/include/grpc/support/host_port.h
index 15819543a9..ee786beb19 100644
--- a/include/grpc/support/host_port.h
+++ b/include/grpc/support/host_port.h
@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Given a host and port, creates a newly-allocated string of the form
+/** Given a host and port, creates a newly-allocated string of the form
    "host:port" or "[ho:st]:port", depending on whether the host contains colons
    like an IPv6 literal.  If the host is already bracketed, then additional
    brackets will not be added.
@@ -52,7 +52,7 @@ extern "C" {
    In the unlikely event of an error, returns -1 and sets *out to NULL. */
 GPRAPI int gpr_join_host_port(char **out, const char *host, int port);
 
-/* Given a name in the form "host:port" or "[ho:st]:port", split into hostname
+/** Given a name in the form "host:port" or "[ho:st]:port", split into hostname
    and port number, into newly allocated strings, which must later be
    destroyed using gpr_free().
    Return 1 on success, 0 on failure. Guarantees *host and *port == NULL on
diff --git a/include/grpc/support/log.h b/include/grpc/support/log.h
index 88346cc9f4..917b01183a 100644
--- a/include/grpc/support/log.h
+++ b/include/grpc/support/log.h
@@ -44,7 +44,7 @@
 extern "C" {
 #endif
 
-/* GPR log API.
+/** GPR log API.
 
    Usage (within grpc):
 
@@ -54,7 +54,7 @@ extern "C" {
    gpr_log(GPR_INFO, "hello world");
    gpr_log(GPR_ERROR, "%d %s!!", argument1, argument2); */
 
-/* The severity of a log message - use the #defines below when calling into
+/** The severity of a log message - use the #defines below when calling into
    gpr_log to additionally supply file and line data */
 typedef enum gpr_log_severity {
   GPR_LOG_SEVERITY_DEBUG,
@@ -64,15 +64,15 @@ typedef enum gpr_log_severity {
 
 #define GPR_LOG_VERBOSITY_UNSET -1
 
-/* Returns a string representation of the log severity */
+/** Returns a string representation of the log severity */
 const char *gpr_log_severity_string(gpr_log_severity severity);
 
-/* Macros to build log contexts at various severity levels */
+/** Macros to build log contexts at various severity levels */
 #define GPR_DEBUG __FILE__, __LINE__, GPR_LOG_SEVERITY_DEBUG
 #define GPR_INFO __FILE__, __LINE__, GPR_LOG_SEVERITY_INFO
 #define GPR_ERROR __FILE__, __LINE__, GPR_LOG_SEVERITY_ERROR
 
-/* Log a message. It's advised to use GPR_xxx above to generate the context
+/** Log a message. It's advised to use GPR_xxx above to generate the context
  * for each message */
 GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity,
                     const char *format, ...) GPR_PRINT_FORMAT_CHECK(4, 5);
@@ -80,12 +80,12 @@ GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity,
 GPRAPI void gpr_log_message(const char *file, int line,
                             gpr_log_severity severity, const char *message);
 
-/* Set global log verbosity */
+/** Set global log verbosity */
 GPRAPI void gpr_set_log_verbosity(gpr_log_severity min_severity_to_print);
 
 GPRAPI void gpr_log_verbosity_init();
 
-/* Log overrides: applications can use this API to intercept logging calls
+/** Log overrides: applications can use this API to intercept logging calls
    and use their own implementations */
 
 typedef struct {
@@ -98,7 +98,7 @@ typedef struct {
 typedef void (*gpr_log_func)(gpr_log_func_args *args);
 GPRAPI void gpr_set_log_function(gpr_log_func func);
 
-/* abort() the process if x is zero, having written a line to the log.
+/** abort() the process if x is zero, having written a line to the log.
 
    Intended for internal invariants.  If the error can be recovered from,
    without the possibility of corruption, or might best be reflected via
diff --git a/include/grpc/support/log_windows.h b/include/grpc/support/log_windows.h
index 943a8e908b..b8a4078464 100644
--- a/include/grpc/support/log_windows.h
+++ b/include/grpc/support/log_windows.h
@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Returns a string allocated with gpr_malloc that contains a UTF-8
+/** Returns a string allocated with gpr_malloc that contains a UTF-8
  * formatted error message, corresponding to the error messageid.
  * Use in conjunction with GetLastError() et al.
  */
diff --git a/include/grpc/support/string_util.h b/include/grpc/support/string_util.h
index 5ab983d15d..8b268a6006 100644
--- a/include/grpc/support/string_util.h
+++ b/include/grpc/support/string_util.h
@@ -40,13 +40,13 @@
 extern "C" {
 #endif
 
-/* String utility functions */
+/** String utility functions */
 
-/* Returns a copy of src that can be passed to gpr_free().
+/** Returns a copy of src that can be passed to gpr_free().
    If allocation fails or if src is NULL, returns NULL. */
 GPRAPI char *gpr_strdup(const char *src);
 
-/* printf to a newly-allocated string.  The set of supported formats may vary
+/** printf to a newly-allocated string.  The set of supported formats may vary
    between platforms.
 
    On success, returns the number of bytes printed (excluding the final '\0'),
diff --git a/include/grpc/support/subprocess.h b/include/grpc/support/subprocess.h
index 2baa43ece2..dfb80989dc 100644
--- a/include/grpc/support/subprocess.h
+++ b/include/grpc/support/subprocess.h
@@ -42,13 +42,13 @@ extern "C" {
 
 typedef struct gpr_subprocess gpr_subprocess;
 
-/* .exe on windows, empty on unices */
+/** .exe on windows, empty on unices */
 GPRAPI const char *gpr_subprocess_binary_extension();
 
 GPRAPI gpr_subprocess *gpr_subprocess_create(int argc, const char **argv);
-/* if subprocess has not been joined, kill it */
+/** if subprocess has not been joined, kill it */
 GPRAPI void gpr_subprocess_destroy(gpr_subprocess *p);
-/* returns exit status; can be called at most once */
+/** returns exit status; can be called at most once */
 GPRAPI int gpr_subprocess_join(gpr_subprocess *p);
 GPRAPI void gpr_subprocess_interrupt(gpr_subprocess *p);
 
diff --git a/include/grpc/support/sync.h b/include/grpc/support/sync.h
index 5cfeecb601..7d727a0cfc 100644
--- a/include/grpc/support/sync.h
+++ b/include/grpc/support/sync.h
@@ -41,49 +41,49 @@
 extern "C" {
 #endif
 
-/* --- Mutex interface ---
+/** --- Mutex interface ---
 
    At most one thread may hold an exclusive lock on a mutex at any given time.
    Actions taken by a thread that holds a mutex exclusively happen after
    actions taken by all previous holders of the mutex.  Variables of type
    gpr_mu are uninitialized when first declared.  */
 
-/* Initialize *mu.  Requires:  *mu uninitialized.  */
+/** Initialize *mu.  Requires:  *mu uninitialized.  */
 GPRAPI void gpr_mu_init(gpr_mu *mu);
 
-/* Cause *mu no longer to be initialized, freeing any memory in use.  Requires:
+/** Cause *mu no longer to be initialized, freeing any memory in use.  Requires:
    *mu initialized; no other concurrent operation on *mu.  */
 GPRAPI void gpr_mu_destroy(gpr_mu *mu);
 
-/* Wait until no thread has a lock on *mu, cause the calling thread to own an
+/** Wait until no thread has a lock on *mu, cause the calling thread to own an
    exclusive lock on *mu, then return.  May block indefinitely or crash if the
    calling thread has a lock on *mu.  Requires:  *mu initialized.  */
 GPRAPI void gpr_mu_lock(gpr_mu *mu);
 
-/* Release an exclusive lock on *mu held by the calling thread.  Requires:  *mu
+/** Release an exclusive lock on *mu held by the calling thread.  Requires:  *mu
    initialized; the calling thread holds an exclusive lock on *mu.  */
 GPRAPI void gpr_mu_unlock(gpr_mu *mu);
 
-/* Without blocking, attempt to acquire an exclusive lock on *mu for the
+/** Without blocking, attempt to acquire an exclusive lock on *mu for the
    calling thread, then return non-zero iff success.  Fail, if any thread holds
    the lock; succeeds with high probability if no thread holds the lock.
    Requires:  *mu initialized.  */
 GPRAPI int gpr_mu_trylock(gpr_mu *mu);
 
-/* --- Condition variable interface ---
+/** --- Condition variable interface ---
 
    A while-loop should be used with gpr_cv_wait() when waiting for conditions
    to become true.  See the example below.  Variables of type gpr_cv are
    uninitialized when first declared.  */
 
-/* Initialize *cv.  Requires:  *cv uninitialized.  */
+/** Initialize *cv.  Requires:  *cv uninitialized.  */
 GPRAPI void gpr_cv_init(gpr_cv *cv);
 
-/* Cause *cv no longer to be initialized, freeing any memory in use.  Requires:
+/** Cause *cv no longer to be initialized, freeing any memory in use.  Requires:
    *cv initialized; no other concurrent operation on *cv.*/
 GPRAPI void gpr_cv_destroy(gpr_cv *cv);
 
-/* Atomically release *mu and wait on *cv.  When the calling thread is woken
+/** Atomically release *mu and wait on *cv.  When the calling thread is woken
    from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu)
    and return whether the deadline was exceeded.  Use
    abs_deadline==gpr_inf_future for no deadline.  abs_deadline can be either
@@ -92,83 +92,83 @@ GPRAPI void gpr_cv_destroy(gpr_cv *cv);
    holds an exclusive lock on *mu.  */
 GPRAPI int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline);
 
-/* If any threads are waiting on *cv, wake at least one.
+/** If any threads are waiting on *cv, wake at least one.
    Clients may treat this as an optimization of gpr_cv_broadcast()
    for use in the case where waking more than one waiter is not useful.
    Requires:  *cv initialized.  */
 GPRAPI void gpr_cv_signal(gpr_cv *cv);
 
-/* Wake all threads waiting on *cv.  Requires:  *cv initialized.  */
+/** Wake all threads waiting on *cv.  Requires:  *cv initialized.  */
 GPRAPI void gpr_cv_broadcast(gpr_cv *cv);
 
-/* --- One-time initialization ---
+/** --- One-time initialization ---
 
    gpr_once must be declared with static storage class, and initialized with
    GPR_ONCE_INIT.  e.g.,
      static gpr_once once_var = GPR_ONCE_INIT;     */
 
-/* Ensure that (*init_routine)() has been called exactly once (for the
+/** Ensure that (*init_routine)() has been called exactly once (for the
    specified gpr_once instance) and then return.
    If multiple threads call gpr_once() on the same gpr_once instance, one of
    them will call (*init_routine)(), and the others will block until that call
    finishes.*/
 GPRAPI void gpr_once_init(gpr_once *once, void (*init_routine)(void));
 
-/* --- One-time event notification ---
+/** --- One-time event notification ---
 
   These operations act on a gpr_event, which should be initialized with
   gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g.,
        static gpr_event event_var = GPR_EVENT_INIT;
   It requires no destruction.  */
 
-/* Initialize *ev. */
+/** Initialize *ev. */
 GPRAPI void gpr_event_init(gpr_event *ev);
 
-/* Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
+/** Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
    Requires:  *ev initialized; value != NULL; no prior or concurrent calls to
    gpr_event_set(ev, ...) since initialization.  */
 GPRAPI void gpr_event_set(gpr_event *ev, void *value);
 
-/* Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
+/** Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
    completed.  If the result is non-NULL, all operations that occurred prior to
    the gpr_event_set(ev, ...) set will be visible after this call returns.
    Requires:  *ev initialized.  This operation is faster than acquiring a mutex
    on most platforms.  */
 GPRAPI void *gpr_event_get(gpr_event *ev);
 
-/* Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
+/** Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
    exceeded, then return gpr_event_get(ev).  Requires:  *ev initialized.  Use
    abs_deadline==gpr_inf_future for no deadline.  When the event has been
    signalled before the call, this operation is faster than acquiring a mutex
    on most platforms.  */
 GPRAPI void *gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline);
 
-/* --- Reference counting ---
+/** --- Reference counting ---
 
    These calls act on the type gpr_refcount.  It requires no destruction.  */
 
-/* Initialize *r to value n.  */
+/** Initialize *r to value n.  */
 GPRAPI void gpr_ref_init(gpr_refcount *r, int n);
 
-/* Increment the reference count *r.  Requires *r initialized. */
+/** Increment the reference count *r.  Requires *r initialized. */
 GPRAPI void gpr_ref(gpr_refcount *r);
 
-/* Increment the reference count *r.  Requires *r initialized.
+/** Increment the reference count *r.  Requires *r initialized.
    Crashes if refcount is zero */
 GPRAPI void gpr_ref_non_zero(gpr_refcount *r);
 
-/* Increment the reference count *r by n.  Requires *r initialized, n > 0. */
+/** Increment the reference count *r by n.  Requires *r initialized, n > 0. */
 GPRAPI void gpr_refn(gpr_refcount *r, int n);
 
-/* Decrement the reference count *r and return non-zero iff it has reached
+/** Decrement the reference count *r and return non-zero iff it has reached
    zero. .  Requires *r initialized. */
 GPRAPI int gpr_unref(gpr_refcount *r);
 
-/* Return non-zero iff the reference count of *r is one, and thus is owned
+/** Return non-zero iff the reference count of *r is one, and thus is owned
    by exactly one object. */
 GPRAPI int gpr_ref_is_unique(gpr_refcount *r);
 
-/* --- Stats counters ---
+/** --- Stats counters ---
 
    These calls act on the integral type gpr_stats_counter.  It requires no
    destruction.  Static instances may be initialized with
@@ -176,16 +176,16 @@ GPRAPI int gpr_ref_is_unique(gpr_refcount *r);
    Beware:  These operations do not imply memory barriers.  Do not use them to
    synchronize other events.  */
 
-/* Initialize *c to the value n. */
+/** Initialize *c to the value n. */
 GPRAPI void gpr_stats_init(gpr_stats_counter *c, intptr_t n);
 
-/* *c += inc.  Requires: *c initialized. */
+/** *c += inc.  Requires: *c initialized. */
 GPRAPI void gpr_stats_inc(gpr_stats_counter *c, intptr_t inc);
 
-/* Return *c.  Requires: *c initialized. */
+/** Return *c.  Requires: *c initialized. */
 GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter *c);
 
-/* ==================Example use of interface===================
+/** ==================Example use of interface===================
    A producer-consumer queue of up to N integers,
    illustrating the use of the calls in this interface. */
 #if 0
diff --git a/include/grpc/support/thd.h b/include/grpc/support/thd.h
index 0514288793..ba6cbb0cb0 100644
--- a/include/grpc/support/thd.h
+++ b/include/grpc/support/thd.h
@@ -33,7 +33,7 @@
 
 #ifndef GRPC_SUPPORT_THD_H
 #define GRPC_SUPPORT_THD_H
-/* Thread interface for GPR.
+/** Thread interface for GPR.
 
    Types
         gpr_thd_id        a thread identifier.
@@ -50,37 +50,37 @@ extern "C" {
 
 typedef uintptr_t gpr_thd_id;
 
-/* Thread creation options. */
+/** Thread creation options. */
 typedef struct {
-  int flags; /* Opaque field. Get and set with accessors below. */
+  int flags; /** Opaque field. Get and set with accessors below. */
 } gpr_thd_options;
 
-/* Create a new thread running (*thd_body)(arg) and place its thread identifier
+/** Create a new thread running (*thd_body)(arg) and place its thread identifier
    in *t, and return true.  If there are insufficient resources, return false.
    If options==NULL, default options are used.
    The thread is immediately runnable, and exits when (*thd_body)() returns.  */
 GPRAPI int gpr_thd_new(gpr_thd_id *t, void (*thd_body)(void *arg), void *arg,
                        const gpr_thd_options *options);
 
-/* Return a gpr_thd_options struct with all fields set to defaults. */
+/** Return a gpr_thd_options struct with all fields set to defaults. */
 GPRAPI gpr_thd_options gpr_thd_options_default(void);
 
-/* Set the thread to become detached on startup - this is the default. */
+/** Set the thread to become detached on startup - this is the default. */
 GPRAPI void gpr_thd_options_set_detached(gpr_thd_options *options);
 
-/* Set the thread to become joinable - mutually exclusive with detached. */
+/** Set the thread to become joinable - mutually exclusive with detached. */
 GPRAPI void gpr_thd_options_set_joinable(gpr_thd_options *options);
 
-/* Returns non-zero if the option detached is set. */
+/** Returns non-zero if the option detached is set. */
 GPRAPI int gpr_thd_options_is_detached(const gpr_thd_options *options);
 
-/* Returns non-zero if the option joinable is set. */
+/** Returns non-zero if the option joinable is set. */
 GPRAPI int gpr_thd_options_is_joinable(const gpr_thd_options *options);
 
-/* Returns the identifier of the current thread. */
+/** Returns the identifier of the current thread. */
 GPRAPI gpr_thd_id gpr_thd_currentid(void);
 
-/* Blocks until the specified thread properly terminates.
+/** Blocks until the specified thread properly terminates.
    Calling this on a detached thread has unpredictable results. */
 GPRAPI void gpr_thd_join(gpr_thd_id t);
 
diff --git a/include/grpc/support/time.h b/include/grpc/support/time.h
index 66bcfca6ed..2384f5e906 100644
--- a/include/grpc/support/time.h
+++ b/include/grpc/support/time.h
@@ -43,11 +43,11 @@
 extern "C" {
 #endif
 
-/* Time constants. */
+/** Time constants. */
 GPRAPI gpr_timespec
-gpr_time_0(gpr_clock_type type); /* The zero time interval. */
-GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /* The far future */
-GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type);   /* The far past. */
+gpr_time_0(gpr_clock_type type); /** The zero time interval. */
+GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /** The far future */
+GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type);   /** The far past. */
 
 #define GPR_MS_PER_SEC 1000
 #define GPR_US_PER_SEC 1000000
@@ -56,28 +56,28 @@ GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type);   /* The far past. */
 #define GPR_NS_PER_US 1000
 #define GPR_US_PER_MS 1000
 
-/* initialize time subsystem */
+/** initialize time subsystem */
 GPRAPI void gpr_time_init(void);
 
-/* Return the current time measured from the given clocks epoch. */
+/** Return the current time measured from the given clocks epoch. */
 GPRAPI gpr_timespec gpr_now(gpr_clock_type clock);
 
-/* Convert a timespec from one clock to another */
+/** Convert a timespec from one clock to another */
 GPRAPI gpr_timespec gpr_convert_clock_type(gpr_timespec t,
                                            gpr_clock_type target_clock);
 
-/* Return -ve, 0, or +ve according to whether a < b, a == b, or a > b
+/** Return -ve, 0, or +ve according to whether a < b, a == b, or a > b
    respectively.  */
 GPRAPI int gpr_time_cmp(gpr_timespec a, gpr_timespec b);
 
 GPRAPI gpr_timespec gpr_time_max(gpr_timespec a, gpr_timespec b);
 GPRAPI gpr_timespec gpr_time_min(gpr_timespec a, gpr_timespec b);
 
-/* Add and subtract times.  Calculations saturate at infinities. */
+/** Add and subtract times.  Calculations saturate at infinities. */
 GPRAPI gpr_timespec gpr_time_add(gpr_timespec a, gpr_timespec b);
 GPRAPI gpr_timespec gpr_time_sub(gpr_timespec a, gpr_timespec b);
 
-/* Return a timespec representing a given number of time units. INT64_MIN is
+/** Return a timespec representing a given number of time units. INT64_MIN is
    interpreted as gpr_inf_past, and INT64_MAX as gpr_inf_future.  */
 GPRAPI gpr_timespec gpr_time_from_micros(int64_t x, gpr_clock_type clock_type);
 GPRAPI gpr_timespec gpr_time_from_nanos(int64_t x, gpr_clock_type clock_type);
@@ -88,12 +88,12 @@ GPRAPI gpr_timespec gpr_time_from_hours(int64_t x, gpr_clock_type clock_type);
 
 GPRAPI int32_t gpr_time_to_millis(gpr_timespec timespec);
 
-/* Return 1 if two times are equal or within threshold of each other,
+/** Return 1 if two times are equal or within threshold of each other,
    0 otherwise */
 GPRAPI int gpr_time_similar(gpr_timespec a, gpr_timespec b,
                             gpr_timespec threshold);
 
-/* Sleep until at least 'until' - an absolute timeout */
+/** Sleep until at least 'until' - an absolute timeout */
 GPRAPI void gpr_sleep_until(gpr_timespec until);
 
 GPRAPI double gpr_timespec_to_micros(gpr_timespec t);
diff --git a/include/grpc/support/tls.h b/include/grpc/support/tls.h
index 5365449f0d..a48c73b26f 100644
--- a/include/grpc/support/tls.h
+++ b/include/grpc/support/tls.h
@@ -36,7 +36,7 @@
 
 #include <grpc/support/port_platform.h>
 
-/* Thread local storage.
+/** Thread local storage.
 
    A minimal wrapper that should be implementable across many compilers,
    and implementable efficiently across most modern compilers.
diff --git a/include/grpc/support/tls_gcc.h b/include/grpc/support/tls_gcc.h
index a47275f6f4..9667524d34 100644
--- a/include/grpc/support/tls_gcc.h
+++ b/include/grpc/support/tls_gcc.h
@@ -38,7 +38,7 @@
 
 #include <grpc/support/log.h>
 
-/* Thread local storage based on gcc compiler primitives.
+/** Thread local storage based on gcc compiler primitives.
    #include tls.h to use this - and see that file for documentation */
 
 #ifndef NDEBUG
@@ -58,7 +58,7 @@ struct gpr_gcc_thread_local {
     *((tls)->inited) = true;               \
   } while (0)
 
-/* It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */
+/** It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */
 #define gpr_tls_destroy(tls)      \
   do {                            \
     GPR_ASSERT(*((tls)->inited)); \
diff --git a/include/grpc/support/tls_msvc.h b/include/grpc/support/tls_msvc.h
index efc653b4e4..4ef8eeff0d 100644
--- a/include/grpc/support/tls_msvc.h
+++ b/include/grpc/support/tls_msvc.h
@@ -34,7 +34,7 @@
 #ifndef GRPC_SUPPORT_TLS_MSVC_H
 #define GRPC_SUPPORT_TLS_MSVC_H
 
-/* Thread local storage based on ms visual c compiler primitives.
+/** Thread local storage based on ms visual c compiler primitives.
    #include tls.h to use this - and see that file for documentation */
 
 struct gpr_msvc_thread_local {
diff --git a/include/grpc/support/tls_pthread.h b/include/grpc/support/tls_pthread.h
index e681da2ecd..7cc6a40645 100644
--- a/include/grpc/support/tls_pthread.h
+++ b/include/grpc/support/tls_pthread.h
@@ -37,7 +37,7 @@
 #include <grpc/support/log.h> /* for GPR_ASSERT */
 #include <pthread.h>
 
-/* Thread local storage based on pthread library calls.
+/** Thread local storage based on pthread library calls.
    #include tls.h to use this - and see that file for documentation */
 
 struct gpr_pthread_thread_local {
diff --git a/include/grpc/support/useful.h b/include/grpc/support/useful.h
index 9d8314e4be..c261fbaa14 100644
--- a/include/grpc/support/useful.h
+++ b/include/grpc/support/useful.h
@@ -34,12 +34,12 @@
 #ifndef GRPC_SUPPORT_USEFUL_H
 #define GRPC_SUPPORT_USEFUL_H
 
-/* useful macros that don't belong anywhere else */
+/** useful macros that don't belong anywhere else */
 
 #define GPR_MIN(a, b) ((a) < (b) ? (a) : (b))
 #define GPR_MAX(a, b) ((a) > (b) ? (a) : (b))
 #define GPR_CLAMP(a, min, max) ((a) < (min) ? (min) : (a) > (max) ? (max) : (a))
-/* rotl, rotr assume x is unsigned */
+/** rotl, rotr assume x is unsigned */
 #define GPR_ROTL(x, n) (((x) << (n)) | ((x) >> (sizeof(x) * 8 - (n))))
 #define GPR_ROTR(x, n) (((x) >> (n)) | ((x) << (sizeof(x) * 8 - (n))))