From 7c2ee962221445d1f3976d10da3d6c64e6db238e Mon Sep 17 00:00:00 2001
From: Randy Merrill <randymerrill@google.com>
Date: Mon, 23 May 2016 12:31:22 -0700
Subject: [PATCH] Updating the documentation to make it more clear how the
 `google-signin` works.

Also provides guidance on how to use the `google-signin-aware` with custom signin UIs.

Closes #143
---
 google-signin-aware.html | 88 +++++++++++++++++++------------------
 google-signin.html       | 94 ++++++++++++++++++++--------------------
 2 files changed, 93 insertions(+), 89 deletions(-)

diff --git a/google-signin-aware.html b/google-signin-aware.html
index f05b978..ba40167 100644
--- a/google-signin-aware.html
+++ b/google-signin-aware.html
@@ -486,48 +486,52 @@
 
     AuthEngine.init();
 
-/**
-`google-signin-aware` is used to enable authentication in custom elements by
-interacting with a google-signin element that needs to be present somewhere
-on the page.
-
-The `scopes` attribute allows you to specify which scope permissions are required
-(e.g do you want to allow interaction with the Google Drive API).
-
-The `google-signin-aware-success` event is triggered when a user successfully
-authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
-authentication will also trigger the `google-signin-offline-success`event.
-The `google-signin-aware-signed-out` event is triggered when a user explicitly
-signs out via the google-signin element.
-
-You can bind to `isAuthorized` property to monitor authorization state.
-##### Example
-
-    <google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>
-
-
-##### Example with offline
-    <template id="awareness" is="dom-bind">
-      <google-signin-aware
-          scopes="https://www.googleapis.com/auth/drive"
-          offline
-          on-google-signin-aware-success="handleSignin"
-          on-google-signin-offline-success="handleOffline"></google-signin-aware>
-    <\/template>
-    <script>
-      var aware = document.querySelector('#awareness');
-      aware.handleSignin = function(response) {
-        var user = gapi.auth2.getAuthInstance().currentUser.get();
-        console.log('User name: ' + user.getBasicProfile().getName());
-      };
-      aware.handleOffline = function(response) {
-        console.log('Offline code received: ' + response.detail.code);
-        // Here you would POST response.detail.code to your webserver, which can
-        // exchange the authorization code for an access token. More info at:
-        // https://developers.google.com/identity/protocols/OAuth2WebServer
-      };
-    <\/script>
-*/
+    /**
+    `<google-signin-aware>` is used to enable authentication in custom elements.
+
+    The `scopes` attribute allows you to specify which scope permissions are required
+    (e.g do you want to allow interaction with the Google Drive API).
+
+    The `google-signin-aware-success` event is triggered when a user successfully
+    authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
+    authentication will also trigger the `google-signin-offline-success`event.
+    The `google-signin-aware-signed-out` event is triggered when a user explicitly
+    signs out via the google-signin element.
+
+    You can bind to `isAuthorized` property to monitor authorization state.
+
+    The `<google-signin>` element provides the standard Google signin button UI and should be placed
+    within the application to allow the user to trigger the authentication. When opting to use a
+    custom signin UI, trigger the authentication by calling the `signin()` method of the
+    `<google-signin-aware>` component.
+
+    #### Example
+
+        <google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>
+
+    #### Example with offline
+
+        <template id="awareness" is="dom-bind">
+          <google-signin-aware
+              scopes="https://www.googleapis.com/auth/drive"
+              offline
+              on-google-signin-aware-success="handleSignin"
+              on-google-signin-offline-success="handleOffline"></google-signin-aware>
+        <\/template>
+        <script>
+          var aware = document.querySelector('#awareness');
+          aware.handleSignin = function(response) {
+            var user = gapi.auth2.getAuthInstance().currentUser.get();
+            console.log('User name: ' + user.getBasicProfile().getName());
+          };
+          aware.handleOffline = function(response) {
+            console.log('Offline code received: ' + response.detail.code);
+            // Here you would POST response.detail.code to your webserver, which can
+            // exchange the authorization code for an access token. More info at:
+            // https://developers.google.com/identity/protocols/OAuth2WebServer
+          };
+        <\/script>
+    */
     Polymer({
 
       is: 'google-signin-aware',
diff --git a/google-signin.html b/google-signin.html
index 908aaa3..ffd6b00 100644
--- a/google-signin.html
+++ b/google-signin.html
@@ -118,73 +118,73 @@
       WIDE: 'wide'
     };
 
-/**
-&lt;google-signin&gt; is used to authenticate with Google, allowing you to interact
-with other Google APIs such as Drive and Google+.
-
-<img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>
-
-If you do not need to show the button, use companion `<google-signin-aware>` element to declare scopes, check authentication state.
+    /**
+    `<google-signin>` is used to authenticate with Google, allowing you to interact
+    with other Google APIs such as Drive and Google+.
 
-#### Examples
+    <img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>
 
-    <google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
+    #### Examples
 
-    <google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
+        <google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
 
-    <google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
+        <google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
 
+        <google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
 
-#### Notes
+    #### Notes
 
-The attribute `clientId` is provided in your Google Developers Console
-(https://console.developers.google.com).
+    If you do not want to display the signin button, use the `<google-signin-aware>` element to
+    declare scopes and listen for authentication events. If there is no `<google-signin>` element on
+    the page the `<google-signin-aware>.signIn()` will need to be manually triggered.
 
-The `scopes` attribute allows you to specify which scope permissions are required
-(e.g do you want to allow interaction with the Google Drive API). Many APIs also
-need to be enabled in the Google Developers Console before you can use them.
+    The attribute `clientId` is provided in your Google Developers Console
+    (https://console.developers.google.com).
 
-The `requestVisibleActions` attribute is necessary if you want to write app
-activities (https://developers.google.com/+/web/app-activities/) on behalf of
-the user. Please note that this attribute is only valid in combination with the
-plus.login scope (https://www.googleapis.com/auth/plus.login).
+    The `scopes` attribute allows you to specify which scope permissions are required
+    (e.g do you want to allow interaction with the Google Drive API). Many APIs also
+    need to be enabled in the Google Developers Console before you can use them.
 
-The `offline` attribute allows you to get an auth code which your server can
-redeem for an offline access token
-(https://developers.google.com/identity/sign-in/web/server-side-flow).
-You can also set `offline-always-prompt` instead of `offline` to ensure that your app
-will re-prompt the user for offline access and generate a working `refresh_token`
-even if they have already granted offline access to your app in the past.
+    The `requestVisibleActions` attribute is necessary if you want to write app
+    activities (https://developers.google.com/+/web/app-activities/) on behalf of
+    the user. Please note that this attribute is only valid in combination with the
+    plus.login scope (https://www.googleapis.com/auth/plus.login).
 
-Use label properties to customize prompts.
+    The `offline` attribute allows you to get an auth code which your server can
+    redeem for an offline access token
+    (https://developers.google.com/identity/sign-in/web/server-side-flow).
+    You can also set `offline-always-prompt` instead of `offline` to ensure that your app
+    will re-prompt the user for offline access and generate a working `refresh_token`
+    even if they have already granted offline access to your app in the past.
 
-The button can be styled in using the `height`, `width`, and `theme` attributes.
-These attributes help you follow the Google+ Sign-In button branding guidelines
-(https://developers.google.com/+/branding-guidelines).
+    Use label properties to customize prompts.
 
-The `google-signin-success` event is triggered when a user successfully authenticates
-and `google-signed-out` is triggered when user signs out.
-You can also use `isAuthorized` attribute to observe user's authentication state.
+    The button can be styled in using the `height`, `width`, and `theme` attributes.
+    These attributes help you follow the Google+ Sign-In button branding guidelines
+    (https://developers.google.com/+/branding-guidelines).
 
-Additional events, such as `google-signout-attempted` are
-triggered when the user attempts to sign-out and successfully signs out.
+    The `google-signin-success` event is triggered when a user successfully authenticates
+    and `google-signed-out` is triggered when user signs out.
+    You can also use `isAuthorized` attribute to observe user's authentication state.
 
-When requesting offline access, the `google-signin-offline-success` event is
-triggered when the user successfully consents with offline support.
+    Additional events, such as `google-signout-attempted` are
+    triggered when the user attempts to sign-out and successfully signs out.
 
-The `google-signin-necessary` event is fired when scopes requested via
-google-signin-aware elements require additional user permissions.
+    When requesting offline access, the `google-signin-offline-success` event is
+    triggered when the user successfully consents with offline support.
 
-#### Testing
+    The `google-signin-necessary` event is fired when scopes requested via
+    google-signin-aware elements require additional user permissions.
 
-By default, the demo accompanying this element is setup to work on localhost with
-port 8080. That said, you *should* update the `clientId` to your own one for
-any apps you're building. See the Google Developers Console
-(https://console.developers.google.com) for more info.
+    #### Testing
 
-@demo
-*/
+    By default, the demo accompanying this element is setup to work on localhost with
+    port 8080. That said, you *should* update the `clientId` to your own one for
+    any apps you're building. See the Google Developers Console
+    (https://console.developers.google.com) for more info.
 
+    @demo
+    */
     Polymer({
 
       is: 'google-signin',