[IdentityManager] Add code usage snippet for PAATF

Similar to the code usage snippet that was added for AccessTokenFetcher.

Bug: 970295
Change-Id: I80b261978ff475e39a01d03b5756ec81cb7b45d4
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1724078Reviewed-by: Lowell Manners <lowell@chromium.org>
Commit-Queue: Colin Blundell <blundell@chromium.org>
Cr-Commit-Position: refs/heads/master@{#682270}

components/signin/public/identity_manager/README.md

@@ -39,7 +39,8 @@ A quick guide through the core concepts:
     system level that embedder-level code then made visible to IdentityManager).
 - PrimaryAccountTokenFetcher is the primary client-side interface for obtaining
   access tokens for the primary account. In particular, it can take care of
-  waiting until the primary account is available.
+  waiting until the primary account is available. See
+  primary_account_access_token_fetcher.h for usage explanation and examples.
 - AccessTokenFetcher is the client-side interface for obtaining access tokens
   for arbitrary accounts; see access_token_fetcher.h for usage explanation and
   examples.

components/signin/public/identity_manager/access_token_fetcher.h

@@ -92,6 +92,7 @@ struct AccessTokenInfo;
 //       access_token_fetcher_ =
 //           identity_manager_->CreateAccessTokenFetcherForAccount(
 //               account_id, /*consumer_name=*/"MyClass",
+//               scopes,
 //               base::BindOnce(&MyClass::OnAccessTokenRequestCompleted,
 //                              // It is safe to use base::Unretained as
 //                              // |this| owns |access_token_fetcher_|.

components/signin/public/identity_manager/primary_account_access_token_fetcher.h

@@ -19,11 +19,116 @@ class GoogleServiceAuthError;
 namespace signin {
 struct AccessTokenInfo;
 
-// Helper class to ease the task of obtaining an OAuth2 access token for the
-// authenticated account. This handles various special cases, e.g. when the
-// refresh token isn't loaded yet (during startup), or when there is some
-// transient error.
-// May only be used on the UI thread.
+// Class that supports obtaining OAuth2 access tokens for the user's primary
+// account.See ./README.md for the definition of "accounts with OAuth2 refresh
+// tokens" and "primary account".
+//
+// The usage model of this class is as follows: When a
+// PrimaryAccountAccessTokenFetcher is created, it will make an access token
+// request for the primary account (either immediately or if/once the primary
+// account becomes available, based on the value of the specified |Mode|
+// parameter). When the access token request is fulfilled the
+// PrimaryAccountAccessTokenFetcher will call the specified callback, at which
+// point it is safe for the caller to destroy the object. If the object is
+// destroyed before the request is fulfilled the request is dropped and the
+// callback will never be invoked. This class may only be used on the UI thread.
+//
+// To drive responses to access token fetches in unittests of clients of this
+// class, use IdentityTestEnvironment.
+//
+// Concrete usage example (related concrete test example follows):
+//   class MyClass {
+//    public:
+//     MyClass(IdentityManager* identity_manager) :
+//       identity_manager_(identity_manager) {
+//         // An access token request could also be initiated at any arbitrary
+//         // point in the lifetime of |MyClass|.
+//         StartAccessTokenRequestForPrimaryAccount();
+//       }
+//
+//
+//     ~MyClass() {
+//       // If the access token request is still live, the destruction of
+//       |access_token_fetcher_| will cause it to be dropped.
+//     }
+//
+//    private:
+//     IdentityManager* identity_manager_;
+//     std::unique_ptr<PrimaryAccountAccessTokenFetcher> access_token_fetcher_;
+//     std::string access_token_;
+//     GoogleServiceAuthError access_token_request_error_;
+//
+//     // Most commonly invoked as part of some larger flow to hit a Gaia
+//     // endpoint for a client-specific purpose (e.g., hitting sync
+//     // endpoints).
+//     // Could also be public, but in general, any clients that would need to
+//     // create access token requests could and should just create
+//     // PrimaryAccountAccessTokenFetchers directly themselves rather than
+//     // introducing wrapper API surfaces.
+//     MyClass::StartAccessTokenRequestForPrimaryAccount() {
+//       // Choose scopes to obtain for the access token.
+//       identity::ScopeSet scopes;
+//       scopes.insert(GaiaConstants::kMyFirstScope);
+//       scopes.insert(GaiaConstants::kMySecondScope);
+
+//       // Choose the mode in which to fetch the access token:
+//       // see AccessTokenFetcher::Mode below for definitions.
+//       auto mode =
+//         signin::PrimaryAccountAccessTokenFetcher::Mode::kWaitUntilAvailable;
+
+//       // Create the fetcher.
+//       access_token_fetcher_ =
+//           std::make_unique<PrimaryAccountAccessTokenFetcher(
+//               /*consumer_name=*/"MyClass",
+//               identity_manager_,
+//               scopes,
+//               base::BindOnce(&MyClass::OnAccessTokenRequestCompleted,
+//                              // It is safe to use base::Unretained as
+//                              // |this| owns |access_token_fetcher_|.
+//                              base::Unretained(this)),
+//                              mode);
+//
+//     }
+//     MyClass::OnAccessTokenRequestCompleted(
+//         GoogleServiceAuthError error, AccessTokenInfo access_token_info) {
+//       // It is safe to destroy |access_token_fetcher_| from this callback.
+//       access_token_fetcher_.reset();
+//
+//       if (error.state() == GoogleServiceAuthError::NONE) {
+//         // The fetcher successfully obtained an access token.
+//         access_token_ = access_token_info.token;
+//         // MyClass can now take whatever action required having an access
+//         // token (e.g.,hitting a given Gaia endpoint).
+//         ...
+//       } else {
+//         // The fetcher failed to obtain a token; |error| specifies why.
+//         access_token_request_error_ = error;
+//         // MyClass can now perform any desired error handling.
+//         ...
+//       }
+//     }
+//   }
+//
+//   Concrete test example:
+//   TEST(MyClassTest, SuccessfulAccessTokenFetchForPrimaryAccount) {
+//     IdentityTestEnvironment identity_test_env;
+//
+//
+//     MyClass my_class(identity_test_env.identity_manager());
+//
+//     // Make the primary account available, which should result in an access
+//     // token fetch being made on behalf of |my_class|.
+//     identity_test_env.MakePrimaryAccountAvailable("test_email");
+//
+//     identity_test_env.
+//         WaitForAccessTokenRequestIfNecessaryAndRespondWithToken(
+//             "access_token", base::Time::Max());
+//
+//     // MyClass::OnAccessTokenRequestCompleted() will have been invoked with
+//     // an AccessTokenInfo object containing the above-specified parameters;
+//     // the test can now perform any desired validation of expected actions
+//     // |MyClass| took in response.
+//   }
 class PrimaryAccountAccessTokenFetcher : public IdentityManager::Observer {
  public:
   // Specifies how this instance should behave: