docs: update router to use @publicApi tags (#26595)

PR Close #26595

packages/router/src/config.ts

@@ -253,6 +253,7 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
  * Then it will extract the set of routes defined in that NgModule, and will transparently add
  * those routes to the main configuration.
  *
+ * @publicApi
  */
 export type Routes = Route[];
 
@@ -298,6 +299,7 @@ export type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route:
  *
  * See `Routes` for more details.
  *
+ * @publicApi
  */
 export type Data = {
   [name: string]: any
@@ -310,6 +312,7 @@ export type Data = {
  *
  * See `Routes` for more details.
  *
+ * @publicApi
  */
 export type ResolveData = {
   [name: string]: any
@@ -322,6 +325,7 @@ export type ResolveData = {
  *
  * See `Routes` for more details.
  *
+ * @publicApi
  */
 export type LoadChildrenCallback = () =>
     Type<any>| NgModuleFactory<any>| Promise<Type<any>>| Observable<Type<any>>;
@@ -333,6 +337,7 @@ export type LoadChildrenCallback = () =>
  *
  * See `Routes` for more details.
  *
+ * @publicApi
  */
 export type LoadChildren = string | LoadChildrenCallback;
 
@@ -359,6 +364,7 @@ export type RunGuardsAndResolvers = 'paramsChange' | 'paramsOrQueryParamsChange'
 /**
  * See `Routes` for more details.
  *
+ * @publicApi
  */
 export interface Route {
   path?: string;

packages/router/src/directives/router_link.ts

@@ -88,7 +88,7 @@ import {UrlTree} from '../url_tree';
  *
  * @ngModule RouterModule
  *
- *
+ * @publicApi
  */
 @Directive({selector: ':not(a)[routerLink]'})
 export class RouterLink {
@@ -167,7 +167,7 @@ export class RouterLink {
  *
  * @ngModule RouterModule
  *
- *
+ * @publicApi
  */
 @Directive({selector: 'a[routerLink]'})
 export class RouterLinkWithHref implements OnChanges, OnDestroy {

packages/router/src/directives/router_link_active.ts

@@ -70,7 +70,7 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
  *
  * @ngModule RouterModule
  *
- *
+ * @publicApi
  */
 @Directive({
   selector: '[routerLinkActive]',

packages/router/src/directives/router_outlet.ts

@@ -34,7 +34,7 @@ import {PRIMARY_OUTLET} from '../shared';
  * ```
  * @ngModule RouterModule
  *
- *
+ * @publicApi
  */
 @Directive({selector: 'router-outlet', exportAs: 'outlet'})
 export class RouterOutlet implements OnDestroy, OnInit {

packages/router/src/events.ts

@@ -55,7 +55,7 @@ export class RouterEvent {
  *
  * Represents an event triggered when a navigation starts.
  *
- *
+ * @publicApi
  */
 export class NavigationStart extends RouterEvent {
   /**
@@ -104,7 +104,7 @@ export class NavigationStart extends RouterEvent {
  *
  * Represents an event triggered when a navigation ends successfully.
  *
- *
+ * @publicApi
  */
 export class NavigationEnd extends RouterEvent {
   constructor(
@@ -128,7 +128,7 @@ export class NavigationEnd extends RouterEvent {
  *
  * Represents an event triggered when a navigation is canceled.
  *
- *
+ * @publicApi
  */
 export class NavigationCancel extends RouterEvent {
   constructor(
@@ -150,7 +150,7 @@ export class NavigationCancel extends RouterEvent {
  *
  * Represents an event triggered when a navigation fails due to an unexpected error.
  *
- *
+ * @publicApi
  */
 export class NavigationError extends RouterEvent {
   constructor(
@@ -174,7 +174,7 @@ export class NavigationError extends RouterEvent {
  *
  * Represents an event triggered when routes are recognized.
  *
- *
+ * @publicApi
  */
 export class RoutesRecognized extends RouterEvent {
   constructor(
@@ -405,6 +405,8 @@ export class ActivationEnd {
  * @description
  *
  * Represents a scrolling event.
+ *
+ * @publicApi
  */
 export class Scroll {
   constructor(
@@ -447,7 +449,7 @@ export class Scroll {
  * - `NavigationError`
  * - `Scroll`
  *
- *
+ * @publicApi
  */
 export type Event = RouterEvent | RouteConfigLoadStart | RouteConfigLoadEnd | ChildActivationStart |
     ChildActivationEnd | ActivationStart | ActivationEnd | Scroll;

packages/router/src/interfaces.ts

@@ -76,7 +76,7 @@ import {UrlSegment} from './url_tree';
  * class AppModule {}
  * ```
  *
- *
+ * @publicApi
  */
 export interface CanActivate {
   canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot):
@@ -156,7 +156,7 @@ export interface CanActivate {
  * class AppModule {}
  * ```
  *
- *
+ * @publicApi
  */
 export interface CanActivateChild {
   canActivateChild(childRoute: ActivatedRouteSnapshot, state: RouterStateSnapshot):
@@ -229,7 +229,7 @@ export interface CanActivateChild {
  * class AppModule {}
  * ```
  *
- *
+ * @publicApi
  */
 export interface CanDeactivate<T> {
   canDeactivate(
@@ -303,6 +303,7 @@ export interface CanDeactivate<T> {
  * class AppModule {}
  * ```
  *
+ * @publicApi
  */
 export interface Resolve<T> {
   resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<T>|Promise<T>|T;
@@ -371,7 +372,7 @@ export interface Resolve<T> {
  * class AppModule {}
  * ```
  *
- *
+ * @publicApi
  */
 export interface CanLoad {
   canLoad(route: Route, segments: UrlSegment[]): Observable<boolean>|Promise<boolean>|boolean;

packages/router/src/router.ts

@@ -37,7 +37,7 @@ import {Checks, getAllRouteGuards} from './utils/preactivation';
  *
  * Represents the extra options used during navigation.
  *
- *
+ * @publicApi
  */
 export interface NavigationExtras {
   /**
@@ -155,7 +155,7 @@ export interface NavigationExtras {
  * If the handler throws an exception, the navigation promise will be rejected with
  * the exception.
  *
- *
+ * @publicApi
  */
 export type ErrorHandler = (error: any) => any;
 
@@ -222,7 +222,7 @@ function defaultRouterHook(snapshot: RouterStateSnapshot, runExtras: {
  *
  * @ngModule RouterModule
  *
- *
+ * @publicApi
  */
 export class Router {
   private currentUrlTree: UrlTree;

packages/router/src/router_module.ts

@@ -45,7 +45,7 @@ const ROUTER_DIRECTIVES =
  *
  * Is used in DI to configure the router.
  *
- *
+ * @publicApi
  */
 export const ROUTER_CONFIGURATION = new InjectionToken<ExtraOptions>('ROUTER_CONFIGURATION');
 
@@ -128,7 +128,7 @@ export function routerNgProbeToken() {
  * [Read this developer guide](https://angular.io/docs/ts/latest/guide/router.html) to get an
  * overview of how the router should be used.
  *
- *
+ * @publicApi
  */
 @NgModule({
   declarations: ROUTER_DIRECTIVES,
@@ -236,7 +236,7 @@ export function provideForRootGuard(router: Router): any {
  * class MyNgModule {}
  * ```
  *
- *
+ * @publicApi
  */
 export function provideRoutes(routes: Routes): any {
   return [
@@ -278,7 +278,7 @@ export type InitialNavigation =
  *
  * Represents options to configure the router.
  *
- *
+ * @publicApi
  */
 export interface ExtraOptions {
   /**

packages/router/src/router_outlet_context.ts

@@ -15,7 +15,7 @@ import {ActivatedRoute} from './router_state';
 /**
  * Store contextual information about a `RouterOutlet`
  *
- *
+ * @publicApi
  */
 export class OutletContext {
   outlet: RouterOutlet|null = null;
@@ -28,7 +28,7 @@ export class OutletContext {
 /**
  * Store contextual information about the children (= nested) `RouterOutlet`
  *
- *
+ * @publicApi
  */
 export class ChildrenOutletContexts {
   // contexts for child outlets, by name.

packages/router/src/router_preloader.ts

@@ -67,7 +67,7 @@ export class NoPreloading implements PreloadingStrategy {
  *
  * If a route is protected by `canLoad` guards, the preloaded will not load it.
  *
- *
+ * @publicApi
  */
 @Injectable()
 export class RouterPreloader implements OnDestroy {

packages/router/src/router_state.ts

@@ -44,7 +44,7 @@ import {Tree, TreeNode} from './utils/tree';
  *
  * See `ActivatedRoute` for more information.
  *
- *
+ * @publicApi
  */
 export class RouterState extends Tree<ActivatedRoute> {
   /** @internal */
@@ -103,7 +103,7 @@ export function createEmptyStateSnapshot(
  * }
  * ```
  *
- *
+ * @publicApi
  */
 export class ActivatedRoute {
   /** The current snapshot of this route */
@@ -250,7 +250,7 @@ function flattenInherited(pathFromRoot: ActivatedRouteSnapshot[]): Inherited {
  * }
  * ```
  *
- *
+ * @publicApi
  */
 export class ActivatedRouteSnapshot {
   /** The configuration used to match this route **/
@@ -358,7 +358,7 @@ export class ActivatedRouteSnapshot {
  * }
  * ```
  *
- *
+ * @publicApi
  */
 export class RouterStateSnapshot extends Tree<ActivatedRouteSnapshot> {
   /** @internal */

packages/router/src/shared.ts

@@ -15,14 +15,14 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
  *
  * Name of the primary outlet.
  *
- *
+ * @publicApi
  */
 export const PRIMARY_OUTLET = 'primary';
 
 /**
  * A collection of parameters.
  *
- *
+ * @publicApi
  */
 export type Params = {
   [key: string]: any
@@ -38,7 +38,7 @@ export type Params = {
  * The API is inspired by the URLSearchParams interface.
  * see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
  *
- *
+ * @publicApi
  */
 export interface ParamMap {
   has(name: string): boolean;
@@ -91,7 +91,7 @@ class ParamsAsMap implements ParamMap {
 /**
  * Convert a `Params` instance to a `ParamMap`.
  *
- *
+ * @publicApi
  */
 export function convertToParamMap(params: Params): ParamMap {
   return new ParamsAsMap(params);

packages/router/src/url_tree.ts

@@ -101,7 +101,7 @@ function containsSegmentGroupHelper(
  * }
  * ```
  *
- *
+ * @publicApi
  */
 export class UrlTree {
   /** @internal */
@@ -135,7 +135,7 @@ export class UrlTree {
  *
  * See `UrlTree` for more information.
  *
- *
+ * @publicApi
  */
 export class UrlSegmentGroup {
   /** @internal */
@@ -190,7 +190,7 @@ export class UrlSegmentGroup {
  * }
  * ```
  *
- *
+ * @publicApi
  */
 export class UrlSegment {
   /** @internal */
@@ -251,7 +251,7 @@ export function mapChildrenIntoArray<T>(
  *
  * See `DefaultUrlSerializer` for an example of a URL serializer.
  *
- *
+ * @publicApi
  */
 export abstract class UrlSerializer {
   /** Parse a url into a `UrlTree` */
@@ -277,7 +277,7 @@ export abstract class UrlSerializer {
  * colon syntax to specify the outlet, and the ';parameter=value' syntax (e.g., open=true) to
  * specify route specific parameters.
  *
- *
+ * @publicApi
  */
 export class DefaultUrlSerializer implements UrlSerializer {
   /** Parses a url into a `UrlTree` */

packages/router/src/version.ts

@@ -14,4 +14,7 @@
 
 import {Version} from '@angular/core';
 
+/**
+ * @publicApi
+ */
 export const VERSION = new Version('0.0.0-PLACEHOLDER');

packages/router/testing/src/router_testing_module.ts

@@ -40,7 +40,7 @@ import {ChildrenOutletContexts, ExtraOptions, NoPreloading, PreloadingStrategy,
  * router.navigateByUrl('/lazy/loaded');
  * ```
  *
- *
+ * @publicApi
  */
 @Injectable()
 export class SpyNgModuleFactoryLoader implements NgModuleFactoryLoader {
@@ -86,7 +86,7 @@ function isUrlHandlingStrategy(opts: ExtraOptions | UrlHandlingStrategy):
 /**
  * Router setup factory function used for testing.
  *
- *
+ * @publicApi
  */
 export function setupTestingRouter(
     urlSerializer: UrlSerializer, contexts: ChildrenOutletContexts, location: Location,
@@ -98,6 +98,7 @@ export function setupTestingRouter(
  *
  * @deprecated As of v5.2. The 2nd-to-last argument should be `ExtraOptions`, not
  * `UrlHandlingStrategy`
+ * @publicApi
  */
 export function setupTestingRouter(
     urlSerializer: UrlSerializer, contexts: ChildrenOutletContexts, location: Location,
@@ -107,7 +108,7 @@ export function setupTestingRouter(
 /**
  * Router setup factory function used for testing.
  *
- *
+ * @publicApi
  */
 export function setupTestingRouter(
     urlSerializer: UrlSerializer, contexts: ChildrenOutletContexts, location: Location,
@@ -162,7 +163,7 @@ export function setupTestingRouter(
  * });
  * ```
  *
- *
+ * @publicApi
  */
 @NgModule({
   exports: [RouterModule],

packages/upgrade/src/common/angular1.ts

@@ -251,6 +251,8 @@ try {
 
 /**
  * @deprecated Use `setAngularJSGlobal` instead.
+ *
+ * @publicApi
  */
 export function setAngularLib(ng: any): void {
   setAngularJSGlobal(ng);
@@ -258,6 +260,8 @@ export function setAngularLib(ng: any): void {
 
 /**
  * @deprecated Use `getAngularJSGlobal` instead.
+ *
+ * @publicApi
  */
 export function getAngularLib(): any {
   return getAngularJSGlobal();
@@ -267,6 +271,8 @@ export function getAngularLib(): any {
  * Resets the AngularJS global.
  *
  * Used when AngularJS is loaded lazily, and not available on `window`.
+ *
+ * @publicApi
  */
 export function setAngularJSGlobal(ng: any): void {
   angular = ng;
@@ -275,6 +281,8 @@ export function setAngularJSGlobal(ng: any): void {
 
 /**
  * Returns the current AngularJS global.
+ *
+ * @publicApi
  */
 export function getAngularJSGlobal(): any {
   return angular;

packages/upgrade/src/common/version.ts

@@ -14,4 +14,7 @@
 
 import {Version} from '@angular/core';
 
+/**
+ * @publicApi
+ */
 export const VERSION = new Version('0.0.0-PLACEHOLDER');

packages/upgrade/src/dynamic/upgrade_adapter.ts

@@ -99,6 +99,7 @@ let upgradeCount: number = 0;
  *
  * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
  * [Ahead-of-Time compilation](guide/aot-compiler).
+ * @publicApi
  */
 export class UpgradeAdapter {
   private idPrefix: string = `NG2_UPGRADE_${upgradeCount++}_`;
@@ -655,6 +656,7 @@ class ParentInjectorPromise {
  *
  * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
  * [Ahead-of-Time compilation](guide/aot-compiler).
+ * @publicApi
  */
 export class UpgradeAdapterRef {
   /* @internal */

tools/public_api_guard/router/router.d.ts

@@ -37,7 +37,6 @@ export declare class ActivatedRouteSnapshot {
     toString(): string;
 }
 
-/** @experimental */
 export declare class ActivationEnd {
     snapshot: ActivatedRouteSnapshot;
     constructor(
@@ -45,7 +44,6 @@ export declare class ActivationEnd {
     toString(): string;
 }
 
-/** @experimental */
 export declare class ActivationStart {
     snapshot: ActivatedRouteSnapshot;
     constructor(
@@ -69,7 +67,6 @@ export interface CanLoad {
     canLoad(route: Route, segments: UrlSegment[]): Observable<boolean> | Promise<boolean> | boolean;
 }
 
-/** @experimental */
 export declare class ChildActivationEnd {
     snapshot: ActivatedRouteSnapshot;
     constructor(
@@ -77,7 +74,6 @@ export declare class ChildActivationEnd {
     toString(): string;
 }
 
-/** @experimental */
 export declare class ChildActivationStart {
     snapshot: ActivatedRouteSnapshot;
     constructor(
@@ -105,7 +101,6 @@ export declare class DefaultUrlSerializer implements UrlSerializer {
     serialize(tree: UrlTree): string;
 }
 
-/** @experimental */
 export declare type DetachedRouteHandle = {};
 
 export declare type Event = RouterEvent | RouteConfigLoadStart | RouteConfigLoadEnd | ChildActivationStart | ChildActivationEnd | ActivationStart | ActivationEnd | Scroll;
@@ -126,7 +121,6 @@ export interface ExtraOptions {
     useHash?: boolean;
 }
 
-/** @experimental */
 export declare class GuardsCheckEnd extends RouterEvent {
     shouldActivate: boolean;
     state: RouterStateSnapshot;
@@ -140,7 +134,6 @@ export declare class GuardsCheckEnd extends RouterEvent {
     toString(): string;
 }
 
-/** @experimental */
 export declare class GuardsCheckStart extends RouterEvent {
     state: RouterStateSnapshot;
     urlAfterRedirects: string;
@@ -209,7 +202,6 @@ export declare class NavigationStart extends RouterEvent {
     toString(): string;
 }
 
-/** @experimental */
 export declare class NoPreloading implements PreloadingStrategy {
     preload(route: Route, fn: () => Observable<any>): Observable<any>;
 }
@@ -233,12 +225,10 @@ export declare type Params = {
     [key: string]: any;
 };
 
-/** @experimental */
 export declare class PreloadAllModules implements PreloadingStrategy {
     preload(route: Route, fn: () => Observable<any>): Observable<any>;
 }
 
-/** @experimental */
 export declare abstract class PreloadingStrategy {
     abstract preload(route: Route, fn: () => Observable<any>): Observable<any>;
 }
@@ -255,7 +245,6 @@ export declare type ResolveData = {
     [name: string]: any;
 };
 
-/** @experimental */
 export declare class ResolveEnd extends RouterEvent {
     state: RouterStateSnapshot;
     urlAfterRedirects: string;
@@ -267,7 +256,6 @@ export declare class ResolveEnd extends RouterEvent {
     toString(): string;
 }
 
-/** @experimental */
 export declare class ResolveStart extends RouterEvent {
     state: RouterStateSnapshot;
     urlAfterRedirects: string;
@@ -297,7 +285,6 @@ export interface Route {
     runGuardsAndResolvers?: RunGuardsAndResolvers;
 }
 
-/** @experimental */
 export declare class RouteConfigLoadEnd {
     route: Route;
     constructor(
@@ -305,7 +292,6 @@ export declare class RouteConfigLoadEnd {
     toString(): string;
 }
 
-/** @experimental */
 export declare class RouteConfigLoadStart {
     route: Route;
     constructor(
@@ -343,10 +329,8 @@ export declare class Router {
 
 export declare const ROUTER_CONFIGURATION: InjectionToken<ExtraOptions>;
 
-/** @experimental */
 export declare const ROUTER_INITIALIZER: InjectionToken<(compRef: ComponentRef<any>) => void>;
 
-/** @experimental */
 export declare abstract class RouteReuseStrategy {
     abstract retrieve(route: ActivatedRouteSnapshot): DetachedRouteHandle | null;
     abstract shouldAttach(route: ActivatedRouteSnapshot): boolean;
@@ -355,7 +339,6 @@ export declare abstract class RouteReuseStrategy {
     abstract store(route: ActivatedRouteSnapshot, handle: DetachedRouteHandle | null): void;
 }
 
-/** @experimental */
 export declare class RouterEvent {
     id: number;
     url: string;
@@ -455,7 +438,6 @@ export declare class RouterStateSnapshot extends Tree<ActivatedRouteSnapshot> {
 
 export declare type Routes = Route[];
 
-/** @experimental */
 export declare const ROUTES: InjectionToken<Route[][]>;
 
 export declare class RoutesRecognized extends RouterEvent {
@@ -469,7 +451,6 @@ export declare class RoutesRecognized extends RouterEvent {
     toString(): string;
 }
 
-/** @experimental */
 export declare type RunGuardsAndResolvers = 'paramsChange' | 'paramsOrQueryParamsChange' | 'always';
 
 export declare class Scroll {
@@ -483,17 +464,14 @@ export declare class Scroll {
     toString(): string;
 }
 
-/** @experimental */
 export declare abstract class UrlHandlingStrategy {
     abstract extract(url: UrlTree): UrlTree;
     abstract merge(newUrlPart: UrlTree, rawUrl: UrlTree): UrlTree;
     abstract shouldProcessUrl(url: UrlTree): boolean;
 }
 
-/** @experimental */
 export declare type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => UrlMatchResult;
 
-/** @experimental */
 export declare type UrlMatchResult = {
     consumed: UrlSegment[];
     posParams?: {

tools/public_api_guard/router/upgrade.d.ts

@@ -1,4 +1,3 @@
-/** @experimental */
 export declare const RouterUpgradeInitializer: {
     provide: InjectionToken<((compRef: ComponentRef<any>) => void)[]>;
     multi: boolean;
@@ -6,5 +5,4 @@ export declare const RouterUpgradeInitializer: {
     deps: (typeof UpgradeModule)[];
 };
 
-/** @experimental */
 export declare function setUpLocationSync(ngUpgrade: UpgradeModule): void;