grpc 1.3.4 → 1.4.0

data/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);
 

data/include/grpc/grpc.h

@@ -93,55 +93,6 @@ GRPCAPI const char *grpc_version_string(void);
 /** Return a string specifying what the 'g' in gRPC stands for */
 GRPCAPI const char *grpc_g_stands_for(void);
 
-/** Specifies the type of APIs to use to pop events from the completion queue */
-typedef enum {
-  /* Events are popped out by calling grpc_completion_queue_next() API ONLY */
-  GRPC_CQ_NEXT = 1,
-
-  /* Events are popped out by calling grpc_completion_queue_pluck() API ONLY */
-  GRPC_CQ_PLUCK
-} grpc_cq_completion_type;
-
-/** Completion queues internally MAY maintain a set of file descriptors in a
-    structure called 'pollset'. This enum specifies if a completion queue has an
-    associated pollset and any restrictions on the type of file descriptors that
-    can be present in the pollset.
-
-    I/O progress can only be made when grpc_completion_queue_next() or
-    grpc_completion_queue_pluck() are called on the completion queue (unless the
-    grpc_cq_polling_type is GRPC_CQ_NON_POLLING) and hence it is very important
-    to actively call these APIs */
-typedef enum {
-  /** The completion queue will have an associated pollset and there is no
-      restriction on the type of file descriptors the pollset may contain */
-  GRPC_CQ_DEFAULT_POLLING,
-
-  /* Similar to GRPC_CQ_DEFAULT_POLLING except that the completion queues will
-     not contain any 'listening file descriptors' (i.e file descriptors used to
-     listen to incoming channels) */
-  GRPC_CQ_NON_LISTENING,
-
-  /* The completion queue will not have an associated pollset. Note that
-     grpc_completion_queue_next() or grpc_completion_queue_pluck() MUST still be
-     called to pop events from the completion queue; it is not required to call
-     them actively to make I/O progress */
-  GRPC_CQ_NON_POLLING
-} grpc_cq_polling_type;
-
-#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
-     structure in future. */
-  int version; /* Set to GRPC_CQ_CURRENT_VERSION */
-
-  grpc_cq_completion_type cq_completion_type;
-
-  grpc_cq_polling_type cq_polling_type;
-} grpc_completion_queue_attributes;
-
-/** The completion queue factory structure is opaque to the callers of grpc */
-typedef struct grpc_completion_queue_factory grpc_completion_queue_factory;
-
 /** Returns the completion queue factory based on the attributes. MAY return a
     NULL if no factory can be found */
 GRPCAPI const grpc_completion_queue_factory *
@@ -159,7 +110,9 @@ GRPCAPI grpc_completion_queue *grpc_completion_queue_create_for_pluck(
     void *reserved);
 
 /** Create a completion queue */
-GRPCAPI grpc_completion_queue *grpc_completion_queue_create(void *reserved);
+GRPCAPI grpc_completion_queue *grpc_completion_queue_create(
+    const grpc_completion_queue_factory *factory,
+    const grpc_completion_queue_attributes *attributes, void *reserved);
 
 /** Blocks until an event is available, the completion queue is being shut down,
     or deadline is reached.
@@ -269,6 +222,10 @@ GRPCAPI grpc_call *grpc_channel_create_registered_call(
     grpc_completion_queue *completion_queue, void *registered_call_handle,
     gpr_timespec deadline, void *reserved);
 
+/** Allocate memory in the grpc_call arena: this memory is automatically
+    discarded at call completion */
+GRPCAPI void *grpc_call_arena_alloc(grpc_call *call, size_t size);
+
 /** Start a batch of operations defined in the array ops; when complete, post a
     completion of type 'tag' to the completion queue bound to the call.
     The order of ops specified in the batch has no significance.
@@ -300,12 +257,6 @@ GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call *call,
     functionality. Instead, use grpc_auth_context. */
 GRPCAPI char *grpc_call_get_peer(grpc_call *call);
 
-struct grpc_load_reporting_cost_context;
-
-/* Associate costs contained in \a cost_context to \a call. */
-GRPCAPI void grpc_call_set_load_reporting_cost_context(
-    grpc_call *call, struct grpc_load_reporting_cost_context *context);
-
 struct census_context;
 
 /** Set census context for a call; Must be called before first call to
@@ -342,7 +293,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
@@ -351,7 +302,7 @@ GRPCAPI void grpc_channel_destroy(grpc_channel *channel);
 /** Called by clients to cancel an RPC on the server.
     Can be called multiple times, from any thread.
     THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status
-    are thread-safe, and can be called at any point before grpc_call_destroy
+    are thread-safe, and can be called at any point before grpc_call_unref
     is called.*/
 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call *call, void *reserved);
 
@@ -366,9 +317,13 @@ GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call *call,
                                                      const char *description,
                                                      void *reserved);
 
-/** Destroy a call.
-    THREAD SAFETY: grpc_call_destroy is thread-compatible */
-GRPCAPI void grpc_call_destroy(grpc_call *call);
+/** Ref a call.
+    THREAD SAFETY: grpc_call_unref is thread-compatible */
+GRPCAPI void grpc_call_ref(grpc_call *call);
+
+/** Unref a call.
+    THREAD SAFETY: grpc_call_unref is thread-compatible */
+GRPCAPI void grpc_call_unref(grpc_call *call);
 
 /** Request notification of a new call.
     Once a call is received, a notification tagged with \a tag_new is added to
@@ -429,15 +384,6 @@ GRPCAPI void grpc_server_register_completion_queue(grpc_server *server,
                                                    grpc_completion_queue *cq,
                                                    void *reserved);
 
-/** Register a non-listening completion queue with the server. This API is
-    similar to grpc_server_register_completion_queue except that the server will
-    not use this completion_queue to listen to any incoming channels.
-
-    Registering a non-listening completion queue will have negative performance
-    impact and hence this API is not recommended for production use cases. */
-GRPCAPI void grpc_server_register_non_listening_completion_queue(
-    grpc_server *server, grpc_completion_queue *q, void *reserved);
-
 /** Add a HTTP2 over plaintext over tcp listener.
     Returns bound port number on success, 0 on failure.
     REQUIRES: server not started */

data/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,19 +146,19 @@ 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.
-   - pem_roots_cert is the NULL-terminated string containing the PEM encoding
+/** 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
      GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
@@ -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. */