docs(platform): update API docs for platform

include a table that explains what each platform name means.

references driftyco/ionic-site#503

ionic/platform/platform.ts

@@ -7,10 +7,13 @@ import {ready, windowDimensions, flushDimensionCache} from '../util/dom';
 /**
  * @name Platform
  * @description
- * Platform returns the availble information about your current platform.
+ * The Platform service can be used to get information about your current device.
- * Platforms in Ionic 2 are much more complex then in V1, returns not just a single platform,
+ * You can get all of the platforms associated with the device using the [platforms](#platforms)
- * but a hierarchy of information, such as a devices OS, phone vs tablet, or mobile vs browser.
+ * method, including whether the app is being viewed from a tablet, if it's
- * With this information you can completely custimize your app to fit any device and platform.
+ * on a mobile device or browser, and the exact platform (ios, android, etc).
+ * You can also get the orientation of the device, if it uses right-to-left
+ * language direction, and much much more. With this information you can completely
+ * customize your app to fit any device.
  *
  * @usage
  * ```ts
@@ -50,7 +53,6 @@ export class Platform {
   // **********************************************
 
   /**
-   * @param {string} platformName
    * @returns {boolean} returns true/false based on platform.
    * @description
    * Depending on the platform the user is on, `is(platformName)` will
@@ -59,22 +61,7 @@ export class Platform {
    * an iPad would return `true` for the platform names: `mobile`,
    * `ios`, `ipad`, and `tablet`. Additionally, if the app was running
    * from Cordova then `cordova` would be true, and if it was running
-   * from a web browser on the iPad then then `mobileweb` would also
+   * from a web browser on the iPad then `mobileweb` would be `true`.
-   * be `true`.
-   *
-   * Possible built-in platform names:
-   *
-   * - `android`
-   * - `cordova`
-   * - `core`
-   * - `ios`
-   * - `ipad`
-   * - `iphone`
-   * - `mobile`
-   * - `mobileweb`
-   * - `phablet`
-   * - `tablet`
-   * - `windows`
    *
    * ```
    * import {Platform} from 'ionic-angular';
@@ -82,13 +69,31 @@ export class Platform {
    * @Page({...})
    * export MyPage {
    *   constructor(platform: Platform) {
-   *      if (platform.is('ios')) {
+   *     this.platform = platform;
-   *        // what ever you need to do
+   *
-   *        // if the platform is ios
+   *     if (this.platform.is('ios')) {
+   *       // This will only print when on ios
+   *       console.log("I'm an ios device!");
    *     }
    *   }
    * }
    * ```
+   *
+   * | Platform Name   | Description                        |
+   * |-----------------|------------------------------------|
+   * | android         | on a device running Android.       |
+   * | cordova         | on a device running Cordova.       |
+   * | core            | on a desktop device.               |
+   * | ios             | on a device running iOS.           |
+   * | ipad            | on an iPad device.                 |
+   * | iphone          | on an iPhone device.               |
+   * | mobile          | on a mobile device.                |
+   * | mobileweb       | in a browser on a mobile device.   |
+   * | phablet         | on a phablet device.               |
+   * | tablet          | on a tablet device.                |
+   * | windows         | on a device running Windows.       |
+   *
+   * @param {string} platformName
    */
   is(platformName: string): boolean {
     return (this._platforms.indexOf(platformName) > -1);
@@ -99,16 +104,18 @@ export class Platform {
    * @description
    * Depending on what device you are on, `platforms` can return multiple values.
    * Each possible value is a hierarchy of platforms. For example, on an iPhone,
-   * it would return mobile, ios, and iphone.
+   * it would return `mobile`, `ios`, and `iphone`.
    *
    * ```
    * import {Platform} from 'ionic-angular';
+   *
+   * @Page({...})
    * export MyPage {
    *   constructor(platform: Platform) {
    *     this.platform = platform;
+   *
+   *     // This will print an array of the current platforms
    *     console.log(this.platform.platforms());
-   *      // This will return an array of all the availble platforms
-   *      // From if your on mobile, to mobile os, and device name
    *   }
    * }
    * ```
@@ -121,7 +128,7 @@ export class Platform {
 
 
   /**
-   * Returns an object containing information about the platforms.
+   * Returns an object containing version information about all of the platforms.
    *
    * ```
    * import {Platform} from 'ionic-angular';
@@ -129,11 +136,15 @@ export class Platform {
    * @Page({...})
    * export MyPage {
    *   constructor(platform: Platform) {
+   *     this.platform = platform;
+   *
+   *     // This will print an object containing
+   *     // all of the platforms and their versions
    *     console.log(platform.versions());
    *   }
    * }
    * ```
-
+   *
    * @param {string} [platformName] optional platformName
    * @returns {object} An object with various platform info
    *