Merge pull request #2780 from qchong/update-animation-api-docs

docs: Updated descriptions for Animation API docs.

packages/flutter/lib/src/animation/animation_controller.dart

@@ -24,10 +24,17 @@ enum _AnimationDirection {
 
 /// A controller for an animation.
 ///
-/// An animation controller can drive an animation forward or backward and can
-/// set the animation to a particular value. The controller also defines the
-/// bounds of the animation and can drive an animation using a physics
-/// simulation.
+/// This class lets you perform tasks such as:
+///
+/// * Play an animation [forward] or in [reverse], or [stop] an animation.
+/// * Set the animation to a specific [value].
+/// * Define the [upperBound] and [lowerBound] values of an animation.
+/// * Create a [fling] animation effect using a physics simulation.
+///
+/// By default, an [AnimationController] linearly produces values that range from 0.0 to 1.0, during
+/// a given duration. The animation controller generates a new value whenever the device running
+/// your app is ready to display a new frame (typically, this rate is around 60 values per second).
+///
 class AnimationController extends Animation<double>
   with AnimationEagerListenerMixin, AnimationLocalListenersMixin, AnimationLocalStatusListenersMixin {
 

packages/flutter/lib/src/animation/animations.dart

@@ -236,9 +236,23 @@ class ReverseAnimation extends Animation<double>
 
 /// An animation that applies a curve to another animation.
 ///
-/// [CurvedAnimation] is useful when you wish to apply a [Curve] and you already
-/// have the underlying animation object. If you don't yet have an animation and
-/// want to apply a [Curve] to a [Tween], consider using [CurveTween].
+/// [CurvedAnimation] is useful when you want to apply a non-linear [Curve] to
+/// an animation object wrapped in the [CurvedAnimation].
+///
+/// For example, the following code snippet shows how you can apply a curve to a linear animation
+/// produced by an [AnimationController]:
+///
+/// ``` dart
+///     final AnimationController controller =
+///         new AnimationController(duration: const Duration(milliseconds: 500));
+///     final CurvedAnimation animation =
+///         new CurvedAnimation(parent: controller, curve: Curves.ease);
+///```
+/// Depending on the given curve, the output of the [CurvedAnimation] could have a wider range
+/// than its input. For example, elastic curves such as [Curves.elasticIn] will significantly
+/// overshoot or undershoot the default range of 0.0 to 1.0.
+///
+/// If you want to apply a [Curve] to a [Tween], consider using [CurveTween].
 class CurvedAnimation extends Animation<double> with AnimationWithParentMixin<double> {
   CurvedAnimation({
     this.parent,

packages/flutter/lib/src/animation/tween.dart

@@ -55,6 +55,16 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 }
 
 /// A linear interpolation between a beginning and ending value.
+///
+/// [Tween] is useful if you want to interpolate across a range.
+///
+/// To use a [Tween] object with an animation, call the [Tween] object's `animate()` method and
+/// pass it the [Animation] object that you want to modify.
+///
+/// You can chain [Tween] objects together using the `chain()` method, so that a single
+/// [Animation] object is configured by multiple [Tween] objects called in succession. This is
+/// different than calling the `animate()` method twice, which results in two [Animation]
+/// separate objects, each configured with a single [Tween].
 class Tween<T extends dynamic> extends Animatable<T> {
   Tween({ this.begin, this.end });
 
@@ -68,6 +78,8 @@ class Tween<T extends dynamic> extends Animatable<T> {
   T lerp(double t) => begin + (end - begin) * t;
 
   /// Returns the interpolated value for the current value of the given animation.
+  ///
+  /// This method returns `begin` and `end` when the animation values are 0.0 or 1.0, respectively.
   @override
   T evaluate(Animation<double> animation) {
     if (end == null)