From d464f8f02c01583dc9a6d5139b702c9cf8bfe40e Mon Sep 17 00:00:00 2001
From: Drew Rygh <drew.rygh@gmail.com>
Date: Sun, 6 Sep 2015 18:02:26 -0500
Subject: [PATCH] docs: add descriptions and examples for core components

---
 ionic/components/action-menu/action-menu.ts | 41 +++++++++++++--
 ionic/components/checkbox/checkbox.ts       | 13 ++++-
 ionic/components/content/content.ts         |  3 ++
 ionic/components/item/item.ts               | 16 +++---
 ionic/components/modal/modal.ts             | 22 ++++++++-
 ionic/components/popup/popup.ts             | 38 +++++++++++++-
 ionic/components/radio/radio.ts             | 55 +++++++++++++++++++--
 ionic/components/scroll/pull-to-refresh.ts  | 35 ++++++++++++-
 ionic/components/switch/switch.ts           | 39 ++++++++++++++-
 9 files changed, 241 insertions(+), 21 deletions(-)

diff --git a/ionic/components/action-menu/action-menu.ts b/ionic/components/action-menu/action-menu.ts
index b6a6eefe9a..c675a5649a 100644
--- a/ionic/components/action-menu/action-menu.ts
+++ b/ionic/components/action-menu/action-menu.ts
@@ -15,6 +15,44 @@ import {Animation} from '../../animations/animation';
 import * as util from 'ionic/util';
 
 
+/**
+ * @name ActionMenu
+ * @classdesc
+ * The Action Menu is a slide-up pane that lets the user choose from a set of options. Dangerous options are made obvious.
+ *
+ * There are easy ways to cancel out of the action sheet, such as tapping the backdrop or even hitting escape on the keyboard for desktop testing.
+ *
+ * @example
+ * ```ts
+ * openMenu() {
+ *
+ *   this.actionMenu.open({
+ *     buttons: [
+ *       { text: 'Share This' },
+ *       { text: 'Move' }
+ *     ],
+ *     destructiveText: 'Delete',
+ *     titleText: 'Modify your album',
+ *     cancelText: 'Cancel',
+ *     cancel: function() {
+ *       console.log('Canceled');
+ *     },
+ *     destructiveButtonClicked: () => {
+ *       console.log('Destructive clicked');
+ *     },
+ *     buttonClicked: function(index) {
+ *       console.log('Button clicked', index);
+ *       if(index == 1) { return false; }
+ *       return true;
+ *     }
+ *
+ *   }).then(actionMenuRef => {
+ *     this.actionMenuRef = actionMenuRef;
+ *   });
+ *
+ * }
+ * ```
+ */
 @View({
   template:
     '<backdrop (click)="_cancel()" tappable></backdrop>' +
@@ -61,9 +99,6 @@ class ActionMenuDirective {
   }
 }
 
-/**
- * TODO
- */
 @Injectable()
 export class ActionMenu extends Overlay {
   /**
diff --git a/ionic/components/checkbox/checkbox.ts b/ionic/components/checkbox/checkbox.ts
index b8a9abc791..45367b92e0 100644
--- a/ionic/components/checkbox/checkbox.ts
+++ b/ionic/components/checkbox/checkbox.ts
@@ -13,7 +13,18 @@ import {IonicComponent, IonicView} from '../../config/annotations';
 import {TapClick} from '../button/button';
 
 /**
- * Checkbox control value accessor.
+ * @name ionCheckbox
+ * @classdesc
+ * The checkbox is no different than the HTML checkbox input, except it's styled differently
+ *
+ * See the [Angular 2 Docs](https://angular.io/docs/js/latest/api/forms/) for more info on forms and input.
+ *
+ * @example
+ * ```html
+ * <ion-checkbox checked="true" value="isChecked" ng-control="htmlCtrl">
+ *   HTML5
+ * </ion-checkbox>
+ * ```
  */
 @IonicComponent({
   selector: 'ion-checkbox',
diff --git a/ionic/components/content/content.ts b/ionic/components/content/content.ts
index 55cb326478..3e93ae6c46 100644
--- a/ionic/components/content/content.ts
+++ b/ionic/components/content/content.ts
@@ -7,7 +7,10 @@ import {ScrollTo} from '../../animations/scroll-to';
 import {hasFocusedTextInput} from '../../util/dom';
 
 /**
+ * @name ionContent
+ * @classdesc
  * TODO
+ *
  */
 @Component({
   selector: 'ion-content',
diff --git a/ionic/components/item/item.ts b/ionic/components/item/item.ts
index 753dce0241..5221186e40 100644
--- a/ionic/components/item/item.ts
+++ b/ionic/components/item/item.ts
@@ -12,14 +12,14 @@ import {dom} from 'ionic/util';
  *
  * @example
  * ```html
- *  <ion-list>
- *    <ion-item *ng-for="#item of items" (^click)="itemTapped($event, item)">
- *      {{item.title}}
- *      <div class="item-note" item-right>
- *        {{item.note}}
- *      </div>
- *    </ion-item>
- *  </ion-list>
+ * <ion-list>
+ *   <ion-item *ng-for="#item of items" (^click)="itemTapped($event, item)">
+ *     {{item.title}}
+ *     <div class="item-note" item-right>
+ *       {{item.note}}
+ *     </div>
+ *   </ion-item>
+ * </ion-list>
  *  ```
  */
 @Component({
diff --git a/ionic/components/modal/modal.ts b/ionic/components/modal/modal.ts
index 7a650e9f92..30459cb6a7 100644
--- a/ionic/components/modal/modal.ts
+++ b/ionic/components/modal/modal.ts
@@ -5,7 +5,27 @@ import {Animation} from '../../animations/animation';
 import * as util from 'ionic/util';
 
 /**
- * TODO
+ * @name ionModal
+ * @classdesc
+ * The Modal is a content pane that can go over the user's main view temporarily. Usually used for making a choice or editing an item.
+ *
+ * @example
+ * ```ts
+ * class MyApp {
+ * 
+ *  constructor(modal: Modal, app: IonicApp, ionicConfig: IonicConfig) {
+ *    this.modal = modal;
+ *  }
+ * 
+ *  openModal() {
+ *    this.modal.open(ContactModal, {
+ *      enterAnimation: 'my-fade-in',
+ *      leaveAnimation: 'my-fade-out',
+ *      handle: 'my-modal'
+ *    });
+ *  }
+ * }
+ * ```
  */
 @Injectable()
 export class Modal extends Overlay {
diff --git a/ionic/components/popup/popup.ts b/ionic/components/popup/popup.ts
index 754146e84f..72ea5e0472 100644
--- a/ionic/components/popup/popup.ts
+++ b/ionic/components/popup/popup.ts
@@ -7,7 +7,43 @@ import * as util from 'ionic/util';
 
 
 /**
- * TODO
+ * @name ionPopup
+ * @classdesc
+ * The Ionic Popup service allows programmatically creating and showing popup windows that require the user to respond in order to continue.
+ *
+ * The popup system has support for more flexible versions of the built in `alert()`, `prompt()`, and `confirm()` functions that users are used to, in addition to allowing popups with completely custom content and look.
+ *
+ * @example
+ * ```ts
+ * class myApp {
+ * 
+ *   constructor(popup: Popup) {
+ *     this.popup = popup;
+ *   }
+ * 
+ *   doAlert() {
+ *     this.popup.alert('Alert').then(() => {
+ *       console.log('Alert closed');
+ *     });
+ *   }
+ * 
+ *   doPrompt() {
+ *     this.popup.prompt('What is your name?').then((name) => {
+ *       console.log('Name entered:', name);
+ *     }, () => {
+ *       console.error('Prompt closed');
+ *     });
+ *   }
+ * 
+ *   doConfirm() {
+ *     this.popup.confirm('Are you sure?').then((result, ev) => {
+ *       console.log('Confirmed!', result);
+ *     }, () => {
+ *       console.error('Not confirmed!');
+ *     });
+ *   }
+ * }
+ * ```
  */
 @Injectable()
 export class Popup extends Overlay {
diff --git a/ionic/components/radio/radio.ts b/ionic/components/radio/radio.ts
index f6ec7b077f..b3bd25fb61 100644
--- a/ionic/components/radio/radio.ts
+++ b/ionic/components/radio/radio.ts
@@ -6,9 +6,46 @@ import {Ion} from '../ion';
 import {TapClick} from '../button/button';
 import {ListHeader} from '../list/list';
 
+
 /**
- * A radio group component.
- */
+ * @name ionRadioGroup
+ * @classdesc
+ * A radio group is a group of radio components.
+ * 
+ * Selecting a radio button in the group unselects all others in the group.
+ * 
+ * New radios can be registered dynamically. 
+ *
+ * See the [Angular 2 Docs](https://angular.io/docs/js/latest/api/forms/) for more info on forms and input.
+ * 
+ * @example
+ * ```html
+ * <ion-radio-group ng-control="clientside">
+ * 
+ *   <ion-header>
+ *     Clientside
+ *   </ion-header>
+ * 
+ *   <ion-radio value="ember">
+ *     Ember
+ *   </ion-radio>
+ * 
+ *   <ion-radio value="angular1">
+ *     Angular 1
+ *   </ion-radio>
+ * 
+ *   <ion-radio value="angular2" checked="true">
+ *     Angular 2
+ *   </ion-radio>
+ * 
+ *   <ion-radio value="react">
+ *     React
+ *   </ion-radio>
+ * 
+ * </ion-radio-group>
+ * ```
+*/
+
 @IonicDirective({
   selector: 'ion-radio-group',
   host: {
@@ -114,7 +151,19 @@ export class RadioGroup extends Ion {
 }
 
 /**
- * A radio button component.
+ * @name ionRadio
+ * @classdesc
+ * A single radio component. 
+ *
+ * See the [Angular 2 Docs](https://angular.io/docs/js/latest/api/forms/) for more info on forms and input.
+ *
+ * @example
+ * ```html
+ * <ion-radio value="isChecked" checked="true">
+ *   Radio Label
+ * </ion-radio>
+ * ```
+ *
  */
 @IonicComponent({
   selector: 'ion-radio',
diff --git a/ionic/components/scroll/pull-to-refresh.ts b/ionic/components/scroll/pull-to-refresh.ts
index ed8aa9f3e2..46e91714db 100644
--- a/ionic/components/scroll/pull-to-refresh.ts
+++ b/ionic/components/scroll/pull-to-refresh.ts
@@ -6,7 +6,38 @@ import * as util from 'ionic/util';
 import {raf, ready, CSS} from 'ionic/util/dom';
 
 /**
- * TODO
+ * @name ionRefresher
+ * @classdesc
+ * Allows you to add pull-to-refresh to an ionContent component.
+ *
+ * Place it as the first child of your ionContent or ionScroll element.
+ *
+ * When refreshing is complete, call `refresher.complete()` from your controller.
+ * 
+ *  @example
+ *  ```html
+ *  <ion-refresher (starting)="doStarting()" (refresh)="doRefresh($event, refresher)" (pulling)="doPulling($event, amt)">
+ *  ```
+ *
+ *  @example
+ *  ```ts
+ *  doRefresh(refresher) {
+ *    console.log('Refreshing!', refresher);
+ *  
+ *    setTimeout(() => {
+ *      console.log('Pull to refresh complete!', refresher);
+ *      refresher.complete();
+ *    })
+ *  }
+ *  
+ *  doStarting() {
+ *    console.log('Pull started!');
+ *  }
+ *  
+ *  doPulling(amt) {
+ *    console.log('You have pulled', amt);
+ *  }
+ *  ```
  */
 @Component({
   selector: 'ion-refresher',
@@ -94,7 +125,7 @@ export class Refresher {
 
     this.showIcon = util.isDefined(this.refreshingIcon);
 
-    this._touchMoveListener = this._handleTouchMove.bind(this);
+    this._touchMoveListener = this._handleTouchMov.bind(this);
     this._touchEndListener = this._handleTouchEnd.bind(this);
     this._handleScrollListener = this._handleScroll.bind(this);
     sc.addEventListener('touchmove', this._touchMoveListener);
diff --git a/ionic/components/switch/switch.ts b/ionic/components/switch/switch.ts
index f8d9a55915..687eb1df51 100644
--- a/ionic/components/switch/switch.ts
+++ b/ionic/components/switch/switch.ts
@@ -17,7 +17,8 @@ import {IonicComponent, IonicView} from '../../config/annotations';
 import {pointerCoord} from '../../util/dom';
 
 /**
- * TODO
+ * @name mediaSwitch
+ * @private
  */
 @Directive({
   selector: '.media-switch',
@@ -46,7 +47,41 @@ class MediaSwitch {
 
 
 /**
- * TODO
+ * @name ionSwitch
+ * @classdesc
+ * A switch technically is the same thing as an HTML checkbox input, except it looks different and is easier to use on a touch device. Ionic prefers to wrap the checkbox input with the <label> in order to make the entire toggle easy to tap or drag.
+ *
+ * Toggles can also have colors assigned to them, by adding the `toggle-assertive` attribute to assign the assertive color.
+ *
+ * See the [Angular 2 Docs](https://angular.io/docs/js/latest/api/forms/) for more info on forms and input.
+ *
+ * @example
+ * ```html
+ *  <ion-switch checked="true">
+ *    Pineapple
+ *  </ion-switch>
+ * ````
+ *
+ * @example
+ * Create a list of switch components:
+ * ```html
+ *  <ion-list>
+ *
+ *    <ion-switch checked="true">
+ *      Apple
+ *    </ion-switch>
+ *
+ *     <ion-switch checked="false">
+ *       Banana
+ *     </ion-switch>
+ *
+ *     <ion-switch disabled="true">
+ *       Cherry
+ *     </ion-switch>
+ *
+ *  </ion-list>
+ * ```
+ *
  */
 @IonicComponent({
   selector: 'ion-switch',