Replicate C++ docs from master to beta branch

Original PR #3074 by @dgquintas

3 files changed, 98 insertions, 40 deletions

diff --git a/include/grpc++/security/auth_context.h b/include/grpc++/security/auth_context.h
index fc2701e806..4b1bbd85bc 100644
--- a/include/grpc++/security/auth_context.h
+++ b/include/grpc++/security/auth_context.h
@@ -37,6 +37,7 @@
 #include <iterator>
 #include <vector>
 
+#include <grpc/grpc_security.h>
 #include <grpc++/support/config.h>
 #include <grpc++/support/string_ref.h>
 
@@ -73,26 +74,41 @@ 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() {}
 
-  // Returns true if the peer is authenticated.
+  /// Returns true if the peer is authenticated.
   virtual bool IsPeerAuthenticated() const = 0;
 
-  // A peer identity, in general is one or more properties (in which case they
-  // have the same name).
+  /// A peer identity.
+  ///
+  /// It is, in general, comprised of one or more properties (in which case they
+  /// have the same name).
   virtual std::vector<grpc::string_ref> 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_ref> 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;
 
+  static string transport_security_type_property_name() {
+    return GRPC_TRANSPORT_SECURITY_TYPE_PROPERTY_NAME;
+  }
+  static string ssl_transport_security_type() {
+    return GRPC_SSL_TRANSPORT_SECURITY_TYPE;
+  }
+  static string x509_cn_property_name() { return GRPC_X509_CN_PROPERTY_NAME; }
+  static string x509_san_property_name() { return GRPC_X509_SAN_PROPERTY_NAME; }
+
   // Mutation functions: should only be used by an AuthMetadataProcessor.
   virtual void AddProperty(const grpc::string& key,
                            const grpc::string_ref& value) = 0;
diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h
index ce5a9e0606..e423849714 100644
--- a/include/grpc++/security/credentials.h
+++ b/include/grpc++/security/credentials.h
@@ -44,9 +44,17 @@ class ChannelArguments;
 class Channel;
 class SecureCredentials;
 
+/// 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/blob/master/doc/grpc-auth-support.md
 class Credentials : public GrpcLibrary {
  public:
   ~Credentials() GRPC_OVERRIDE;
+
+  /// Apply this instance's credentials to \a call.
   virtual bool ApplyToCall(grpc_call* call) = 0;
 
  protected:
@@ -65,68 +73,96 @@ class Credentials : public GrpcLibrary {
       const grpc::string& target, const ChannelArguments& args) = 0;
 };
 
-// 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.
+/// Options used to build SslCredentials.
 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;
 };
 
-// Factories for building different types of Credentials
-// The functions may return empty shared_ptr when credentials cannot be created.
-// If a Credentials pointer is returned, it can still be invalid when used to
-// create a channel. A lame channel will be created then and all rpcs will
-// fail on it.
-
-// Builds credentials with reasonable defaults.
+// Factories for building different types of Credentials The functions may
+// return empty shared_ptr when credentials cannot be created. If a
+// Credentials pointer is returned, it can still be invalid when used to create
+// 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
+/// Builds SSL Credentials given SSL specific options
 std::shared_ptr<Credentials> SslCredentials(
     const SslCredentialsOptions& options);
 
-// Builds credentials for use when running in GCE
+/// 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> GoogleComputeEngineCredentials();
 
-// Builds Service Account JWT Access credentials.
-// json_key is the JSON key string containing the client's private key.
-// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
-// (JWT) created with this credentials. It should not exceed
-// grpc_max_auth_token_lifetime or will be cropped to this value.
+/// Builds Service Account JWT Access credentials.
+/// json_key is the JSON key string containing the client's private key.
+/// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
+/// (JWT) created with this credentials. It should not exceed
+/// grpc_max_auth_token_lifetime or will be cropped to this value.
 std::shared_ptr<Credentials> ServiceAccountJWTAccessCredentials(
     const grpc::string& json_key, long token_lifetime_seconds);
 
-// Builds refresh token credentials.
-// json_refresh_token is the JSON string containing the refresh token along
-// with a client_id and client_secret.
+/// 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> GoogleRefreshTokenCredentials(
     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.
+/// 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.
+/// 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> GoogleIAMCredentials(
     const grpc::string& authorization_token,
     const grpc::string& authority_selector);
 
-// Combines two credentials objects into a composite credentials
+/// Combines two credentials objects into a composite credentials
 std::shared_ptr<Credentials> CompositeCredentials(
     const std::shared_ptr<Credentials>& creds1,
     const std::shared_ptr<Credentials>& creds2);
 
-// Credentials for an unencrypted, unauthenticated channel
+/// Credentials for an unencrypted, unauthenticated channel
 std::shared_ptr<Credentials> InsecureCredentials();
 
 }  // namespace grpc
diff --git a/include/grpc++/security/server_credentials.h b/include/grpc++/security/server_credentials.h
index 2094c7403c..e933825ec3 100644
--- a/include/grpc++/security/server_credentials.h
+++ b/include/grpc++/security/server_credentials.h
@@ -45,7 +45,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();
@@ -58,11 +58,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) {}
 
@@ -75,10 +80,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