chore(nav): more nav docs

ionic/components/nav/nav-controller.ts

@@ -15,12 +15,98 @@ import * as util from 'ionic/util';
  * NavController is the base class for navigation controller components like
  * [`Nav`](../Nav/) and [`Tab`](../../Tabs/Tab/). At a basic level, it is an array of
  * [views](#creating_views) representing a particular history (of a Tab for example).
- * This array can be manipulated to navigate throughout an app by pushing,
+ * This array can be manipulated to navigate throughout an app by pushing and
- * popping, inserting and removing views.
+ * popping views or inserting and removing them at arbitrary indices.
  *
- * <h3 id="creating_views">How do I create views?</h3>
+ * The current view is the last one in the array, or the top of the stack, if we think of it
- * Any class that is annotated with [@IonicView](../../../config/IonicView/) will
+ * that way.  Pushing a new [view](#creating_views) onto the top of
- * create a view, that is, a component that can be navigated to.
+ * the navigation stack causes the new view to be animated in, while popping the current
+ * view will navigate to the previous view in the stack.
+ *
+ * For examples on the basic usage of NavController, check out the [Navigation section](../../../../components/#navigation)
+ * of the Component docs.  The following is a more in depth explanation of some
+ * of the features of NavController.
+ *
+ * Unless you are using a directive like [NavPush](../NavPush/), or need a
+ * specific NavController, most times you will inject and use a reference to the
+ * nearest NavController to manipulate the navigation stack.
+ *
+ * <h3 id="injecting_nav_controller">Injecting NavController</h3>
+ * Injecting NavController will always get you an instance of the nearest NavController,
+ * regardless of whether it's a Tab or a Nav.
+ *
+ * Behind the scenes, when Ionic instantiates a new NavController, it creates an
+ * injector with NavController bound to that instance (usually either a Nav or Tab)
+ *  and adds the injector to its own bindings.  For more information on binding
+ *  and dependency injection, see [Binding and DI]().
+ *
+ * ```ts
+ * // class NavController
+ * //"this" is either Nav or Tab, both extend NavController
+ * this.bindings = Injector.resolve([
+ *   bind(NavController).toValue(this)
+ * ]);
+ * ```
+ *
+ * That way you don't need to worry about getting a hold of the proper NavController
+ *  for [views](#creating_views) that may be used in either a Tab or a Nav:
+ *
+ * ```ts
+ *  class MyPage {
+ *    constructor(@Optional() tab: Tab, @Optional() nav: Nav) {
+ *    	// Unhhhhh so much typinggggg
+ *      // What if we are in a nav that is in a tab, or vice versa, so these both resolve?
+ *    }
+ *  }
+ * ```
+ *
+ * Instead, you can inject NavController and know that it is the correct
+ * navigation controller for most situations (for more advanced situations, see
+ * [Menu](../../Menu/Menu/) and [Tab](../../Tab/Tab/)).
+ *
+ * ```ts
+ *  class MyComponent {
+ *    constructor(nav: NavController) {
+ *      this.nav = nav;
+ *    }
+ *  }
+ * ```
+ *
+ * <h2 id="creating_views">View creation</h2>
+ * Views are created when they are added to the navigation stack.  For methods
+ * like [push()](#push), the NavController takes any component class that is
+ * decorated with [@IonicView](../../../config/IonicView/) as its first
+ * argument.  The NavController then [compiles]() that component, loads it in
+ * a similar fashion to Angular's [DynamicComponentLoader](https://angular.io/docs/js/latest/api/core/DynamicComponentLoader-interface.html),
+ * and animates it into view.
+ *
+ * By default, views are cached and left in the DOM if they are navigated away from, but are
+ * still in the navigation stack (on a `push()` for example).  They are
+ * destroyed when removed from the navigation stack (on [pop()](#pop) or [setRoot()](#setRoot)).
+ *
+ *
+ * <h2 id="Lifecycle">Lifecycle events</h2>
+ * Lifecycle events are fired during various stages of navigation.  They can be
+ * defined in any `@IonicView` decorated component class.
+ *
+ * ```ts
+ * @IonicView({
+ *   template: 'Hello World'
+ * })
+ * class HelloWorld {
+ *   onViewLoaded() {
+ *     console.log("I'm alive!");
+ *   }
+ * }
+ * ```
+ *
+ * - `onViewLoaded` - Runs when the view has loaded. This event only happens once per view being created and added to the DOM. If a view leaves but is cached, then this event will not fire again on a subsequent viewing. The `onViewLoaded` event is good place to put your setup code for the view.
+ * - `onViewWillEnter` - Runs when the view is about to enter and become the active view.
+ * - `onViewDidEnter` - Runs when the view has fully entered and is now the active view. This event will fire, whether it was the first load or a cached view.
+ * - `onViewWillLeave` - Runs when the view is about to leave and no longer be the active view.
+ * - `onViewDidLeave` - Runs when the view has finished leaving and is no longer the active view.
+ * - `onViewWillUnload` - Runs when the view is about to be destroyed and have its elements removed.
+ * - `onViewDidUnload` - Runs after the view has been destroyed and its elements have been removed.
  *
  */
 export class NavController extends Ion {

ionic/components/nav/nav.ts

@@ -12,6 +12,17 @@ import {NavController} from './nav-controller';
  * For more information on using navigation controllers like Nav or [Tabs](../../Tabs/Tabs/),
  * please take a look at the [NavController API reference](../NavController/).
  *
+ * <h2 id="back_navigation">Back navigation</h2>
+ * One feature of Nav is that if your [view](../NavController/#creating_views) has
+ * a [NavBar](../NavBar/), a back button will be added automatically when there
+ * view before it in the navigation stack.
+ *
+ * Additionally, specifying the `swipe-back-enabled` property will allow you to
+ * swipe to go back:
+ * ```ts
+ * <ion-nav swipe-back-enabled="false" [root]="rootPage"></ion-nav>
+ * ```
+ *
  * Here is a diagram of how Nav animates smoothly between [views](../NavController/#creating_views):
  *
  * <div class="highlight less-margin">
@@ -66,8 +77,8 @@ import {NavController} from './nav-controller';
  *
  * ### Panes
  *
- * NOTE: You don't have to do anything with panes, it is all taken care of for you.
+ * NOTE: You don't have to do anything with panes, Ionic takes care of animated
- * This is just an explanation of how Nav works to accompany the diagram above.
+ * transitions for you. This is an explanation of how Nav works to accompany the diagram above.
  *
  * When you push a new view onto the navigation stack using [NavController.push()](../NavController/#push)
  * or the [NavPush directive](../NavPush/), Nav animates the new view into the

ionic/config/decorators.ts

@@ -26,7 +26,6 @@ import {
  * template.
  */
 export const IONIC_DIRECTIVES = [
-// TODO: Why is forwardRef() required when they're already imported above????
   // Angular
   CORE_DIRECTIVES,
   FORM_DIRECTIVES,
@@ -94,6 +93,9 @@ export const IONIC_DIRECTIVES = [
   forwardRef(() => HideWhen)
 ];
 
+/**
+ * @private
+ */
 class IonicViewImpl extends View {
   constructor(args = {}) {
     args.directives = (args.directives || []).concat(IONIC_DIRECTIVES);
@@ -102,7 +104,13 @@ class IonicViewImpl extends View {
 }
 
 /**
- * TODO
+ * the IonicView decorator indicates that the decorated class is an Ionic
+ * navigation view, meaning it can be navigated to using a [NavController](../../Nav/NavController/)
+ *
+ * Ionic views are automatically wrapped in `<ion-view>`, so although you may
+ * see these tags if you inspect your markup, you don't need to include them in
+ * your templates.
+ *
  */
 export function IonicView(args) {
   return function(cls) {