Merge pull request #562 from ctiller/dox3
More channel argument documentation.
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h
index 621740e..12949d5 100644
--- a/include/grpc/grpc.h
+++ b/include/grpc/grpc.h
@@ -92,7 +92,12 @@
} value;
} grpc_arg;
-/* An array of arguments that can be passed around */
+/* An array of arguments that can be passed around.
+ Used to set optional channel-level configuration.
+ These configuration options are modelled as key-value pairs as defined
+ by grpc_arg; keys are strings to allow easy backwards-compatible extension
+ by arbitrary parties.
+ All evaluation is performed at channel creation time. */
typedef struct {
size_t num_args;
grpc_arg *args;
@@ -411,7 +416,10 @@
grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops,
size_t nops, void *tag);
-/* Create a client channel */
+/* Create a client channel to 'target'. Additional channel level configuration
+ MAY be provided by grpc_channel_args, though the expectation is that most
+ clients will want to simply pass NULL. See grpc_channel_args definition
+ for more on this. */
grpc_channel *grpc_channel_create(const char *target,
const grpc_channel_args *args);
@@ -576,7 +584,9 @@
grpc_byte_buffer **optional_payload,
grpc_completion_queue *cq_bound_to_call, void *tag_new);
-/* Create a server */
+/* Create a server. Additional configuration for each incoming channel can
+ be specified with args. If no additional configuration is needed, args can
+ be NULL. See grpc_channel_args for more. */
grpc_server *grpc_server_create(grpc_completion_queue *cq,
const grpc_channel_args *args);