docs(navController): better navController docs and examples

Closes #417

ionic/components/nav/nav-controller.ts

@@ -156,11 +156,70 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * Push is how we can pass components and navigate to them. We push the component we want to navigate to on to the navigation stack.
+   *
+   * ```typescript
+   * class MyClass{
+   *    constructor(nav:NavController){
+   *      this.nav = nav;
+   *    }
+   *
+   *    pushPage(){
+   *      this.nav.push(SecondView);
+   *    }
+   * }
+   * ```
+   *
+   * We can also pass along parameters to the next view, such as data that we have on the current view. This is a similar concept to to V1 apps with `$stateParams`.
+   *
+   * ```typescript
+   * class MyClass{
+   *    constructor(nav:NavController){
+   *      this.nav = nav;
+   *    }
+   *
+   *    pushPage(user){
+   *      this.nav.push(SecondView,{
+   *       // user is an object we have in our view
+   *       // typically this comes from an ngFor or some array
+   *       // here we can create an object with a property of
+   *       // paramUser, and set it's value to the user object we passed in
+   *       paramUser: user
+   *      });
+   *    }
+   * }
+   * ```
+   *
+   * We'll look at how we can access that data in the `SecondView` in the navParam docs
+   *
+   * We can also pass any options to the transtion from that same method
+   *
+   * ```typescript
+   * class MyClass{
+   *    constructor(nav:NavController){
+   *      this.nav = nav;
+   *    }
+   *
+   *    pushPage(user){
+   *      this.nav.push(SecondView,{
+   *       // user is an object we have in our view
+   *       // typically this comes from an ngFor or some array
+   *       // here we can create an object with a property of
+   *       // paramUser, and set it's value to the user object we passed in
+   *       paramUser: user
+   *      },{
+   *       // here we can configure things like the animations direction or
+   *       // or if the view should animate at all.
+   *       animate: true,
+   *       direction: back
+   *      });
+   *    }
+   * }
+   * ```
    * @name NavController#push
    * @param {Component} The name of the component you want to push on the navigation stack
-   * @param {Component} [params={}] The name of the component you want to push on the navigation stack, plus additional data you want to pass as parameters
+   * @param {Object} [params={}] Any nav-params you want to pass along to the next view
-   * @param {Component} [opts={}]  The name of the component you want to push on the navigation stack, plus additional options for the transition
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    * @returns {Promise} Returns a promise when the transition is completed
    */
   push(componentType, params = {}, opts = {}, callback) {
@@ -222,9 +281,25 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * If you wanted to navigate back from a current view, you can use the back-button or programatically call `pop()`
+   * Similar to `push()`, you can pass animation options.
+   * ```typescript
+   * class SecondView{
+   *    constructor(nav:NavController){
+   *      this.nav = nav;
+   *    }
+   *
+   *    goBack(){
+   *      this.nav.pop({
+   *       animate: true,
+   *       direction: back
+   *      });
+   *    }
+   * }
+   * ```
+   *
    * @name NavController#pop
-   * @param {Object} [opts={}] Any additional option for the transition
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    * @returns {Promise} Returns a promise when the transition is completed
    */
   pop(opts = {}) {
@@ -272,9 +347,8 @@ export class NavController extends Ion {
   /**
    * @private
    * Pop to a specific view in the history stack
-   *
    * @param view {ViewController} to pop to
-   * @param opts {object} pop options
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    */
   popTo(viewCtrl, opts = {}) {
 
@@ -322,8 +396,8 @@ export class NavController extends Ion {
   }
 
   /**
-   * Pop to the root view.
+   * Similar to `pop()`, this method let's you navigate back to the root of the stack, no matter how many views that is
-   * @param opts extra animation options
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    */
   popToRoot(opts = {}) {
     return this.popTo(this.first(), opts);
@@ -331,6 +405,20 @@ export class NavController extends Ion {
 
   /**
    * Inserts a view into the nav stack at the specified index.
+   * This is useful if you need to add a view at any point in your navigation stack
+   *
+   * ```typescript
+   * export class Detail {
+   *    constructor(nav: NavController) {
+   *      this.nav = nav;
+   *    }
+   *    insertView(){
+   *      this.nav.insert(1,Info)
+   *    }
+   *  }
+   *  ```
+   *  This will insert the `Info` view into the second slot of our navigation stack
+   *
    * @param {Index} The index where you want to insert the view
    * @param {Component} The name of the component you want to insert into the nav stack
    * @returns {Promise} Returns a promise when the view has been inserted into the navigation stack
@@ -361,7 +449,20 @@ export class NavController extends Ion {
 
   /**
    * Removes a view from the nav stack at the specified index.
+   *
+   * ```typescript
+   * export class Detail {
+   *    constructor(nav: NavController) {
+   *      this.nav = nav;
+   *    }
+   *    removeView(){
+   *      this.nav.remove(1)
+   *    }
+   *  }
+   *  ```
+   *
    * @param {Index} Remove the view from the nav stack at that index
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    * @returns {Promise} Returns a promise when the view has been removed
    */
   remove(index, opts = {}) {
@@ -389,8 +490,8 @@ export class NavController extends Ion {
 
   /**
    * Set the view stack to reflect the given component classes.
-   * @param {TODO} components  TODO
+   * @param {Component} an arry of components to load in the stack
-   * @param {TODO} [opts={}]  TODO
+   * @param {Object} [opts={}] Any options you want to use pass
    * @returns {Promise} TODO
    */
   setPages(components, opts = {}) {
@@ -460,10 +561,10 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * Set the root for the current navigation stack
-   * @param {Component} The component you want to make root
+   * @param {Component} The name of the component you want to push on the navigation stack
-   * @param {Component} [params={}] The component you want to make root plus any nav params you want to pass
+   * @param {Object} [params={}] Any nav-params you want to pass along to the next view
-   * @param {Component} [opts={}]  The component you want to make root plus any transition params you want to pass
+   * @param {Object} [opts={}] Any options you want to use pass to transtion
    * @returns {Promise} Returns a promise when done
    */
   setRoot(componentType, params = {}, opts = {}) {
@@ -872,7 +973,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * Check to see if swipe-to-go-back is enabled
    * @param {boolean=} isSwipeBackEnabled Set whether or not swipe-to-go-back is enabled
    * @returns {boolean} Whether swipe-to-go-back is enabled
    */
@@ -932,6 +1033,9 @@ export class NavController extends Ion {
     this._cleanup();
   }
 
+  /**
+   * @private
+   */
   _cleanup(activeView) {
     // the active view, and the previous view, should be rendered in dom and ready to go
     // all others, like a cached page 2 back, should be display: none and not rendered
@@ -960,8 +1064,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
-   * Question for ADAM
    * @param {TODO} nbContainer  TODO
    * @returns {TODO} TODO
    */
@@ -978,7 +1081,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @returns {TODO} TODO
    */
   anchorElementRef() {
@@ -1035,7 +1138,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @returns {Component} TODO
    */
   getActive() {
@@ -1048,7 +1151,6 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
    * @param {Index} The index of the view you want to get
    * @returns {Component} Returns the component that matches the index given
    */
@@ -1060,7 +1162,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @param {Handle} The handle of the view you want to get
    * @returns {Component} Returns the component that matches the handle given
    */
@@ -1074,8 +1176,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
-   * QUESTIONS FOR ADAM
    * @param {TODO} pageType  TODO
    * @returns {TODO} TODO
    */
@@ -1089,7 +1190,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @param {TODO} view  TODO
    * @returns {TODO} TODO
    */
@@ -1135,7 +1236,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @param {TODO} view  TODO
    * @returns {TODO} TODO
    */
@@ -1159,7 +1260,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * IS RETURNING UNDEFIND
    * @param {TODO} view  TODO
    * @returns {TODO} TODO
@@ -1169,7 +1270,7 @@ export class NavController extends Ion {
   }
 
   /**
-   * TODO
+   * @private
    * @param {TODO} router  TODO
    */
   registerRouter(router) {