Update //services/identity public docs

Change-Id: I49aa8fc88149bd111969074ef4023d9dcd57edee
Reviewed-on: https://chromium-review.googlesource.com/1162231Reviewed-by: Sylvain Defresne <sdefresne@chromium.org>
Commit-Queue: Colin Blundell <blundell@chromium.org>
Cr-Commit-Position: refs/heads/master@{#580551}

services/identity/public/README.md

+//services/identity/public/cpp contains the next-generation C++ API for
+interacting with the user's Google identities. In the long term, this library
+will become a client library for the Identity Service. In the present, it is
+being developed based directly on the internal C++ classes in
+//components/signin and //google_apis/gaia. This library is almost certainly
+what you want to use if you are developing a browser feature. See
+//services/identity/public/cpp/README.md for details. 
+
+If you are looking to connect to the Identity Service, the current way to do so
+is via //services/identity/public/mojom. You may wish to do this if you are
+developing a feature that is intended to run out of the browser process and
+does not require having a view of Google identity that is synchronously updated
+with the view of Google identity that the browser sees.

services/identity/public/cpp/README.md

@@ -7,9 +7,28 @@ over the bare Identity Service Mojo interfaces such as:
 
 - Synchronous access to the information of the primary account (via caching)
 
-PrimaryAccountTokenFetcher is the primary client-side interface for obtaining
-access tokens for the primary account. In particular, it takes care of waiting
-until the primary account is available.
+A cheat sheet for developers migrating from usage of //components/signin and
+//google_apis/gaia:
+
+- "Primary account" in IdentityManager refers to what is called the
+  "authenticated account" in SigninManager, i.e., the account that has been
+  blessed for sync by the user.
+- 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.
+- AccessTokenFetcher is the client-side interface for obtaining access tokens
+  for arbitrary accounts.
+- IdentityTestEnvironment is the preferred test infrastructure for unittests
+  of production code that interacts with IdentityManager. It is suitable for
+  use in cases where neither the production code nor the unittest is interacting
+  with Profile (e.g., //components-level unittests).
+- identity_test_utils.h provides lower-level test facilities for interacting
+  explicitly with IdentityManager and its dependencies (SigninManager,
+  ProfileOAuth2TokenService). These facilities are the way to interact with
+  IdentityManager in unittest contexts where the production code and/or the
+  unittest are interacting with Profile (in particular, where the
+  IdentityManager instance with which the test is interacting must be
+  IdentityManagerFactory::GetForProfile(profile)).
 
 IMPLEMENTATION NOTES