docs(actionSheet): more docs

ionic/components/action-sheet/action-sheet.ts

@@ -11,14 +11,29 @@ import {Animation} from '../../animations/animation';
 /**
  * @name ActionSheet
  * @description
- * The Action Sheet is a slide-up dialog that lets the user choose from a set
+ * An Action Sheet is a dialog that lets the user choose from a set of
- * of options. Dangerous (destructive) options are made obvious. There are easy
+ * options. Dangerous (destructive) options are made obvious. There are easy
  * ways to cancel out of the action sheet, such as tapping the backdrop or
  * 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 `style` and `handler`.
+ * If a handler returns `false` then the action sheet will not be dismissed. An
+ * action sheet can also optionally have a `title` and a `subTitle`.
+ *
+ * A button's `style` property can either be `destructive` or `cancel`. Buttons
+ * without a style property will have a default style for its platform. Buttons
+ * with the `cancel` style 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
+ * 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.
+ *
+ * Its shorthand is to add all the action sheet's options from within the
+ * `ActionSheet.create(opts)` first argument. Otherwise the action sheet's
+ * instance has methods to add options, such as `setTitle()` or `addButton()`.
+ *
  * @usage
  * ```ts
- *
  * constructor(nav: NavController) {
  *   this.nav = nav;
  * }