From cc1e0bbdc07663ec37e91488f143dba6a8b718b8 Mon Sep 17 00:00:00 2001 From: Andrew Scott Date: Fri, 15 May 2020 12:39:12 -0700 Subject: [PATCH] docs(router): add docs for RouterLink inputs (#37018) The RouterLink and RouterLinkWithHref inputs do not have any docs. This comment adds jsdoc comments to the inputs. PR Close #37018 --- goldens/public-api/router/router.d.ts | 2 +- packages/router/src/directives/router_link.ts | 92 ++++++++++++++++++- 2 files changed, 91 insertions(+), 3 deletions(-) diff --git a/goldens/public-api/router/router.d.ts b/goldens/public-api/router/router.d.ts index 1135b55078..4add286dfd 100644 --- a/goldens/public-api/router/router.d.ts +++ b/goldens/public-api/router/router.d.ts @@ -408,7 +408,7 @@ export declare class RouterLinkWithHref implements OnChanges, OnDestroy { fragment: string; href: string; preserveFragment: boolean; - set preserveQueryParams(value: boolean); + /** @deprecated */ set preserveQueryParams(value: boolean); queryParams: { [k: string]: any; }; diff --git a/packages/router/src/directives/router_link.ts b/packages/router/src/directives/router_link.ts index e3c5a072a7..af8248880d 100644 --- a/packages/router/src/directives/router_link.ts +++ b/packages/router/src/directives/router_link.ts @@ -113,21 +113,55 @@ import {UrlTree} from '../url_tree'; */ @Directive({selector: ':not(a):not(area)[routerLink]'}) export class RouterLink { + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#queryParams NavigationExtras#queryParams} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() queryParams!: {[k: string]: any}; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#fragment NavigationExtras#fragment} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() fragment!: string; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#queryParamsHandling NavigationExtras#queryParamsHandling} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() queryParamsHandling!: QueryParamsHandling; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#preserveFragment NavigationExtras#preserveFragment} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() preserveFragment!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#skipLocationChange NavigationExtras#skipLocationChange} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() skipLocationChange!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#replaceUrl NavigationExtras#replaceUrl} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() replaceUrl!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#state NavigationExtras#state} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ @Input() state?: {[k: string]: any}; private commands: any[] = []; - // TODO(issue/24571): remove '!'. private preserve!: boolean; constructor( @@ -138,6 +172,14 @@ export class RouterLink { } } + /** + * @param commands An array of commands to pass to {@link Router#createUrlTree + * Router#createUrlTree}. + * - **array**: commands to pass to {@link Router#createUrlTree Router#createUrlTree}. + * - **string**: shorthand for array of commands with just the string, i.e. `['/route']` + * - **null|undefined**: shorthand for an empty array of commands, i.e. `[]` + * @see {@link Router#createUrlTree Router#createUrlTree} + */ @Input() set routerLink(commands: any[]|string|null|undefined) { if (commands != null) { @@ -148,7 +190,7 @@ export class RouterLink { } /** - * @deprecated 4.0.0 use `queryParamsHandling` instead. + * @deprecated As of Angular v4.0 use `queryParamsHandling` instead. */ @Input() set preserveQueryParams(value: boolean) { @@ -196,18 +238,53 @@ export class RouterLink { export class RouterLinkWithHref implements OnChanges, OnDestroy { // TODO(issue/24571): remove '!'. @HostBinding('attr.target') @Input() target!: string; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#queryParams NavigationExtras#queryParams} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() queryParams!: {[k: string]: any}; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#fragment NavigationExtras#fragment} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() fragment!: string; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#queryParamsHandling NavigationExtras#queryParamsHandling} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() queryParamsHandling!: QueryParamsHandling; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#preserveFragment NavigationExtras#preserveFragment} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() preserveFragment!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#skipLocationChange NavigationExtras#skipLocationChange} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() skipLocationChange!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#replaceUrl NavigationExtras#replaceUrl} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ // TODO(issue/24571): remove '!'. @Input() replaceUrl!: boolean; + /** + * Passed to {@link Router#createUrlTree Router#createUrlTree} as part of the `NavigationExtras`. + * @see {@link NavigationExtras#state NavigationExtras#state} + * @see {@link Router#createUrlTree Router#createUrlTree} + */ @Input() state?: {[k: string]: any}; private commands: any[] = []; private subscription: Subscription; @@ -228,6 +305,14 @@ export class RouterLinkWithHref implements OnChanges, OnDestroy { }); } + /** + * @param commands An array of commands to pass to {@link Router#createUrlTree + * Router#createUrlTree}. + * - **array**: commands to pass to {@link Router#createUrlTree Router#createUrlTree}. + * - **string**: shorthand for array of commands with just the string, i.e. `['/route']` + * - **null|undefined**: shorthand for an empty array of commands, i.e. `[]` + * @see {@link Router#createUrlTree Router#createUrlTree} + */ @Input() set routerLink(commands: any[]|string|null|undefined) { if (commands != null) { @@ -237,6 +322,9 @@ export class RouterLinkWithHref implements OnChanges, OnDestroy { } } + /** + * @deprecated As of Angular v4.0 use `queryParamsHandling` instead. + */ @Input() set preserveQueryParams(value: boolean) { if (isDevMode() && console && console.warn) {