diff --git a/ionic/platform/platform.ts b/ionic/platform/platform.ts
index b1ace1d408..8a64fc308b 100644
--- a/ionic/platform/platform.ts
+++ b/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.
- * Platforms in Ionic 2 are much more complex then in V1, returns not just a single platform,
- * but a hierarchy of information, such as a devices OS, phone vs tablet, or mobile vs browser.
- * With this information you can completely custimize your app to fit any device and platform.
+ * The Platform service can be used to get information about your current device.
+ * You can get all of the platforms associated with the device using the [platforms](#platforms)
+ * method, including whether the app is being viewed from a tablet, if it's
+ * 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
@@ -18,9 +21,9 @@ import {ready, windowDimensions, flushDimensionCache} from '../util/dom';
  *
  * @Page({...})
  * export MyPage {
- *    constructor(platform: Platform){
- *      this.platform = platform;
- *    }
+ *   constructor(platform: Platform) {
+ *     this.platform = platform;
+ *   }
  * }
  * ```
  * @demo /docs/v2/demos/platform/
@@ -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,36 +61,39 @@ 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
-   * be `true`.
-   *
-   * Possible built-in platform names:
-   *
-   * - `android`
-   * - `cordova`
-   * - `core`
-   * - `ios`
-   * - `ipad`
-   * - `iphone`
-   * - `mobile`
-   * - `mobileweb`
-   * - `phablet`
-   * - `tablet`
-   * - `windows`
+   * from a web browser on the iPad then `mobileweb` would be `true`.
    *
    * ```
    * import {Platform} from 'ionic-angular';
    *
    * @Page({...})
    * export MyPage {
-   *    constructor(platform: Platform) {
-   *      if (platform.is('ios')) {
-   *        // what ever you need to do
-   *        // if the platform is ios
-   *      }
-   *    }
+   *   constructor(platform: Platform) {
+   *     this.platform = platform;
+   *
+   *     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,17 +104,19 @@ 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;
-   *      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
-   *    }
+   *   constructor(platform: Platform) {
+   *     this.platform = platform;
+   *
+   *     // This will print an array of the current platforms
+   *     console.log(this.platform.platforms());
+   *   }
    * }
    * ```
    */
@@ -121,19 +128,23 @@ 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';
    *
    * @Page({...})
    * export MyPage {
-   *    constructor(platform: Platform) {
-   *      console.log(platform.versions());
-   *    }
+   *   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
    *
@@ -167,12 +178,12 @@ export class Platform {
    *
    * @Page({...})
    * export MyPage {
-   *    constructor(platform: Platform) {
-   *      platform.ready().then(() => {
-   *        console.log('Platform ready');
-   *        // The platform is now ready, execute any native code you want
-   *       });
-   *    }
+   *   constructor(platform: Platform) {
+   *     platform.ready().then(() => {
+   *       console.log('Platform ready');
+   *       // The platform is now ready, execute any native code you want
+   *     });
+   *   }
    * }
    * ```
    * @returns {promise}