docs(API): update descriptions to be more clear

also update descriptions for the same properties to be more consistent,
and reword all events to start and end the same.

closes #10248 closes ionic-team/ionic-site#613 closes
ionic-team/ionic-site#899

Author: brandyscarney

src/components/alert/alert.ts

@@ -239,7 +239,7 @@ export class Alert extends ViewController {
  *  | Property | Type     | Description                                                     |
  *  |----------|----------|-----------------------------------------------------------------|
  *  | text     | `string` | The buttons displayed text.                                     |
- *  | handler  | `any`    | Expression that should be evaluated when the button is pressed. |
+ *  | handler  | `any`    | Emitted when the button is pressed.                             |
  *  | cssClass | `string` | An additional CSS class for the button.                         |
  *  | role     | `string` | The buttons role, null or `cancel`.                             |
  *

src/components/badge/badge.ts

@@ -17,15 +17,19 @@ import { Ion } from '../ion';
 export class Badge extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {

src/components/button/button.ts

@@ -153,87 +153,90 @@ export class Button extends Ion {
   _init: boolean;
 
   /**
-   * @input {boolean} Large button.
+   * @input {boolean} If true, activates the large button size.
    */
   @Input()
   set large(val: boolean) {
     this._attr('_size', 'large', val);
   }
 
   /**
-   * @input {boolean} Small button.
+   * @input {boolean} If true, activates the small button size.
    */
   @Input()
   set small(val: boolean) {
     this._attr('_size', 'small', val);
   }
 
   /**
-   * @input {boolean} Default button.
+   * @input {boolean} If true, activates the default button size. Normally the default, useful for buttons in an item.
    */
   @Input()
   set default(val: boolean) {
     this._attr('_size', 'default', val);
   }
 
   /**
-   * @input {boolean} A transparent button with a border.
+   * @input {boolean} If true, activates a transparent button style with a border.
    */
   @Input()
   set outline(val: boolean) {
     this._attr('_style', 'outline', val);
   }
 
   /**
-   * @input {boolean} A transparent button without a border.
+   * @input {boolean} If true, activates a transparent button style without a border.
    */
   @Input()
   set clear(val: boolean) {
     this._attr('_style', 'clear', val);
   }
 
   /**
-   * @input {boolean} Force a solid button. Useful for buttons within an item.
+   * @input {boolean} If true, activates a solid button style. Normally the default, useful for buttons in a toolbar.
    */
   @Input()
   set solid(val: boolean) {
     this._attr('_style', 'solid', val);
   }
 
   /**
-   * @input {boolean} A button with rounded corners.
+   * @input {boolean} If true, activates a button with rounded corners.
    */
   @Input()
   set round(val: boolean) {
     this._attr('_shape', 'round', val);
   }
 
   /**
-   * @input {boolean} A button that fills its parent container with a border-radius.
+   * @input {boolean} If true, activates a button style that fills the available width.
    */
   @Input()
   set block(val: boolean) {
     this._attr('_display', 'block', val);
   }
 
   /**
-   * @input {boolean} A button that fills its parent container without a border-radius or borders on the left/right.
+   * @input {boolean} If true, activates a button style that fills the available width without
+   * a left and right border.
    */
   @Input()
   set full(val: boolean) {
     this._attr('_display', 'full', val);
   }
 
   /**
-   * @input {boolean} A button that has strong importance, ie. it represents an important action.
+   * @input {boolean} If true, activates a button with a heavier font weight.
    */
   @Input()
   set strong(val: boolean) {
     this._attr('_decorator', 'strong', val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {
@@ -264,7 +267,9 @@ export class Button extends Ion {
   }
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {

src/components/card/card.ts

@@ -13,15 +13,19 @@ import { Ion } from '../ion';
 export class Card extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {
@@ -44,16 +48,20 @@ export class Card extends Ion {
 export class CardContent extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component.
-   */
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
+  */
   @Input()
   set mode(val: string) {
     this._setMode(val);
@@ -75,15 +83,19 @@ export class CardContent extends Ion {
 export class CardHeader extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {
@@ -105,15 +117,19 @@ export class CardHeader extends Ion {
 export class CardTitle extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {

src/components/checkbox/checkbox.ts

@@ -87,23 +87,27 @@ export class Checkbox extends Ion implements IonicTapInput, AfterContentInit, Co
   id: string;
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {
     this._setMode(val);
   }
 
   /**
-   * @output {Checkbox} expression to evaluate when the checkbox value changes
+   * @output {Checkbox} Emitted when the checkbox value changes.
    */
   @Output() ionChange: EventEmitter<Checkbox> = new EventEmitter<Checkbox>();
 
@@ -138,7 +142,7 @@ export class Checkbox extends Ion implements IonicTapInput, AfterContentInit, Co
   }
 
   /**
-   * @input {boolean} whether or not the checkbox is checked (defaults to false)
+   * @input {boolean} If `true`, the element is selected.
    */
   @Input()
   get checked(): boolean {
@@ -189,7 +193,7 @@ export class Checkbox extends Ion implements IonicTapInput, AfterContentInit, Co
   registerOnTouched(fn: any) { this.onTouched = fn; }
 
   /**
-   * @input {boolean} whether or not the checkbox is disabled or not.
+   * @input {boolean} If true, the user cannot interact with this element.
    */
   @Input()
   get disabled(): boolean {

src/components/chip/chip.ts

@@ -96,15 +96,19 @@ import { Ion } from '../ion';
 export class Chip extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {

src/components/content/content.ts

@@ -463,23 +463,15 @@ export class Content extends Ion implements OnDestroy, OnInit {
   }
 
   /**
-   * @input {boolean} By default, content is positioned between the headers
-   * and footers. However, using `fullscreen="true"`, the content will be
-   * able to scroll "under" the headers and footers. At first glance the
-   * fullscreen option may not look any different than the default, however,
-   * by adding a transparency effect to a header then the content can be
-   * seen under the header as the user scrolls.
-   *
-   * @returns {boolean}
+   * @input {boolean} If true, the content will scroll behind the headers
+   * and footers. This effect can easily be seen by setting the toolbar
+   * to transparent.
    */
   @Input()
   get fullscreen(): boolean {
     return !!this._fullscreen;
   }
 
-  /**
-   * @param {boolean} val
-   */
   set fullscreen(val: boolean) {
     this._fullscreen = isTrueProperty(val);
   }

src/components/datetime/datetime.ts

@@ -408,20 +408,22 @@ export class DateTime extends Ion implements AfterContentInit, ControlValueAcces
   @Input() pickerOptions: any = {};
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {
     this._setMode(val);
   }
 
   /**
-   * @output {any} Any expression to evaluate when the datetime selection has changed.
+   * @output {any} Emitted when the datetime selection has changed.
    */
   @Output() ionChange: EventEmitter<any> = new EventEmitter();
 
   /**
-   * @output {any} Any expression to evaluate when the datetime selection was cancelled.
+   * @output {any} Emitted when the datetime selection was cancelled.
    */
   @Output() ionCancel: EventEmitter<any> = new EventEmitter();
 
@@ -784,14 +786,14 @@ export class DateTime extends Ion implements AfterContentInit, ControlValueAcces
   }
 
   /**
-   * @input {boolean} Whether or not the datetime component is disabled. Default `false`.
+   * @input {boolean} If true, the user cannot interact with this element.
    */
   @Input()
-  get disabled() {
+  get disabled(): boolean {
     return this._disabled;
   }
 
-  set disabled(val) {
+  set disabled(val: boolean) {
     this._disabled = isTrueProperty(val);
     this._item && this._item.setElementClass('item-datetime-disabled', this._disabled);
   }

src/components/fab/fab.ts

@@ -66,15 +66,19 @@ import { UIEventManager } from '../../gestures/ui-event-manager';
 export class FabButton extends Ion {
 
   /**
-   * @input {string} The predefined color to use. For example: `"primary"`, `"secondary"`, `"danger"`.
+   * @input {string} The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/v2/theming/theming-your-app).
    */
   @Input()
   set color(val: string) {
     this._setColor(val);
   }
 
   /**
-   * @input {string} The mode to apply to this component. Mode can be `ios`, `wp`, or `md`.
+   * @input {string} The mode determines which platform styles to use.
+   * Possible values are: `"ios"`, `"md"`, or `"wp"`.
+   * For more information, see [Platform Styles](/docs/v2/theming/platform-specific-styles).
    */
   @Input()
   set mode(val: string) {