Better document GaiaOAuthClient via comments and updated method name.

BUG=

Review URL: https://chromiumcodereview.appspot.com/17696002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@208615 0039d316-1c4b-4281-b951-d872f2087c98

3 files changed, 43 insertions, 19 deletions

diff --git a/google_apis/gaia/gaia_oauth_client.cc b/google_apis/gaia/gaia_oauth_client.cc
index d00b7d24e..a2b6dc5 100644
--- a/google_apis/gaia/gaia_oauth_client.cc
+++ b/google_apis/gaia/gaia_oauth_client.cc
@@ -49,9 +49,9 @@ class GaiaOAuthClient::Core
                     const std::vector<std::string>& scopes,
                     int max_retries,
                     GaiaOAuthClient::Delegate* delegate);
-  void GetUserInfo(const std::string& oauth_access_token,
-                   int max_retries,
-                   Delegate* delegate);
+  void GetUserEmail(const std::string& oauth_access_token,
+                    int max_retries,
+                    Delegate* delegate);
   void GetTokenInfo(const std::string& oauth_access_token,
                     int max_retries,
                     Delegate* delegate);
@@ -131,9 +131,9 @@ void GaiaOAuthClient::Core::RefreshToken(
                   post_body, max_retries, delegate);
 }
 
-void GaiaOAuthClient::Core::GetUserInfo(const std::string& oauth_access_token,
-                                        int max_retries,
-                                        Delegate* delegate) {
+void GaiaOAuthClient::Core::GetUserEmail(const std::string& oauth_access_token,
+                                         int max_retries,
+                                         Delegate* delegate) {
   DCHECK_EQ(request_type_, NO_PENDING_REQUEST);
   DCHECK(!request_.get());
   request_type_ = USER_INFO;
@@ -253,7 +253,7 @@ void GaiaOAuthClient::Core::HandleResponse(
     case USER_INFO: {
       std::string email;
       response_dict->GetString("email", &email);
-      delegate_->OnGetUserInfoResponse(email);
+      delegate_->OnGetUserEmailResponse(email);
       break;
     }
 
@@ -322,10 +322,10 @@ void GaiaOAuthClient::RefreshToken(
                              delegate);
 }
 
-void GaiaOAuthClient::GetUserInfo(const std::string& access_token,
+void GaiaOAuthClient::GetUserEmail(const std::string& access_token,
                                   int max_retries,
                                   Delegate* delegate) {
-  return core_->GetUserInfo(access_token, max_retries, delegate);
+  return core_->GetUserEmail(access_token, max_retries, delegate);
 }
 
 void GaiaOAuthClient::GetTokenInfo(const std::string& access_token,
diff --git a/google_apis/gaia/gaia_oauth_client.h b/google_apis/gaia/gaia_oauth_client.h
index a8af658..94d3313 100644
--- a/google_apis/gaia/gaia_oauth_client.h
+++ b/google_apis/gaia/gaia_oauth_client.h
@@ -17,8 +17,9 @@ namespace net {
 class URLRequestContextGetter;
 }
 
-// A helper class to get and refresh OAuth tokens given an authorization code.
-// Also exposes utility methods for fetching user email and token owner.
+// A helper class to get and refresh OAuth2 refresh and access tokens.
+// Also exposes utility methods for fetching user email and token information.
+//
 // Supports one request at a time; for parallel requests, create multiple
 // instances.
 namespace gaia {
@@ -43,7 +44,7 @@ class GaiaOAuthClient {
     virtual void OnRefreshTokenResponse(const std::string& access_token,
                                         int expires_in_seconds) {}
     // Invoked on a successful response to the GetUserInfo request.
-    virtual void OnGetUserInfoResponse(const std::string& user_email) {}
+    virtual void OnGetUserEmailResponse(const std::string& user_email) {}
     // Invoked on a successful response to the GetTokenInfo request.
     virtual void OnGetTokenInfoResponse(
         scoped_ptr<DictionaryValue> token_info) {}
@@ -65,18 +66,41 @@ class GaiaOAuthClient {
   // we should retry on a network error in invalid response. This does not
   // apply in the case of an OAuth error (i.e. there was something wrong with
   // the input arguments). Setting |max_retries| to -1 implies infinite retries.
+
+  // Given an OAuth2 authorization code, fetch the long-lived refresh token
+  // and a valid access token. After the access token expires, RefreshToken()
+  // can be used to fetch a fresh access token. See |max_retries| docs above.
   void GetTokensFromAuthCode(const OAuthClientInfo& oauth_client_info,
                              const std::string& auth_code,
                              int max_retries,
                              Delegate* delegate);
+
+  // Given a valid refresh token (usually fetched via
+  // |GetTokensFromAuthCode()|), fetch a fresh access token that can be used
+  // to authenticate an API call. If |scopes| is non-empty, then fetch an
+  // access token for those specific scopes (assuming the refresh token has the
+  // appropriate permissions). See |max_retries| docs above.
   void RefreshToken(const OAuthClientInfo& oauth_client_info,
                     const std::string& refresh_token,
                     const std::vector<std::string>& scopes,
                     int max_retries,
                     Delegate* delegate);
-  void GetUserInfo(const std::string& oauth_access_token,
-                   int max_retries,
-                   Delegate* delegate);
+
+  // Call the userinfo API, returning the user email address associated
+  // with the given access token. The provided access token must have
+  // https://www.googleapis.com/auth/userinfo.email as one of its scopes.
+  // See |max_retries| docs above.
+  void GetUserEmail(const std::string& oauth_access_token,
+                    int max_retries,
+                    Delegate* delegate);
+
+  // Call the tokeninfo API, returning a dictionary of response values. The
+  // provided access token may have any scope, and basic results will be
+  // returned: issued_to, audience, scope, expires_in, access_type. In
+  // addition, if the https://www.googleapis.com/auth/userinfo.email scope is
+  // present, the email and verified_email fields will be returned. If the
+  // https://www.googleapis.com/auth/userinfo.profile scope is present, the
+  // user_id field will be returned. See |max_retries| docs above.
   void GetTokenInfo(const std::string& oauth_access_token,
                     int max_retries,
                     Delegate* delegate);
diff --git a/google_apis/gaia/gaia_oauth_client_unittest.cc b/google_apis/gaia/gaia_oauth_client_unittest.cc
index e91e4f6..acb366a 100644
--- a/google_apis/gaia/gaia_oauth_client_unittest.cc
+++ b/google_apis/gaia/gaia_oauth_client_unittest.cc
@@ -179,7 +179,7 @@ class MockGaiaOAuthClientDelegate : public gaia::GaiaOAuthClient::Delegate {
                                          int expires_in_seconds));
   MOCK_METHOD2(OnRefreshTokenResponse, void(const std::string& access_token,
                                             int expires_in_seconds));
-  MOCK_METHOD1(OnGetUserInfoResponse, void(const std::string& user_email));
+  MOCK_METHOD1(OnGetUserEmailResponse, void(const std::string& user_email));
   MOCK_METHOD0(OnOAuthError, void());
   MOCK_METHOD1(OnNetworkError, void(int response_code));
 
@@ -294,15 +294,15 @@ TEST_F(GaiaOAuthClientTest, RefreshTokenDownscopingSuccess) {
 }
 
 
-TEST_F(GaiaOAuthClientTest, GetUserInfo) {
+TEST_F(GaiaOAuthClientTest, GetUserEmail) {
   MockGaiaOAuthClientDelegate delegate;
-  EXPECT_CALL(delegate, OnGetUserInfoResponse(kTestUserEmail)).Times(1);
+  EXPECT_CALL(delegate, OnGetUserEmailResponse(kTestUserEmail)).Times(1);
 
   MockOAuthFetcherFactory factory;
   factory.set_results(kDummyUserInfoResult);
 
   GaiaOAuthClient auth(profile_.GetRequestContext());
-  auth.GetUserInfo("access_token", 1, &delegate);
+  auth.GetUserEmail("access_token", 1, &delegate);
 }
 
 TEST_F(GaiaOAuthClientTest, GetTokenInfo) {