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/core/src/animation/animation_player.ts

@@ -9,6 +9,10 @@
 import {BaseException} from '../facade/exceptions';
 import {scheduleMicroTask} from '../facade/lang';
 
+
+/**
+ * @experimental Animation support is experimental.
+ */
 export abstract class AnimationPlayer {
   abstract onDone(fn: Function): void;
   abstract play(): void;

modules/@angular/core/src/animation/metadata.ts

@@ -7,25 +7,35 @@
  */
 
 import {BaseException} from '../facade/exceptions';
-import {NumberWrapper, isArray, isPresent, isString, isStringMap} from '../facade/lang';
+import {NumberWrapper, isArray, isPresent, isString} from '../facade/lang';
 
+/**
+ * @experimental Animation support is experimental.
+ */
 export const AUTO_STYLE = '*';
 
 /**
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link trigger trigger
  * animation function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationEntryMetadata {
   constructor(public name: string, public definitions: AnimationStateMetadata[]) {}
 }
 
+/**
+ * @experimental Animation support is experimental.
+ */
 export abstract class AnimationStateMetadata {}
 
 /**
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link state state animation
  * function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationStateDeclarationMetadata extends AnimationStateMetadata {
   constructor(public stateNameExpr: string, public styles: AnimationStyleMetadata) { super(); }
@@ -35,17 +45,24 @@ export class AnimationStateDeclarationMetadata extends AnimationStateMetadata {
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the
  * {@link transition transition animation function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationStateTransitionMetadata extends AnimationStateMetadata {
   constructor(public stateChangeExpr: string, public steps: AnimationMetadata) { super(); }
 }
 
+/**
+ * @experimental Animation support is experimental.
+ */
 export abstract class AnimationMetadata {}
 
 /**
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link keyframes keyframes
  * animation function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationKeyframesSequenceMetadata extends AnimationMetadata {
   constructor(public steps: AnimationStyleMetadata[]) { super(); }
@@ -55,6 +72,8 @@ export class AnimationKeyframesSequenceMetadata extends AnimationMetadata {
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link style style animation
  * function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationStyleMetadata extends AnimationMetadata {
   constructor(
@@ -67,6 +86,8 @@ export class AnimationStyleMetadata extends AnimationMetadata {
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link animate animate
  * animation function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationAnimateMetadata extends AnimationMetadata {
   constructor(
@@ -76,6 +97,9 @@ export class AnimationAnimateMetadata extends AnimationMetadata {
   }
 }
 
+/**
+ * @experimental Animation support is experimental.
+ */
 export abstract class AnimationWithStepsMetadata extends AnimationMetadata {
   constructor() { super(); }
   get steps(): AnimationMetadata[] { throw new BaseException('NOT IMPLEMENTED: Base Class'); }
@@ -85,6 +109,8 @@ export abstract class AnimationWithStepsMetadata extends AnimationMetadata {
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link sequence sequence
  * animation function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationSequenceMetadata extends AnimationWithStepsMetadata {
   constructor(private _steps: AnimationMetadata[]) { super(); }
@@ -95,6 +121,8 @@ export class AnimationSequenceMetadata extends AnimationWithStepsMetadata {
  * Metadata representing the entry of animations.
  * Instances of this class are provided via the animation DSL when the {@link group group animation
  * function} is called.
+ *
+ * @experimental Animation support is experimental.
  */
 export class AnimationGroupMetadata extends AnimationWithStepsMetadata {
   constructor(private _steps: AnimationMetadata[]) { super(); }
@@ -150,6 +178,8 @@ export class AnimationGroupMetadata extends AnimationWithStepsMetadata {
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function animate(
     timing: string | number, styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata =
@@ -197,6 +227,8 @@ export function animate(
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function group(steps: AnimationMetadata[]): AnimationGroupMetadata {
   return new AnimationGroupMetadata(steps);
@@ -238,6 +270,8 @@ export function group(steps: AnimationMetadata[]): AnimationGroupMetadata {
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function sequence(steps: AnimationMetadata[]): AnimationSequenceMetadata {
   return new AnimationSequenceMetadata(steps);
@@ -287,6 +321,8 @@ export function sequence(steps: AnimationMetadata[]): AnimationSequenceMetadata
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function style(
     tokens: string | {[key: string]: string | number} |
@@ -362,6 +398,8 @@ export function style(
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function state(
     stateNameExpr: string, styles: AnimationStyleMetadata): AnimationStateDeclarationMetadata {
@@ -414,6 +452,8 @@ export function state(
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata {
   return new AnimationKeyframesSequenceMetadata(steps);
@@ -504,6 +544,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function transition(stateChangeExpr: string, steps: AnimationMetadata | AnimationMetadata[]):
     AnimationStateTransitionMetadata {
@@ -565,6 +607,8 @@ export function transition(stateChangeExpr: string, steps: AnimationMetadata | A
  * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
  *
  * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ *
+ * @experimental Animation support is experimental.
  */
 export function trigger(name: string, animation: AnimationMetadata[]): AnimationEntryMetadata {
   return new AnimationEntryMetadata(name, animation);

modules/@angular/core/src/application_ref.ts

@@ -41,7 +41,8 @@ var _inPlatformCreate: boolean = false;
  * One important assertion this disables verifies that a change detection pass
  * does not result in additional changes to any bindings (also known as
  * unidirectional data flow).
- * @stable
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function enableProdMode(): void {
   if (_runModeLocked) {
@@ -56,6 +57,8 @@ export function enableProdMode(): void {
  * This can only be read after `lockRunMode` has been called.
  *
  * By default, this is true, unless a user calls `enableProdMode`.
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function isDevMode(): boolean {
   if (!_runModeLocked) {
@@ -68,6 +71,8 @@ export function isDevMode(): boolean {
  * Locks the run mode of Angular. After this has been called,
  * it can't be changed any more. I.e. `isDevMode()` will always
  * return the same value.
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function lockRunMode(): void {
   _runModeLocked = true;
@@ -76,7 +81,8 @@ export function lockRunMode(): void {
 /**
  * Creates a platform.
  * Platforms have to be eagerly created via this function.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function createPlatform(injector: Injector): PlatformRef {
   if (_inPlatformCreate) {
@@ -99,7 +105,8 @@ export function createPlatform(injector: Injector): PlatformRef {
 /**
  * Checks that there currently is a platform
  * which contains the given token as a provider.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function assertPlatform(requiredToken: any): PlatformRef {
   var platform = getPlatform();
@@ -115,7 +122,8 @@ export function assertPlatform(requiredToken: any): PlatformRef {
 
 /**
  * Dispose the existing platform.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function disposePlatform(): void {
   if (isPresent(_platform) && !_platform.disposed) {
@@ -125,7 +133,8 @@ export function disposePlatform(): void {
 
 /**
  * Returns the current platform.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function getPlatform(): PlatformRef {
   return isPresent(_platform) && !_platform.disposed ? _platform : null;
@@ -134,7 +143,8 @@ export function getPlatform(): PlatformRef {
 /**
  * Shortcut for ApplicationRef.bootstrap.
  * Requires a platform to be created first.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function coreBootstrap<C>(
     componentFactory: ComponentFactory<C>, injector: Injector): ComponentRef<C> {
@@ -146,7 +156,8 @@ export function coreBootstrap<C>(
  * Resolves the componentFactory for the given component,
  * waits for asynchronous initializers and bootstraps the component.
  * Requires a platform to be created first.
- * @experimental
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export function coreLoadAndBootstrap(
     componentType: Type, injector: Injector): Promise<ComponentRef<any>> {
@@ -166,7 +177,8 @@ export function coreLoadAndBootstrap(
  *
  * A page's platform is initialized implicitly when {@link bootstrap}() is called, or
  * explicitly by calling {@link createPlatform}().
- * @stable
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export abstract class PlatformRef {
   /**
@@ -228,7 +240,8 @@ export class PlatformRef_ extends PlatformRef {
  * A reference to an Angular application running on a page.
  *
  * For more about Angular applications, see the documentation for {@link bootstrap}.
- * @stable
+ *
+ * @experimental APIs related to application bootstrap are currently under review.
  */
 export abstract class ApplicationRef {
   /**

modules/@angular/core/src/change_detection/differs/iterable_differs.ts

@@ -25,14 +25,18 @@ export interface IterableDiffer {
 }
 
 /**
-  * An optional function passed into {@link NgFor} that defines how to track
-  * items in an iterable (e.g. by index or id)
+ * An optional function passed into {@link NgFor} that defines how to track
+ * items in an iterable (e.g. by index or id)
+ *
+ * @stable
  */
 export interface TrackByFn { (index: number, item: any): any; }
 
 
 /**
  * Provides a factory for {@link IterableDiffer}.
+ *
+ * @stable
  */
 export interface IterableDifferFactory {
   supports(objects: any): boolean;

modules/@angular/core/src/change_detection/differs/keyvalue_differs.ts

@@ -15,6 +15,8 @@ import {ChangeDetectorRef} from '../change_detector_ref';
 
 /**
  * A differ that tracks changes made to an object over time.
+ *
+ * @stable
  */
 export interface KeyValueDiffer {
   diff(object: any): any /** TODO #9100 */;
@@ -23,6 +25,8 @@ export interface KeyValueDiffer {
 
 /**
  * Provides a factory for {@link KeyValueDiffer}.
+ *
+ * @stable
  */
 export interface KeyValueDifferFactory {
   supports(objects: any): boolean;

modules/@angular/core/src/change_detection/pipe_transform.ts

@@ -33,5 +33,6 @@
  *
  * Invoking `{{ 'ok' | repeat:3 }}` in a template produces `okokok`.
  *
+ * @stable
  */
 export interface PipeTransform { transform(value: any, ...args: any[]): any; }

modules/@angular/core/src/debug/debug_node.ts

@@ -14,7 +14,7 @@ import {RenderDebugInfo} from '../render/api';
 export class EventListener { constructor(public name: string, public callback: Function){}; }
 
 /**
- * @experimental
+ * @experimental All debugging apis are currently experimental.
  */
 export class DebugNode {
   nativeNode: any;
@@ -58,7 +58,7 @@ export class DebugNode {
 }
 
 /**
- * @experimental
+ * @experimental All debugging apis are currently experimental.
  */
 export class DebugElement extends DebugNode {
   name: string;

modules/@angular/core/src/di/forward_ref.ts

@@ -15,6 +15,7 @@ import {Type, isFunction, stringify} from '../facade/lang';
  * ### Example
  *
  * {@example core/di/ts/forward_ref/forward_ref.ts region='forward_ref_fn'}
+ * @experimental
  */
 export interface ForwardRefFn { (): any; }
 

modules/@angular/core/src/di/reflective_injector.ts

@@ -355,6 +355,8 @@ export class ReflectiveInjectorDynamicStrategy implements ReflectiveInjectorStra
  *
  * Notice, we don't use the `new` operator because we explicitly want to have the `Injector`
  * resolve all of the object's dependencies automatically.
+ *
+ * @stable
  */
 export abstract class ReflectiveInjector implements Injector {
   /**

modules/@angular/core/src/di/reflective_provider.ts

@@ -47,6 +47,8 @@ const _EMPTY_LIST: any[] /** TODO #9100 */ = /*@ts2dart_const*/[];
  *
  * expect(injector.get('message')).toEqual('Hello');
  * ```
+ *
+ * @experimental
  */
 export interface ResolvedReflectiveProvider {
   /**

modules/@angular/core/src/linker/component_factory.ts

@@ -86,6 +86,10 @@ export class ComponentRef_<C> extends ComponentRef<C> {
  * @ts2dart_const
  */
 const EMPTY_CONTEXT = /*@ts2dart_const*/ new Object();
+
+/**
+ * @stable
+ */
 export class ComponentFactory<C> {
   constructor(
       public selector: string, private _viewFactory: Function, private _componentType: Type) {}

modules/@angular/core/src/linker/component_factory_resolver.ts

@@ -12,6 +12,10 @@ import {ClassWithConstructor, stringify} from '../facade/lang';
 
 import {ComponentFactory} from './component_factory';
 
+
+/**
+ * @stable
+ */
 export class NoComponentFactoryError extends BaseException {
   constructor(public component: Function) {
     super(`No component factory found for ${stringify(component)}`);
@@ -24,6 +28,9 @@ class _NullComponentFactoryResolver implements ComponentFactoryResolver {
   }
 }
 
+/**
+ * @stable
+ */
 export abstract class ComponentFactoryResolver {
   static NULL: ComponentFactoryResolver = new _NullComponentFactoryResolver();
   abstract resolveComponentFactory<T>(component: ClassWithConstructor<T>): ComponentFactory<T>;

modules/@angular/core/src/linker/element_ref.ts

@@ -11,6 +11,8 @@
  *
  * An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
  * element.
+ *
+ * @stable
  */
 // Note: We don't expose things like `Injector`, `ViewContainer`, ... here,
 // i.e. users have to ask for what they need. With that, we can build better analysis tools

modules/@angular/core/src/metadata.ts

@@ -30,6 +30,8 @@ import {Type} from '../src/facade/lang';
  * Interface for the {@link DirectiveMetadata} decorator function.
  *
  * See {@link DirectiveFactory}.
+ *
+ * @stable
  */
 export interface DirectiveDecorator extends TypeDecorator {}
 
@@ -37,6 +39,8 @@ export interface DirectiveDecorator extends TypeDecorator {}
  * Interface for the {@link ComponentMetadata} decorator function.
  *
  * See {@link ComponentFactory}.
+ *
+ * @stable
  */
 export interface ComponentDecorator extends TypeDecorator {
   /**
@@ -59,6 +63,8 @@ export interface ComponentDecorator extends TypeDecorator {
  * Interface for the {@link ViewMetadata} decorator function.
  *
  * See {@link ViewFactory}.
+ *
+ * @experimental
  */
 export interface ViewDecorator extends TypeDecorator {
   /**
@@ -107,6 +113,8 @@ export interface ViewDecorator extends TypeDecorator {
  *   new ng.Directive({...})
  * ]
  * ```
+ *
+ * @stable
  */
 export interface DirectiveMetadataFactory {
   (obj: {
@@ -163,6 +171,8 @@ export interface DirectiveMetadataFactory {
  *   new ng.Component({...})
  * ]
  * ```
+ *
+ * @stable
  */
 export interface ComponentMetadataFactory {
   (obj: {
@@ -256,6 +266,8 @@ export interface ComponentMetadataFactory {
  *   new ng.View({...})
  * ]
  * ```
+ *
+ * @experimental You should most likely use ComponentMetadataFactory instead
  */
 export interface ViewMetadataFactory {
   (obj: {
@@ -315,6 +327,8 @@ export interface ViewMetadataFactory {
  *   [new ng.Attribute('title')]
  * ]
  * ```
+ *
+ * @stable
  */
 export interface AttributeMetadataFactory {
   (name: string): TypeDecorator;

modules/@angular/core/src/metadata/view.ts

@@ -72,6 +72,8 @@ export var VIEW_ENCAPSULATION_VALUES =
  * }
  * ```
  * @ts2dart_const
+ *
+ * @experimental You should most likely be using ComponentMetadata instead.
  */
 export class ViewMetadata {
   /**

modules/@angular/core/src/profile/wtf_impl.ts

@@ -10,6 +10,8 @@ import {global} from '../facade/lang';
 
 /**
  * A scope function for the Web Tracing Framework (WTF).
+ *
+ * @experimental
  */
 export interface WtfScopeFn { (arg0?: any, arg1?: any): any; }
 

modules/@angular/core/src/security.ts

@@ -12,6 +12,8 @@
  * handled.
  *
  * See DomSanitizationService for more details on security in Angular applications.
+ *
+ * @stable
  */
 export enum SecurityContext {
   NONE,
@@ -25,6 +27,8 @@ export enum SecurityContext {
 /**
  * SanitizationService is used by the views to sanitize potentially dangerous values. This is a
  * private API, use code should only refer to DomSanitizationService.
+ *
+ * @stable
  */
 export abstract class SanitizationService {
   abstract sanitize(context: SecurityContext, value: string): string;

modules/@angular/core/src/testability/testability.ts

@@ -138,6 +138,9 @@ export class TestabilityRegistry {
 /**
  * Adapter interface for retrieving the `Testability` service associated for a
  * particular context.
+ *
+ * @experimental Testability apis are primarily intended to be used by e2e test tool vendors like
+ * the Protractor team.
  */
 export interface GetTestability {
   addToWindow(registry: TestabilityRegistry): void;

modules/@angular/core/src/util/decorators.ts

@@ -12,6 +12,8 @@ var _nextClassId = 0;
 
 /**
  * Declares the interface to be used with {@link Class}.
+ *
+ * @stable
  */
 export interface ClassDefinition {
   /**
@@ -58,6 +60,7 @@ export interface ClassDefinition {
  * @ng.View({...})
  * class MyClass {...}
  * ```
+ * @stable
  */
 export interface TypeDecorator {
   /**