Update chrome.identity API documentation to mention best practices.

chrome/common/extensions/api/identity.idl

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.identity</code> API to get OAuth2 access tokens.
 namespace identity {
 
   dictionary TokenDetails {
     // Fetching a token may require the user to sign-in to Chrome, or
     // approve the application's requested scopes. If the interactive
@@ skipping 44 matching lines @@
     // present on the profile.<br>
     // <code>getAccounts</code> is only supported on dev channel.
     static void getAccounts(GetAccountsCallback callback);
 
     // Gets an OAuth2 access token using the client ID and scopes
     // specified in the <a
     // href="app_identity.html#update_manifest"><code>oauth2</code>
     // section of manifest.json</a>.
     //
     // The Identity API caches access tokens in memory, so it's ok to
-    // call <code>getAuthToken</code> any time a token is
+    // call <code>getAuthToken</code> non-interactively any time a token is
     // required. The token cache automatically handles expiration.
     //
+    // For a good user experience it is important interactive token requests are
+    // initiated by UI in your app explaining what the authorization is for.
+    // Failing to do this will cause your users to get authorization requests,
+    // or Chrome sign in screens if they are not signed in, with with no
+    // context. In particular, do not use <code>getAuthToken</code>
+    // interactively when your app is first launched.
+    //
     // |details| : Token options.
     // |callback| : Called with an OAuth2 access token as specified by the
     // manifest, or undefined if there was an error.
     static void getAuthToken(optional TokenDetails details,
                              GetAuthTokenCallback callback);
 
     // Removes an OAuth2 access token from the Identity API's token cache.
     //
     // If an access token is discovered to be invalid, it should be
     // passed to removeCachedAuthToken to remove it from the
@@ skipping 11 matching lines @@
     // providers by launching a web view and navigating it to the
     // first URL in the provider's auth flow. When the provider
     // redirects to a URL matching the pattern
     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>, the
     // window will close, and the final redirect URL will be passed to
     // the <var>callback</var> function.
     //
     // For a good user experience it is important interactive auth flows are
     // initiated by UI in your app explaining what the authorization is for.
     // Failing to do this will cause your users to get authorization requests
-    // - or even Chrome sign in screens if they are not signed in - with
-    // no context. In particular, do not launch an interactive auth flow when
-    // your app is first launched.
+    // with no context. In particular, do not launch an interactive auth flow
+    // when your app is first launched.
     //
     // |details| : WebAuth flow options.
     // |callback| : Called with the URL redirected back to your application.
     static void launchWebAuthFlow(WebAuthFlowDetails details,
                                   LaunchWebAuthFlowCallback callback);
 
     // Generates a redirect URL to be used in |launchWebAuthFlow|.
     //
     // The generated URLs match the pattern
     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>.
     //
     // |path| : The path appended to the end of the generated URL.
     [nocompile] static DOMString getRedirectURL(optional DOMString path);
   };
 
   interface Events {
     // Fired when signin state changes for an account on the user's profile.
     static void onSignInChanged(AccountInfo account, boolean signedIn);
   };
 };