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

angular/src/directives/navigation/ion-router-outlet.ts

@@ -182,20 +182,32 @@ export class IonRouterOutlet implements OnDestroy, OnInit {
     });
   }
 
-  canGoBack(deep = 1, stackId?: string) {
+  /**
+   * Returns `true` if there are pages in the stack to go back.
+   */
+  canGoBack(deep = 1, stackId?: string): boolean {
     return this.stackCtrl.canGoBack(deep, stackId);
   }
 
-  pop(deep = 1, stackId?: string) {
+  /**
+   * Resolves to `true` if it the outlet was able to sucessfully pop the last N pages.
+   */
+  pop(deep = 1, stackId?: string): Promise<boolean> {
     return this.stackCtrl.pop(deep, stackId);
   }
 
-  getLastUrl(stackId?: string) {
+  /**
+   * Returns the URL of the active page of each stack.
+   */
+  getLastUrl(stackId?: string): string | undefined {
     const active = this.stackCtrl.getLastUrl(stackId);
     return active ? active.url : undefined;
   }
 
-  getActiveStackId() {
+  /**
+   * Returns the active stack ID. In the context of ion-tabs, it means the active tab.
+   */
+  getActiveStackId(): string | undefined {
     return this.stackCtrl.getActiveStackId();
   }
 }

angular/src/providers/dom-controller.ts

@@ -5,10 +5,18 @@ import { Injectable } from '@angular/core';
 })
 export class DomController {
 
+  /**
+   * Schedules a task to run during the READ phase of the next frame.
+   * This task should only read the DOM, but never modify it.
+   */
   read(cb: RafCallback) {
     getQueue().read(cb);
   }
 
+  /**
+   * Schedules a task to run during the WRITE phase of the next frame.
+   * This task should write the DOM, but never READ it.
+   */
   write(cb: RafCallback) {
     getQueue().write(cb);
   }

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)) {
+   * Same as [Location](https://angular.io/api/common/Location)'s back() method.
-      return this.router!.navigate(url, options);
+   * It will use the standard `window.history.back()` under the hood, but featuring a `back` animation.
-    } else {
+   */
-      return this.router!.navigateByUrl(url, options);
-    }
-  }
-
   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 {

angular/src/providers/platform.ts

@@ -131,10 +131,45 @@ export class Platform {
     return getPlatforms(window);
   }
 
+  /**
+   * Returns a promise when the platform is ready and native functionality
+   * can be called. If the app is running from within a web browser, then
+   * the promise will resolve when the DOM is ready. When the app is running
+   * from an application engine such as Cordova, then the promise will
+   * resolve when Cordova triggers the `deviceready` event.
+   *
+   * The resolved value is the `readySource`, which states which platform
+   * ready was used. For example, when Cordova is ready, the resolved ready
+   * source is `cordova`. The default ready source value will be `dom`. The
+   * `readySource` is useful if different logic should run depending on the
+   * platform the app is running from. For example, only Cordova can execute
+   * the status bar plugin, so the web should not run status bar plugin logic.
+   *
+   * ```
+   * import { Component } from '@angular/core';
+   * import { Platform } from 'ionic-angular';
+   *
+   * @Component({...})
+   * export MyApp {
+   *   constructor(public platform: Platform) {
+   *     this.platform.ready().then((readySource) => {
+   *       console.log('Platform ready from', readySource);
+   *       // Platform now ready, execute any required native code
+   *     });
+   *   }
+   * }
+   * ```
+   */
   ready(): Promise<string> {
     return this._readyPromise;
   }
 
+  /**
+   * Returns if this app is using right-to-left language direction or not.
+   * We recommend the app's `index.html` file already has the correct `dir`
+   * attribute value set, such as `<html dir="ltr">` or `<html dir="rtl">`.
+   * [W3C: Structural markup and right-to-left text in HTML](http://www.w3.org/International/questions/qa-html-dir)
+   */
   get isRTL(): boolean {
     return document.dir === 'rtl';
   }
@@ -146,10 +181,16 @@ export class Platform {
     return readQueryParam(window.location.href, key);
   }
 
+  /**
+   * Returns `true` if the app is in landscape mode.
+   */
   isLandscape(): boolean {
     return !this.isPortrait();
   }
 
+  /**
+   * Returns `true` if the app is in portait mode.
+   */
   isPortrait(): boolean {
     return window.matchMedia('(orientation: portrait)').matches;
   }
@@ -158,14 +199,23 @@ export class Platform {
     return navigator.userAgent.indexOf(expression) >= 0;
   }
 
+  /**
+   * Get the current url.
+   */
   url() {
     return window.location.href;
   }
 
+  /**
+   * Gets the width of the platform's viewport using `window.innerWidth`.
+   */
   width() {
     return window.innerWidth;
   }
 
+  /**
+   * Gets the height of the platform's viewport using `window.innerHeight`.
+   */
   height(): number {
     return window.innerHeight;
   }

angular/src/util/overlay.ts

@@ -3,14 +3,23 @@ import { proxyMethod } from './util';
 export class OverlayBaseController<Opts, Overlay> {
   constructor(private ctrl: string) {}
 
+  /**
+   * Creates a new overlay
+   */
   create(opts?: Opts): Promise<Overlay> {
     return proxyMethod(this.ctrl, 'create', opts);
   }
 
+  /**
+   * When `id` is not provided, it dismisses the top overlay.
+   */
   dismiss(data?: any, role?: string, id?: string): Promise<void> {
     return proxyMethod(this.ctrl, 'dismiss', data, role, id);
   }
 
+  /**
+   * Returns the top overlay.
+   */
   getTop(): Promise<Overlay> {
     return proxyMethod(this.ctrl, 'getTop');
   }