cpp doc nits

20 files changed, 70 insertions, 59 deletions

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: