docs(nav): add Nav Transition Promises section

ionic/components/nav/nav-controller.ts

@@ -101,6 +101,44 @@ import {ViewController} from './view-controller';
  * - `onPageWillUnload` - Runs when the page is about to be destroyed and have its elements removed.
  * - `onPageDidUnload` - Runs after the page has been destroyed and its elements have been removed.
  *
+ *
+ * ### Nav Transition Promises
+ *
+ * Navigation transitions are asynchronous, meaning they take a few moments to finish, and
+ * the duration of a transition could be any number. In most cases the async nature of a
+ * transition doesn't cause any problems and the nav controller is pretty good about handling
+ * which transition was the most recent when multiple transitions have been kicked off.
+ * However, when an app begins firing off many transitions, on the same stack at
+ * *roughly* the same time, the nav controller can start to get lost as to which transition
+ * should be finishing, and which transitions should not be animated.
+ *
+ * In cases where an app's navigation can be altered by other async tasks, which may or
+ * may not take a long time, it's best to rely on each nav transition's returned
+ * promise. So instead of firing and forgetting multiple `push` or `pop` nav transitions,
+ * it's better to fire the next nav transition when the previous on has finished.
+ *
+ * In the example below, after we receive some data asynchronously, we then want transition
+ * to another page. Where the problem comes in, is that if we received the data 200ms after
+ * the first transition started, then kicking off another transition halfway through
+ * the first transition ends up with a janky transition. Instead, it's best to always
+ * ensure the first transition has already finished before starting the next.
+ *
+ * ```ts
+ * // begin the first transition
+ * let navTransition = this.nav.push(SomePage);
+ *
+ * // start an async call, we're not sure how long it'll take
+ * getSomeAsyncData().then(() => {
+ *   // incase we received the data faster than the time it
+ *   // took to finish the first transition, this logic should
+ *   // always wait that the previous transition has resolved
+ *   // first before kicking off the next transition
+ *   navTransition.then(() => {
+ *     this.nav.push(AnotherPage);
+ *   });
+ * });
+ * ```
+ *
  * @see {@link /docs/v2/components#navigation Navigation Component Docs}
  */
 export class NavController extends Ion {
@@ -178,6 +216,9 @@ export class NavController extends Ion {
     ]);
   }
 
+  /**
+   * @private
+   */
   setPortal(val: Portal) {
     this._portal = val;
   }