fix: public api surface fixes + stability markers

- ts-api-guardian will now error if a new public symbol is added with a stability marker (`@stable`, `@experimental`, `@deprecated`)
- DomEventsPlugin and KeyEventsPlugin were removed from public api surface - these classes is an implementation detail
- deprecated BROWSER_PROVIDERS was removed completely
- `@angular/compiler` was removed from the ts-api-guardian check since this package shouldn't contain anything that users need to directly import
- the rest of the api surface was conservatively marked as stable or experimental

BREAKING CHANGES: DomEventsPlugin and KeyEventsPlugin previously exported from core are no longer public - these classes are implementation detail.

Previously deprecated BROWSER_PROVIDERS was completely removed from platform-browser.

Closes #9236
Closes #9235
Ref #9234

modules/@angular/platform-browser/src/browser.ts

@@ -34,6 +34,8 @@ const BROWSER_PLATFORM_MARKER = new OpaqueToken('BrowserPlatformMarker');
  * A set of providers to initialize the Angular platform in a web browser.
  *
  * Used automatically by `bootstrap`, or can be passed to {@link platform}.
+ *
+ * @experimental API related to bootstrapping are still under review.
  */
 export const BROWSER_PLATFORM_PROVIDERS: Array<any /*Type | Provider | any[]*/> = [
   {provide: BROWSER_PLATFORM_MARKER, useValue: true}, PLATFORM_COMMON_PROVIDERS,
@@ -41,6 +43,9 @@ export const BROWSER_PLATFORM_PROVIDERS: Array<any /*Type | Provider | any[]*/>
   {provide: PlatformLocation, useClass: BrowserPlatformLocation}
 ];
 
+/**
+ * @experimental
+ */
 export const BROWSER_SANITIZATION_PROVIDERS: Array<any> = [
   {provide: SanitizationService, useExisting: DomSanitizationService},
   {provide: DomSanitizationService, useClass: DomSanitizationServiceImpl},
@@ -50,6 +55,8 @@ export const BROWSER_SANITIZATION_PROVIDERS: Array<any> = [
  * A set of providers to initialize an Angular application in a web browser.
  *
  * Used automatically by `bootstrap`, or can be passed to {@link PlatformRef.application}.
+ *
+ * @experimental API related to bootstrapping are still under review.
  */
 export const BROWSER_APP_PROVIDERS: Array<any /*Type | Provider | any[]*/> = [
   APPLICATION_COMMON_PROVIDERS, FORM_PROVIDERS, BROWSER_SANITIZATION_PROVIDERS,
@@ -66,6 +73,9 @@ export const BROWSER_APP_PROVIDERS: Array<any /*Type | Provider | any[]*/> = [
   Testability, EventManager, ELEMENT_PROBE_PROVIDERS
 ];
 
+/**
+ * @experimental API related to bootstrapping are still under review.
+ */
 export function browserPlatform(): PlatformRef {
   if (isBlank(getPlatform())) {
     createPlatform(ReflectiveInjector.resolveAndCreate(BROWSER_PLATFORM_PROVIDERS));

modules/@angular/platform-browser/src/browser/location/browser_platform_location.ts

@@ -20,6 +20,8 @@ import {supportsState} from './history';
  * `PlatformLocation` encapsulates all of the direct calls to platform APIs.
  * This class should not be used directly by an application developer. Instead, use
  * {@link Location}.
+ *
+ * @stable
  */
 @Injectable()
 export class BrowserPlatformLocation extends PlatformLocation {

modules/@angular/platform-browser/src/browser/tools/tools.dart

@@ -15,6 +15,8 @@ import 'common_tools.dart' show AngularTools;
  * 1. Type `ng.` (usually the console will show auto-complete suggestion)
  * 1. Try the change detection profiler `ng.profiler.timeChangeDetection()`
  *    then hit Enter.
+ *
+ * @experimental All debugging apis are currently experimental.
  */
 void enableDebugTools(ComponentRef<dynamic> ref) {
   final tools = new AngularTools(ref);
@@ -29,6 +31,8 @@ void enableDebugTools(ComponentRef<dynamic> ref) {
 
 /**
  * Disables Angular 2 tools.
+ *
+ * @experimental All debugging apis are currently experimental.
  */
 void disableDebugTools() {
   context.deleteProperty('ng');

modules/@angular/platform-browser/src/browser/tools/tools.ts

@@ -23,6 +23,8 @@ var context = <any>global;
  * 1. Type `ng.` (usually the console will show auto-complete suggestion)
  * 1. Try the change detection profiler `ng.profiler.timeChangeDetection()`
  *    then hit Enter.
+ *
+ * @experimental All debugging apis are currently experimental.
  */
 export function enableDebugTools<T>(ref: ComponentRef<T>): ComponentRef<T> {
   context.ng = new AngularTools(ref);
@@ -31,6 +33,8 @@ export function enableDebugTools<T>(ref: ComponentRef<T>): ComponentRef<T> {
 
 /**
  * Disables Angular 2 tools.
+ *
+ * @experimental All debugging apis are currently experimental.
  */
 export function disableDebugTools(): void {
   delete context.ng;

modules/@angular/platform-browser/src/dom/debug/by.ts

@@ -16,6 +16,8 @@ import {Type, isPresent} from '../../facade/lang';
 
 /**
  * Predicates for use with {@link DebugElement}'s query functions.
+ *
+ * @experimental All debugging apis are currently experimental.
  */
 export class By {
   /**

modules/@angular/platform-browser/src/dom/dom_tokens.ts

@@ -13,5 +13,7 @@ import {OpaqueToken} from '@angular/core';
  *
  * Note: Document might not be available in the Application Context when Application and Rendering
  * Contexts are not the same (e.g. when running the application into a Web Worker).
+ *
+ * @stable
  */
 export const DOCUMENT: OpaqueToken = new OpaqueToken('DocumentToken');

modules/@angular/platform-browser/src/dom/events/event_manager.ts

@@ -12,8 +12,14 @@ import {ListWrapper} from '../../facade/collection';
 import {BaseException} from '../../facade/exceptions';
 
 
+/**
+ * @stable
+ */
 export const EVENT_MANAGER_PLUGINS: OpaqueToken = new OpaqueToken('EventManagerPlugins');
 
+/**
+ * @stable
+ */
 @Injectable()
 export class EventManager {
   private _plugins: EventManagerPlugin[];

modules/@angular/platform-browser/src/dom/events/hammer_gestures.ts

@@ -13,6 +13,12 @@ import {isPresent} from '../../facade/lang';
 
 import {HammerGesturesPluginCommon} from './hammer_common';
 
+/**
+ * A DI token that you can use to provide{@link HammerGestureConfig} to Angular. Use it to configure
+ * Hammer gestures.
+ *
+ * @experimental
+ */
 export const HAMMER_GESTURE_CONFIG: OpaqueToken = new OpaqueToken('HammerGestureConfig');
 
 export interface HammerInstance {
@@ -20,6 +26,9 @@ export interface HammerInstance {
   off(eventName: string, callback: Function): void;
 }
 
+/**
+ * @experimental
+ */
 @Injectable()
 export class HammerGestureConfig {
   events: string[] = [];

modules/@angular/platform-browser/src/dom/events/key_events.ts

@@ -23,6 +23,10 @@ var modifierKeyGetters: {[key: string]: (event: KeyboardEvent) => boolean} = {
   'shift': (event: KeyboardEvent) => event.shiftKey
 };
 
+
+/**
+ * @experimental
+ */
 @Injectable()
 export class KeyEventsPlugin extends EventManagerPlugin {
   constructor() { super(); }

modules/@angular/platform-browser/src/security/dom_sanitization_service.ts

@@ -19,17 +19,44 @@ export {SecurityContext};
 
 /**
  * Marker interface for a value that's safe to use in a particular context.
+ *
+ * @stable
  */
 export interface SafeValue {}
-/** Marker interface for a value that's safe to use as HTML. */
+
+/**
+ * Marker interface for a value that's safe to use as HTML.
+ *
+ * @stable
+ */
 export interface SafeHtml extends SafeValue {}
-/** Marker interface for a value that's safe to use as style (CSS). */
+
+/**
+ * Marker interface for a value that's safe to use as style (CSS).
+ *
+ * @stable
+ */
 export interface SafeStyle extends SafeValue {}
-/** Marker interface for a value that's safe to use as JavaScript. */
+
+/**
+ * Marker interface for a value that's safe to use as JavaScript.
+ *
+ * @stable
+ */
 export interface SafeScript extends SafeValue {}
-/** Marker interface for a value that's safe to use as a URL linking to a document. */
+
+/**
+ * Marker interface for a value that's safe to use as a URL linking to a document.
+ *
+ * @stable
+ */
 export interface SafeUrl extends SafeValue {}
-/** Marker interface for a value that's safe to use as a URL to load executable code from. */
+
+/**
+ * Marker interface for a value that's safe to use as a URL to load executable code from.
+ *
+ * @stable
+ */
 export interface SafeResourceUrl extends SafeValue {}
 
 /**
@@ -55,6 +82,8 @@ export interface SafeResourceUrl extends SafeValue {}
  * It is not required (and not recommended) to bypass security if the value is safe, e.g. a URL that
  * does not start with a suspicious protocol, or an HTML snippet that does not contain dangerous
  * code. The sanitizer leaves safe values intact.
+ *
+ * @stable
  */
 export abstract class DomSanitizationService implements SanitizationService {
   /**

modules/@angular/platform-browser/src/web_workers/shared/client_message_broker.ts

@@ -16,7 +16,7 @@ import {MessageBus} from './message_bus';
 import {Serializer} from './serializer';
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is experimental.
  */
 export abstract class ClientMessageBrokerFactory {
   /**
@@ -44,7 +44,7 @@ export class ClientMessageBrokerFactory_ extends ClientMessageBrokerFactory {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is experimental.
  */
 export abstract class ClientMessageBroker {
   abstract runOnService(args: UiArguments, returnType: Type): Promise<any>;
@@ -163,14 +163,14 @@ class MessageData {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is experimental.
  */
 export class FnArg {
   constructor(public value: any /** TODO #9100 */, public type: Type) {}
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is experimental.
  */
 export class UiArguments {
   constructor(public method: string, public args?: FnArg[]) {}

modules/@angular/platform-browser/src/web_workers/shared/message_bus.ts

@@ -16,7 +16,8 @@ import {EventEmitter} from '../../facade/async';
  * Communication is based on a channel abstraction. Messages published in a
  * given channel to one MessageBusSink are received on the same channel
  * by the corresponding MessageBusSource.
- * @experimental
+ *
+ * @experimental WebWorker support in Angular is currenlty experimental.
  */
 export abstract class MessageBus implements MessageBusSource, MessageBusSink {
   /**
@@ -51,7 +52,7 @@ export abstract class MessageBus implements MessageBusSource, MessageBusSink {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is currenlty experimental.
  */
 export interface MessageBusSource {
   /**
@@ -77,7 +78,7 @@ export interface MessageBusSource {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is currenlty experimental.
  */
 export interface MessageBusSink {
   /**

modules/@angular/platform-browser/src/web_workers/shared/serializer.ts

@@ -20,7 +20,7 @@ import {LocationType} from './serialized_types';
 // PRIMITIVE is any type that does not need to be serialized (string, number, boolean)
 // We set it to String so that it is considered a Type.
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is currently experimental.
  */
 export const PRIMITIVE: Type = String;
 

modules/@angular/platform-browser/src/web_workers/shared/service_message_broker.ts

@@ -14,6 +14,9 @@ import {FunctionWrapper, Type, isPresent} from '../../facade/lang';
 import {MessageBus} from '../shared/message_bus';
 import {Serializer} from '../shared/serializer';
 
+/**
+ * @experimental WebWorker support in Angular is currently experimental.
+ */
 export abstract class ServiceMessageBrokerFactory {
   /**
    * Initializes the given channel and attaches a new {@link ServiceMessageBroker} to it.
@@ -38,19 +41,18 @@ export class ServiceMessageBrokerFactory_ extends ServiceMessageBrokerFactory {
 }
 
 /**
- * @experimental
+ * Helper class for UIComponents that allows components to register methods.
+ * If a registered method message is received from the broker on the worker,
+ * the UIMessageBroker deserializes its arguments and calls the registered method.
+ * If that method returns a promise, the UIMessageBroker returns the result to the worker.
+ *
+ * @experimental WebWorker support in Angular is currently experimental.
  */
 export abstract class ServiceMessageBroker {
   abstract registerMethod(
       methodName: string, signature: Type[], method: Function, returnType?: Type): void;
 }
 
-/**
- * Helper class for UIComponents that allows components to register methods.
- * If a registered method message is received from the broker on the worker,
- * the UIMessageBroker deserializes its arguments and calls the registered method.
- * If that method returns a promise, the UIMessageBroker returns the result to the worker.
- */
 export class ServiceMessageBroker_ extends ServiceMessageBroker {
   private _sink: EventEmitter<any>;
   private _methods: Map<string, Function> = new Map<string, Function>();
@@ -100,7 +102,7 @@ export class ServiceMessageBroker_ extends ServiceMessageBroker {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support in Angular is currently experimental.
  */
 export class ReceivedMessage {
   method: string;

modules/@angular/platform-browser/src/worker_render.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {APPLICATION_COMMON_PROVIDERS, APP_INITIALIZER, ApplicationRef, ExceptionHandler, Injectable, Injector, NgZone, OpaqueToken, PLATFORM_COMMON_PROVIDERS, PLATFORM_INITIALIZER, PlatformRef, ReflectiveInjector, RootRenderer, Testability, assertPlatform, createPlatform, getPlatform} from '@angular/core';
+import {APPLICATION_COMMON_PROVIDERS, APP_INITIALIZER, ExceptionHandler, Injectable, Injector, NgZone, OpaqueToken, PLATFORM_COMMON_PROVIDERS, PLATFORM_INITIALIZER, PlatformRef, ReflectiveInjector, RootRenderer, Testability, assertPlatform, createPlatform, getPlatform} from '@angular/core';
 
 import {AnimationDriver, NoOpAnimationDriver, wtfInit} from '../core_private';
 
@@ -37,7 +37,8 @@ const WORKER_RENDER_PLATFORM_MARKER = new OpaqueToken('WorkerRenderPlatformMarke
 /**
  * Wrapper class that exposes the Worker
  * and underlying {@link MessageBus} for lower level message passing.
- * @experimental
+ *
+ * @experimental WebWorker support is currently experimental.
  */
 @Injectable()
 export class WebWorkerInstance {
@@ -52,7 +53,7 @@ export class WebWorkerInstance {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support is currently experimental.
  */
 export const WORKER_SCRIPT: OpaqueToken = new OpaqueToken('WebWorkerScript');
 
@@ -61,13 +62,13 @@ export const WORKER_SCRIPT: OpaqueToken = new OpaqueToken('WebWorkerScript');
  * created.
  *
  * TODO(vicb): create an interface for startable services to implement
- * @experimental
+ * @experimental WebWorker support is currently experimental.
  */
 export const WORKER_UI_STARTABLE_MESSAGING_SERVICE =
     new OpaqueToken('WorkerRenderStartableMsgService');
 
 /**
- * @experimental
+ * @experimental WebWorker support is currently experimental.
  */
 export const WORKER_UI_PLATFORM_PROVIDERS: Array<any /*Type | Provider | any[]*/> = [
   PLATFORM_COMMON_PROVIDERS, {provide: WORKER_RENDER_PLATFORM_MARKER, useValue: true},
@@ -75,7 +76,7 @@ export const WORKER_UI_PLATFORM_PROVIDERS: Array<any /*Type | Provider | any[]*/
 ];
 
 /**
- * @experimental
+ * @experimental WebWorker support is currently experimental.
  */
 export const WORKER_UI_APPLICATION_PROVIDERS: Array<any /*Type | Provider | any[]*/> = [
   APPLICATION_COMMON_PROVIDERS,
@@ -128,7 +129,7 @@ function initWebWorkerRenderPlatform(): void {
 }
 
 /**
- * @experimental
+ * @experimental WebWorker support is currently experimental.
  */
 export function workerUiPlatform(): PlatformRef {
   if (isBlank(getPlatform())) {