From c4de3a2c24ebf512127d706689edc8e6170b0ee2 Mon Sep 17 00:00:00 2001
From: David Garcia Quintas <dgq@google.com>
Date: Wed, 26 Aug 2015 11:36:08 -0700
Subject: [PATCH] Docstrings for Channel, ChannelCreate and ChannelArguments.

---
 include/grpc++/channel.h                   | 13 +++++------
 include/grpc++/create_channel.h            |  7 +++++-
 include/grpc++/support/channel_arguments.h | 25 +++++++++++++---------
 3 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/include/grpc++/channel.h b/include/grpc++/channel.h
index a8af74175b4..0ad3cc42522 100644
--- a/include/grpc++/channel.h
+++ b/include/grpc++/channel.h
@@ -65,18 +65,19 @@ class ClientAsyncReaderWriter;
 template <class R>
 class ClientAsyncResponseReader;
 
+/// Channels represent a connection to an endpoint. Created by \a CreateChannel.
 class Channel GRPC_FINAL : public GrpcLibrary,
                            public CallHook,
                            public std::enable_shared_from_this<Channel> {
  public:
   ~Channel();
 
-  // Get the current channel state. If the channel is in IDLE and try_to_connect
-  // is set to true, try to connect.
+  /// Get the current channel state. If the channel is in IDLE and try_to_connect
+  /// is set to true, try to connect.
   grpc_connectivity_state GetState(bool try_to_connect);
 
-  // Return the tag on cq when the channel state is changed or deadline expires.
-  // GetState needs to called to get the current state.
+  /// Return the tag on cq when the channel state is changed or deadline expires.
+  /// GetState needs to called to get the current state.
   template <typename T>
   void NotifyOnStateChange(grpc_connectivity_state last_observed, T deadline,
                            CompletionQueue* cq, void* tag) {
@@ -84,8 +85,8 @@ class Channel GRPC_FINAL : public GrpcLibrary,
     NotifyOnStateChangeImpl(last_observed, deadline_tp.raw_time(), cq, tag);
   }
 
-  // Blocking wait for channel state change or deadline expiration.
-  // GetState needs to called to get the current state.
+  /// Blocking wait for channel state change or deadline expiration.
+  /// GetState needs to called to get the current state.
   template <typename T>
   bool WaitForStateChange(grpc_connectivity_state last_observed, T deadline) {
     TimePoint<T> deadline_tp(deadline);
diff --git a/include/grpc++/create_channel.h b/include/grpc++/create_channel.h
index 0e559ac53e4..0d8f9018184 100644
--- a/include/grpc++/create_channel.h
+++ b/include/grpc++/create_channel.h
@@ -42,7 +42,12 @@
 
 namespace grpc {
 
-// If creds does not hold an object or is invalid, a lame channel is returned.
+/// Create a new \a Channel pointing to \a target
+///
+/// \param target The URI of the endpoint to connect to.
+/// \param creds Credentials to use for the created channel. If it does not hold
+/// an object or is invalid, a lame channel is returned.
+/// \param args Options for channel creation.
 std::shared_ptr<Channel> CreateChannel(
     const grpc::string& target, const std::shared_ptr<Credentials>& creds,
     const ChannelArguments& args);
diff --git a/include/grpc++/support/channel_arguments.h b/include/grpc++/support/channel_arguments.h
index cee68467c73..9957712a965 100644
--- a/include/grpc++/support/channel_arguments.h
+++ b/include/grpc++/support/channel_arguments.h
@@ -46,9 +46,9 @@ namespace testing {
 class ChannelArgumentsTest;
 }  // namespace testing
 
-// Options for channel creation. The user can use generic setters to pass
-// key value pairs down to c channel creation code. For grpc related options,
-// concrete setters are provided.
+/// Options for channel creation. The user can use generic setters to pass
+/// key value pairs down to c channel creation code. For grpc related options,
+/// concrete setters are provided.
 class ChannelArguments {
  public:
   ChannelArguments() {}
@@ -62,21 +62,26 @@ class ChannelArguments {
 
   void Swap(ChannelArguments& other);
 
-  // grpc specific channel argument setters
-  // Set target name override for SSL host name checking.
+  /// Populates this instance with the arguments from \a channel_args. Does not
+  /// take ownership of \a channel_args.
+  ///
+  /// Note that the underlying arguments are shared. Changes made to either \a
+  /// channel_args or this instance would be reflected on both.
+  void SetChannelArgs(grpc_channel_args* channel_args) const;
+
+  // gRPC specific channel argument setters
+  /// Set target name override for SSL host name checking.
   void SetSslTargetNameOverride(const grpc::string& name);
   // TODO(yangg) add flow control options
-
-  // Set the compression algorithm for the channel.
+  /// Set the compression algorithm for the channel.
   void SetCompressionAlgorithm(grpc_compression_algorithm algorithm);
 
   // Generic channel argument setters. Only for advanced use cases.
+  /// Set an integer argument \a value under \a key.
   void SetInt(const grpc::string& key, int value);
+  /// Set a textual argument \a value under \a key.
   void SetString(const grpc::string& key, const grpc::string& value);
 
-  // Populates given channel_args with args_, does not take ownership.
-  void SetChannelArgs(grpc_channel_args* channel_args) const;
-
  private:
   friend class SecureCredentials;
   friend class testing::ChannelArgumentsTest;