diff --git a/ionic/components/nav/nav.ts b/ionic/components/nav/nav.ts
index 0818bc2977..fcd98b00e8 100644
--- a/ionic/components/nav/nav.ts
+++ b/ionic/components/nav/nav.ts
@@ -5,12 +5,27 @@ import {NavController} from './nav-controller';
 
 /**
  * Nav is a basic navigation controller component.  As a subclass of [NavController](../NavController/)
- * you use it to navigate to views in your app. Nav automatically animates
- * transitions between views for you.
+ * you use it to navigate to views in your app and manipulate the navigation stack.
+ * Nav automatically animates transitions between views for you.
  *
  * For more information on using navigation controllers like Nav or [Tabs](../../Tabs/Tabs/),
  * take a look at the [NavController API reference](../NavController/).
  *
+ * You must set a root view to be loaded initially for any Nav you create, using
+ * the 'root' property:
+ *
+ * ```ts
+ * import {GettingStartedPage} from 'getting-started';
+ * @App({
+ *   template: `<ion-nav [root]="rootPage"></ion-nav>`
+ * })
+ * class MyApp {
+ *   constructor(){
+ *     this.rootPage = GettingStartedPage;
+ *   }
+ * }
+ * ```
+ *
  * <h2 id="back_navigation">Back navigation</h2>
  * If a [view](../NavController/#creating_views) you navigate to has a [NavBar](../NavBar/),
  * Nav will automatically add a back button to it if there is a view
diff --git a/ionic/components/tabs/tab.ts b/ionic/components/tabs/tab.ts
index 920cebb005..7f9775ce42 100644
--- a/ionic/components/tabs/tab.ts
+++ b/ionic/components/tabs/tab.ts
@@ -6,14 +6,37 @@ import {Tabs} from './tabs';
 
 
 /**
- * @name ionTab
- * @requires ionTabs
- * @description
- * Contains a tab's content. The content only exists while the given tab is selected.
+ * Tab components are basic navigation controllers used with [Tabs]().  Much like
+ * [Nav](), they are a subclass of [NavController]() and are used to navigate to
+ * views and manipulate the navigation stack of a particular tab.
  *
- * @usage
+ * For basic Tabs usage, see the [Tabs section]() of the component docs.
+ *
+ * Like Nav, you must set a root view to be loaded initially for each Tab with
+ * the 'root' property:
+ * ```
+ * import {GettingStartedPage} from 'getting-started';
+ * @App({
+ *   template: `<ion-tabs>
+ *                <ion-tab [root]="tabOneRoot"></ion-tab>
+ *                <ion-tab [root]="tabTwoRoot"></ion-tab>
+ *              <ion-tabs>`
+ * })
+ * class MyApp {
+ *   constructor(){
+ *     this.tabOneRoot = GettingStartedPage;
+ *     this.tabTwoRoot = GettingStartedPage;
+ *   }
+ * }
+ * ```
+ *
+ * To change the title and icon for each tab, use the `tab-title` and `tab-icon`
+ * properties:
  * ```html
- * <ion-tab tab-title="Heart" tab-icon="ion-ios-heart-outline" [root]="root1"></ion-tab>
+ * <ion-tabs>
+ * 	 <ion-tab tab-title="Home" tab-icon="home" [root]="tabOneRoot"></ion-tab>
+ * 	 <ion-tab tab-title="Login" tab-icon="star" [root]="tabTwoRoot"></ion-tab>
+ * <ion-tabs>
  * ```
  */
 @Component({
diff --git a/ionic/components/tabs/tabs.ts b/ionic/components/tabs/tabs.ts
index 6089652454..0d3093151d 100644
--- a/ionic/components/tabs/tabs.ts
+++ b/ionic/components/tabs/tabs.ts
@@ -10,28 +10,49 @@ import * as dom from 'ionic/util/dom';
 
 
 /**
- * @name ionTabs
- * @description
- * Powers a multi-tabbed interface with a Tab Bar and a set of "pages"
- * that can be tabbed through.
+ * The Tabs component is a container with a [TabBar]() and any number of
+ * individual [Tab]() components. On iOS, the TabBar is placed on the bottom of
+ * the screen, while on Android it is at the top.
  *
- * Assign any tabs attribute to the element to define its look and feel.
+ * For basic Tabs usage, see the [Tabs section](../../../../components/#tabs) of the component docs.
+ * See the [Tab API reference](../Tab/) for more details on individual Tab components.
  *
- * For iOS, tabs will appear at the bottom of the screen. For Android, tabs
- * will be at the top of the screen, below the nav-bar. This follows each platform's
- * design specification, but can be configured with IonicConfig.
+ * You can override the platform specific TabBar placement by using the
+ * `tab-bar-placement` property:
  *
- * See the ionTab component's documentation for more details on individual tabs.
- *
- * @usage
- * ```html
- * <ion-tabs>
- *   <ion-tab tab-title="Heart" tab-icon="heart-" [root]="root1"></ion-tab>
- *   <ion-tab tab-title="Star" tab-icon="star" [root]="root2"></ion-tab>
- *   <ion-tab tab-title="Stopwatch" tab-icon="stopwatch" [root]="root3"></ion-tab>
+ * ```ts
+ * <ion-tabs tab-bar-placement="top">
+ *   <ion-tab [root]="tabRoot"></ion-tab>
  * </ion-tabs>
  * ```
  *
+ * To change the location of the icons in the TabBar, use the `tab-bar-icons`
+ * property:
+ * ```ts
+ * <ion-tabs tab-bar-icons="bottom">
+ *   <ion-tab [root]="tabRoot"></ion-tab>
+ * </ion-tabs>
+ * ```
+ *
+ * You can select tabs programatically by injecting Tabs into any child
+ * component, and using the [select()](#select) method:
+ * ```ts
+ * @IonicView({
+ *   template: `<button (click)="goToTabTwo()">Go to Tab2</button>`
+ * })
+ * class TabOne {
+ *   constructor(tabs: Tabs){
+ *     this.tabs = tabs;
+ *   }
+ *
+ *   goToTabTwo() {
+ *     this.tabs.select(this.tabs.tabs[1]);
+ *   }
+ * }
+ * ```
+ * The [tabs](#tabs) property is an array of all child [Tab](../Tab/) components
+ * of this Tabs component.
+ *
  */
 @IonicComponent({
   selector: 'ion-tabs',
@@ -110,6 +131,10 @@ export class Tabs extends NavController {
 
   }
 
+  /**
+   * @private
+   * TODO
+   */
   addTab(tab) {
     this.add(tab.viewCtrl);
 
@@ -161,6 +186,7 @@ export class Tabs extends NavController {
   }
 
   /**
+   * @private
    * "Touch" the active tab, either going back to the root view of the tab
    * or scrolling the tab to the top
    */
@@ -173,6 +199,10 @@ export class Tabs extends NavController {
     }
   }
 
+  /**
+   * TODO
+   * @return TODO
+   */
   get tabs() {
     return this.instances();
   }
@@ -180,6 +210,7 @@ export class Tabs extends NavController {
 }
 
 /**
+ * @private
  * TODO
  */
 @Directive({
@@ -225,7 +256,10 @@ class TabButton extends Ion {
   }
 }
 
-
+/**
+ * @private
+ * TODO
+ */
 @Directive({
   selector: 'tab-highlight'
 })
@@ -255,6 +289,10 @@ class TabHighlight {
 }
 
 
+/**
+ * @private
+ * TODO
+ */
 @Directive({selector: 'template[navbar-anchor]'})
 class TabNavBarAnchor {
   constructor(