diff --git a/src/components/menu/menu-toggle.ts b/src/components/menu/menu-toggle.ts
index 48cc64c834..080b712477 100644
--- a/src/components/menu/menu-toggle.ts
+++ b/src/components/menu/menu-toggle.ts
@@ -21,13 +21,60 @@ import {MenuController} from './menu-controller';
*
* ```
*
- * To toggle a certain menu by its id or side, give the `menuToggle`
+ * To toggle a specific menu by its id or side, give the `menuToggle`
* directive a value.
*
* ```html
*
* ```
*
+ * If placing the `menuToggle` in a navbar or toolbar, it should be
+ * placed as a child of the `` or ``, and not in
+ * the `` element:
+ *
+ * ```html
+ *
+ *
+ *
+ *
+ *
+ *
+ * Title
+ *
+ *
+ *
+ *
+ *
+ * ```
+ *
+ * Similar to ``, the `menuToggle` can be positioned using
+ * `start`, `end`, `left`, or `right`:
+ *
+ * ```html
+ *
+ *
+ *
+ * Title
+ *
+ *
+ *
+ *
+ *
+ * ```
+ *
+ * See the [Toolbar API docs](../../toolbar/Toolbar) for more information
+ * on the different positions.
+ *
* @demo /docs/v2/demos/menu/
* @see {@link /docs/v2/components#menus Menu Component Docs}
* @see {@link ../../menu/Menu Menu API Docs}
diff --git a/src/components/toolbar/toolbar.ts b/src/components/toolbar/toolbar.ts
index 2fb332a0b9..024292bc1b 100644
--- a/src/components/toolbar/toolbar.ts
+++ b/src/components/toolbar/toolbar.ts
@@ -64,17 +64,41 @@ export class ToolbarBase extends Ion {
/**
* @name Toolbar
* @description
- * The toolbar is generic bar that sits above or below content.
- * Unlike an `Navbar`, `Toolbar` can be used for a subheader as well.
- * Since it's based on flexbox, you can place the toolbar where you
- * need it and flexbox will handle everything else. Toolbars will automatically
- * assume they should be placed before an `ion-content`, so to specify that you want it
- * below, you can add the property `position="bottom"`. This will change the flex order
+ * A Toolbar is a generic bar that is positioned above or below content.
+ * Unlike a [Navbar](../../nav/Navbar), a toolbar can be used as a subheader.
+ * Toolbars are positioned automatically at the `top`, but they can be
+ * positioned at the bottom by setting `position="bottom"` on the component.
+ *
+ *
+ * ### Buttons in a Toolbar
+ * Buttons placed in a toolbar should be placed inside of the ``
+ * element. An exception to this is a [menuToggle](../../menu/MenuToggle) button.
+ * It should not be placed inside of the `` element. Both the
+ * `` element and the `menuToggle` can be positioned inside of the
+ * toolbar using different properties. The below chart has a description of each
* property.
*
+ * | Property | Description |
+ * |-------------|-----------------------------------------------------------------------------------------------------------------------|
+ * | `start` | Positions element to the left of the content in `ios` mode, and directly to the right in `md` and `wp` mode. |
+ * | `end` | Positions element to the right of the content in `ios` mode, and to the far right in `md` and `wp` mode. |
+ * | `left` | Positions element to the left of all other elements. |
+ * | `right` | Positions element to the right of all other elements. |
+ *
+ * See [usage](#usage) below for some examples.
+ *
+ *
* @usage
* ```html
*
+ *
+ *
+ *
+ *
* My Toolbar Title
*
*
@@ -82,16 +106,28 @@ export class ToolbarBase extends Ion {
* I'm a subheader
*
*
- *
+ *
*
*
* I'm a subfooter
+ *
+ *
+ *
*
*
*
* I'm a footer
+ *
+ *
+ *
+ *
*
- *
* ```
*
* @property {any} [position] - set position of the toolbar, `top` or `bottom`.
@@ -134,20 +170,27 @@ export class Toolbar extends ToolbarBase {
* @name Title
* @description
* `ion-title` is a component that sets the title of the `Toolbar` or `Navbar`
+ *
* @usage
+ *
+ * ```html
+ *
+ * Tab 1
+ *
+ * ```
+ *
+ * Or to create a navbar with a toolbar as a subheader:
+ *
* ```html
*
* Tab 1
*
*
- *
- *
- * Tab 1
- *
*
- * SubHeader
+ * Subheader
*
- * ```
+ * ```
+ *
* @demo /docs/v2/demos/title/
*/
@Component({
@@ -195,23 +238,6 @@ export class ToolbarItem {
toolbar && toolbar.addItemRef(elementRef);
navbar && navbar.addItemRef(elementRef);
this.inToolbar = !!(toolbar || navbar);
-
- // Deprecation warning
- if (elementRef.nativeElement.tagName === 'ION-NAV-ITEMS') {
-
- if (elementRef.nativeElement.hasAttribute('primary')) {
- console.warn(' has been renamed to , please update your HTML');
- elementRef.nativeElement.setAttribute('start', '');
-
- } else if (elementRef.nativeElement.hasAttribute('secondary')) {
- console.warn(' has been renamed to , please update your HTML');
- elementRef.nativeElement.setAttribute('end', '');
-
- } else {
- console.warn(' has been renamed to , please update your HTML');
- }
- }
-
}
@ContentChildren(Button)