diff --git a/ionic/components/action-sheet/action-sheet.ts b/ionic/components/action-sheet/action-sheet.ts
index eff9962746..44af5bb44b 100644
--- a/ionic/components/action-sheet/action-sheet.ts
+++ b/ionic/components/action-sheet/action-sheet.ts
@@ -16,9 +16,9 @@ import {ViewController} from '../nav/view-controller';
* An Action Sheet is a dialog that lets the user choose from a set of
* options. It appears on top of the app's content, and must be manually
* dismissed by the user before they can resume interaction with the app.
- * Dangerous (destructive) options are made obvious. There are easy
+ * Dangerous (destructive) options are made obvious in `ios` mode. There are easy
* ways to cancel out of the action sheet, such as tapping the backdrop or
- * hitting the escape key on desktop.
+ * hitting the escape key on desktop.
*
* An action sheet is created from an array of `buttons`, with each button
* including properties for its `text`, and optionally a `handler` and `role`.
@@ -26,16 +26,16 @@ import {ViewController} from '../nav/view-controller';
* action sheet can also optionally have a `title` and a `subTitle`.
*
* A button's `role` property can either be `destructive` or `cancel`. Buttons
- * without a role property will have a default look for its platform. Buttons
+ * without a role property will have the default look for the platform. Buttons
* with the `cancel` role will always load as the bottom button, no matter where
- * it shows up in the array. All other buttons will show up in the order they
+ * they are in the array. All other buttons will be displayed in the order they
* have been added to the `buttons` array. Note: We recommend that `destructive`
- * buttons show be the first button in the array, making it the button on top.
+ * buttons are always the first button in the array, making them the top button.
* Additionally, if the action sheet is dismissed by tapping the backdrop, then
* it will fire the handler from the button with the cancel role.
*
- * Its shorthand is to add all the action sheet's options from within the
- * `ActionSheet.create(opts)` first argument. Otherwise the action sheet's
+ * You can pass all of the action sheet's options in the first argument of
+ * the create method: `ActionSheet.create(opts)`. Otherwise the action sheet's
* instance has methods to add options, like `setTitle()` or `addButton()`.
*
* @usage
diff --git a/ionic/components/alert/alert.ts b/ionic/components/alert/alert.ts
index 8743b24936..e8e4aee1b2 100644
--- a/ionic/components/alert/alert.ts
+++ b/ionic/components/alert/alert.ts
@@ -12,8 +12,8 @@ import {ViewController} from '../nav/view-controller';
/**
* @name Alert
* @description
- * An Alert is a dialog that presents users with either information, or used
- * to receive information from the user using inputs. An alert appears on top
+ * An Alert is a dialog that presents users with information or collects
+ * information from the user using inputs. An alert appears on top
* of the app's content, and must be manually dismissed by the user before
* they can resume interaction with the app.
*
@@ -31,11 +31,11 @@ import {ViewController} from '../nav/view-controller';
* by tapping the backdrop, then it will fire the handler from the button
* with a cancel role.
*
- * Alerts can also include inputs whos data can be passed back to the app.
+ * Alerts can also include inputs whose data can be passed back to the app.
* Inputs can be used to prompt users for information.
*
- * Its shorthand is to add all the alert's options from within the
- * `Alert.create(opts)` first argument. Otherwise the alert's instance
+ * You can pass all of the alert's options in the first argument of
+ * the create method: `Alert.create(opts)`. Otherwise the alert's instance
* has methods to add options, such as `setTitle()` or `addButton()`.
*
* @usage
diff --git a/ionic/components/app/id.ts b/ionic/components/app/id.ts
index 0a1b453510..4729ad0e73 100644
--- a/ionic/components/app/id.ts
+++ b/ionic/components/app/id.ts
@@ -5,9 +5,9 @@ import {IonicApp} from './app';
/**
* @name Id
* @description
- * IdRef is an easy way to identify unique components in an app and access them
+ * The `id` attribute is an easy way to identify unique components in an app and access them
* no matter where in the UI hierarchy you are. For example, this makes toggling
- * a global side menu feasible from any place in the application.
+ * a global side menu possible from any place in the application.
*
* See the [Menu section](http://ionicframework.com/docs/v2/components/#menus) of
* the Component docs for an example of how Menus rely on ID's.
diff --git a/ionic/components/button/button.ts b/ionic/components/button/button.ts
index 14ec44ffb1..02cad24786 100644
--- a/ionic/components/button/button.ts
+++ b/ionic/components/button/button.ts
@@ -7,26 +7,29 @@ import {Toolbar} from '../toolbar/toolbar';
/**
* @name Button
* @module ionic
- * @property [outline] - for an unfilled outline button
- * @property [clear] - for a transparent button that only shows text and icons
- * @property [round] - for a button with rounded corners
- * @property [block] - for a block button that fills it's parent container
- * @property [full] - for a full width button
- * @property [small] - sets button size to small
- * @property [large] - sets button size to large
- * @property [disabled] - disables the button
- * @property [fab] - for a floating action button
- * @property [fab-left] - position a fab button to the left
- * @property [fab-right] - position a fab button to the right
- * @property [fab-center] - position a fab button towards the center
- * @property [fab-top] - position a fab button towards the top
- * @property [fab-bottom] - position a fab button towards the bottom
- * @property [color] - Dynamically set which color attribute this button should use.
+ *
* @description
- * Buttons are simple components in Ionic, can consist of text, an icon, or both, and can be enhanced with a wide range of attributes.
+ * Buttons are simple components in Ionic. They can consist of text and icons
+ * and be enhanced by a wide range of attributes.
+ *
+ * @property [outline] - A transparent button with a border.
+ * @property [clear] - A transparent button without a border.
+ * @property [round] - A button with rounded corners.
+ * @property [block] - A button that fills its parent container with a border-radius.
+ * @property [full] - A button that fills its parent container without a border-radius or borders on the left/right.
+ * @property [small] - A button with size small.
+ * @property [large] - A button with size large.
+ * @property [disabled] - A disabled button.
+ * @property [fab] - A floating action button.
+ * @property [fab-left] - Position a fab button to the left.
+ * @property [fab-right] - Position a fab button to the right.
+ * @property [fab-center] - Position a fab button towards the center.
+ * @property [fab-top] - Position a fab button towards the top.
+ * @property [fab-bottom] - Position a fab button towards the bottom.
+ * @property [color] - Dynamically set which color attribute this button should use.
+ *
* @demo /docs/v2/demos/button/
* @see {@link /docs/v2/components#buttons Button Component Docs}
-
*/
@Component({
selector: 'button:not([ion-item]),[button]',
diff --git a/ionic/components/checkbox/checkbox.ts b/ionic/components/checkbox/checkbox.ts
index bcb2d8dad1..ca7d6d6c28 100644
--- a/ionic/components/checkbox/checkbox.ts
+++ b/ionic/components/checkbox/checkbox.ts
@@ -10,9 +10,12 @@ const CHECKBOX_VALUE_ACCESSOR = new Provider(
/**
- * The checkbox is no different than the HTML checkbox input, except
- * it's styled accordingly to the the platform and design mode, such
- * as iOS or Material Design.
+ * @name Checkbox
+ * @module ionic
+ *
+ * @description
+ * The Checkbox is a simple component styled based on the mode. It can be
+ * placed in an `ion-item` or used as a stand-alone checkbox.
*
* See the [Angular 2 Docs](https://angular.io/docs/ts/latest/guide/forms.html)
* for more info on forms and inputs.
@@ -40,6 +43,7 @@ const CHECKBOX_VALUE_ACCESSOR = new Provider(
*
*
* ```
+ *
* @demo /docs/v2/demos/checkbox/
* @see {@link /docs/v2/components#checkbox Checkbox Component Docs}
*/
diff --git a/ionic/components/icon/icon.ts b/ionic/components/icon/icon.ts
index 45b99af1b5..540299a217 100644
--- a/ionic/components/icon/icon.ts
+++ b/ionic/components/icon/icon.ts
@@ -10,12 +10,12 @@ import {Config} from '../../config/config';
* For a full list of available icons, check out the
* [Ionicons resource docs](../../../../resources/ionicons).
*
- * One feature of Ionicons is that when icon names are set, the actual icon
+ * One feature of Ionicons in Ionic is when icon names are set, the actual icon
* which is rendered can change slightly depending on the mode the app is
* running from. For example, by setting the icon name of `alarm`, on iOS the
* icon will automatically apply `ios-alarm`, and on Material Design it will
- * automatically apply `md-alarm`. This allow the developer to write the
- * markup once, and let Ionic automatically apply the appropriate icon.
+ * automatically apply `md-alarm`. This allows the developer to write the
+ * markup once while Ionic applies the appropriate icon based on the mode.
*
* @usage
* ```html
diff --git a/ionic/components/label/label.ts b/ionic/components/label/label.ts
index bef41feb2c..280c4d8366 100644
--- a/ionic/components/label/label.ts
+++ b/ionic/components/label/label.ts
@@ -4,10 +4,8 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul
/**
* @name Label
* @description
- * Labels describe the data that the user should enter in to an input
- * element. You can give `ion-label` attributes to tell it how to
- * handle its display type, which is especially useful for an
- * `ion-item` which contains a text input.
+ * Labels are placed inside of an `ion-item` element and can be used
+ * to describe an `ion-input`, `ion-toggle`, `ion-checkbox`, and more.
*
* @property [fixed] - a persistant label that sits next the the input
* @property [floating] - a label that will float about the input if the input is empty of looses focus
@@ -22,7 +20,7 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul
*
*
*
- * Website
+ * Website
*
*
*
@@ -36,6 +34,15 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul
*
*
*
+ *
+ * Toggle
+ *
+ *
+ *
+ *
+ * Checkbox
+ *
+ *
* ```
*
* @demo /docs/v2/demos/label/
diff --git a/ionic/components/menu/menu-controller.ts b/ionic/components/menu/menu-controller.ts
index 161ae339fc..df22a92bd3 100644
--- a/ionic/components/menu/menu-controller.ts
+++ b/ionic/components/menu/menu-controller.ts
@@ -8,7 +8,7 @@ import {MenuType} from './menu-types';
* _For basic Menu usage, see the [Menu section](../../../../components/#menus)
* of the Component docs._
*
- * Menu is a side-menu interface that can be dragged out or toggled to open or closed.
+ * Menu is a side-menu interface that can be dragged and toggled to open or close.
* An Ionic app can have numerous menus, all of which can be controlled within
* template HTML, or programmatically.
*
diff --git a/ionic/components/navbar/navbar.ts b/ionic/components/navbar/navbar.ts
index 4774ec9fd3..4f4dce9aed 100644
--- a/ionic/components/navbar/navbar.ts
+++ b/ionic/components/navbar/navbar.ts
@@ -63,17 +63,14 @@ class ToolbarBackground {
* @name Navbar
* @description
* Navbar is a global level toolbar that gets updated every time a page gets
- * loaded. You can pass the navbar a `ion-title` or any number of buttons.
+ * loaded. You can pass the navbar an `ion-title`, any number of buttons, a segment, or a searchbar.
*
* @usage
* ```html
*
- *
- *
- *
- *
+ *
*
*
* Page Title
@@ -81,7 +78,7 @@ class ToolbarBackground {
*
*
*
*
*
diff --git a/ionic/components/show-hide-when/show-hide-when.ts b/ionic/components/show-hide-when/show-hide-when.ts
index b655369890..65b5c68111 100644
--- a/ionic/components/show-hide-when/show-hide-when.ts
+++ b/ionic/components/show-hide-when/show-hide-when.ts
@@ -65,7 +65,25 @@ export class DisplayWhen {
* Complements the [hideWhen attribute](../HideWhen).
* @usage
* ```html
- *
* ```
+ *
* @demo /docs/v2/demos/hide-when/
* @see {@link ../ShowWhen ShowWhen API Docs}
*/
diff --git a/ionic/config/config.ts b/ionic/config/config.ts
index 0f11e5e377..639a9ca765 100644
--- a/ionic/config/config.ts
+++ b/ionic/config/config.ts
@@ -13,7 +13,8 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util';
* @name Config
* @demo /docs/v2/demos/config/
* @description
- * Config lets you change multiple or a single value in an apps mode configuration. Things such as tab placement, icon changes, and view animations can be set here.
+ * The Config lets you configure your entire app or specific platforms.
+ * You can set the tab placement, icon mode, animations, and more here.
*
* ```ts
* @App({
@@ -29,7 +30,7 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util';
* })
* ```
*
- * Or change the whole mode
+ * To change the mode to always use Material Design (md).
*
* ```ts
* @App({
@@ -40,7 +41,7 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util';
* })
* ```
*
- * Config can be overwritting at multiple levels, allowing deeper configuration. Taking the example from earlier, we can override any setting we want based on a platform.
+ * Config can be overwritten at multiple levels allowing for more configuration. Taking the example from earlier, we can override any setting we want based on a platform.
* ```ts
* @App({
* template: ``
@@ -63,8 +64,6 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util';
*
* ```
*
- * The property will override anything else set in the apps.
- *
* The last way we could configure is through URL query strings. This is useful for testing while in the browser.
* Simply add `?ionic=` to the url.
*
diff --git a/ionic/util/events.ts b/ionic/util/events.ts
index 3aa444ac21..413e4b459d 100644
--- a/ionic/util/events.ts
+++ b/ionic/util/events.ts
@@ -1,8 +1,9 @@
/**
* @name Events
* @description
- * Events is a pub/sub style event system for sending and responding to application-level
+ * Events is a publish-subscribe style event system for sending and responding to application-level
* events across your app.
+ *
* @usage
* ```ts
* // first page (publish an event when a user is created)
diff --git a/ionic/util/keyboard.ts b/ionic/util/keyboard.ts
index 0d3c0bc558..7614041539 100644
--- a/ionic/util/keyboard.ts
+++ b/ionic/util/keyboard.ts
@@ -7,7 +7,7 @@ import {hasFocusedTextInput, raf, rafFrames} from './dom';
/**
* @name Keyboard
* @description
- * The `Keyboard` class allows you to work with the keyboard events provide by the Ionic keyboard plugin.
+ * The `Keyboard` class allows you to work with the keyboard events provided by the Ionic keyboard plugin.
*
* @usage
* ```ts