From a577c9e1f484780e8798f0ed519e9c3ec8adda0b Mon Sep 17 00:00:00 2001
From: Judy Bogart <jbogart@gmail.com>
Date: Thu, 3 May 2018 10:54:51 -0700
Subject: [PATCH] docs: edit api doc comments for new template and style
 (#23682)

PR Close #23682
---
 packages/animations/src/animation_metadata.ts | 1309 +++++++++--------
 .../animations/animations.d.ts                |   32 -
 2 files changed, 666 insertions(+), 675 deletions(-)

diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts
index cd0e463c06..c2c4afad43 100755
--- a/packages/animations/src/animation_metadata.ts
+++ b/packages/animations/src/animation_metadata.ts
@@ -5,275 +5,436 @@
  * 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
  */
+
+/**
+ * Represents a set of CSS styles for use in an animation style.
+ */
 export interface ɵStyleData { [key: string]: string|number; }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are created internally
- * within the Angular animation DSL.
- *
- * @experimental Animation support is experimental.
- */
+* Represents animation-step timing parameters for an animation step.  
+* @see `animate()`
+*/
 export declare type AnimateTimings = {
+  /**
+   * The full duration of an animation step. A number and optional time unit,
+   * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
+   * The default unit is milliseconds.
+   */
   duration: number,
+  /**
+   * The delay in applying an animation step. A number and optional time unit.
+   * The default unit is milliseconds.
+   */
   delay: number,
+  /**
+   * An easing style that controls how an animations step accelerates
+   * and decelerates during its run time. An easing function such as `cubic-bezier()`,
+   * or one of the following constants:
+   * - `ease-in`
+   * - `ease-out`
+   * - `ease-in-and-out`
+   */
   easing: string | null
 };
 
 /**
- * `AnimationOptions` represents options that can be passed into most animation DSL methods.
- * When options are provided, the delay value of an animation can be changed and animation input
- * parameters can be passed in to change styling and timing data when an animation is started.
+ * @description Options that control animation styling and timing.
+ * The following animation functions accept `AnimationOptions` data:
  *
- * The following animation DSL functions are able to accept animation option data:
+ * - `transition`
+ * - `sequence`
+ * - `group()`
+ * - `query()`
+ * - `animation()`
+ * - `useAnimation()`
+ * - `animateChild()`
  *
- * - {@link transition transition()}
- * - {@link sequence sequence()}
- * - {@link group group()}
- * - {@link query query()}
- * - {@link animation animation()}
- * - {@link useAnimation useAnimation()}
- * - {@link animateChild animateChild()}
- *
- * Programmatic animations built using {@link AnimationBuilder the AnimationBuilder service} also
- * make use of AnimationOptions.
- *
- * @experimental Animation support is experimental.
+ * Programmatic animations built using the `AnimationBuilder` service also
+ * make use of `AnimationOptions`.
  */
 export declare interface AnimationOptions {
+  /**
+   * Sets a time-delay for initiating an animation action.
+   * A number and optional time unit, such as "1s" or "10ms" for one second
+   * and 10 milliseconds, respectively.The default unit is milliseconds.
+   * Default value is 0, meaning no delay.
+   */
   delay?: number|string;
+  /**
+  * A set of developer-defined parameters that modify styling and timing
+  * when an animation action starts. An array of key-value pairs, where the provided value
+  * is used as a default.
+  */
   params?: {[name: string]: any};
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are created internally
- * within the Angular animation DSL when {@link animateChild animateChild()} is used.
+ * Adds duration options to control animation styling and timing for a child animation.
  *
- * @experimental Animation support is experimental.
+ * @see `animateChild()`
  */
 export declare interface AnimateChildOptions extends AnimationOptions { duration?: number|string; }
 
 /**
- * Metadata representing the entry of animations. Usages of this enum are created
- * each time an animation DSL function is used.
+ * @description Constants for the categories of parameters that can be defined for animations.
  *
- * @experimental Animation support is experimental.
+ * A corresponding function defines a set of parameters for each category, and
+ * collects them into a corresponding `AnimationMetadata` object.
  */
 export const enum AnimationMetadataType {
+  /**
+   * Associates a named animation state with a set of CSS styles.
+   * See `state()`
+   */
   State = 0,
+  /**
+   * Data for a transition from one animation state to another.
+   * See `transition()`
+   */
   Transition = 1,
+  /**
+   * Contains a set of animation steps.
+   * See `sequence()`
+   */
   Sequence = 2,
+  /**
+   * Contains a set of animation steps.
+   * See `group()`
+   */
   Group = 3,
+  /**
+   * Contains an animation step.
+   * See `animate()`
+   */
   Animate = 4,
+  /**
+   * Contains a set of animation steps.
+   * See `keyframes()`
+   */
   Keyframes = 5,
+  /**
+   * Contains a set of CSS property-value pairs into a named style.
+   * See `style()`
+   */
   Style = 6,
+  /**
+   * Associates an animation with an entry trigger that can be attached to an element.
+   * See `trigger()`
+   */
   Trigger = 7,
+  /**
+   * Contains a re-usable animation.
+   * See `animation()`
+   */
   Reference = 8,
+  /**
+   * Contains data to use in executing child animations returned by a query.
+   * See `animateChild()`
+   */
   AnimateChild = 9,
+  /**
+   * Contains animation parameters for a re-usable animation.
+   * See `useAnimation()`
+   */
   AnimateRef = 10,
+  /**
+   * Contains child-animation query data.
+   * See `query()`
+   */
   Query = 11,
+  /**
+   * Contains data for staggering an animation sequence.
+   * See `stagger()`
+   */
   Stagger = 12
 }
 
 /**
- * @experimental Animation support is experimental.
+ * Specifies automatic styling.
  */
 export const AUTO_STYLE = '*';
 
 /**
- * @experimental Animation support is experimental.
+ * Base for animation data structures.
  */
 export interface AnimationMetadata { type: AnimationMetadataType; }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link trigger trigger animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Contains an animation trigger. Instantiated and returned by the
+ * `trigger()` function.
  */
 export interface AnimationTriggerMetadata extends AnimationMetadata {
+  /**
+    * The trigger name, used to associate it with an element. Unique within the component.
+    */
   name: string;
+  /**
+   * An animation definition object, containing an array of state and transition declarations.
+   */
   definitions: AnimationMetadata[];
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: {params?: {[name: string]: any}}|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link state state animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation state by associating a state name with a set of CSS styles.
+ * Instantiated and returned by the `state()` function.
  */
 export interface AnimationStateMetadata extends AnimationMetadata {
+  /**
+   * The state name, unique within the component.
+   */
   name: string;
+  /**
+   *  The CSS styles associated with this state.
+   */
   styles: AnimationStyleMetadata;
+  /**
+   * An options object containing
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation.
+   */
   options?: {params: {[name: string]: any}};
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link transition transition animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation transition. Instantiated and returned by the
+ * `transition()` function.
  */
 export interface AnimationTransitionMetadata extends AnimationMetadata {
+  /**
+   * An expression that describes a state change.
+   */
   expr: string|
       ((fromState: string, toState: string, element?: any,
         params?: {[key: string]: any}) => boolean);
+  /**
+   * One or more animation objects to which this transition applies.
+   */
   animation: AnimationMetadata|AnimationMetadata[];
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * @experimental Animation support is experimental.
+ * Encapsulates a reusable animation, which is a collection of individual animation steps.
+ * Instantiated and returned by the `animation()` function, and
+ * passed to the `useAnimation()` function.
  */
 export interface AnimationReferenceMetadata extends AnimationMetadata {
+  /**
+   *  One or more animation step objects.
+   */
   animation: AnimationMetadata|AnimationMetadata[];
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * @experimental Animation support is experimental.
+ * Encapsulates an animation query. Instantiated and returned by
+ * the `query()` function.
  */
 export interface AnimationQueryMetadata extends AnimationMetadata {
+  /**
+   *  The CSS selector for this query.
+   */
   selector: string;
+  /**
+   * One or more animation step objects.
+   */
   animation: AnimationMetadata|AnimationMetadata[];
+  /**
+   * A query options object.
+   */
   options: AnimationQueryOptions|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link keyframes keyframes animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a keyframes sequence. Instantiated and returned by
+ * the `keyframes()` function.
  */
 export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
+  /**
+   * An array of animation styles.
+   */
   steps: AnimationStyleMetadata[];
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link style style animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation style. Instantiated and returned by
+ * the `style()` function.
  */
 export interface AnimationStyleMetadata extends AnimationMetadata {
+  /**
+   * A set of CSS style properties.
+   */
   styles: '*'|{[key: string]: string | number}|Array<{[key: string]: string | number}|'*'>;
+  /**
+   * A percentage of the total animate time at which the style is to be applied.
+   */
   offset: number|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link animate animate animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation step. Instantiated and returned by
+ * the `animate()` function.
  */
 export interface AnimationAnimateMetadata extends AnimationMetadata {
+  /**
+   * The timing data for the step.
+   */
   timings: string|number|AnimateTimings;
+  /**
+   * A set of styles used in the step.
+   */
   styles: AnimationStyleMetadata|AnimationKeyframesSequenceMetadata|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link animateChild animateChild animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a child animation, that can be run explicitly when the parent is run.
+ * Instantiated and returned by the `animateChild` function.
  */
 export interface AnimationAnimateChildMetadata extends AnimationMetadata {
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link useAnimation useAnimation animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a reusable animation.
+ * Instantiated and returned by the `useAnimation()` function.
  */
 export interface AnimationAnimateRefMetadata extends AnimationMetadata {
+  /**
+   * An animation reference object.
+   */
   animation: AnimationReferenceMetadata;
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link sequence sequence animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation sequence.
+ * Instantiated and returned by the `sequence()` function.
  */
 export interface AnimationSequenceMetadata extends AnimationMetadata {
+  /**
+   *  An array of animation step objects.
+   */
   steps: AnimationMetadata[];
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link group group animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation group.
+ * Instantiated and returned by the `group()` function.
  */
 export interface AnimationGroupMetadata extends AnimationMetadata {
+  /**
+   * One or more animation or style steps that form this group.
+   */
   steps: AnimationMetadata[];
+  /**
+   * An options object containing a delay and
+   * developer-defined parameters that provide styling defaults and
+   * can be overridden on invocation. Default delay is 0.
+   */
   options: AnimationOptions|null;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link query query animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates animation query options.
+ * Passed to the `query()` function.
  */
 export declare interface AnimationQueryOptions extends AnimationOptions {
+  /**
+   * True if this query is optional, false if it is required. Default is false.
+   * A required query throws an error if no elements are retrieved when
+   * the query is executed. An optional query does not.
+   *
+   */
   optional?: boolean;
   /**
-   * Used to limit the total amount of results from the start of the query list.
-   *
-   * If a negative value is provided then the queried results will be limited from the
-   * end of the query list towards the beginning (e.g. if `limit: -3` is used then the
-   * final 3 (or less) queried results will be used for the animation).
+   * A maximum total number of results to return from the query.
+   * If negative, results are limited from the end of the query list towards the beginning.
+   * By default, results are not limited.
    */
   limit?: number;
 }
 
 /**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link stagger stagger animation function} is called.
- *
-* @experimental Animation support is experimental.
-*/
+ * Encapsulates parameters for staggering the start times of a set of animation steps.
+ * Instantiated and returned by the `stagger()` function.
+ **/
 export interface AnimationStaggerMetadata extends AnimationMetadata {
+  /**
+   * The timing data for the steps.
+   */
   timings: string|number;
+  /**
+   * One or more animation steps.
+   */
   animation: AnimationMetadata|AnimationMetadata[];
 }
 
 /**
- * `trigger` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the
- * {@link Component#animations component animations metadata page} to gain a better
- * understanding of how animations in Angular are used.
- *
- * `trigger` Creates an animation trigger which will a list of {@link state state} and
- * {@link transition transition} entries that will be evaluated when the expression
+ * Creates a named animation trigger, containing a  list of `state()`
+ * and `transition()` entries to be evaluated when the expression
  * bound to the trigger changes.
  *
- * Triggers are registered within the component annotation data under the
- * {@link Component#animations animations section}. An animation trigger can be placed on an element
- * within a template by referencing the name of the trigger followed by the expression value that
- the
- * trigger is bound to (in the form of `[@triggerName]="expression"`.
+ * @param name An identifying string.
+ * @param definitions  An animation definition object, containing an array of `state()`
+ * and `transition()` declarations.
  *
- * Animation trigger bindings strigify values and then match the previous and current values against
- * any linked transitions. If a boolean value is provided into the trigger binding then it will both
- * be represented as `1` or `true` and `0` or `false` for a true and false boolean values
- * respectively.
+ * @return An object that encapsulates the trigger data.
+ * 
+ * @usageNotes
+ * Define an animation trigger in the `animations` section of `@Component` metadata.
+ * In the template, reference the trigger by name and bind it to a trigger expression that
+ * evaluates to a defined animation state, using the following format:
  *
- * ### Usage
+ * `[@triggerName]="expression"`
  *
- * `trigger` will create an animation trigger reference based on the provided `name` value. The
- * provided `animation` value is expected to be an array consisting of {@link state state} and
- * {@link transition transition} declarations.
+ * Animation trigger bindings convert all values to strings, and then match the 
+ * previous and current values against any linked transitions.
+ * Booleans can be specified as `1` or `true` and `0` or `false`.
+ *
+ * ### Usage Example
+ * 
+ * The following example creates an animation trigger reference based on the provided
+ * name value.
+ * The provided animation value is expected to be an array consisting of state and
+ * transition declarations.
  *
  * ```typescript
  * @Component({
- *   selector: 'my-component',
- *   templateUrl: 'my-component-tpl.html',
+ *   selector: "my-component",
+ *   templateUrl: "my-component-tpl.html",
  *   animations: [
  *     trigger("myAnimationTrigger", [
  *       state(...),
@@ -288,8 +449,8 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
  * }
  * ```
  *
- * The template associated with this component will make use of the `myAnimationTrigger` animation
- trigger by binding to an element within its template code.
+ * The template associated with this component makes use of the defined trigger
+ * by binding to an element within its template code.
  *
  * ```html
  * <!-- somewhere inside of my-component-tpl.html -->
@@ -300,9 +461,8 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
  * The `transition` animation method also supports reading an inline function which can decide
  * if its associated animation should be run.
  *
- * ```
- * // this method will be run each time the `myAnimationTrigger`
- * // trigger value changes...
+ * ```typescript
+ * // this method is run each time the `myAnimationTrigger` trigger value changes.
  * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
  string]: any}): boolean {
  *   // notice that `element` and `params` are also available here
@@ -325,18 +485,16 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
  * }
  * ```
  *
- * The inline method will be run each time the trigger
- * value changes
+ * ### Disabling Animations
+ * When true, the special animation control binding `@.disabled` binding prevents 
+ * all animations from rendering.
+ * Place the  `@.disabled` binding on an element to disable
+ * animations on the element itself, as well as any inner animation triggers
+ * within the element.
  *
- * ## Disable Animations
- * A special animation control binding called `@.disabled` can be placed on an element which will
- then disable animations for any inner animation triggers situated within the element as well as
- any animations on the element itself.
+ * The following example shows how to use this feature:
  *
- * When true, the `@.disabled` binding will prevent all animations from rendering. The example
- below shows how to use this feature:
- *
- * ```ts
+ * ```typescript
  * @Component({
  *   selector: 'my-component',
  *   template: `
@@ -356,19 +514,16 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
  * }
  * ```
  *
- * The `@childAnimation` trigger will not animate because `@.disabled` prevents it from happening
- (when true).
+ * When `@.disabled` is true, it prevents the `@childAnimation` trigger from animating,
+ * along with any inner animations.
  *
- * Note that `@.disabled` will only disable all animations (this means any animations running on
- * the same element will also be disabled).
+ * ### Disable animations application-wide
+ * When an area of the template is set to have animations disabled, 
+ * **all** inner components have their animations disabled as well.
+ * This means that you can disable all animations for an app
+ * by placing a host binding set on `@.disabled` on the topmost Angular component.
  *
- * ### Disabling Animations Application-wide
- * When an area of the template is set to have animations disabled, **all** inner components will
- also have their animations disabled as well. This means that all animations for an angular
- application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular
- component.
- *
- * ```ts
+ * ```typescript
  * import {Component, HostBinding} from '@angular/core';
  *
  * @Component({
@@ -381,19 +536,17 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
  * }
  * ```
  *
- * ### What about animations that us `query()` and `animateChild()`?
- * Despite inner animations being disabled, a parent animation can {@link query query} for inner
- elements located in disabled areas of the template and still animate them as it sees fit. This is
- also the case for when a sub animation is queried by a parent and then later animated using {@link
- animateChild animateChild}.
-
- * ### Detecting when an animation is disabled
- * If a region of the DOM (or the entire application) has its animations disabled, then animation
- * trigger callbacks will still fire just as normal (only for zero seconds).
+ * ### Overriding disablement of inner animations
+ * Despite inner animations being disabled, a parent animation can `query()`
+ * for inner elements located in disabled areas of the template and still animate 
+ * them if needed. This is also the case for when a sub animation is 
+ * queried by a parent and then later animated using `animateChild()`.
  *
- * When a trigger callback fires it will provide an instance of an {@link AnimationEvent}. If
- animations
- * are disabled then the `.disabled` flag on the event will be true.
+ * ### Detecting when an animation is disabled
+ * If a region of the DOM (or the entire application) has its animations disabled, the animation
+ * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides
+ * an instance of an `AnimationEvent`. If animations are disabled,
+ * the `.disabled` flag on the event is true.
  *
  * @experimental Animation support is experimental.
  */
@@ -402,49 +555,60 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati
 }
 
 /**
- * `animate` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines an animation step that combines styling information with timing information.
  *
- * `animate` specifies an animation step that will apply the provided `styles` data for a given
- * amount of time based on the provided `timing` expression value. Calls to `animate` are expected
- * to be used within {@link sequence an animation sequence}, {@link group group}, or {@link
- * transition transition}.
+ * @param timings Sets `AnimateTimings` for the parent animation.
+ * A string in the format "duration [delay] [easing]".
+ *  - Duration and delay are expressed as a number and optional time unit,
+ * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
+ * The default unit is milliseconds.
+ *  - The easing value controls how the animation accelerates and decelerates
+ * during its runtime. Value is one of  `ease`, `ease-in`, `ease-out`,
+ * `ease-in-out`, or a `cubic-bezier()` function call.
+ * If not supplied, no easing is applied.
  *
- * ### Usage
+ * For example, the string "1s 100ms ease-out" specifies a duration of
+ * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style,
+ * which decelerates near the end of the duration.
+ * @param styles Sets AnimationStyles for the parent animation.
+ * A function call to either `style()` or `keyframes()`
+ * that returns a collection of CSS style entries to be applied to the parent animation.
+ * When null, uses the styles from the destination state.
+ * This is useful when describing an animation step that will complete an animation;
+ * see "Animating to the final state" in `transitions()`.
+ * @returns An object that encapsulates the animation step.
  *
- * The `animate` function accepts two input parameters: `timing` and `styles`:
+ * @usageNotes
+ * Call within an animation `sequence()`, `group()`, or
+ * `transition()` call to specify an animation step
+ * that applies given style data to the parent animation for a given amount of time.
  *
- * - `timing` is a string based value that can be a combination of a duration with optional delay
- * and easing values. The format for the expression breaks down to `duration delay easing`
- * (therefore a value such as `1s 100ms ease-out` will be parse itself into `duration=1000,
- * delay=100, easing=ease-out`. If a numeric value is provided then that will be used as the
- * `duration` value in millisecond form.
- * - `styles` is the style input data which can either be a call to {@link style style} or {@link
- * keyframes keyframes}. If left empty then the styles from the destination state will be collected
- * and used (this is useful when describing an animation step that will complete an animation by
- * {@link transition#the-final-animate-call animating to the final state}).
+ * ### Syntax Examples
+ * **Timing examples**
  *
+ * The following examples show various `timings` specifications.
+ * - `animate(500)` : Duration is 500 milliseconds.
+ * - `animate("1s")` : Duration is 1000 milliseconds.
+ * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds.
+ * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in.
+ * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10
+ * milliseconds, easing according to a bezier curve.
+ *
+ * **Style examples**
+ *
+ * The following example calls `style()` to set a single CSS style.
  * ```typescript
- * // various functions for specifying timing data
- * animate(500, style(...))
- * animate("1s", style(...))
- * animate("100ms 0.5s", style(...))
- * animate("5s ease", style(...))
- * animate("5s 10ms cubic-bezier(.17,.67,.88,.1)", style(...))
- *
- * // either style() of keyframes() can be used
  * animate(500, style({ background: "red" }))
- * animate(500, keyframes([
+ * ```
+ * The following example calls `keyframes()` to set a CSS style
+ * to different values for successive keyframes.
+ * ```typescript
+ * animate(500, keyframes(
+ *  [
  *   style({ background: "blue" })),
  *   style({ background: "red" }))
- * ])
+ *  ])
  * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
  */
 export function animate(
     timings: string | number, styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata |
@@ -453,25 +617,15 @@ export function animate(
 }
 
 /**
- * `group` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
- *
- * `group` specifies a list of animation steps that are all run in parallel. Grouped animations are
- * useful when a series of styles must be animated/closed off at different starting/ending times.
- *
- * The `group` function can either be used within a {@link sequence sequence} or a {@link transition
- * transition} and it will only continue to the next instruction once all of the inner animation
- * steps have completed.
- *
- * ### Usage
- *
- * The `steps` data that is passed into the `group` animation function can either consist of {@link
- * style style} or {@link animate animate} function calls. Each call to `style()` or `animate()`
- * within a group will be executed instantly (use {@link keyframes keyframes} or a {@link
- * animate#usage animate() with a delay value} to offset styles to be applied at a later time).
+ * @description Defines a list of animation steps to be run in parallel.
  *
+ * @param steps An array of animation step objects.
+ * - When steps are defined by `style()` or `animate()`
+ * function calls, each call within the group is executed instantly.
+ * - To specify offset styles to be applied at a later time, define steps with
+ * `keyframes()`, or use `animate()` calls with a delay value.
+ * For example:
+ * 
  * ```typescript
  * group([
  *   animate("1s", { background: "black" }))
@@ -479,9 +633,19 @@ export function animate(
  * ])
  * ```
  *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ * @param options An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation.
  *
- * @experimental Animation support is experimental.
+ * @return An object that encapsulates the group data.
+ *
+ * @usageNotes
+ * Grouped animations are useful when a series of styles must be 
+ * animated at different starting times and closed off at different ending times.
+ *
+ * When called within a `sequence()` or a
+ * `transition()` call, does not continue to the next
+ * instruction until all of the inner animation steps have completed.
  */
 export function group(
     steps: AnimationMetadata[], options: AnimationOptions | null = null): AnimationGroupMetadata {
@@ -489,27 +653,12 @@ export function group(
 }
 
 /**
- * `sequence` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines a list of animation steps to be run sequentially, one by one.
  *
- * `sequence` Specifies a list of animation steps that are run one by one. (`sequence` is used by
- * default when an array is passed as animation data into {@link transition transition}.)
- *
- * The `sequence` function can either be used within a {@link group group} or a {@link transition
- * transition} and it will only continue to the next instruction once each of the inner animation
- * steps have completed.
- *
- * To perform animation styling in parallel with other animation steps then have a look at the
- * {@link group group} animation function.
- *
- * ### Usage
- *
- * The `steps` data that is passed into the `sequence` animation function can either consist of
- * {@link style style} or {@link animate animate} function calls. A call to `style()` will apply the
- * provided styling data immediately while a call to `animate()` will apply its styling data over a
- * given time depending on its timing data.
+ * @param steps An array of animation step objects.
+ * - Steps defined by `style()` calls apply the styling data immediately.
+ * - Steps defined by `animate()` calls apply the styling data over time
+ *   as specified by the timing data.
  *
  * ```typescript
  * sequence([
@@ -518,57 +667,65 @@ export function group(
  * ])
  * ```
  *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ * @param options An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation.
  *
- * @experimental Animation support is experimental.
- */
+ * @return An object that encapsulates the sequence data.
+ *
+ * @usageNotes
+ * When you pass an array of steps to a
+ * `transition()` call, the steps run sequentially by default.
+ * Compare this to the `group()` call, which runs animation steps in parallel.
+ *
+ * When a sequence is used within a `group()` or a `transition()` call,
+ * execution continues to the next instruction only after each of the inner animation
+ * steps have completed.
+ *
+ **/
 export function sequence(steps: AnimationMetadata[], options: AnimationOptions | null = null):
     AnimationSequenceMetadata {
   return {type: AnimationMetadataType.Sequence, steps, options};
 }
 
 /**
- * `style` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Declares a key/value object containing CSS properties/styles that
+ * can then be used for an animation `state`, within an animation `sequence`,
+ * or as styling data for calls to `animate()` and `keyframes()`.
  *
- * `style` declares a key/value object containing CSS properties/styles that can then be used for
- * {@link state animation states}, within an {@link sequence animation sequence}, or as styling data
- * for both {@link animate animate} and {@link keyframes keyframes}.
+ * @param tokens A set of CSS styles or HTML styles associated with an animation state.
+ * The value can be any of the following:
+ * - A key-value style pair associating a CSS property with a value.
+ * - An array of key-value style pairs.
+ * - An asterisk (*), to use auto-styling, where styles are derived from the element
+ * being animated and applied to the animation when it starts.
  *
- * ### Usage
+ * Auto-styling can be used to define a state that depends on layout or other 
+ * environmental factors.
  *
- * `style` takes in a key/value string map as data and expects one or more CSS property/value pairs
- * to be defined.
+ * @return An object that encapsulates the style data.
  *
+ * @usageNotes
+ * The following examples create animation styles that collect a set of
+ * CSS property values:
+ * 
  * ```typescript
- * // string values are used for css properties
+ * // string values for CSS properties
  * style({ background: "red", color: "blue" })
  *
- * // numerical (pixel) values are also supported
+ * // numerical pixel values
  * style({ width: 100, height: 0 })
  * ```
  *
- * #### Auto-styles (using `*`)
+ * The following example uses auto-styling to allow a component to animate from
+ * a height of 0 up to the height of the parent element:
  *
- * When an asterix (`*`) character is used as a value then it will be detected from the element
- * being animated and applied as animation data when the animation starts.
- *
- * This feature proves useful for a state depending on layout and/or environment factors; in such
- * cases the styles are calculated just before the animation starts.
- *
- * ```typescript
- * // the steps below will animate from 0 to the
- * // actual height of the element
+ * ```
  * style({ height: 0 }),
  * animate("1s", style({ height: "*" }))
  * ```
  *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ **/
 export function style(
     tokens: '*' | {[key: string]: string | number} |
     Array<'*'|{[key: string]: string | number}>): AnimationStyleMetadata {
@@ -576,53 +733,32 @@ export function style(
 }
 
 /**
- * `state` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Declares an animation state within a trigger attached to an element.
  *
- * `state` declares an animation state within the given trigger. When a state is active within a
- * component then its associated styles will persist on the element that the trigger is attached to
- * (even when the animation ends).
+ * @param name One or more names for the defined state in a comma-separated string.
+ * The following reserved state names can be supplied to define a style for specific use
+ * cases:
  *
- * To animate between states, have a look at the animation {@link transition transition} DSL
- * function. To register states to an animation trigger please have a look at the {@link trigger
- * trigger} function.
+ * - `void` You can associate styles with this name to be used when
+ * the element is detached from the application. For example, when an `ngIf` evaluates
+ * to false, the state of the associated element is void.
+ *  - `*` (asterisk) Indicates the default state. You can associate styles with this name
+ * to be used as the fallback when the state that is being animated is not declared
+ * within the trigger.
  *
- * #### The `void` state
+ * @param styles A set of CSS styles associated with this state, created using the
+ * `style()` function.
+ * This set of styles persists on the element once the state has been reached.
+ * @param options Parameters that can be passed to the state when it is invoked.
+ * 0 or more key-value pairs.
+ * @return An object that encapsulates the new state data.
  *
- * The `void` state value is a reserved word that angular uses to determine when the element is not
- * apart of the application anymore (e.g. when an `ngIf` evaluates to false then the state of the
- * associated element is void).
- *
- * #### The `*` (default) state
- *
- * The `*` state (when styled) is a fallback state that will be used if the state that is being
- * animated is not declared within the trigger.
- *
- * ### Usage
- *
- * `state` will declare an animation state with its associated styles
- * within the given trigger.
- *
- * - `stateNameExpr` can be one or more state names separated by commas.
- * - `styles` refers to the {@link style styling data} that will be persisted on the element once
- * the state has been reached.
- *
- * ```typescript
- * // "void" is a reserved name for a state and is used to represent
- * // the state in which an element is detached from from the application.
- * state("void", style({ height: 0 }))
- *
- * // user-defined states
- * state("closed", style({ height: 0 }))
- * state("open, visible", style({ height: "*" }))
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ * @usageNotes
+ * Use the `trigger()` function to register states to an animation trigger.
+ * Use the `transition()` function to animate between states.
+ * When a state is active within a component, its associated styles persist on the element,
+ * even when the animation ends.
+ **/
 export function state(
     name: string, styles: AnimationStyleMetadata,
     options?: {params: {[name: string]: any}}): AnimationStateMetadata {
@@ -630,26 +766,28 @@ export function state(
 }
 
 /**
- * `keyframes` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines a set of animation styles, associating each style with an optional `offset` value.
  *
- * `keyframes` specifies a collection of {@link style style} entries each optionally characterized
- * by an `offset` value.
+ * @param steps A set of animation styles with optional offset data.
+ * The optional `offset` value for a style specifies a percentage of the total animation
+ * time at which that style is applied.
+ * @returns An object that encapsulates the keyframes data.
+ *
+ * @usageNotes
+ * Use with the `animate()` call. Instead of applying animations
+ * from the current state
+ * to the destination state, keyframes describe how each style entry is applied and at what point
+ * within the animation arc.
+ * Compare [CSS Keyframe Animations](https://www.w3schools.com/css/css3_animations.asp).
  *
  * ### Usage
  *
- * The `keyframes` animation function is designed to be used alongside the {@link animate animate}
- * animation function. Instead of applying animations from where they are currently to their
- * destination, keyframes can describe how each style entry is applied and at what point within the
- * animation arc (much like CSS Keyframe Animations do).
- *
- * For each `style()` entry an `offset` value can be set. Doing so allows to specify at what
- * percentage of the animate time the styles will be applied.
+ * In the following example, the offset values describe
+ * when each `backgroundColor` value is applied. The color is red at the start, and changes to
+ * blue when 20% of the total time has elapsed.
  *
  * ```typescript
- * // the provided offset values describe when each backgroundColor value is applied.
+ * // the provided offset values
  * animate("5s", keyframes([
  *   style({ backgroundColor: "red", offset: 0 }),
  *   style({ backgroundColor: "blue", offset: 0.2 }),
@@ -658,8 +796,8 @@ export function state(
  * ]))
  * ```
  *
- * Alternatively, if there are no `offset` values used within the style entries then the offsets
- * will be calculated automatically.
+ * If there are no `offset` values specified in the style entries, the offsets
+ * are calculated automatically.
  *
  * ```typescript
  * animate("5s", keyframes([
@@ -668,127 +806,170 @@ export function state(
  *   style({ backgroundColor: "orange" }) // offset = 0.66
  *   style({ backgroundColor: "black" }) // offset = 1
  * ]))
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
+ *```
  */
 export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata {
   return {type: AnimationMetadataType.Keyframes, steps};
 }
 
 /**
- * `transition` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. If this information is new, please navigate to the {@link
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
- *
- * `transition` declares the {@link sequence sequence of animation steps} that will be run when the
- * provided `stateChangeExpr` value is satisfied. The `stateChangeExpr` consists of a `state1 =>
- * state2` which consists of two known states (use an asterix (`*`) to refer to a dynamic starting
- * and/or ending state).
- *
- * A function can also be provided as the `stateChangeExpr` argument for a transition and this
- * function will be executed each time a state change occurs. If the value returned within the
- * function is true then the associated animation will be run.
- *
- * Animation transitions are placed within an {@link trigger animation trigger}. For an transition
- * to animate to a state value and persist its styles then one or more {@link state animation
- * states} is expected to be defined.
- *
- * ### Usage
- *
- * An animation transition is kicked off the `stateChangeExpr` predicate evaluates to true based on
- * what the previous state is and what the current state has become. In other words, if a transition
- * is defined that matches the old/current state criteria then the associated animation will be
+ * Declares an animation transition as a sequence of animation steps to run when a given
+ * condition is satisfied. The condition is a Boolean expression or function that compares
+ * the previous and current animation states, and returns true if this transition should occur.
+ * When the state criteria of a defined transition are met, the associated animation is
  * triggered.
  *
- * ```typescript
- * // all transition/state changes are defined within an animation trigger
- * trigger("myAnimationTrigger", [
- *   // if a state is defined then its styles will be persisted when the
- *   // animation has fully completed itself
- *   state("on", style({ background: "green" })),
- *   state("off", style({ background: "grey" })),
+ * @param stateChangeExpr A Boolean expression or function that compares the previous and current
+ * animation states, and returns true if this transition should occur. Note that  "true" and "false"
+ * match 1 and 0, respectively. An expression is evaluated each time a state change occurs in the
+ * animation trigger element.
+ * The animation steps run when the expression evaluates to true.
  *
- *   // a transition animation that will be kicked off when the state value
- *   // bound to "myAnimationTrigger" changes from "on" to "off"
- *   transition("on => off", animate(500)),
+ * - A state-change string takes the form "state1 => state2", where each side is a defined animation
+ * state, or an asterix (*) to refer to a dynamic start or end state.
+ *   - The expression string can contain multiple comma-separated statements;
+ * for example "state1 => state2, state3 => state4".
+ *   - Special values `:enter` and `:leave` initiate a transition on the entry and exit states,
+ * equivalent to  "void => *"  and "* => void".
+ *   - Special values `:increment` and `:decrement` initiate a transition when a numeric value has
+ * increased or decreased in value.
+ * - A function is executed each time a state change occurs in the animation trigger element.
+ * The animation steps run when the function returns true.
  *
- *   // it is also possible to do run the same animation for both directions
- *   transition("on <=> off", animate(500)),
+ * @param steps One or more animation objects, as returned by the `animate()` or
+ * `sequence()` function, that form a transformation from one state to another.
+ * A sequence is used by default when you pass an array.
+ * @param options An options object that can contain a delay value for the start of the animation,
+ * and additional developer-defined parameters. Provided values for additional parameters are used
+ * as defaults, and override values can be passed to the caller on invocation.
+ * @returns An object that encapsulates the transition data.
  *
- *   // or to define multiple states pairs separated by commas
- *   transition("on => off, off => void", animate(500)),
+ * @usageNotes
+ * The template associated with a component binds an animation trigger to an element.
  *
- *   // this is a catch-all state change for when an element is inserted into
- *   // the page and the destination state is unknown
- *   transition("void => *", [
- *     style({ opacity: 0 }),
- *     animate(500)
- *   ]),
- *
- *   // this will capture a state change between any states
- *   transition("* => *", animate("1s 0s")),
- *
- *   // you can also go full out and include a function
- *   transition((fromState, toState) => {
- *     // when `true` then it will allow the animation below to be invoked
- *     return fromState == "off" && toState == "on";
- *   }, animate("1s 0s"))
- * ])
- * ```
- *
- * The template associated with this component will make use of the `myAnimationTrigger` animation
- * trigger by binding to an element within its template code.
- *
- * ```html
+ * ```HTML
  * <!-- somewhere inside of my-component-tpl.html -->
  * <div [@myAnimationTrigger]="myStatusExp">...</div>
  * ```
  *
- * #### The final `animate` call
- *
- * If the final step within the transition steps is a call to `animate()` that **only** uses a
- * timing value with **no style data** then it will be automatically used as the final animation arc
- * for the element to animate itself to the final state. This involves an automatic mix of
- * adding/removing CSS styles so that the element will be in the exact state it should be for the
- * applied state to be presented correctly.
+ * All transitions are defined within an animation trigger,
+ * along with named states that the transitions change to and from.
  *
+ * ```typescript
+ * trigger("myAnimationTrigger", [
+ *  // define states
+ *  state("on", style({ background: "green" })),
+ *  state("off", style({ background: "grey" })),
+ *  ...]
  * ```
- * // start off by hiding the element, but make sure that it animates properly to whatever state
- * // is currently active for "myAnimationTrigger"
+ *
+ * Note that when you call the `sequence()` function within a `group()`
+ * or a `transition()` call, execution does not continue to the next instruction
+ * until each of the inner animation steps have completed.
+ *
+ * ### Syntax examples
+ *
+ * The following examples define transitions between the two defined states (and default states),
+ * using various options:
+ *
+ * ```typescript
+ * // Transition occurs when the state value
+ * // bound to "myAnimationTrigger" changes from "on" to "off"
+ * transition("on => off", animate(500))
+ * // Run the same animation for both directions
+ * transition("on <=> off", animate(500))
+ * // Define multiple state-change pairs separated by commas
+ * transition("on => off, off => void", animate(500))
+ * ```
+ *
+ * ### Special values for state-change expressions
+ *
+ * - Catch-all state change for when an element is inserted into the page and the
+ * destination state is unknown:
+ *
+ * ```typescript
  * transition("void => *", [
- *   style({ opacity: 0 }),
- *   animate(500)
- * ])
+ *  style({ opacity: 0 }),
+ *  animate(500)
+ *  ])
  * ```
  *
- * ### Using :enter and :leave
+ * - Capture a state change between any states:
  *
- * Given that enter (insertion) and leave (removal) animations are so common, the `transition`
- * function accepts both `:enter` and `:leave` values which are aliases for the `void => *` and `*
- * => void` state changes.
+ *  `transition("* => *", animate("1s 0s"))`
  *
- * ```
+ * - Entry and exit transitions:
+ *
+ * ```typescript
  * transition(":enter", [
  *   style({ opacity: 0 }),
  *   animate(500, style({ opacity: 1 }))
- * ]),
+ *   ]),
  * transition(":leave", [
  *   animate(500, style({ opacity: 0 }))
- * ])
+ *   ])
  * ```
  *
- * ### Boolean values
- * if a trigger binding value is a boolean value then it can be matched using a transition
- * expression that compares `true` and `false` or `1` and `0`.
+ * - Use `:increment` and `:decrement` to initiate transitions:
+ *
+ * ```typescript
+ * transition(":increment", group([
+ *  query(':enter', [
+ *     style({ left: '100%' }),
+ *     animate('0.5s ease-out', style('*'))
+ *   ]),
+ *  query(':leave', [
+ *     animate('0.5s ease-out', style({ left: '-100%' }))
+ *  ])
+ * ]))
+ *
+ * transition(":decrement", group([
+ *  query(':enter', [
+ *     style({ left: '100%' }),
+ *     animate('0.5s ease-out', style('*'))
+ *   ]),
+ *  query(':leave', [
+ *     animate('0.5s ease-out', style({ left: '-100%' }))
+ *  ])
+ * ]))
+ * ```
+ *
+ * ### State-change functions
+ *
+ * Here is an example of a `fromState` specified as a state-change function that invokes an
+ * animation when true:
+ *
+ * ```typescript
+ * transition((fromState, toState) =>
+ *  {
+ *   return fromState == "off" && toState == "on";
+ *  },
+ *  animate("1s 0s"))
+ * ```
+ *
+ * ### Animating to the final state
+ *
+ * If the final step in a transition is a call to `animate()` that uses a timing value
+ * with no style data, that step is automatically considered the final animation arc,
+ * for the element to reach the final state. Angular automatically adds or removes
+ * CSS styles to ensure that the element is in the correct final state.
+ *
+ * The following example defines a transition that starts by hiding the element,
+ * then makes sure that it animates properly to whatever state is currently active for trigger:
+ *
+ * ```typescript
+ * transition("void => *", [
+ *   style({ opacity: 0 }),
+ *   animate(500)
+ *  ])
+ * ```
+ * ### Boolean value matching
+ * If a trigger binding value is a Boolean, it can be matched using a transition expression
+ * that compares true and false or 1 and 0. For example:
  *
  * ```
  * // in the template
  * <div [@openClose]="open ? true : false">...</div>
- *
  * // in the component metadata
  * trigger('openClose', [
  *   state('true', style({ height: '*' })),
@@ -796,87 +977,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
  *   transition('false <=> true', animate(500))
  * ])
  * ```
- *
- * ### Using :increment and :decrement
- * In addition to the :enter and :leave transition aliases, the :increment and :decrement aliases
- * can be used to kick off a transition when a numeric value has increased or decreased in value.
- *
- * ```
- * import {group, animate, query, transition, style, trigger} from '@angular/animations';
- * import {Component} from '@angular/core';
- *
- * @Component({
- *   selector: 'banner-carousel-component',
- *   styles: [`
- *     .banner-container {
- *        position:relative;
- *        height:500px;
- *        overflow:hidden;
- *      }
- *     .banner-container > .banner {
- *        position:absolute;
- *        left:0;
- *        top:0;
- *        font-size:200px;
- *        line-height:500px;
- *        font-weight:bold;
- *        text-align:center;
- *        width:100%;
- *      }
- *   `],
- *   template: `
- *     <button (click)="previous()">Previous</button>
- *     <button (click)="next()">Next</button>
- *     <hr>
- *     <div [@bannerAnimation]="selectedIndex" class="banner-container">
- *       <div class="banner" *ngFor="let banner of banners"> {{ banner }} </div>
- *     </div>
- *   `,
- *   animations: [
- *     trigger('bannerAnimation', [
- *       transition(":increment", group([
- *         query(':enter', [
- *           style({ left: '100%' }),
- *           animate('0.5s ease-out', style('*'))
- *         ]),
- *         query(':leave', [
- *           animate('0.5s ease-out', style({ left: '-100%' }))
- *         ])
- *       ])),
- *       transition(":decrement", group([
- *         query(':enter', [
- *           style({ left: '-100%' }),
- *           animate('0.5s ease-out', style('*'))
- *         ]),
- *         query(':leave', [
- *           animate('0.5s ease-out', style({ left: '100%' }))
- *         ])
- *       ]))
- *     ])
- *   ]
- * })
- * class BannerCarouselComponent {
- *   allBanners: string[] = ['1', '2', '3', '4'];
- *   selectedIndex: number = 0;
- *
- *   get banners() {
- *      return [this.allBanners[this.selectedIndex]];
- *   }
- *
- *   previous() {
- *     this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
- *   }
- *
- *   next() {
- *     this.selectedIndex = Math.min(this.selectedIndex + 1, this.allBanners.length - 1);
- *   }
- * }
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ **/
 export function transition(
     stateChangeExpr: string | ((fromState: string, toState: string, element?: any,
                                 params?: {[key: string]: any}) => boolean),
@@ -886,27 +987,35 @@ export function transition(
 }
 
 /**
- * `animation` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language.
+ * Produces a reusable animation that can be invoked in another animation or sequence,
+ * by calling the `useAnimation()` function.
  *
- * `var myAnimation = animation(...)` is designed to produce a reusable animation that can be later
- * invoked in another animation or sequence. Reusable animations are designed to make use of
- * animation parameters and the produced animation can be used via the `useAnimation` method.
+ * @param steps One or more animation objects, as returned by the `animate()`
+ * or `sequence()` function, that form a transformation from one state to another.
+ * A sequence is used by default when you pass an array.
+ * @param options An options object that can contain a delay value for the start of the
+ * animation, and additional developer-defined parameters.
+ * Provided values for additional parameters are used as defaults,
+ * and override values can be passed to the caller on invocation.
+ * @returns An object that encapsulates the animation data.
  *
- * ```
+ * @usageNotes
+ * The following example defines a reusable animation, providing some default parameter
+ * values.
+ *
+ * ```typescript
  * var fadeAnimation = animation([
  *   style({ opacity: '{{ start }}' }),
  *   animate('{{ time }}',
- *     style({ opacity: '{{ end }}'}))
- * ], { params: { time: '1000ms', start: 0, end: 1 }});
+ *   style({ opacity: '{{ end }}'}))
+ *   ],
+ *   { params: { time: '1000ms', start: 0, end: 1 }});
  * ```
  *
- * If parameters are attached to an animation then they act as **default parameter values**. When an
- * animation is invoked via `useAnimation` then parameter values are allowed to be passed in
- * directly. If any of the passed in parameter values are missing then the default values will be
- * used.
+ * The following invokes the defined animation with a call to `useAnimation()`,
+ * passing in override parameter values.
  *
- * ```
+ * ```js
  * useAnimation(fadeAnimation, {
  *   params: {
  *     time: '2s',
@@ -916,9 +1025,9 @@ export function transition(
  * })
  * ```
  *
- * If one or more parameter values are missing before animated then an error will be thrown.
- *
- * @experimental Animation support is experimental.
+ * If any of the passed-in parameter values are missing from this call,
+ * the default values are used. If one or more parameter values are missing before a step is
+ * animated, `useAnimation()` throws an error.
  */
 export function animation(
     steps: AnimationMetadata | AnimationMetadata[],
@@ -927,101 +1036,21 @@ export function animation(
 }
 
 /**
- * `animateChild` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. It works by allowing a queried element to execute its own
- * animation within the animation sequence.
+ * Executes a queried inner animation element within an animation sequence.
  *
- * Each time an animation is triggered in angular, the parent animation
- * will always get priority and any child animations will be blocked. In order
+ * @param options An options object that can contain a delay value for the start of the
+ * animation, and additional override values for developer-defined parameters.
+ * @return An object that encapsulates the child animation data.
+ *
+ * @usageNotes
+ * Each time an animation is triggered in Angular, the parent animation
+ * has priority and any child animations are blocked. In order
  * for a child animation to run, the parent animation must query each of the elements
- * containing child animations and then allow the animations to run using `animateChild`.
+ * containing child animations, and run them using this function.
  *
- * The example HTML code below shows both parent and child elements that have animation
- * triggers that will execute at the same time.
- *
- * ```html
- * <!-- parent-child.component.html -->
- * <button (click)="exp =! exp">Toggle</button>
- * <hr>
- *
- * <div [@parentAnimation]="exp">
- *   <header>Hello</header>
- *   <div [@childAnimation]="exp">
- *       one
- *   </div>
- *   <div [@childAnimation]="exp">
- *       two
- *   </div>
- *   <div [@childAnimation]="exp">
- *       three
- *   </div>
- * </div>
- * ```
- *
- * Now when the `exp` value changes to true, only the `parentAnimation` animation will animate
- * because it has priority. However, using `query` and `animateChild` each of the inner animations
- * can also fire:
- *
- * ```ts
- * // parent-child.component.ts
- * import {trigger, transition, animate, style, query, animateChild} from '@angular/animations';
- * @Component({
- *   selector: 'parent-child-component',
- *   animations: [
- *     trigger('parentAnimation', [
- *       transition('false => true', [
- *         query('header', [
- *           style({ opacity: 0 }),
- *           animate(500, style({ opacity: 1 }))
- *         ]),
- *         query('@childAnimation', [
- *           animateChild()
- *         ])
- *       ])
- *     ]),
- *     trigger('childAnimation', [
- *       transition('false => true', [
- *         style({ opacity: 0 }),
- *         animate(500, style({ opacity: 1 }))
- *       ])
- *     ])
- *   ]
- * })
- * class ParentChildCmp {
- *   exp: boolean = false;
- * }
- * ```
- *
- * In the animation code above, when the `parentAnimation` transition kicks off it first queries to
- * find the header element and fades it in. It then finds each of the sub elements that contain the
- * `@childAnimation` trigger and then allows for their animations to fire.
- *
- * This example can be further extended by using stagger:
- *
- * ```ts
- * query('@childAnimation', stagger(100, [
- *   animateChild()
- * ]))
- * ```
- *
- * Now each of the sub animations start off with respect to the `100ms` staggering step.
- *
- * ## The first frame of child animations
- * When sub animations are executed using `animateChild` the animation engine will always apply the
- * first frame of every sub animation immediately at the start of the animation sequence. This way
- * the parent animation does not need to set any initial styling data on the sub elements before the
- * sub animations kick off.
- *
- * In the example above the first frame of the `childAnimation`'s `false => true` transition
- * consists of a style of `opacity: 0`. This is applied immediately when the `parentAnimation`
- * animation transition sequence starts. Only then when the `@childAnimation` is queried and called
- * with `animateChild` will it then animate to its destination of `opacity: 1`.
- *
- * Note that this feature designed to be used alongside {@link query query()} and it will only work
- * with animations that are assigned using the Angular animation DSL (this means that CSS keyframes
- * and transitions are not handled by this API).
- *
- * @experimental Animation support is experimental.
+ * Note that this feature designed to be used with `query()` and it will only work
+ * with animations that are assigned using the Angular animation library. CSS keyframes
+ * and transitions are not handled by this API.
  */
 export function animateChild(options: AnimateChildOptions | null = null):
     AnimationAnimateChildMetadata {
@@ -1029,11 +1058,12 @@ export function animateChild(options: AnimateChildOptions | null = null):
 }
 
 /**
- * `useAnimation` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. It is used to kick off a reusable animation that is created using {@link
- * animation animation()}.
+ * Starts a reusable animation that is created using the `animation()` function.
  *
- * @experimental Animation support is experimental.
+ * @param animation The reusable animation to start.
+ * @param options An options object that can contain a delay value for the start of 
+ * the animation, and additional override values for developer-defined parameters.
+ * @return An object that contains the animation parameters.
  */
 export function useAnimation(
     animation: AnimationReferenceMetadata,
@@ -1042,19 +1072,33 @@ export function useAnimation(
 }
 
 /**
- * `query` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language.
+ * Finds one or more inner elements within the current element that is
+ * being animated within a sequence. Use with `animateChild()`.
  *
- * query() is used to find one or more inner elements within the current element that is
- * being animated within the sequence. The provided animation steps are applied
- * to the queried element (by default, an array is provided, then this will be
- * treated as an animation sequence).
+ * @param selector The element to query, or a set of elements that contain Angular-specific
+ * characteristics, specified with one or more of the following tokens.
+ *  - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements.
+ *  - `query(":animating")` : Query all currently animating elements.
+ *  - `query("@triggerName")` : Query elements that contain an animation trigger.
+ *  - `query("@*")` : Query all elements that contain an animation triggers.
+ *  - `query(":self")` : Include the current element into the animation sequence.
  *
- * ### Usage
+ * @param animation One or more animation steps to apply to the queried element or elements.
+ * An array is treated as an animation sequence.
+ * @param options An options object. Use the 'limit' field to limit the total number of
+ * items to collect.
+ * @return An object that encapsulates the query data.
  *
- * query() is designed to collect multiple elements and works internally by using
- * `element.querySelectorAll`. An additional options object can be provided which
- * can be used to limit the total amount of items to be collected.
+ * @usageNotes
+ * Tokens can be merged into a combined query selector string. For example:
+ *
+ * ```typescript
+ *  query(':self, .record:enter, .record:leave, @subTrigger', [...])
+ * ```
+ *
+ * The `query()` function collects multiple elements and works internally by using
+ * `element.querySelectorAll`. Use the `limit` field of an options object to limit
+ * the total number of items to be collected. For example:
  *
  * ```js
  * query('div', [
@@ -1063,8 +1107,8 @@ export function useAnimation(
  * ], { limit: 1 })
  * ```
  *
- * query(), by default, will throw an error when zero items are found. If a query
- * has the `optional` flag set to true then this error will be ignored.
+ * By default, throws an error when zero items are found. Set the
+ * `optional` flag to ignore this error. For example:
  *
  * ```js
  * query('.some-element-that-may-not-be-there', [
@@ -1073,31 +1117,12 @@ export function useAnimation(
  * ], { optional: true })
  * ```
  *
- * ### Special Selector Values
+ * ### Usage Example
  *
- * The selector value within a query can collect elements that contain angular-specific
- * characteristics
- * using special pseudo-selectors tokens.
+ * The following example queries for inner elements and animates them
+ * individually using `animateChild()`. 
  *
- * These include:
- *
- *  - Querying for newly inserted/removed elements using `query(":enter")`/`query(":leave")`
- *  - Querying all currently animating elements using `query(":animating")`
- *  - Querying elements that contain an animation trigger using `query("@triggerName")`
- *  - Querying all elements that contain an animation triggers using `query("@*")`
- *  - Including the current element into the animation sequence using `query(":self")`
- *
- *
- *  Each of these pseudo-selector tokens can be merged together into a combined query selector
- * string:
- *
- *  ```
- *  query(':self, .record:enter, .record:leave, @subTrigger', [...])
- *  ```
- *
- * ### Demo
- *
- * ```
+ * ```typescript
  * @Component({
  *   selector: 'inner',
  *   template: `
@@ -1130,8 +1155,6 @@ export function useAnimation(
  *   }
  * }
  * ```
- *
- * @experimental Animation support is experimental.
  */
 export function query(
     selector: string, animation: AnimationMetadata | AnimationMetadata[],
@@ -1140,16 +1163,23 @@ export function query(
 }
 
 /**
- * `stagger` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. It is designed to be used inside of an animation {@link query query()}
- * and works by issuing a timing gap between after each queried item is animated.
+ * Use within an animation `query()` call to issue a timing gap after
+ * each queried item is animated.
  *
- * ### Usage
+ * @param timings A delay value.
+ * @param animation One ore more animation steps.
+ * @returns An object that encapsulates the stagger data.
  *
- * In the example below there is a container element that wraps a list of items stamped out
- * by an ngFor. The container element contains an animation trigger that will later be set
+ * @usageNotes
+ * In the following example, a container element wraps a list of items stamped out
+ * by an `ngFor`. The container element contains an animation trigger that will later be set
  * to query for each of the inner items.
  *
+ * Each time items are added, the opacity fade-in animation runs,
+ * and each removed item is faded out.
+ * When either of these animations occur, the stagger effect is
+ * applied after each item's animation is started.
+ *
  * ```html
  * <!-- list.component.html -->
  * <button (click)="toggle()">Show / Hide Items</button>
@@ -1161,15 +1191,15 @@ export function query(
  * </div>
  * ```
  *
- * The component code for this looks as such:
+ * Here is the component code:
  *
- * ```ts
+ * ```typescript
  * import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
  * @Component({
  *   templateUrl: 'list.component.html',
  *   animations: [
  *     trigger('listAnimation', [
- *        //...
+ *     ...
  *     ])
  *   ]
  * })
@@ -1186,13 +1216,13 @@ export function query(
  *
  *   toggle() {
  *     this.items.length ? this.hideItems() : this.showItems();
- *   }
- * }
+ *    }
+ *  }
  * ```
  *
- * And now for the animation trigger code:
+ * Here is the animation trigger code:
  *
- * ```ts
+ * ```typescript
  * trigger('listAnimation', [
  *   transition('* => *', [ // each time the binding value changes
  *     query(':leave', [
@@ -1209,13 +1239,6 @@ export function query(
  *   ])
  * ])
  * ```
- *
- * Now each time the items are added/removed then either the opacity
- * fade-in animation will run or each removed item will be faded out.
- * When either of these animations occur then a stagger effect will be
- * applied after each item's animation is started.
- *
- * @experimental Animation support is experimental.
  */
 export function stagger(
     timings: string | number,
diff --git a/tools/public_api_guard/animations/animations.d.ts b/tools/public_api_guard/animations/animations.d.ts
index 07f51a54f8..2f85467bdc 100644
--- a/tools/public_api_guard/animations/animations.d.ts
+++ b/tools/public_api_guard/animations/animations.d.ts
@@ -1,36 +1,28 @@
-/** @experimental */
 export declare function animate(timings: string | number, styles?: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null): AnimationAnimateMetadata;
 
-/** @experimental */
 export declare function animateChild(options?: AnimateChildOptions | null): AnimationAnimateChildMetadata;
 
-/** @experimental */
 export interface AnimateChildOptions extends AnimationOptions {
     duration?: number | string;
 }
 
-/** @experimental */
 export declare type AnimateTimings = {
     duration: number;
     delay: number;
     easing: string | null;
 };
 
-/** @experimental */
 export declare function animation(steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationReferenceMetadata;
 
-/** @experimental */
 export interface AnimationAnimateChildMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
 }
 
-/** @experimental */
 export interface AnimationAnimateMetadata extends AnimationMetadata {
     styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null;
     timings: string | number | AnimateTimings;
 }
 
-/** @experimental */
 export interface AnimationAnimateRefMetadata extends AnimationMetadata {
     animation: AnimationReferenceMetadata;
     options: AnimationOptions | null;
@@ -57,23 +49,19 @@ export declare abstract class AnimationFactory {
     abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
 }
 
-/** @experimental */
 export interface AnimationGroupMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
     steps: AnimationMetadata[];
 }
 
-/** @experimental */
 export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
     steps: AnimationStyleMetadata[];
 }
 
-/** @experimental */
 export interface AnimationMetadata {
     type: AnimationMetadataType;
 }
 
-/** @experimental */
 export declare const enum AnimationMetadataType {
     State = 0,
     Transition = 1,
@@ -90,7 +78,6 @@ export declare const enum AnimationMetadataType {
     Stagger = 12,
 }
 
-/** @experimental */
 export interface AnimationOptions {
     delay?: number | string;
     params?: {
@@ -118,38 +105,32 @@ export interface AnimationPlayer {
     setPosition(p: any): void;
 }
 
-/** @experimental */
 export interface AnimationQueryMetadata extends AnimationMetadata {
     animation: AnimationMetadata | AnimationMetadata[];
     options: AnimationQueryOptions | null;
     selector: string;
 }
 
-/** @experimental */
 export interface AnimationQueryOptions extends AnimationOptions {
     limit?: number;
     optional?: boolean;
 }
 
-/** @experimental */
 export interface AnimationReferenceMetadata extends AnimationMetadata {
     animation: AnimationMetadata | AnimationMetadata[];
     options: AnimationOptions | null;
 }
 
-/** @experimental */
 export interface AnimationSequenceMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
     steps: AnimationMetadata[];
 }
 
-/** @experimental */
 export interface AnimationStaggerMetadata extends AnimationMetadata {
     animation: AnimationMetadata | AnimationMetadata[];
     timings: string | number;
 }
 
-/** @experimental */
 export interface AnimationStateMetadata extends AnimationMetadata {
     name: string;
     options?: {
@@ -160,7 +141,6 @@ export interface AnimationStateMetadata extends AnimationMetadata {
     styles: AnimationStyleMetadata;
 }
 
-/** @experimental */
 export interface AnimationStyleMetadata extends AnimationMetadata {
     offset: number | null;
     styles: '*' | {
@@ -170,7 +150,6 @@ export interface AnimationStyleMetadata extends AnimationMetadata {
     } | '*'>;
 }
 
-/** @experimental */
 export interface AnimationTransitionMetadata extends AnimationMetadata {
     animation: AnimationMetadata | AnimationMetadata[];
     expr: string | ((fromState: string, toState: string, element?: any, params?: {
@@ -179,7 +158,6 @@ export interface AnimationTransitionMetadata extends AnimationMetadata {
     options: AnimationOptions | null;
 }
 
-/** @experimental */
 export interface AnimationTriggerMetadata extends AnimationMetadata {
     definitions: AnimationMetadata[];
     name: string;
@@ -190,13 +168,10 @@ export interface AnimationTriggerMetadata extends AnimationMetadata {
     } | null;
 }
 
-/** @experimental */
 export declare const AUTO_STYLE = "*";
 
-/** @experimental */
 export declare function group(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationGroupMetadata;
 
-/** @experimental */
 export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata;
 
 /** @experimental */
@@ -219,30 +194,24 @@ export declare class NoopAnimationPlayer implements AnimationPlayer {
     setPosition(p: number): void;
 }
 
-/** @experimental */
 export declare function query(selector: string, animation: AnimationMetadata | AnimationMetadata[], options?: AnimationQueryOptions | null): AnimationQueryMetadata;
 
-/** @experimental */
 export declare function sequence(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationSequenceMetadata;
 
-/** @experimental */
 export declare function stagger(timings: string | number, animation: AnimationMetadata | AnimationMetadata[]): AnimationStaggerMetadata;
 
-/** @experimental */
 export declare function state(name: string, styles: AnimationStyleMetadata, options?: {
     params: {
         [name: string]: any;
     };
 }): AnimationStateMetadata;
 
-/** @experimental */
 export declare function style(tokens: '*' | {
     [key: string]: string | number;
 } | Array<'*' | {
     [key: string]: string | number;
 }>): AnimationStyleMetadata;
 
-/** @experimental */
 export declare function transition(stateChangeExpr: string | ((fromState: string, toState: string, element?: any, params?: {
     [key: string]: any;
 }) => boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationTransitionMetadata;
@@ -250,5 +219,4 @@ export declare function transition(stateChangeExpr: string | ((fromState: string
 /** @experimental */
 export declare function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata;
 
-/** @experimental */
 export declare function useAnimation(animation: AnimationReferenceMetadata, options?: AnimationOptions | null): AnimationAnimateRefMetadata;