1 files changed, 66 insertions, 25 deletions

diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h
index d81d2e735d..0ea970417e 100644
--- a/include/grpc++/completion_queue.h
+++ b/include/grpc++/completion_queue.h
@@ -31,6 +31,8 @@
  *
  */
 
+/// A completion queue implements a concurrent producer-consumer queue, with two
+/// main methods, \a Next and \a AsyncNext.
 #ifndef GRPCXX_COMPLETION_QUEUE_H
 #define GRPCXX_COMPLETION_QUEUE_H
 
@@ -67,53 +69,79 @@ class UnknownMethodHandler;
 
 class Channel;
 class ClientContext;
+class CompletionQueueTag;
 class CompletionQueue;
 class RpcMethod;
 class Server;
 class ServerBuilder;
 class ServerContext;
 
-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
-  virtual bool FinalizeResult(void** tag, bool* status) = 0;
-};
-
-// grpc_completion_queue wrapper class
+/// A thin wrapper around \a grpc_completion_queue (see / \a
+/// src/core/surface/completion_queue.h).
 class CompletionQueue : public GrpcLibrary {
  public:
+  /// Default constructor. Implicitly creates a \a grpc_completion_queue
+  /// instance.
   CompletionQueue();
+
+  /// Wrap \a take, taking ownership of the instance.
+  ///
+  /// \param take The completion queue instance to wrap. Ownership is taken.
   explicit CompletionQueue(grpc_completion_queue* take);
-  ~CompletionQueue() GRPC_OVERRIDE;
 
-  // Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT
-  enum NextStatus { SHUTDOWN, GOT_EVENT, TIMEOUT };
+  /// Destructor. Destroys the owned wrapped completion queue / instance.
+  ~CompletionQueue() GRPC_OVERRIDE;
 
-  // Nonblocking (until deadline) read from queue.
-  // Cannot rely on result of tag or ok if return is TIMEOUT
+  /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT.
+  enum NextStatus {
+    SHUTDOWN,   ///< The completion queue has been shutdown.
+    GOT_EVENT,  ///< Got a new event; \a tag will be filled in with its
+                ///< associated value; \a ok indicating its success.
+    TIMEOUT     ///< deadline was reached.
+  };
+
+  /// Read from the queue, blocking up to \a deadline (or the queue's shutdown).
+  /// Both \a tag and \a ok are updated upon success (if an event is available
+  /// within the \a deadline).  A \a tag points to an arbitrary location usually
+  /// employed to uniquely identify an event.
+  ///
+  /// \param tag[out] Upon sucess, updated to point to the event's tag.
+  /// \param ok[out] Upon sucess, true if read a regular event, false otherwise.
+  /// \param deadline[in] How long to block in wait for an event.
+  ///
+  /// \return The type of event read.
   template <typename T>
   NextStatus AsyncNext(void** tag, bool* ok, const T& deadline) {
     TimePoint<T> deadline_tp(deadline);
     return AsyncNextInternal(tag, ok, deadline_tp.raw_time());
   }
 
-  // Blocking read from queue.
-  // Returns false if the queue is ready for destruction, true if event
-
+  /// Read from the queue, blocking until an event is available or the queue is
+  /// shutting down.
+  ///
+  /// \param tag[out] Updated to point to the read event's tag.
+  /// \param ok[out] true if read a regular event, false otherwise.
+  ///
+  /// \return true if read a regular event, false if the queue is shutting down.
   bool Next(void** tag, bool* ok) {
     return (AsyncNextInternal(tag, ok, gpr_inf_future(GPR_CLOCK_REALTIME)) !=
             SHUTDOWN);
   }
 
-  // Shutdown has to be called, and the CompletionQueue can only be
-  // destructed when false is returned from Next().
+  /// Request the shutdown of the queue.
+  ///
+  /// \warning This method must be called at some point. Once invoked, \a Next
+  /// 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.
   void Shutdown();
 
+  /// Returns a \em raw pointer to the underlying \a grpc_completion_queue
+  /// instance.
+  ///
+  /// \warning Remember that the returned instance is owned. No transfer of
+  /// owership is performed.
   grpc_completion_queue* cq() { return cq_; }
 
  private:
@@ -150,16 +178,29 @@ class CompletionQueue : public GrpcLibrary {
 
   NextStatus AsyncNextInternal(void** tag, bool* ok, gpr_timespec deadline);
 
-  // Wraps grpc_completion_queue_pluck.
-  // Cannot be mixed with calls to Next().
+  /// Wraps \a grpc_completion_queue_pluck.
+  /// \warning Must not be mixed with calls to \a Next.
   bool Pluck(CompletionQueueTag* tag);
 
-  // Does a single polling pluck on tag
+  /// Performs a single polling pluck on \a tag.
   void TryPluck(CompletionQueueTag* tag);
 
   grpc_completion_queue* cq_;  // owned
 };
 
+/// An interface allowing implementors to process and filter event tags.
+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
+  virtual bool FinalizeResult(void** tag, bool* status) = 0;
+};
+
+/// A specific type of completion queue used by the processing of notifications
+/// by servers. Instantiated by \a ServerBuilder.
 class ServerCompletionQueue : public CompletionQueue {
  private:
   friend class ServerBuilder;