docs(breaking): update breaking changes to include overlays

closes #14633

angular/BREAKING.md

@@ -25,6 +25,7 @@ A list of the breaking changes introduced in Ionic Angular v4.
 - [Nav](#nav)
 - [Navbar](#navbar)
 - [Option](#option)
+- [Overlays](#overlays)
 - [Radio](#radio)
 - [Range](#range)
 - [Segment](#segment)
@@ -430,6 +431,8 @@ The `<ion-fab>` container was previously placed inside of the fixed content by d
 
 ## Grid
 
+### Markup Changed
+
 The Grid has been refactored in order to support css variables and a dynamic number of columns. The following column attributes have been changed.
 
 _In the following examples, `{breakpoint}` refers to the optional screen breakpoint (xs, sm, md, lg, xl) and `{value}` refers to the number of columns._
@@ -439,7 +442,7 @@ _In the following examples, `{breakpoint}` refers to the optional screen breakpo
 - `push-{breakpoint}-{value}` attributes have been renamed to `push-{breakpoint}=“{value}”`
 - `pull-{breakpoint}-{value}` attributes have been renamed to `pull-{breakpoint}=“{value}”`
 
-Customizing the padding styles should now be done with css variables. For more information, see [Grid Layout](https://github.com/ionic-team/ionic-docs/blob/master/src/content/layout/grid.md).
+Customizing the padding and width of a grid should now be done with css variables. For more information, see [Grid Layout](https://github.com/ionic-team/ionic-docs/blob/master/src/content/layout/grid.md).
 
 ## Icon
 
@@ -780,6 +783,40 @@ Select's option element should now be written as `<ion-select-option>`. This mak
 
 The class has been renamed from `Option` to `SelectOption` to keep it consistent with the element tag name.
 
+## Overlays
+
+### Markup Changed
+
+Action Sheet, Alert, Loading, Modal, Popover, and Toast should now use `async`/`await`:
+
+**New Usage Example:**
+
+```javascript
+presentPopover(ev: any) {
+  const popover = this.popoverController.create({
+    component: PopoverComponent,
+    ev: event,
+    translucent: true
+  });
+  popover.present();
+}
+```
+
+**Old Usage Example:**
+
+```javascript
+async presentPopover(ev: any) {
+  const popover = await this.popoverController.create({
+    component: PopoverComponent,
+    ev: event,
+    translucent: true
+  });
+  return await popover.present();
+}
+```
+
+
+
 ## Radio
 
 ### Slot Required

core/src/components.d.ts

@@ -4666,8 +4666,17 @@ declare global {
 
   namespace StencilComponents {
     interface IonPopoverController {
+      /**
+       * Create a popover overlay with popover options.
+       */
       'create': (opts?: PopoverOptions | undefined) => Promise<HTMLIonPopoverElement | null>;
+      /**
+       * Dismiss the open popover overlay.
+       */
       'dismiss': (data?: any, role?: string | undefined, popoverId?: number) => Promise<void>;
+      /**
+       * Get the most recently opened popover overlay.
+       */
       'getTop': () => HTMLIonPopoverElement;
     }
   }
@@ -7592,7 +7601,7 @@ declare global {
        */
       'checked': boolean;
       /**
-       * The color to use from your Sass `$colors` map. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information, see [Theming your App](/docs/theming/theming-your-app).
+       * The color to use from your Sass `$colors` map. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
        */
       'color': Color;
       /**
@@ -7600,7 +7609,7 @@ declare global {
        */
       'disabled': boolean;
       /**
-       * The mode determines which platform styles to use. Possible values are: `"ios"` or `"md"`. For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
+       * The mode determines which platform styles to use. Possible values are: `"ios"` or `"md"`.
        */
       'mode': Mode;
       /**
@@ -7638,7 +7647,7 @@ declare global {
        */
       'checked'?: boolean;
       /**
-       * The color to use from your Sass `$colors` map. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information, see [Theming your App](/docs/theming/theming-your-app).
+       * The color to use from your Sass `$colors` map. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
        */
       'color'?: Color;
       /**
@@ -7646,7 +7655,7 @@ declare global {
        */
       'disabled'?: boolean;
       /**
-       * The mode determines which platform styles to use. Possible values are: `"ios"` or `"md"`. For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
+       * The mode determines which platform styles to use. Possible values are: `"ios"` or `"md"`.
        */
       'mode'?: Mode;
       /**

core/src/components/popover-controller/readme.md

@@ -10,12 +10,18 @@ Popover controllers programmatically control the popover component. Popovers can
 
 #### create()
 
+Create a popover overlay with popover options.
+
 
 #### dismiss()
 
+Dismiss the open popover overlay.
+
 
 #### getTop()
 
+Get the most recently opened popover overlay.
+
 
 
 ----------------------------------------------

core/src/components/toggle/readme.md

@@ -22,7 +22,6 @@ string
 
 The color to use from your Sass `$colors` map.
 Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
-For more information, see [Theming your App](/docs/theming/theming-your-app).
 
 
 #### disabled
@@ -38,7 +37,6 @@ string
 
 The mode determines which platform styles to use.
 Possible values are: `"ios"` or `"md"`.
-For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
 
 
 #### name
@@ -70,7 +68,6 @@ string
 
 The color to use from your Sass `$colors` map.
 Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
-For more information, see [Theming your App](/docs/theming/theming-your-app).
 
 
 #### disabled
@@ -86,7 +83,6 @@ string
 
 The mode determines which platform styles to use.
 Possible values are: `"ios"` or `"md"`.
-For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
 
 
 #### name