docs(angular): adds docs to angular API (#17211)

angular/src/providers/nav-controller.ts

@@ -47,34 +47,85 @@ export class NavController {
     platform.backButton.subscribeWithPriority(0, () => this.pop());
   }
 
+  /**
+   * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood,
+   * it's equivalent to call `this.router.navigateByUrl()`, but it's explicit about the **direction** of the transition.
+   *
+   * Going **forward** means that a new page it's going to be pushed to the stack of the outlet (ion-router-outlet),
+   * and that it will show a "forward" animation by default.
+   *
+   * Navigating forward can also be trigger in a declarative manner by using the `[routerDirection]` directive:
+   *
+   * ```html
+   * <a routerLink="/path/to/page" routerDirection="forward">Link</a>
+   * ```
+   */
   navigateForward(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise<boolean> {
     this.setDirection('forward', options.animated, options.animationDirection);
     return this.navigate(url, options);
   }
 
+  /**
+   * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood,
+   * it's equivalent to call:
+   *
+   * ```ts
+   * this.navController.setDirection('back');
+   * this.router.navigateByUrl(path);
+   * ```
+   *
+   * Going **back** means that all the pages in the stack until the navigated page is found will be pop,
+   * and that it will show a "back" animation by default.
+   *
+   * Navigating back can also be trigger in a declarative manner by using the `[routerDirection]` directive:
+   *
+   * ```html
+   * <a routerLink="/path/to/page" routerDirection="back">Link</a>
+   * ```
+   */
   navigateBack(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise<boolean> {
     this.setDirection('back', options.animated, options.animationDirection);
     return this.navigate(url, options);
   }
 
+  /**
+   * This method uses Angular's [Router](https://angular.io/api/router/Router) under the hood,
+   * it's equivalent to call:
+   *
+   * ```ts
+   * this.navController.setDirection('root');
+   * this.router.navigateByUrl(path);
+   * ```
+   *
+   * Going **root** means that all existing pages in the stack will be removed,
+   * and the navigated page will become the single page in the stack.
+   *
+   * Navigating root can also be trigger in a declarative manner by using the `[routerDirection]` directive:
+   *
+   * ```html
+   * <a routerLink="/path/to/page" routerDirection="root">Link</a>
+   * ```
+   */
   navigateRoot(url: string | UrlTree | any[], options: NavigationOptions = {}): Promise<boolean> {
     this.setDirection('root', options.animated, options.animationDirection);
     return this.navigate(url, options);
   }
 
-  private navigate(url: string | UrlTree | any[], options: NavigationOptions) {
-    if (Array.isArray(url)) {
-      return this.router!.navigate(url, options);
-    } else {
-      return this.router!.navigateByUrl(url, options);
-    }
-  }
-
+  /**
+   * Same as [Location](https://angular.io/api/common/Location)'s back() method.
+   * It will use the standard `window.history.back()` under the hood, but featuring a `back` animation.
+   */
   back(options: AnimationOptions = { animated: true, animationDirection: 'back' }) {
     this.setDirection('back', options.animated, options.animationDirection);
     return this.location.back();
-   }
+  }
 
+  /**
+   * This methods goes back in the context of ionic's stack navigation.
+   *
+   * It recursivelly finds the top active `ion-router-outlet` and calls `pop()`.
+   * This is the recommended way to go back when you are using `ion-router-outlet`.
+   */
   async pop() {
     let outlet = this.topOutlet;
 
@@ -85,17 +136,30 @@ export class NavController {
         outlet = outlet.parentOutlet;
       }
     }
-   }
+  }
 
+  /**
+   * This methods specifies the direction of the next navigation performed by the angular router.
+   *
+   * `setDirection()` does not trigger any transition, it just sets a set of flags to be consumed by `ion-router-outlet`.
+   *
+   * It's recommended to use `navigateForward()`, `navigateBack()` and `navigateBack()` instead of `setDirection()`.
+   */
   setDirection(direction: RouterDirection, animated?: boolean, animationDirection?: 'forward' | 'back') {
     this.direction = direction;
     this.animated = getAnimation(direction, animated, animationDirection);
   }
 
+  /**
+   * @internal
+   */
   setTopOutlet(outlet: IonRouterOutlet) {
     this.topOutlet = outlet;
   }
 
+  /**
+   * @internal
+   */
   consumeTransition() {
     let direction: RouterDirection = 'root';
     let animation: NavDirection | undefined;
@@ -115,6 +179,14 @@ export class NavController {
       animation
     };
   }
+
+  private navigate(url: string | UrlTree | any[], options: NavigationOptions) {
+    if (Array.isArray(url)) {
+      return this.router!.navigate(url, options);
+    } else {
+      return this.router!.navigateByUrl(url, options);
+    }
+  }
 }
 
 function getAnimation(direction: RouterDirection, animated: boolean | undefined, animationDirection: 'forward' | 'back' | undefined): NavDirection | undefined {