Merge pull request #28 from GoogleWebComponents/fix15

Add API docs

Author: addyosmani

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "google-apis",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "homepage": "http://googlewebcomponents.github.io/google-apis",
   "description": "Web components to load Google API libraries",
   "main": "google-apis.html",

google-client-api.html

@@ -15,17 +15,45 @@
 
 Any number of components can use `<google-client-api>` elements, and the library will only be loaded once.
 
+##### Example
+
+    <google-client-api></google-client-api>
+    <script>
+      var client = document.querySelector('google-client-api');
+      client.addEventListener('api-load', function(e) {
+        // this.api === gapi.client
+        // this.auth === gapi.auth
+      });
+    </script>
+
 @element google-client-api
 @extends core-shared-lib
+@homepage https://googlewebcomponents.github.io/google-apis
 -->
 <polymer-element name="google-client-api" extends="core-shared-lib">
 <script>
   Polymer({
     defaultUrl: 'https://apis.google.com/js/client.js?onload=%%callback%%',
+    
+    /**
+     * Fired when the API library is loaded and available.
+     * @event api-load
+     */
     notifyEvent: 'api-load',
+
+    /**
+     * Wrapper for `gapi.client`.
+     * @property api
+     * @type gapi.client
+     */
     get api() {
       return gapi.client;
     },
+    /**
+     * Wrapper for `gapi.auth`.
+     * @property auth
+     * @type gapi.auth
+     */
     get auth() {
       return gapi.auth;
     }
@@ -38,21 +66,24 @@
 
 ##### Example
 
-    <google-api-loader id="shortener" name="urlshortener" version="v1">
-    </google-api-loader>
+    <google-api-loader id="shortener" name="urlshortener"
+                       version="v1"></google-api-loader>
 
     <script>
       var shortener = document.getElementById('shortener');
       shortener.addEventListener('google-api-load', function(event) {
-        var request = shortener.api.url.get({'shortUrl': 'http://goo.gl/fbsS'});
-        request.execute(function(resp) { console.log(resp); });
+        var request = shortener.api.url.get({
+           shortUrl: 'http://goo.gl/fbsS'
+        });
+        request.execute(function(resp) {
+          console.log(resp);
+        });
       });
     </script>
 
 @element google-api-loader
-@status alpha
 @extends google-client-api
-@homepage http://polymerlabs.github.io/google-apis
+@homepage https://googlewebcomponents.github.io/google-apis
 -->
 <polymer-element name="google-api-loader"
                  attributes="name version appId root"
@@ -73,12 +104,14 @@
 
     Polymer('google-api-loader', {
       /**
-       * Fired when the requested API is loaded.
+       * Fired when the requested API is loaded. Override this name
+       * by setting `successEventName`. 
        * @event google-api-load
        */
 
       /**
-       * Fired if an error occurs while loading the requested API.
+       * Fired if an error occurs while loading the requested API. Override this name
+       * by setting `errorEventName`. 
        * @event google-api-load-error
        */
 
@@ -123,12 +156,26 @@
       // core-shared-lib.
       waiting: false,
 
+      /**
+       * Used to override the event that is fired when the API lib is successfully loaded.
+       * @property successEventName
+       * @type string
+       * @default 'google-api-load'
+       */
       successEventName: 'google-api-load',
+      
+      /**
+       * Used to override the event that is fired when there is an error loading the API.
+       * @property errorEventName
+       * @type string
+       * @default 'google-api-load-error'
+       */
       errorEventName: 'google-api-load-error',
 
       /**
        * Returns the loaded API.
-       * @method api
+       * @property api
+       * @type gapi.client
        */
       get api() {
         if (window.gapi && window.gapi.client &&

google-jsapi.html

@@ -17,12 +17,24 @@
 Any number of components can use `<google-jsapi>` elements, and the library will only be loaded once.
 
 @element google-jsapi
+@extends core-shared-lib
+@homepage https://googlewebcomponents.github.io/google-apis
 -->
 <polymer-element name="google-jsapi" extends="core-shared-lib">
 <script>
   Polymer({
     defaultUrl: 'https://www.google.com/jsapi?callback=%%callback%%',
+		
+		/**
+		 * Fired when the API library is loaded and available.
+		 * @event api-load
+		 */
     notifyEvent: 'api-load',
+		
+		/**
+		 * Wrapper for `google` API namespace.
+		 * @property api
+		 */
     get api() {
       return google;
     }

google-maps-api.html

@@ -27,7 +27,7 @@
 
 @element google-maps-api
 @blurb Element wrapper around Google Maps API.
-@homepage github.io
+@homepage https://googlewebcomponents.github.io/google-apis
 @extends core-shared-lib
 -->
 <!--

google-plusone-api.html

@@ -17,12 +17,23 @@
 
 @element google-plusone-api
 @extends core-shared-lib
+@homepage https://googlewebcomponents.github.io/google-apis
 -->
 <polymer-element name="google-plusone-api" extends="core-shared-lib">
 <script>
   Polymer({
     defaultUrl: 'https://apis.google.com/js/plusone.js?onload=%%callback%%',
+    /**
+     * Fired when the API library is loaded and available.
+     * @event api-load
+     */
     notifyEvent: 'api-load',
+		
+    /**
+     * Wrapper for `gapi`.
+     * @property api
+     * @type gapi
+     */
     get api() {
       return gapi;
     }

google-youtube-api.html

@@ -16,13 +16,26 @@
 Any number of components can use `<google-youtube-api>` elements, and the library will only be loaded once.
 
 @element google-youtube-api
+@extends core-shared-lib
+@homepage https://googlewebcomponents.github.io/google-apis
 -->
 <polymer-element name="google-youtube-api" extends="core-shared-lib">
 <script>
   Polymer({
     defaultUrl: 'https://www.youtube.com/iframe_api',
+    /**
+     * Fired when the API library is loaded and available.
+     * @event api-load
+     */
     notifyEvent: 'api-load',
+
     callbackName: 'onYouTubeIframeAPIReady',
+		
+    /**
+     * Wrapper for `YT` API object.
+     * @property api
+     * @type YT
+     */
     get api() {
       return YT;
     }

index.html

@@ -9,7 +9,10 @@
 </head>
 <body unresolved>
 
-  <core-component-page></core-component-page>
+  <core-component-page
+     moduleName="google-apis"
+     sources='["google-client-api.html", "google-jsapi.html", "google-maps-api.html", "google-plusone-api.html", "google-youtube-api.html"]'>
+  </core-component-page>
 
 </body>
 </html>