From 617475005f65b8129be1b03878889187479fedb4 Mon Sep 17 00:00:00 2001 From: vsavkin Date: Sat, 10 Sep 2016 16:51:27 -0700 Subject: [PATCH] docs(router): update docs of the Router service --- modules/@angular/router/src/router.ts | 122 ++++++++++++++---- .../@angular/router/src/router_outlet_map.ts | 9 ++ 2 files changed, 103 insertions(+), 28 deletions(-) diff --git a/modules/@angular/router/src/router.ts b/modules/@angular/router/src/router.ts index 9e99f1de30..faeec8b136 100644 --- a/modules/@angular/router/src/router.ts +++ b/modules/@angular/router/src/router.ts @@ -36,13 +36,15 @@ import {TreeNode} from './utils/tree'; declare var Zone: any; /** + * @whatItDoes Represents the extra options used during navigation. + * * @stable */ export interface NavigationExtras { /** - * Enables relative navigation from the current ActivatedRoute + * Enables relative navigation from the current ActivatedRoute. * - * Configuration + * Configuration: * * ``` * [{ @@ -61,7 +63,7 @@ export interface NavigationExtras { * }] * ``` * - * Navigate to list route from child route + * Navigate to list route from child route: * * ``` * @Component({...}) @@ -75,8 +77,9 @@ export interface NavigationExtras { * ``` */ relativeTo?: ActivatedRoute; + /** - * Sets query parameters to the URL + * Sets query parameters to the URL. * * ``` * // Navigate to /results?page=1 @@ -84,8 +87,9 @@ export interface NavigationExtras { * ``` */ queryParams?: Params; + /** - * Sets the hash fragment for the URL + * Sets the hash fragment for the URL. * * ``` * // Navigate to /results#top @@ -93,8 +97,9 @@ export interface NavigationExtras { * ``` */ fragment?: string; + /** - * Preserves the query parameters for the next navigation + * Preserves the query parameters for the next navigation. * * ``` * // Preserve query params from /results?page=1 to /view?page=1 @@ -112,7 +117,7 @@ export interface NavigationExtras { */ preserveFragment?: boolean; /** - * Navigates without pushing a new state into history + * Navigates without pushing a new state into history. * * ``` * // Navigate silently to /view @@ -121,7 +126,7 @@ export interface NavigationExtras { */ skipLocationChange?: boolean; /** - * Navigates while replacing the current state in history + * Navigates while replacing the current state in history. * * ``` * // Navigate to /view @@ -132,78 +137,131 @@ export interface NavigationExtras { } /** - * An event triggered when a navigation starts + * @whatItDoes Represents an event triggered when a navigation starts. * * @stable */ export class NavigationStart { - constructor(public id: number, public url: string) {} + // TODO: vsavkin: make internal + constructor( + /** @docsNotRequired */ + public id: number, + /** @docsNotRequired */ + public url: string) {} + + /** @docsNotRequired */ toString(): string { return `NavigationStart(id: ${this.id}, url: '${this.url}')`; } } /** - * An event triggered when a navigation ends successfully + * @whatItDoes Represents an event triggered when a navigation ends successfully. * * @stable */ export class NavigationEnd { - constructor(public id: number, public url: string, public urlAfterRedirects: string) {} + // TODO: vsavkin: make internal + constructor( + /** @docsNotRequired */ + public id: number, + /** @docsNotRequired */ + public url: string, + + /** @docsNotRequired */ + public urlAfterRedirects: string) {} + + /** @docsNotRequired */ toString(): string { return `NavigationEnd(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}')`; } } /** - * An event triggered when a navigation is canceled + * @whatItDoes Represents an event triggered when a navigation is canceled. * * @stable */ export class NavigationCancel { - constructor(public id: number, public url: string, public reason: string) {} + // TODO: vsavkin: make internal + constructor( + /** @docsNotRequired */ + public id: number, + /** @docsNotRequired */ + public url: string, + + /** @docsNotRequired */ + public reason: string) {} + + /** @docsNotRequired */ toString(): string { return `NavigationCancel(id: ${this.id}, url: '${this.url}')`; } } /** - * An event triggered when a navigation fails due to unexpected error + * @whatItDoes Represents an event triggered when a navigation fails due to an unexpected error. * * @stable */ export class NavigationError { - constructor(public id: number, public url: string, public error: any) {} + // TODO: vsavkin: make internal + constructor( + /** @docsNotRequired */ + public id: number, + /** @docsNotRequired */ + public url: string, + + /** @docsNotRequired */ + public error: any) {} + + /** @docsNotRequired */ toString(): string { return `NavigationError(id: ${this.id}, url: '${this.url}', error: ${this.error})`; } } /** - * An event triggered when routes are recognized + * @whatItDoes Represents an event triggered when routes are recognized. * * @stable */ export class RoutesRecognized { + // TODO: vsavkin: make internal constructor( - public id: number, public url: string, public urlAfterRedirects: string, + /** @docsNotRequired */ + public id: number, + + /** @docsNotRequired */ + public url: string, + /** @docsNotRequired */ + public urlAfterRedirects: string, + /** @docsNotRequired */ public state: RouterStateSnapshot) {} + /** @docsNotRequired */ toString(): string { return `RoutesRecognized(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}', state: ${this.state})`; } } /** + * @whatItDoes Represents a router event. + * + * Please see {@link NavigationStart}, {@link NavigationEnd}, {@link NavigationCancel}, {@link + * NavigationError}, + * {@link RoutesRecognized} for more information. + * * @stable */ export type Event = NavigationStart | NavigationEnd | NavigationCancel | NavigationError | RoutesRecognized; /** - * Error handler that is invoked when a navigation errors. + * @whatItDoes Error handler that is invoked when a navigation errors. * - * If the handler retuns a value, the navigation promise will be resolved with this value. + * @description + * If the handler returns a value, the navigation promise will be resolved with this value. * If the handler throws an exception, the navigation promise will be rejected with * the exception. * @@ -216,10 +274,12 @@ function defaultErrorHandler(error: any): any { } /** - * The `Router` is responsible for mapping URLs to components. + * @whatItDoes Provides the navigation and url manipulation capabilities. * * See {@link Routes} for more details and examples. * + * @ngModule RouterModule + * * @stable */ export class Router { @@ -230,18 +290,22 @@ export class Router { private navigationId: number = 0; private configLoader: RouterConfigLoader; + /** + * Error handler that is invoked when a navigation errors. + * + * See {@link ErrorHandler} for more information. + */ errorHandler: ErrorHandler = defaultErrorHandler; /** * Indicates if at least one navigation happened. - * - * @stable */ navigated: boolean = false; /** * Creates the router service. */ + // TODO: vsavkin make internal after the final is out. constructor( private rootComponentType: Type, private urlSerializer: UrlSerializer, private outletMap: RouterOutletMap, private location: Location, private injector: Injector, @@ -254,7 +318,7 @@ export class Router { } /** - * Sets up the location change listener and performs the inital navigation + * Sets up the location change listener and performs the initial navigation. */ initialNavigation(): void { this.setUpLocationChangeListener(); @@ -262,7 +326,7 @@ export class Router { } /** - * Sets up the location change listener + * Sets up the location change listener. */ setUpLocationChangeListener(): void { // Zone.current.wrap is needed because of the issue with RxJS scheduler, @@ -311,6 +375,9 @@ export class Router { this.config = config; } + /** + * @docsNotRequired + */ ngOnDestroy() { this.dispose(); } /** @@ -319,8 +386,7 @@ export class Router { dispose(): void { this.locationSubscription.unsubscribe(); } /** - * Applies an array of commands to the current url tree and creates - * a new url tree. + * Applies an array of commands to the current url tree and creates a new url tree. * * When given an activate route, applies the given commands starting from the route. * When not given a route, applies the given command starting from the root. @@ -431,7 +497,7 @@ export class Router { serializeUrl(url: UrlTree): string { return this.urlSerializer.serialize(url); } /** - * Parse a string into a {@link UrlTree}. + * Parses a string into a {@link UrlTree}. */ parseUrl(url: string): UrlTree { return this.urlSerializer.parse(url); } diff --git a/modules/@angular/router/src/router_outlet_map.ts b/modules/@angular/router/src/router_outlet_map.ts index 5c9bef1dee..fb8e21c854 100644 --- a/modules/@angular/router/src/router_outlet_map.ts +++ b/modules/@angular/router/src/router_outlet_map.ts @@ -9,12 +9,21 @@ import {RouterOutlet} from './directives/router_outlet'; /** + * @whatItDoes Contains all the router outlets created in a component. + * * @stable */ export class RouterOutletMap { /** @internal */ _outlets: {[name: string]: RouterOutlet} = {}; + + /** + * Adds an outlet to this map. + */ registerOutlet(name: string, outlet: RouterOutlet): void { this._outlets[name] = outlet; } + /** + * Removes an outlet from this map. + */ removeOutlet(name: string): void { this._outlets[name] = undefined; } }