Comments on the comments. Meta much?

include/grpc++/client_context.h

@@ -39,10 +39,10 @@
 /// - Initial and trailing metadata coming from the server.
 /// - Get performance metrics (ie, census).
 ///
-/// Context settings are only relevant to the previous/next call (depending on
-/// the method semantics), that is to say, they aren't sticky. Some of these
-/// settings, such as the compression options, can be made persistant at channel
-/// construction time (see \a grpc::CreateChannel).
+/// Context settings are only relevant to the call they are invoked with, that
+/// is to say, they aren't sticky. Some of these settings, such as the
+/// compression options, can be made persistant at channel construction time
+/// (see \a grpc::CreateChannel).
 
 #ifndef GRPCXX_CLIENT_CONTEXT_H
 #define GRPCXX_CLIENT_CONTEXT_H
@@ -148,8 +148,8 @@ class ClientContext {
   ClientContext();
   ~ClientContext();
 
-  /// Create a new \a ClientContext according to \a options (\see
-  /// PropagationOptions).
+  /// Create a new \a ClientContext as a child of an incoming server call,
+  /// according to \a options (\see PropagationOptions).
   ///
   /// \param server_context The source server context to use as the basis for
   /// constructing the client context.
@@ -166,6 +166,8 @@ class ClientContext {
   /// a client call. These are made available at the server side by the \a
   /// grpc::ServerContext::client_metadata() method.
   ///
+  /// \warning This method should only be called before invoking the rpc.
+  ///
   /// \param meta_key The metadata key. If \a meta_value is binary data, it must
   /// end in "-bin".
   /// \param meta_value The metadata value. If its value is binary, it must be
@@ -177,7 +179,9 @@ class ClientContext {
   /// Return a collection of initial metadata key-value pairs. Note that keys
   /// may happen more than once (ie, a \a std::multimap is returned).
   ///
-  /// This should only be called upon a successful reply from the server.
+  /// \warning This method should only be called after initial metadata has been
+  /// received. For streaming calls, see \a
+  /// ClientReaderInterface::WaitForInitialMetadata().
   ///
   /// \return A multimap of initial metadata key-value pairs from the server.
   const std::multimap<grpc::string, grpc::string>& GetServerInitialMetadata() {
@@ -189,6 +193,8 @@ class ClientContext {
   /// Return a collection of trailing metadata key-value pairs. Note that keys
   /// may happen more than once (ie, a \a std::multimap is returned).
   ///
+  /// \warning This method is only callable once the stream has finished.
+  ///
   /// \return A multimap of metadata trailing key-value pairs from the server.
   const std::multimap<grpc::string, grpc::string>& GetServerTrailingMetadata() {
     // TODO(yangg) check finished
@@ -197,6 +203,8 @@ class ClientContext {
 
   /// Set the deadline for the client call.
   ///
+  /// \warning This method should only be called before invoking the rpc.
+  ///
   /// \param deadline the deadline for the client call. Units are determined by
   /// the type used.
   template <typename T>

include/grpc++/completion_queue.h

@@ -94,7 +94,12 @@ class CompletionQueue : public GrpcLibrary {
   ~CompletionQueue() GRPC_OVERRIDE;
 
   /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT.
-  enum NextStatus { 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
@@ -196,7 +201,7 @@ class CompletionQueueTag {
 };
 
 /// A specific type of completion queue used by the processing of notifications
-/// by servers.
+/// by servers. Instantiated by \a ServerBuilder.
 class ServerCompletionQueue : public CompletionQueue {
  private:
   friend class ServerBuilder;

include/grpc++/credentials.h

@@ -74,18 +74,21 @@ class Credentials : public GrpcLibrary {
 };
 
 /// Options used to build SslCredentials.
-///
-/// pem_roots_cert is the buffer containing the PEM encoding of the server root
-/// certificates. If this parameter is empty, the default roots will be used.
-/// pem_private_key is the buffer containing the PEM encoding of the client's
-/// private key. This parameter can be empty if the client does not have a
-/// private key.
-/// pem_cert_chain is the buffer containing the PEM encoding of the client's
-/// certificate chain. This parameter can be empty if the client does not have
-/// a certificate chain.
 struct SslCredentialsOptions {
+  /// The buffer containing the PEM encoding of the server root certificates. If
+  /// this parameter is empty, the default roots will be used.  The default
+  /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
+  /// environment variable pointing to a file on the file system containing the
+  /// roots.
   grpc::string pem_root_certs;
+
+  /// The buffer containing the PEM encoding of the client's private key. This
+  /// parameter can be empty if the client does not have a private key.
   grpc::string pem_private_key;
+
+  /// The buffer containing the PEM encoding of the client's certificate chain.
+  /// This parameter can be empty if the client does not have a certificate
+  /// chain.
   grpc::string pem_cert_chain;
 };
 
@@ -95,6 +98,11 @@ struct SslCredentialsOptions {
 // a channel. A lame channel will be created then and all rpcs will fail on it.
 
 /// Builds credentials with reasonable defaults.
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> GoogleDefaultCredentials();
 
 /// Builds SSL Credentials given SSL specific options
@@ -102,6 +110,11 @@ std::shared_ptr<Credentials> SslCredentials(
     const SslCredentialsOptions& options);
 
 /// Builds credentials for use when running in GCE
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> ComputeEngineCredentials();
 
 /// Builds service account credentials.
@@ -110,6 +123,11 @@ std::shared_ptr<Credentials> ComputeEngineCredentials();
 /// token_lifetime_seconds is the lifetime in seconds of each token acquired
 /// through this service account credentials. It should be positive and should
 /// not exceed grpc_max_auth_token_lifetime or will be cropped to this value.
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> ServiceAccountCredentials(
     const grpc::string& json_key, const grpc::string& scope,
     long token_lifetime_seconds);
@@ -125,16 +143,31 @@ std::shared_ptr<Credentials> ServiceAccountJWTAccessCredentials(
 /// Builds refresh token credentials.
 /// json_refresh_token is the JSON string containing the refresh token along
 /// with a client_id and client_secret.
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> RefreshTokenCredentials(
     const grpc::string& json_refresh_token);
 
 /// Builds access token credentials.
 /// access_token is an oauth2 access token that was fetched using an out of band
 /// mechanism.
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> AccessTokenCredentials(
     const grpc::string& access_token);
 
 /// Builds IAM credentials.
+///
+/// \warning Only use these credentials when connecting to a Google endpoint.
+/// Using these credentials to connect to any other service may result in this
+/// service being able to impersonate your client for requests to Google
+/// services.
 std::shared_ptr<Credentials> IAMCredentials(
     const grpc::string& authorization_token,
     const grpc::string& authority_selector);

include/grpc++/server.h

@@ -44,10 +44,6 @@
 #include <grpc++/support/config.h>
 #include <grpc++/support/status.h>
 
-/// The \a Server class models a gRPC server.
-///
-/// Servers are configured and started via \a grpc::ServerBuilder.
-
 struct grpc_server;
 
 namespace grpc {
@@ -61,6 +57,9 @@ class ServerAsyncStreamingInterface;
 class ServerCredentials;
 class ThreadPoolInterface;
 
+/// Models a gRPC server.
+///
+/// Servers are configured and started via \a grpc::ServerBuilder.
 class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
  public:
   ~Server();
@@ -126,7 +125,6 @@ class Server GRPC_FINAL : public GrpcLibrary, private CallHook {
   /// \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.