docs(overlays): update to match style guide and update comments

packages/core/src/components/alert-controller/alert-controller.tsx

@@ -25,7 +25,7 @@ export class AlertController implements OverlayController {
   }
 
   /*
-   * Create an alert with optional titles, buttons and inputs.
+   * Create an alert overlay with alert options.
    */
   @Method()
   create(opts?: AlertOptions): Promise<HTMLIonAlertElement> {
@@ -47,7 +47,7 @@ export class AlertController implements OverlayController {
   }
 
   /*
-   * Dismiss an open alert.
+   * Dismiss the open alert overlay.
    */
   @Method()
   dismiss(data?: any, role?: any, alertId = -1) {
@@ -60,7 +60,7 @@ export class AlertController implements OverlayController {
   }
 
   /*
-   * Get the most recently opened alert.
+   * Get the most recently opened alert overlay.
    */
   @Method()
   getTop() {

packages/core/src/components/loading-controller/loading-controller.tsx

@@ -9,6 +9,24 @@ const loadings = new Map<number, HTMLIonLoadingElement>();
 })
 export class LoadingController implements OverlayController {
 
+  @Listen('body:ionLoadingWillPresent')
+  protected loadingWillPresent(ev: LoadingEvent) {
+    loadings.set(ev.target.loadingId, ev.target);
+  }
+
+  @Listen('body:ionLoadingWillDismiss, body:ionLoadingDidUnload')
+  protected loadingWillDismiss(ev: LoadingEvent) {
+    loadings.delete(ev.target.loadingId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastLoading();
+  }
+
+  /*
+   * Create a loading overlay with loading options.
+   */
   @Method()
   create(opts?: LoadingOptions): Promise<HTMLIonLoadingElement> {
     // create ionic's wrapping ion-loading component
@@ -28,6 +46,9 @@ export class LoadingController implements OverlayController {
     return loadingElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open loading overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, loadingId = -1) {
     loadingId = loadingId >= 0 ? loadingId : getHighestId();
@@ -35,27 +56,13 @@ export class LoadingController implements OverlayController {
     return loading.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened loading overlay.
+   */
   @Method()
   getTop() {
     return loadings.get(getHighestId());
   }
-
-  @Listen('body:ionLoadingWillPresent')
-  protected loadingWillPresent(ev: LoadingEvent) {
-    loadings.set(ev.target.loadingId, ev.target);
-  }
-
-
-  @Listen('body:ionLoadingWillDismiss, body:ionLoadingDidUnload')
-  protected loadingWillDismiss(ev: LoadingEvent) {
-    loadings.delete(ev.target.loadingId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastLoading();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/modal-controller/modal-controller.tsx

@@ -9,6 +9,24 @@ const modals = new Map<number, HTMLIonModalElement>();
 })
 export class ModalController implements OverlayController {
 
+  @Listen('body:ionModalWillPresent')
+  protected modalWillPresent(ev: ModalEvent) {
+    modals.set(ev.target.modalId, ev.target);
+  }
+
+  @Listen('body:ionModalWillDismiss, body:ionModalDidUnload')
+  protected modalWillDismiss(ev: ModalEvent) {
+    modals.delete(ev.target.modalId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastModal();
+  }
+
+  /*
+   * Create a modal overlay with modal options.
+   */
   @Method()
   create(opts?: ModalOptions): Promise<HTMLIonModalElement> {
     // create ionic's wrapping ion-modal component
@@ -28,6 +46,9 @@ export class ModalController implements OverlayController {
     return modalElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open modal overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, modalId = -1) {
     modalId = modalId >= 0 ? modalId : getHighestId();
@@ -38,26 +59,13 @@ export class ModalController implements OverlayController {
     return modal.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened modal overlay.
+   */
   @Method()
   getTop() {
     return modals.get(getHighestId());
   }
-
-  @Listen('body:ionModalWillPresent')
-  protected modalWillPresent(ev: ModalEvent) {
-    modals.set(ev.target.modalId, ev.target);
-  }
-
-
-  @Listen('body:ionModalWillDismiss, body:ionModalDidUnload')
-  protected modalWillDismiss(ev: ModalEvent) {
-    modals.delete(ev.target.modalId);
-  }
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastModal();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/picker-controller/picker-controller.tsx

@@ -9,6 +9,24 @@ const pickers = new Map<number, HTMLIonPickerElement>();
 })
 export class PickerController implements OverlayController {
 
+  @Listen('body:ionPickerWillPresent')
+  protected pickerWillPresent(ev: PickerEvent) {
+    pickers.set(ev.target.pickerId, ev.target);
+  }
+
+  @Listen('body:ionPickerWillDismiss, body:ionPickerDidUnload')
+  protected pickerWillDismiss(ev: PickerEvent) {
+    pickers.delete(ev.target.pickerId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastPicker();
+  }
+
+  /*
+   * Create a picker overlay with picker options.
+   */
   @Method()
   create(opts?: PickerOptions): Promise<HTMLIonPickerElement> {
     // create ionic's wrapping ion-picker component
@@ -28,6 +46,9 @@ export class PickerController implements OverlayController {
     return pickerElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open picker overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, pickerId = -1) {
     pickerId = pickerId >= 0 ? pickerId : getHighestId();
@@ -38,27 +59,13 @@ export class PickerController implements OverlayController {
     return picker.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened picker overlay.
+   */
   @Method()
   getTop() {
     return pickers.get(getHighestId());
   }
-
-  @Listen('body:ionPickerWillPresent')
-  protected pickerWillPresent(ev: PickerEvent) {
-    pickers.set(ev.target.pickerId, ev.target);
-  }
-
-
-  @Listen('body:ionPickerWillDismiss, body:ionPickerDidUnload')
-  protected pickerWillDismiss(ev: PickerEvent) {
-    pickers.delete(ev.target.pickerId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastPicker();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/popover-controller/popover-controller.tsx

@@ -9,6 +9,24 @@ const popovers = new Map<number, HTMLIonPopoverElement>();
 })
 export class PopoverController implements OverlayController {
 
+  @Listen('body:ionPopoverWillPresent')
+  protected popoverWillPresent(ev: PopoverEvent) {
+    popovers.set(ev.target.popoverId, ev.target);
+  }
+
+  @Listen('body:ionPopoverWillDismiss, body:ionPopoverDidUnload')
+  protected popoverWillDismiss(ev: PopoverEvent) {
+    popovers.delete(ev.target.popoverId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastPopover();
+  }
+
+  /*
+   * Create a popover overlay with popover options.
+   */
   @Method()
   create(opts?: PopoverOptions): Promise<HTMLIonPopoverElement> {
     // create ionic's wrapping ion-popover component
@@ -28,6 +46,9 @@ export class PopoverController implements OverlayController {
     return popoverElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open popover overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, popoverId = -1) {
     popoverId = popoverId >= 0 ? popoverId : getHighestId();
@@ -38,27 +59,13 @@ export class PopoverController implements OverlayController {
     return popover.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened popover overlay.
+   */
   @Method()
   getTop() {
     return popovers.get(getHighestId());
   }
-
-  @Listen('body:ionPopoverWillPresent')
-  protected popoverWillPresent(ev: PopoverEvent) {
-    popovers.set(ev.target.popoverId, ev.target);
-  }
-
-
-  @Listen('body:ionPopoverWillDismiss, body:ionPopoverDidUnload')
-  protected popoverWillDismiss(ev: PopoverEvent) {
-    popovers.delete(ev.target.popoverId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastPopover();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/toast-controller/toast-controller.tsx

@@ -9,6 +9,24 @@ const toasts = new Map<number, HTMLIonToastElement>();
 })
 export class ToastController implements OverlayController {
 
+  @Listen('body:ionToastWillPresent')
+  protected toastWillPresent(ev: ToastEvent) {
+    toasts.set(ev.target.toastId, ev.target);
+  }
+
+  @Listen('body:ionToastWillDismiss, body:ionToastDidUnload')
+  protected toastWillDismiss(ev: ToastEvent) {
+    toasts.delete(ev.target.toastId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastToast();
+  }
+
+  /*
+   * Create a toast overlay with toast options.
+   */
   @Method()
   create(opts?: ToastOptions): Promise<HTMLIonToastElement> {
     // create ionic's wrapping ion-toast component
@@ -28,6 +46,9 @@ export class ToastController implements OverlayController {
     return toastElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open toast overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, toastId = -1) {
     toastId = toastId >= 0 ? toastId : getHighestId();
@@ -38,27 +59,13 @@ export class ToastController implements OverlayController {
     return toast.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened toast overlay.
+   */
   @Method()
   getTop() {
     return toasts.get(getHighestId());
   }
-
-  @Listen('body:ionToastWillPresent')
-  protected toastWillPresent(ev: ToastEvent) {
-    toasts.set(ev.target.toastId, ev.target);
-  }
-
-
-  @Listen('body:ionToastWillDismiss, body:ionToastDidUnload')
-  protected toastWillDismiss(ev: ToastEvent) {
-    toasts.delete(ev.target.toastId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastToast();
-  }
 }
 
 function getHighestId() {