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 a8af74175b..0ad3cc4252 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 0e559ac53e..0d8f901818 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 cee68467c7..9957712a96 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;
--
GitLab