diff --git a/ionic/components/modal/modal.ts b/ionic/components/modal/modal.ts
index d2178c1ad1..4da81de5d8 100644
--- a/ionic/components/modal/modal.ts
+++ b/ionic/components/modal/modal.ts
@@ -8,14 +8,9 @@ import {extend} from 'ionic/util';
 /**
  * The Modal is a content pane that can go over the user's current page.
  * Usually used for making a choice or editing an item. A modal can be opened
- * similar to how NavController#push works, where you pass it a Page component,
+ * similar to how NavController#push works, where it is passed a Page component,
  * along with optional Page params, and options for presenting the modal.
  *
- *
- * The `modal.open()` function can receive an object as the second argument that will be passed to the modal. For example, `modal.open(MyModal, {data: 7})` will open and pass a data object to `MyModal`.
- * Inside of `MyModal`, this data can be accessed through the modal's `_defaults` property (eg: `this.modal._defaults`).
- *
- *
  * @usage
  * ```ts
  * class MyApp {
@@ -24,13 +19,18 @@ import {extend} from 'ionic/util';
  *    this.modal = modal;
  *  }
  *
- *  openModal() {
- *    this.modal.open(ContactPage, null, {
+ *  openContactModal() {
+ *    this.modal.open(ContactUs);
+ *  }
+ *
+ *  openProfileModal() {
+ *    this.modal.open(Profile, { userId: 8675309 }, {
  *      enterAnimation: 'my-fade-in',
  *      leaveAnimation: 'my-fade-out',
- *      handle: 'my-modal'
+ *      handle: 'profile-modal'
  *    });
  *  }
+ *
  * }
  * ```
  */
@@ -43,26 +43,42 @@ export class Modal {
   }
 
   /**
-   * TODO
-   * @param {TODO} componentType  TODO
-   * @param {TODO} [params={}]  TODO
-   * @param {TODO} [opts={}]  TODO
-   * @returns {Promise} TODO
+   * Opens a new modal using the page component is was pass as the first
+   * argument. This is similar to how NavController's `push` method works.
+   * Currently you must have `<ion-overlay>` in the @App component's template
+   * for the modal to work correctly. (This is something that will
+   * be hopefully be removed in the near future.)
+   * @param pageComponent  The Page component to load in the modal.
+   * @param [params={}]  Optional data which can be passed to the page
+   * component, which can be read from the constructor's `NavParams`.
+   * @param [opts={}]  Additional options for this one modal instance of.
+   * Options include `enterAnimation` and `leaveAnimation`, which
+   * allows customization of which animation to use.
+   * @returns {Promise} Returns a promise which resolves when the modal has
+   * loaded and its entering animation has completed. The resolved promise's
+   * value is the instance of the newly created modal.
    */
-  open(componentType: Type, params={}, opts={}) {
+  open(pageComponent: Type, params={}, opts={}) {
     opts = extend({
       pageType: OVERLAY_TYPE,
       enterAnimation: this.config.get('modalEnter'),
       leaveAnimation: this.config.get('modalLeave'),
     }, opts);
 
-    return this.ctrl.open(componentType, params, opts);
+    return this.ctrl.open(pageComponent, params, opts);
   }
 
   /**
-   * TODO
-   * @param {TODO} handle  TODO
-   * @returns {TODO} TODO
+   * Get the instance of a modal. This is usually helpful to getting ahold of a
+   * certain modal, from anywhere within the app, and closing it. By calling
+   * just `get()` without a `handle` argument, it'll return the active modal
+   * on top (it is possible to have multipe modals opened at the same time).
+   * If getting just the active modal isn't enough, when creating
+   * a modal, it's options can be given a `handle`, which is simply a string-based
+   * name for the modal instance. You can later get a reference to that modal's
+   * instance by calling this method with the same handle name.
+   * @param  [handle]  Optional string name given in the modal's options when it was opened.
+   * @returns Returns the instance of the modal if it is found, otherwise `null`.
    */
   get(handle) {
     if (handle) {
diff --git a/ionic/components/overlay/overlay-controller.ts b/ionic/components/overlay/overlay-controller.ts
index 777a10aaff..9dfbc50c3d 100644
--- a/ionic/components/overlay/overlay-controller.ts
+++ b/ionic/components/overlay/overlay-controller.ts
@@ -2,6 +2,9 @@ import {Animation} from '../../animations/animation';
 import {extend} from 'ionic/util';
 
 
+/**
+ * @private
+ */
 export class OverlayController {
 
   open(componentType, params = {}, opts = {}) {
@@ -34,8 +37,11 @@ export class OverlayController {
         };
 
         document.addEventListener('keyup', escape, true);
+        resolve(viewCtrl.instance);
+
+      } else {
+        reject();
       }
-      resolve();
     })
 
     return promise;
@@ -52,6 +58,3 @@ export class OverlayController {
   }
 
 }
-
-
-const ROOT_Z_INDEX = 1000;