wip

include/grpc++/auth_context.h

@@ -72,20 +72,26 @@ class AuthPropertyIterator
   const char* name_;
 };
 
+/// Class encapsulating the Authentication Information.
+/// 
+/// It includes the secure identity of the peer, the type of secure transport
+/// used as well as any other properties required by the authorization layer.
 class AuthContext {
  public:
   virtual ~AuthContext() {}
 
-  // A peer identity, in general is one or more properties (in which case they
+  /// A peer identity. 
-  // have the same name).
+  ///
+  /// It is, in general, comprised of one or more properties (in which case they
+  /// have the same name).
   virtual std::vector<grpc::string> GetPeerIdentity() const = 0;
   virtual grpc::string GetPeerIdentityPropertyName() const = 0;
 
-  // Returns all the property values with the given name.
+  /// Returns all the property values with the given name.
   virtual std::vector<grpc::string> FindPropertyValues(
       const grpc::string& name) const = 0;
 
-  // Iteration over all the properties.
+  /// Iteration over all the properties.
   virtual AuthPropertyIterator begin() const = 0;
   virtual AuthPropertyIterator end() const = 0;
 };

include/grpc++/client_context.h

@@ -206,21 +206,32 @@ class ClientContext {
   }
 
 #ifndef GRPC_CXX0X_NO_CHRONO
+  /// Return the deadline for the client call.
   std::chrono::system_clock::time_point deadline() {
     return Timespec2Timepoint(deadline_);
   }
 #endif  // !GRPC_CXX0X_NO_CHRONO
 
-  /// XXX: what's raw about this? is it absolute time?
+  /// Return a \a gpr_timespec representation of the client call's deadline.
   gpr_timespec raw_deadline() { return deadline_; }
 
-  /// XXX what's an authority?
+  /// Set the per call authority header (see
+  /// https://tools.ietf.org/html/rfc7540#section-8.1.2.3).
   void set_authority(const grpc::string& authority) { authority_ = authority; }
 
-  /// XXX: what's an auth context? what is it used for?
+  /// Return the authentication context for this client call.
+  ///
+  /// \see grpc::AuthContext.
   std::shared_ptr<const AuthContext> auth_context() const;
 
-  /// Set credentials for the rpc. XXX: how do credentials work?
+  /// Set credentials for the client call.
+  ///
+  /// A credentials object encapsulates all the state needed by a client to
+  /// authenticate with a server and make various assertions, e.g., about the
+  /// client’s identity, role, or whether it is authorized to make a particular
+  /// call.
+  ///
+  /// \see https://github.com/grpc/grpc-common/blob/master/grpc-auth-support.md
   void set_credentials(const std::shared_ptr<Credentials>& creds) {
     creds_ = creds;
   }

include/grpc++/completion_queue.h

@@ -32,12 +32,8 @@
  */
 
 
-/// A completion queue implements a producer-consumer queue, with two main
+/// A completion queue implements a concurrent producer-consumer queue, with two
-/// methods:
+/// main methods, \a Next and \a AsyncNext.
-///
-/// - Next
-/// - AsyncNext XXX
-///
 #ifndef GRPCXX_COMPLETION_QUEUE_H
 #define GRPCXX_COMPLETION_QUEUE_H
 
@@ -81,35 +77,67 @@ class Server;
 class ServerBuilder;
 class ServerContext;
 
-// grpc_completion_queue wrapper class
+// This class is 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);
+
+  /// Destructor. Destroys the owned wrapped completion queue / instance.
   ~CompletionQueue() GRPC_OVERRIDE;
 
-  // Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT
+  /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT.
   enum NextStatus { SHUTDOWN, GOT_EVENT, TIMEOUT };
 
-  // Nonblocking (until deadline) read from queue.
+  /// Read from the queue, blocking up to \a deadline (or the queue's shutdown).
-  // Cannot rely on result of tag or ok if return is TIMEOUT
+  /// 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.
+  /// Read from the queue, blocking until an event is available or the queue is
-  // Returns false if the queue is ready for destruction, true if event
+  /// 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
+  /// Request the shutdown of the queue.
-  // destructed when false is returned from Next().
+  ///
+  /// \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:
@@ -147,27 +175,29 @@ class CompletionQueue : public GrpcLibrary {
 
   NextStatus AsyncNextInternal(void** tag, bool* ok, gpr_timespec deadline);
 
-  // Wraps grpc_completion_queue_pluck.
+  /// Wraps \a grpc_completion_queue_pluck.
-  // Cannot be mixed with calls to Next().
+  /// \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
+  // Called prior to returning from Next(), return value is the status of the
-  // is the status of the operation (return status is the default thing
+  // operation (return status is the default thing to do). If this function
-  // to do)
+  // returns false, the tag is dropped and not returned from the completion
-  // If this function returns false, the tag is dropped and not returned
+  // queue
-  // 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.
 class ServerCompletionQueue : public CompletionQueue {
  private:
   friend class ServerBuilder;

include/grpc++/server.h

@@ -44,6 +44,10 @@
 #include <grpc++/impl/sync.h>
 #include <grpc++/status.h>
 
+/// The \a Server class models a gRPC server.
+///
+/// Servers are configured and started via \a grpc::ServerBuilder.
+
 struct grpc_server;
 
 namespace grpc {
@@ -57,24 +61,27 @@ class ServerAsyncStreamingInterface;
 class ServerCredentials;
 class ThreadPoolInterface;
 
-// Currently it only supports handling rpcs in a single thread.
 class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
  public:
   ~Server();
 
-  // Shutdown the server, block until all rpc processing finishes.
+  /// Shutdown the server, blocking until all rpc processing finishes.
-  // Forcefully terminate pending calls after deadline expires.
+  /// Forcefully terminate pending calls after \a deadline expires.
+  ///
+  /// \param deadline How long to wait until pending rpcs are forcefully
+  /// terminated.
   template <class T>
   void Shutdown(const T& deadline) {
     ShutdownInternal(TimePoint<T>(deadline).raw_time());
   }
 
-  // Shutdown the server, waiting for all rpc processing to finish.
+  /// Shutdown the server, waiting for all rpc processing to finish.
   void Shutdown() { ShutdownInternal(gpr_inf_future(GPR_CLOCK_MONOTONIC)); }
 
-  // Block waiting for all work to complete (the server must either
+  /// Block waiting for all work to complete.
-  // be shutting down or some other thread must call Shutdown for this
+  ///
-  // function to ever return)
+  /// \warning The server must be either shutting down or some other thread must
+  /// call \a Shutdown for this function to ever return.
   void Wait();
 
  private:
@@ -86,22 +93,53 @@ class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
   class AsyncRequest;
   class ShutdownRequest;
 
-  // ServerBuilder use only
+  /// Server constructors. To be used by \a ServerBuilder only.
+  ///
+  /// \param thread_pool The threadpool instance to use for call processing.
+  /// \param thread_pool_owned Does the server own the \a thread_pool instance?
+  /// \param max_message_size Maximum message length that the channel can
+  /// receive.
   Server(ThreadPoolInterface* thread_pool, bool thread_pool_owned,
          int max_message_size);
-  // Register a service. This call does not take ownership of the service.
+
-  // The service must exist for the lifetime of the Server instance.
+  /// Register a service. This call does not take ownership of the service.
+  /// The service must exist for the lifetime of the Server instance.
   bool RegisterService(const grpc::string* host, RpcService* service);
+
+  /// Register an asynchronous service. This call does not take ownership of the
+  /// service. The service must exist for the lifetime of the Server instance.
   bool RegisterAsyncService(const grpc::string* host,
                             AsynchronousService* service);
+
+  /// Register a generic service. This call does not take ownership of the
+  /// service. The service must exist for the lifetime of the Server instance.
   void RegisterAsyncGenericService(AsyncGenericService* service);
-  // Add a listening port. Can be called multiple times.
+
+  /// Tries to bind \a server to the given \a addr.
+  ///
+  /// It can be invoked multiple times.
+  ///
+  /// \param addr The address to try to bind to the server (eg, localhost:1234,
+  /// 192.168.1.1:31416, [::1]:27182, etc.).
+  /// \params creds The credentials associated with the server.
+  ///
+  /// \return bound port number on sucess, 0 on failure.
+  ///
+  /// \warning It's an error to call this method on an already started server.
+  // TODO(dgq): the "port" part seems to be a misnomer.
   int AddListeningPort(const grpc::string& addr, ServerCredentials* creds);
-  // Start the server.
+
+  /// Start the server.
+  ///
+  /// \return true on a successful shutdown.
   bool Start();
 
   void HandleQueueClosed();
+
+  /// Process one or more incoming calls.
   void RunRpc();
+
+  /// Schedule \a RunRpc to run in the threadpool.
   void ScheduleCallback();
 
   void PerformOpsOnCall(CallOpSetInterface* ops, Call* call) GRPC_OVERRIDE;

include/grpc++/server_credentials.h

@@ -11,7 +11,7 @@
  * notice, this list of conditions and the following disclaimer.
  *     * Redistributions in binary form must reproduce the above
  * copyright notice, this list of conditions and the following disclaimer
- * in the documentation and/or other materials provided with the
+ a * in the documentation and/or other materials provided with the
  * distribution.
  *     * Neither the name of Google Inc. nor the names of its
  * contributors may be used to endorse or promote products derived from
@@ -44,7 +44,7 @@ struct grpc_server;
 namespace grpc {
 class Server;
 
-// grpc_server_credentials wrapper class.
+// Wrapper around \a grpc_server_credentials, a way to authenticate a server.
 class ServerCredentials {
  public:
   virtual ~ServerCredentials();
@@ -52,11 +52,16 @@ class ServerCredentials {
  private:
   friend class ::grpc::Server;
 
+  /// Tries to bind \a server to the given \a addr (eg, localhost:1234,
+  /// 192.168.1.1:31416, [::1]:27182, etc.)
+  ///
+  /// \return bound port number on sucess, 0 on failure.
+  // TODO(dgq): the "port" part seems to be a misnomer.
   virtual int AddPortToServer(const grpc::string& addr,
                               grpc_server* server) = 0;
 };
 
-// Options to create ServerCredentials with SSL
+/// Options to create ServerCredentials with SSL
 struct SslServerCredentialsOptions {
   SslServerCredentialsOptions() : force_client_auth(false) {}
 
@@ -69,10 +74,11 @@ struct SslServerCredentialsOptions {
   bool force_client_auth;
 };
 
-// Builds SSL ServerCredentials given SSL specific options
+/// Builds SSL ServerCredentials given SSL specific options
 std::shared_ptr<ServerCredentials> SslServerCredentials(
     const SslServerCredentialsOptions& options);
 
+/// Builds insecure server credentials.
 std::shared_ptr<ServerCredentials> InsecureServerCredentials();
 
 }  // namespace grpc