Fix review comments

include/grpc++/impl/codegen/async_stream.h

@@ -53,7 +53,7 @@ class ClientAsyncStreamingInterface {
   /// Request notification of the reading of the initial metadata. Completion
   /// will be notified by \a tag on the associated completion queue.
   /// This call is optional, but if it is used, it cannot be used concurrently
-  /// with Read
+  /// with or after the \a Read method.
   ///
   /// \param[in] tag Tag identifying this request.
   virtual void ReadInitialMetadata(void* tag) = 0;
@@ -74,8 +74,8 @@ class AsyncReaderInterface {
 
   /// Read a message of type \a R into \a msg. Completion will be notified by \a
   /// tag on the associated completion queue.
-  /// This is thread-safe with respect to other streaming APIs except for Finish
-  /// on the same stream.
+  /// This is thread-safe with respect to other streaming APIs except for \a
+  /// Finish on the same stream.
   ///
   /// \param[out] msg Where to eventually store the read message.
   /// \param[in] tag The tag identifying the operation.
@@ -93,7 +93,7 @@ class AsyncWriterInterface {
   /// Only one write may be outstanding at any given time. This means that
   /// after calling Write, one must wait to receive \a tag from the completion
   /// queue BEFORE calling Write again.
-  /// This is thread-safe with respect to Read
+  /// This is thread-safe with respect to \a Read
   ///
   /// \param[in] msg The message to be written.
   /// \param[in] tag The tag identifying the operation.
@@ -164,7 +164,7 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface,
                                    public AsyncWriterInterface<W> {
  public:
   /// Signal the client is done with the writes.
-  /// Thread-safe with respect to Read
+  /// Thread-safe with respect to \a Read
   ///
   /// \param[in] tag The tag identifying the operation.
   virtual void WritesDone(void* tag) = 0;
@@ -236,7 +236,7 @@ class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface,
                                          public AsyncReaderInterface<R> {
  public:
   /// Signal the client is done with the writes.
-  /// Thread-safe with respect to Read
+  /// Thread-safe with respect to \a Read
   ///
   /// \param[in] tag The tag identifying the operation.
   virtual void WritesDone(void* tag) = 0;

include/grpc++/impl/codegen/completion_queue.h

@@ -34,15 +34,16 @@
 /// A completion queue implements a concurrent producer-consumer queue, with
 /// two main API-exposed methods: \a Next and \a AsyncNext. These
 /// methods are the essential component of the gRPC C++ asynchronous API.
-/// There is also a Shutdown method to indicate that a given completion queue
+/// There is also a \a Shutdown method to indicate that a given completion queue
 /// will no longer have regular events. This must be called before the
 /// completion queue is destroyed.
 /// All completion queue APIs are thread-safe and may be used concurrently with
 /// any other completion queue API invocation; it is acceptable to have
-/// multiple threads calling Next or AsyncNext on the same or different
-/// completion queues, or to call these methods concurrently with a Shutdown
-/// elsewhere. All of these should be completed, though, before a completion
-/// queue destructor is called.
+/// multiple threads calling \a Next or \a AsyncNext on the same or different
+/// completion queues, or to call these methods concurrently with a \a Shutdown
+/// elsewhere.
+/// \remark{All other API calls on completion queue should be completed before
+/// a completion queue destructor is called.}
 #ifndef GRPCXX_IMPL_CODEGEN_COMPLETION_QUEUE_H
 #define GRPCXX_IMPL_CODEGEN_COMPLETION_QUEUE_H
 

include/grpc++/impl/codegen/sync_stream.h

@@ -71,8 +71,8 @@ class ReaderInterface {
   virtual ~ReaderInterface() {}
 
   /// Blocking read a message and parse to \a msg. Returns \a true on success.
-  /// This is thread-safe with respect to other streaming APIs except for Finish
-  /// on the same stream. (Finish must be called as described above.)
+  /// This is thread-safe with respect to other streaming APIs except for \a
+  /// Finish on the same stream. (\a Finish must be called as described above.)
   ///
   /// \param[out] msg The read message.
   ///
@@ -89,7 +89,7 @@ class WriterInterface {
   virtual ~WriterInterface() {}
 
   /// Blocking write \a msg to the stream with options.
-  /// This is thread-safe with respect to Read
+  /// This is thread-safe with respect to \a Read
   ///
   /// \param msg The message to be written to the stream.
   /// \param options Options affecting the write operation.
@@ -98,7 +98,7 @@ class WriterInterface {
   virtual bool Write(const W& msg, const WriteOptions& options) = 0;
 
   /// Blocking write \a msg to the stream with default options.
-  /// This is thread-safe with respect to Read
+  /// This is thread-safe with respect to \a Read
   ///
   /// \param msg The message to be written to the stream.
   ///
@@ -179,7 +179,7 @@ class ClientWriterInterface : public ClientStreamingInterface,
  public:
   /// Half close writing from the client.
   /// Block until currently-pending writes are completed.
-  /// Thread safe with respect to Read operations only
+  /// Thread safe with respect to \a Read operations only
   ///
   /// \return Whether the writes were successful.
   virtual bool WritesDone() = 0;
@@ -263,7 +263,7 @@ class ClientReaderWriterInterface : public ClientStreamingInterface,
   virtual void WaitForInitialMetadata() = 0;
 
   /// Block until currently-pending writes are completed.
-  /// Thread-safe with respect to Read
+  /// Thread-safe with respect to \a Read
   ///
   /// \return Whether the writes were successful.
   virtual bool WritesDone() = 0;