From 70c2b06155e99568da966b507b8638376e20de31 Mon Sep 17 00:00:00 2001
From: Quddus Chong <quddusc@google.com>
Date: Tue, 19 Aug 2014 18:01:11 -0700
Subject: [PATCH] docs: Added additional documentation for specifying OAuth
 scopes. bug: 12650251

Change-Id: I8905ed63208aff82d0c0caf1b3503831f121b09e
---
 docs/html/_redirects.yaml          |  3 +++
 docs/html/google/auth/http-auth.jd | 34 +++++++++++++++++++++++++-----
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index c5b6c24451ee6..45e2fedb6cb04 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -59,6 +59,9 @@ redirects:
 - from: /guide/google/gcm/server-javadoc/...
   to: /reference/com/google/android/gcm/server/package-summary.html
 
+- from: /google/play-services/auth.html
+  to: /google/auth/http-auth.html
+
 - from: /guide/google/play/services.html
   to: /google/play-services/index.html
 
diff --git a/docs/html/google/auth/http-auth.jd b/docs/html/google/auth/http-auth.jd
index 3b2a83f996280..804ba1225e017 100644
--- a/docs/html/google/auth/http-auth.jd
+++ b/docs/html/google/auth/http-auth.jd
@@ -342,9 +342,9 @@ public class GetUsernameTask extends AsyncTask<Void, Void, Void>{
 "{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">
 {@code GoogleAuthUtil.getToken()}</a>, you must provide the app {@link android.content.Context},
 the account name retrieved from the account picker, and the scope for your auth
-token request. The above sample code (and the attached sample) defines these arguments with
-class members that the host activity passes to
-the {@link android.os.AsyncTask} class constructor.</p>
+token request. The above sample code (and the attached sample) defines these
+arguments with class members that the host activity passes to the {@link android.os.AsyncTask} class constructor. For more information about setting the scope, see
+the <a href="#SpecifyingScopes">Specifying Scopes</a> section below. </p>
 
 <p class="note"><strong>Note:</strong>
 As shown by the {@code fetchToken()} method above, you must handle
@@ -397,8 +397,32 @@ the {@code isDeviceOnline()} method above), see the attached sample app or the
 "{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">
 {@code GoogleAuthUtil.getToken()}</a>.</p>
 
-
-
+<h3 id="SpecifyingScopes">Specifying scopes</h3>
+<p>The scope string is used to specify which Google services can be accessed by
+  an app using the requested auth token. An auth token can be associated with
+  multiple scopes.</p>
+<p>When specifying the scopes in your auth token request, prefix the
+  scope string with {@code "oauth2:"} followed by a list of one or more OAuth scope
+  values. Use a space to separate each scope value in the list. To see a list of
+  valid OAuth scope values for Google services, browse
+  the <a href="https://developers.google.com/oauthplayground/"
+  class="external-link">OAuth 2.0 Playground</a>.</p>
+<p class="note"><strong>Tip:</strong> Specify {@code "oauth2:&lt;scope&gt;"}
+  for a single scope. Specify
+  {@code "oauth2:&lt;scope1&gt; &lt;scope2&gt; &lt;scopeN&gt;"} for multiple
+  scopes (using a space to separate each scope).</p>
+<p>For example, to access the Google Books API, the scope is
+  {@code "oauth2:https://www.googleapis.com/auth/books"}. To add an additional
+  scope, say for Google+ login, your code might look like this:</p>
+<pre>
+private final static String BOOKS_API_SCOPE
+        = "https://www.googleapis.com/auth/books";
+private fina; static String GPLUS_SCOPE
+        = "https://www.googleapis.com/auth/plus.login";
+private final static String mScopes
+        = "oauth2:" + BOOKS_API_SCOPE + " " + GPLUS_SCOPE;
+String token = GoogleAuthUtil.getToken(mActivity, mEmail, mScopes);
+</pre>
 
 <h2 id="HandleExceptions">Handle Exceptions</h2>