docs: add api doc for programmatic animation classes (#24668)

PR Close #24668

packages/animations/src/animation_builder.ts

@@ -9,31 +9,42 @@ import {AnimationMetadata, AnimationOptions} from './animation_metadata';
 import {AnimationPlayer} from './players/animation_player';
 
 /**
- * AnimationBuilder is an injectable service that is available when the {@link
+ * An injectable service that produces an animation sequence programmatically within an
- * BrowserAnimationsModule BrowserAnimationsModule} or {@link NoopAnimationsModule
+ * Angular component or directive.
- * NoopAnimationsModule} modules are used within an application.
+ * Provided by the `BrowserAnimationsModule` or `NoopAnimationsModule`.
  *
- * The purpose of this service is to produce an animation sequence programmatically within an
+ * @usageNotes
- * angular component or directive.
  *
- * Programmatic animations are first built and then a player is created when the build animation is
+ * To use this service, add it to your component or directive as a dependency.
- * attached to an element.
+ * The service is instantiated along with your component.
+ *
+ * Apps do not typically need to create their own animation players, but if you
+ * do need to, follow these steps:
+ *
+ * 1. Use the `build()` method to create a programmatic animation using the
+ * `animate()` function. The method returns an `AnimationFactory` instance.
+ *
+ * 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element.
+ *
+ * 3. Use the player object to control the animation programmatically.
+ *
+ * For example:
  *
  * ```ts
- * // remember to include the BrowserAnimationsModule module for this to work...
+ * // import the service from BrowserAnimationsModule
  * import {AnimationBuilder} from '@angular/animations';
- *
+ * // require the service as a dependency
  * class MyCmp {
  *   constructor(private _builder: AnimationBuilder) {}
  *
  *   makeAnimation(element: any) {
- *     // first build the animation
+ *     // first define a reusable animation
  *     const myAnimation = this._builder.build([
  *       style({ width: 0 }),
  *       animate(1000, style({ width: '100px' }))
  *     ]);
  *
- *     // then create a player from it
+ *     // use the returned factory object to create a player
  *     const player = myAnimation.create(element);
  *
  *     player.play();
@@ -41,22 +52,29 @@ import {AnimationPlayer} from './players/animation_player';
  * }
  * ```
  *
- * 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 {
+  /**
+   * Builds a factory for producing a defined animation. 
+   * @param animation A reusable animation definition.
+   * @returns A factory object that can create a player for the defined animation.
+   * @see `animate()`
+   */
   abstract build(animation: AnimationMetadata|AnimationMetadata[]): AnimationFactory;
 }
 
 /**
- * An instance of `AnimationFactory` is returned from {@link AnimationBuilder#build
+ * A factory object returned from the `AnimationBuilder`.`build()` method.
- * AnimationBuilder.build}.
  *
- * @experimental Animation support is experimental.
  */
 export abstract class AnimationFactory {
+  /**
+   * Creates an `AnimationPlayer` instance for the reusable animation defined by
+   * the `AnimationBuilder`.`build()` method that created this factory.
+   * Attaches the new player a DOM element.
+   * @param element The DOM element to which to attach the animation.
+   * @param options A set of options that can include a time delay and
+   * additional developer-defined parameters.
+   */
   abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
 }

packages/animations/src/animation_event.ts

@@ -38,11 +38,33 @@
  * @experimental Animation support is experimental.
  */
 export interface AnimationEvent {
+  /**
+   * The name of the state from which the animation is triggered.
+   */
   fromState: string;
+  /**
+   * The name of the state in which the animation completes.
+   */
   toState: string;
+  /**
+   * The time it takes the animation to complete, in milliseconds.
+   */
   totalTime: number;
+  /**
+   * The animation phase in which the callback was invoked, one of
+   * "start" or "done".
+   */
   phaseName: string;
+  /**
+   * The element to which the animation is attached.
+   */
   element: any;
+  /**
+   * Internal.
+   */
   triggerName: string;
+  /**
+   * Internal.
+   */
   disabled: boolean;
 }

packages/animations/src/players/animation_group_player.ts

@@ -9,6 +9,14 @@
 import {scheduleMicroTask} from '../util';
 import {AnimationPlayer} from './animation_player';
 
+/**
+ * A programmatic controller for a group of reusable animations.
+ * Used internally to control animations.
+ *
+ * @see `AnimationPlayer`
+ * @see `{@link animations/group group()}`
+ *
+ */
 export class AnimationGroupPlayer implements AnimationPlayer {
   private _onDoneFns: Function[] = [];
   private _onStartFns: Function[] = [];

packages/animations/src/players/animation_player.ts

@@ -8,37 +8,110 @@
 import {scheduleMicroTask} from '../util';
 
 /**
- * AnimationPlayer controls an animation sequence that was produced from a programmatic animation.
+ * Provides programmatic control of a reusable animation sequence,
- * (see {@link AnimationBuilder AnimationBuilder} for more information on how to create programmatic
+ * built using the `build()` method of `AnimationBuilder`. The `build()` method
- * animations.)
+ * returns a factory, whose `create()` method instantiates and initializes this interface.
+ *
+ * @see `AnimationBuilder`
+ * @see `AnimationFactory`
+ * @see `animate()` 
  *
- * @experimental Animation support is experimental.
  */
 export interface AnimationPlayer {
+  /**
+   * Provides a callback to invoke when the animation finishes.
+   * @param fn The callback function.
+   * @see `finish()`
+   */
   onDone(fn: () => void): void;
+  /**
+   * Provides a callback to invoke when the animation starts.
+   * @param fn The callback function.
+   * @see `run()`
+   */
   onStart(fn: () => void): void;
+  /**
+   * Provides a callback to invoke after the animation is destroyed.
+   * @param fn The callback function.
+   * @see `destroy()`
+   * @see `beforeDestroy()`
+   */
   onDestroy(fn: () => void): void;
+  /**
+   * Initializes the animation.
+   */
   init(): void;
+  /**
+   * Reports whether the animation has started.
+   * @returns True if the animation has started, false otherwise.
+   */
   hasStarted(): boolean;
+  /**
+   * Runs the animation, invoking the `onStart()` callback.
+   */
   play(): void;
+  /**
+   * Pauses the animation.
+   */
   pause(): void;
+  /**
+   * Restarts the paused animation.
+   */
   restart(): void;
+  /**
+   * Ends the animation, invoking the `onDone()` callback.
+   */
   finish(): void;
+  /**
+   * Destroys the animation, after invoking the `beforeDestroy()` callback.
+   * Calls the `onDestroy()` callback when destruction is completed.
+   */
   destroy(): void;
+  /**
+   * Resets the animation to its initial state.
+   */
   reset(): void;
+  /**
+   * Sets the position of the animation.
+   * @param position A 0-based offset into the duration, in milliseconds.
+   */
   setPosition(position: any /** TODO #9100 */): void;
+  /**
+   * Reports the current position of the animation.
+   * @returns A 0-based offset into the duration, in milliseconds.
+   */
   getPosition(): number;
+  /**
+   * The parent of this player, if any.
+   */
   parentPlayer: AnimationPlayer|null;
+  /**
+   * The total run time of the animation, in milliseconds.
+   */
   readonly totalTime: number;
+  /**
+   * Provides a callback to invoke before the animation is destroyed.
+   */
   beforeDestroy?: () => any;
-  /** @internal */
+  /** @internal
+   * Internal
+   */
   triggerCallback?: (phaseName: string) => void;
-  /** @internal */
+  /** @internal
+   * Internal
+   */
   disabled?: boolean;
 }
 
 /**
- * @experimental Animation support is experimental.
+ * An empty programmatic controller for reusable animations.
+ * Used internally when animations are disabled, to avoid
+ * checking for the null case when an animation player is expected.
+ *
+ * @see `animate()`
+ * @see `AnimationPlayer`
+ * @see `GroupPlayer`
+ *
  */
 export class NoopAnimationPlayer implements AnimationPlayer {
   private _onDoneFns: Function[] = [];

tools/public_api_guard/animations/animations.d.ts

@@ -28,7 +28,6 @@ export interface AnimationAnimateRefMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
 }
 
-/** @experimental */
 export declare abstract class AnimationBuilder {
     abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory;
 }
@@ -44,7 +43,6 @@ export interface AnimationEvent {
     triggerName: string;
 }
 
-/** @experimental */
 export declare abstract class AnimationFactory {
     abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
 }
@@ -85,7 +83,6 @@ export declare interface AnimationOptions {
     };
 }
 
-/** @experimental */
 export interface AnimationPlayer {
     beforeDestroy?: () => any;
     parentPlayer: AnimationPlayer | null;
@@ -174,7 +171,6 @@ export declare function group(steps: AnimationMetadata[], options?: AnimationOpt
 
 export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata;
 
-/** @experimental */
 export declare class NoopAnimationPlayer implements AnimationPlayer {
     parentPlayer: AnimationPlayer | null;
     readonly totalTime: number;