docs(animations): add documentation for new animation features

packages/animations/src/animation_builder.ts

@@ -9,15 +9,54 @@ import {AnimationMetadata, AnimationOptions} from './animation_metadata';
 import {AnimationPlayer} from './players/animation_player';
 
 /**
+ * AnimationBuilder is an injectable service that is available when the {@link
+ * BrowserAnimationsModule BrowserAnimationsModule} or {@link NoopAnimationsModule
+ * NoopAnimationsModule} modules are used within an application.
+ *
+ * The purpose if this service is to produce an animation sequence programmatically within an
+ * angular component or directive.
+ *
+ * Programmatic animations are first built and then a player is created when the build animation is
+ * attached to an element.
+ *
+ * ```ts
+ * // remember to include the BrowserAnimationsModule module for this to work...
+ * import {AnimationBuilder} from '@angular/animations';
+ *
+ * class MyCmp {
+ *   constructor(private _builder: AnimationBuilder) {}
+ *
+ *   makeAnimation(element: any) {
+ *     // first build the animation
+ *     const myAnimation = this._builder.build([
+ *       style({ width: 0 }),
+ *       animate(1000, style({ width: '100px' }))
+ *     ]);
+ *
+ *     // then create a player from it
+ *     const player = myAnimation.create(element);
+ *
+ *     player.play();
+ *   }
+ * }
+ * ```
+ *
+ * When an animation is built an instance of {@link AnimationFactory AnimationFactory} will be
+ * returned. Using that an {@link AnimationPlayer AnimationPlayer} can be created which can then be
+ * used to start the animation.
+ *
  * @experimental Animation support is experimental.
  */
 export abstract class AnimationBuilder {
-  abstract build(animation: AnimationMetadata|AnimationMetadata[]): Animation;
+  abstract build(animation: AnimationMetadata|AnimationMetadata[]): AnimationFactory;
 }
 
 /**
+ * An instance of `AnimationFactory` is returned from {@link AnimationBuilder#build
+ * AnimationBuilder.build}.
+ *
  * @experimental Animation support is experimental.
  */
-export abstract class Animation {
+export abstract class AnimationFactory {
   abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
 }

packages/animations/src/animations.ts

@@ -11,7 +11,7 @@
  * @description
  * Entry point for all animation APIs of the animation package.
  */
-export {Animation, AnimationBuilder} from './animation_builder';
+export {AnimationBuilder, AnimationFactory} from './animation_builder';
 export {AnimationEvent} from './animation_event';
 export {AUTO_STYLE, AnimateChildOptions, AnimateTimings, AnimationAnimateChildMetadata, AnimationAnimateMetadata, AnimationAnimateRefMetadata, AnimationGroupMetadata, AnimationKeyframesSequenceMetadata, AnimationMetadata, AnimationMetadataType, AnimationOptions, AnimationQueryMetadata, AnimationQueryOptions, AnimationReferenceMetadata, AnimationSequenceMetadata, AnimationStaggerMetadata, AnimationStateMetadata, AnimationStyleMetadata, AnimationTransitionMetadata, AnimationTriggerMetadata, animate, animateChild, animation, group, keyframes, query, sequence, stagger, state, style, transition, trigger, useAnimation, ɵStyleData} from './animation_metadata';
 export {AnimationPlayer, NoopAnimationPlayer} from './players/animation_player';

packages/animations/src/players/animation_player.ts

@@ -8,6 +8,10 @@
 import {scheduleMicroTask} from '../util';
 
 /**
+ * AnimationPlayer controls an animation sequence that was produced from a programmatic animation.
+ * (see {@link AnimationBuilder AnimationBuilder} for more information on how to create programmatic
+ * animations.)
+ *
  * @experimental Animation support is experimental.
  */
 export interface AnimationPlayer {

packages/platform-browser/animations/src/animation_builder.ts

@@ -5,7 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import {Animation, AnimationBuilder, AnimationMetadata, AnimationOptions, AnimationPlayer, NoopAnimationPlayer, sequence} from '@angular/animations';
+import {AnimationBuilder, AnimationFactory, AnimationMetadata, AnimationOptions, AnimationPlayer, NoopAnimationPlayer, sequence} from '@angular/animations';
 import {Injectable, RendererFactory2, RendererType2, ViewEncapsulation} from '@angular/core';
 
 import {AnimationRenderer} from './animation_renderer';
@@ -26,16 +26,16 @@ export class BrowserAnimationBuilder extends AnimationBuilder {
     this._renderer = rootRenderer.createRenderer(document.body, typeData) as AnimationRenderer;
   }
 
-  build(animation: AnimationMetadata|AnimationMetadata[]): Animation {
+  build(animation: AnimationMetadata|AnimationMetadata[]): AnimationFactory {
     const id = this._nextAnimationId.toString();
     this._nextAnimationId++;
     const entry = Array.isArray(animation) ? sequence(animation) : animation;
     issueAnimationCommand(this._renderer, null, id, 'register', [entry]);
-    return new BrowserAnimation(id, this._renderer);
+    return new BrowserAnimationFactory(id, this._renderer);
   }
 }
 
-export class BrowserAnimation extends Animation {
+export class BrowserAnimationFactory extends AnimationFactory {
   constructor(private _id: string, private _renderer: AnimationRenderer) { super(); }
 
   create(element: any, options?: AnimationOptions): AnimationPlayer {

packages/platform-browser/animations/src/private_export.ts

@@ -5,5 +5,5 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-export {BrowserAnimation as ɵBrowserAnimation, BrowserAnimationBuilder as ɵBrowserAnimationBuilder} from './animation_builder';
+export {BrowserAnimationBuilder as ɵBrowserAnimationBuilder, BrowserAnimationFactory as ɵBrowserAnimationFactory} from './animation_builder';
 export {AnimationRenderer as ɵAnimationRenderer, AnimationRendererFactory as ɵAnimationRendererFactory} from './animation_renderer';

tools/public_api_guard/animations/animations.d.ts

@@ -19,11 +19,6 @@ export declare type AnimateTimings = {
 /** @experimental */
 export declare function animation(steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationReferenceMetadata;
 
-/** @experimental */
-export declare abstract class Animation {
-    abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
-}
-
 /** @experimental */
 export interface AnimationAnimateChildMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
@@ -43,7 +38,7 @@ export interface AnimationAnimateRefMetadata extends AnimationMetadata {
 
 /** @experimental */
 export declare abstract class AnimationBuilder {
-    abstract build(animation: AnimationMetadata | AnimationMetadata[]): Animation;
+    abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory;
 }
 
 /** @experimental */
@@ -56,6 +51,11 @@ export interface AnimationEvent {
     triggerName: string;
 }
 
+/** @experimental */
+export declare abstract class AnimationFactory {
+    abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
+}
+
 /** @experimental */
 export interface AnimationGroupMetadata extends AnimationMetadata {
     options: AnimationOptions | null;