Finish dartdocs for animation.dart and foundation.dart (#3963)

Everything now has dartdocs except one setter whose getter already has
docs.

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

@@ -44,15 +44,23 @@ abstract class Animation<T> {
   // keep these next five dartdocs in sync with the dartdocs in AnimationWithParentMixin<T>
 
   /// Calls the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be removed with [removeListener].
   void addListener(VoidCallback listener);
 
   /// Stop calling the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be added with [addListener].
   void removeListener(VoidCallback listener);
 
   /// Calls listener every time the status of the animation changes.
+  ///
+  /// Listeners can be removed with [removeStatusListener].
   void addStatusListener(AnimationStatusListener listener);
 
   /// Stops calling the listener every time the status of the animation changes.
+  ///
+  /// Listeners can be added with [addStatusListener].
   void removeStatusListener(AnimationStatusListener listener);
 
   /// The current status of this animation.

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

@@ -123,15 +123,23 @@ abstract class AnimationWithParentMixin<T> {
   // keep these next five dartdocs in sync with the dartdocs in Animation<T>
 
   /// Calls the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be removed with [removeListener].
   void addListener(VoidCallback listener) => parent.addListener(listener);
 
   /// Stop calling the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be added with [addListener].
   void removeListener(VoidCallback listener) => parent.removeListener(listener);
 
   /// Calls listener every time the status of the animation changes.
+  ///
+  /// Listeners can be removed with [removeStatusListener].
   void addStatusListener(AnimationStatusListener listener) => parent.addStatusListener(listener);
 
   /// Stops calling the listener every time the status of the animation changes.
+  ///
+  /// Listeners can be added with [addStatusListener].
   void removeStatusListener(AnimationStatusListener listener) => parent.removeStatusListener(listener);
 
   /// The current status of this animation.
@@ -146,6 +154,11 @@ abstract class AnimationWithParentMixin<T> {
 /// its value.
 class ProxyAnimation extends Animation<double>
   with AnimationLazyListenerMixin, AnimationLocalListenersMixin, AnimationLocalStatusListenersMixin {
+
+  /// Creates a proxy animation.
+  ///
+  /// If the animation argument is omitted, the proxy animation will have the
+  /// status [AnimationStatus.dismissed] and a value of 0.0.
   ProxyAnimation([Animation<double> animation]) {
     _parent = animation;
     if (_parent == null) {
@@ -224,7 +237,13 @@ class ProxyAnimation extends Animation<double>
 /// animation.
 class ReverseAnimation extends Animation<double>
   with AnimationLazyListenerMixin, AnimationLocalStatusListenersMixin {
-  ReverseAnimation(this.parent);
+
+  /// Creates a reverse animation.
+  ///
+  /// The parent argument must not be null.
+  ReverseAnimation(this.parent) {
+    assert(parent != null);
+  }
 
   /// The animation whose value and direction this animation is reversing.
   final Animation<double> parent;
@@ -296,9 +315,12 @@ class ReverseAnimation extends Animation<double>
 ///
 /// If you want to apply a [Curve] to a [Tween], consider using [CurveTween].
 class CurvedAnimation extends Animation<double> with AnimationWithParentMixin<double> {
+  /// Creates a curved animation.
+  ///
+  /// The parent and curve arguments must not be null.
   CurvedAnimation({
     this.parent,
-    this.curve: Curves.linear,
+    this.curve,
     this.reverseCurve
   }) {
     assert(parent != null);
@@ -362,7 +384,7 @@ class CurvedAnimation extends Animation<double> with AnimationWithParentMixin<do
   String toString() {
     if (reverseCurve == null)
       return '$parent\u27A9$curve';
-    if (_useForwardCurve) 
+    if (_useForwardCurve)
      return '$parent\u27A9$curve\u2092\u2099/$reverseCurve';
     return '$parent\u27A9$curve/$reverseCurve\u2092\u2099';
   }
@@ -382,6 +404,11 @@ enum _TrainHoppingMode { minimize, maximize }
 /// object down.
 class TrainHoppingAnimation extends Animation<double>
   with AnimationEagerListenerMixin, AnimationLocalListenersMixin, AnimationLocalStatusListenersMixin {
+
+  /// Creates a train-hopping animation.
+  ///
+  /// The current train argument must not be null but the next train argument
+  /// can be null.
   TrainHoppingAnimation(this._currentTrain, this._nextTrain, { this.onSwitchedTrain }) {
     assert(_currentTrain != null);
     if (_nextTrain != null) {

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

@@ -36,17 +36,26 @@ abstract class Curve {
 }
 
 /// The identity map over the unit interval.
+///
+/// See [Curves.linear] for an instance of this class.
 class Linear extends Curve {
-  const Linear();
+  const Linear._();
 
   @override
   double transform(double t) => t;
 }
 
 /// A sawtooth curve that repeats a given number of times over the unit interval.
+///
+/// The curve rises linearly from 0.0 to 1.0 and then falls discontinuously back
+/// to 0.0 each iteration.
 class SawTooth extends Curve {
+  /// Creates a sawtooth curve.
+  ///
+  /// The [count] argument must not be null.
   const SawTooth(this.count);
 
+  /// The number of repetitions of the sawtooth pattern in the unit interval.
   final int count;
 
   @override
@@ -61,8 +70,11 @@ class SawTooth extends Curve {
   }
 }
 
-/// A curve that is 0.0 until start, then curved from 0.0 to 1.0 at end, then 1.0.
+/// A curve that is 0.0 until [start], then curved from 0.0 to 1.0 at [end], then 1.0.
 class Interval extends Curve {
+  /// Creates an interval curve.
+  ///
+  /// The [start] and [end] arguments must not be null.
   const Interval(this.start, this.end, { this.curve: Curves.linear });
 
   /// The smallest value for which this interval is 0.0.
@@ -97,11 +109,14 @@ class Interval extends Curve {
 
 /// A curve that is 0.0 until it hits the threshold, then it jumps to 1.0.
 class Step extends Curve {
+  /// Creates a step cruve.
+  ///
+  /// The [threshold] argument must not be null.
   const Step(this.threshold);
 
   /// The value before which the curve is 0.0 and after which the curve is 1.0.
   ///
-  /// At exactly step, the curve has the value 1.0.
+  /// When t is exactly [threshold], the curve has the value 1.0.
   final double threshold;
 
   @override
@@ -115,12 +130,46 @@ class Step extends Curve {
 }
 
 /// A cubic polynomial mapping of the unit interval.
+///
+/// See [Curves] for a number of commonly used cubic curves.
+///
+/// See also:
+///
+///  * [Curves.ease]
+///  * [Curves.easeIn]
+///  * [Curves.easeOut]
+///  * [Curves.easeInOut]
 class Cubic extends Curve {
+  /// Creates a cubic curve.
+  ///
+  /// Rather than creating a new instance, consider using one of the common
+  /// cubic curves in [Curves].
+  ///
+  /// The [a], [b], [c], and [d] arguments must not be null.
   const Cubic(this.a, this.b, this.c, this.d);
 
+  /// The x coordinate of the first control point.
+  ///
+  /// The line through the point (0, 0) and the first control point is tangent
+  /// to the curve at the point (0, 0).
   final double a;
+
+  /// The y coordinate of the first control point.
+  ///
+  /// The line through the point (0, 0) and the first control point is tangent
+  /// to the curve at the point (0, 0).
   final double b;
+
+  /// The x coordinate of the second control point.
+  ///
+  /// The line through the point (1, 1) and the second control point is tangent
+  /// to the curve at the point (1, 1).
   final double c;
+
+  /// The y coordinate of the second control point.
+  ///
+  /// The line through the point (1, 1) and the second control point is tangent
+  /// to the curve at the point (1, 1).
   final double d;
 
   @override
@@ -160,9 +209,17 @@ double _bounce(double t) {
 }
 
 /// A curve that is the reversed inversion of its given curve.
+///
+/// This curve evalutes the given curve in reverse (i.e., from 1.0 to 0.0 as t
+/// increases from 0.0 to 1.0) and returns the inverse of the given curve's value
+/// (i.e., 1.0 minus the given curve's value).
 class FlippedCurve extends Curve {
-  FlippedCurve(this.curve);
+  /// Creates a flipped curve.
+  ///
+  /// The [curve] argument must not be null.
+  const FlippedCurve(this.curve);
 
+  /// The curve that is being flipped.
   final Curve curve;
 
   @override
@@ -175,8 +232,10 @@ class FlippedCurve extends Curve {
 }
 
 /// An oscillating curve that grows in magnitude.
+///
+/// See [Curves.bounceIn] for an instance of this class.
 class BounceInCurve extends Curve {
-  const BounceInCurve();
+  const BounceInCurve._();
 
   @override
   double transform(double t) {
@@ -185,8 +244,10 @@ class BounceInCurve extends Curve {
 }
 
 /// An oscillating curve that shrink in magnitude.
+///
+/// See [Curves.bounceOut] for an instance of this class.
 class BounceOutCurve extends Curve {
-  const BounceOutCurve();
+  const BounceOutCurve._();
 
   @override
   double transform(double t) {
@@ -195,8 +256,10 @@ class BounceOutCurve extends Curve {
 }
 
 /// An oscillating curve that first grows and then shrink in magnitude.
+///
+/// See [Curves.bounceInOut] for an instance of this class.
 class BounceInOutCurve extends Curve {
-  const BounceInOutCurve();
+  const BounceInOutCurve._();
 
   @override
   double transform(double t) {
@@ -209,8 +272,12 @@ class BounceInOutCurve extends Curve {
 
 /// An oscillating curve that grows in magnitude while overshooting its bounds.
 class ElasticInCurve extends Curve {
+  /// Creates an elastic-in curve.
+  ///
+  /// Rather than creating a new instance, consider using [Curves.elasticIn].
   const ElasticInCurve([this.period = 0.4]);
 
+  /// The duration of the oscillation.
   final double period;
 
   @override
@@ -228,8 +295,12 @@ class ElasticInCurve extends Curve {
 
 /// An oscillating curve that shrinks in magnitude while overshooting its bounds.
 class ElasticOutCurve extends Curve {
+  /// Creates an elastic-out curve.
+  ///
+  /// Rather than creating a new instance, consider using [Curves.elasticOut].
   const ElasticOutCurve([this.period = 0.4]);
 
+  /// The duration of the oscillation.
   final double period;
 
   @override
@@ -246,8 +317,12 @@ class ElasticOutCurve extends Curve {
 
 /// An oscillating curve that grows and then shrinks in magnitude while overshooting its bounds.
 class ElasticInOutCurve extends Curve {
+  /// Creates an elastic-in-out curve.
+  ///
+  /// Rather than creating a new instance, consider using [Curves.elasticInOut].
   const ElasticInOutCurve([this.period = 0.4]);
 
+  /// The duration of the oscillation.
   final double period;
 
   @override
@@ -271,7 +346,7 @@ class Curves {
   Curves._();
 
   /// A linear animation curve
-  static const Linear linear = const Linear();
+  static const Linear linear = const Linear._();
 
   /// A cubic animation curve that speeds up quickly and ends slowly.
   static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0);
@@ -286,13 +361,13 @@ class Curves {
   static const Cubic easeInOut = const Cubic(0.42, 0.0, 0.58, 1.0);
 
   /// An oscillating curve that grows in magnitude.
-  static const BounceInCurve bounceIn = const BounceInCurve();
+  static const BounceInCurve bounceIn = const BounceInCurve._();
 
   /// An oscillating curve that first grows and then shrink in magnitude.
-  static const BounceOutCurve bounceOut = const BounceOutCurve();
+  static const BounceOutCurve bounceOut = const BounceOutCurve._();
 
   /// An oscillating curve that first grows and then shrink in magnitude.
-  static const BounceInOutCurve bounceInOut = const BounceInOutCurve();
+  static const BounceInOutCurve bounceInOut = const BounceInOutCurve._();
 
   /// An oscillating curve that grows in magnitude while overshootings its bounds.
   static const ElasticInCurve elasticIn = const ElasticInCurve();

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

@@ -18,6 +18,10 @@ abstract class Force {
 
 /// A factory for spring-based physics simulations.
 class SpringForce extends Force {
+  /// Creates a spring force.
+  ///
+  /// The [spring], [left], and [right] arguments must not be null. The [left]
+  /// argument defaults to 0.0 and the [right] argument defaults to 1.0.
   const SpringForce(this.spring, { this.left: 0.0, this.right: 1.0 });
 
   /// The description of the spring to be used in the created simulations.

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

@@ -31,8 +31,13 @@ abstract class AnimationLazyListenerMixin implements _ListenerMixin {
       didStopListening();
   }
 
+  /// Called when the number of listeners changes from zero to one.
   void didStartListening();
+
+  /// Called when the number of listeners changes from one to zero.
   void didStopListening();
+
+  /// Whether there are any listeners.
   bool get isListening => _listenerCounter > 0;
 }
 
@@ -53,14 +58,27 @@ abstract class AnimationEagerListenerMixin implements _ListenerMixin {
 /// all the registered listeners when notifyListeners is invoked.
 abstract class AnimationLocalListenersMixin extends _ListenerMixin {
   final List<VoidCallback> _listeners = <VoidCallback>[];
+
+  /// Calls the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be removed with [removeListener].
   void addListener(VoidCallback listener) {
     didRegisterListener();
     _listeners.add(listener);
   }
+
+  /// Stop calling the listener every time the value of the animation changes.
+  ///
+  /// Listeners can be added with [addListener].
   void removeListener(VoidCallback listener) {
     _listeners.remove(listener);
     didUnregisterListener();
   }
+
+  /// Calls all the listeners.
+  ///
+  /// If listeners are added or removed during this function, the modifications
+  /// will not change which listeners are called during this iteration.
   void notifyListeners() {
     List<VoidCallback> localListeners = new List<VoidCallback>.from(_listeners);
     for (VoidCallback listener in localListeners)
@@ -73,14 +91,27 @@ abstract class AnimationLocalListenersMixin extends _ListenerMixin {
 /// invoked.
 abstract class AnimationLocalStatusListenersMixin extends _ListenerMixin {
   final List<AnimationStatusListener> _statusListeners = <AnimationStatusListener>[];
+
+  /// Calls listener every time the status of the animation changes.
+  ///
+  /// Listeners can be removed with [removeStatusListener].
   void addStatusListener(AnimationStatusListener listener) {
     didRegisterListener();
     _statusListeners.add(listener);
   }
+
+  /// Stops calling the listener every time the status of the animation changes.
+  ///
+  /// Listeners can be added with [addStatusListener].
   void removeStatusListener(AnimationStatusListener listener) {
     _statusListeners.remove(listener);
     didUnregisterListener();
   }
+
+  /// Calls all the status listeners.
+  ///
+  /// If listeners are added or removed during this function, the modifications
+  /// will not change which listeners are called during this iteration.
   void notifyStatusListeners(AnimationStatus status) {
     List<AnimationStatusListener> localListeners = new List<AnimationStatusListener>.from(_statusListeners);
     for (AnimationStatusListener listener in localListeners)

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

@@ -82,6 +82,9 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 /// 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> {
+  /// Creates a tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   Tween({ this.begin, this.end });
 
   /// The value this variable has at the beginning of the animation.
@@ -115,6 +118,9 @@ class Tween<T extends dynamic> extends Animatable<T> {
 /// This class specializes the interpolation of Tween<Color> to be
 /// appropriate for colors.
 class ColorTween extends Tween<Color> {
+  /// Creates a color tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   ColorTween({ Color begin, Color end }) : super(begin: begin, end: end);
 
   @override
@@ -126,6 +132,9 @@ class ColorTween extends Tween<Color> {
 /// This class specializes the interpolation of Tween<Size> to be
 /// appropriate for rectangles.
 class SizeTween extends Tween<Size> {
+  /// Creates a size tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   SizeTween({ Size begin, Size end }) : super(begin: begin, end: end);
 
   @override
@@ -137,6 +146,9 @@ class SizeTween extends Tween<Size> {
 /// This class specializes the interpolation of Tween<Rect> to be
 /// appropriate for rectangles.
 class RectTween extends Tween<Rect> {
+  /// Creates a rect tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   RectTween({ Rect begin, Rect end }) : super(begin: begin, end: end);
 
   @override
@@ -153,6 +165,9 @@ class RectTween extends Tween<Rect> {
 /// This is the closest approximation to a linear tween that is
 /// possible with an integer. Compare to [StepTween].
 class IntTween extends Tween<int> {
+  /// Creates an int tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   IntTween({ int begin, int end }) : super(begin: begin, end: end);
 
   // The inherited lerp() function doesn't work with ints because it multiplies
@@ -171,6 +186,9 @@ class IntTween extends Tween<int> {
 /// This results in a value that is never greater than the equivalent
 /// value from a linear double interpolation. Compare to [IntTween].
 class StepTween extends Tween<int> {
+  /// Creates a step tween.
+  ///
+  /// The [begin] and [end] arguments must not be null.
   StepTween({ int begin, int end }) : super(begin: begin, end: end);
 
   // The inherited lerp() function doesn't work with ints because it multiplies
@@ -185,7 +203,12 @@ class StepTween extends Tween<int> {
 /// a curve to an existing [Animation] object whereas [CurveTween] can be
 /// chained with another [Tween] prior to receiving the underlying [Animation].
 class CurveTween extends Animatable<double> {
-  CurveTween({ this.curve });
+  /// Creates a curve tween.
+  ///
+  /// The [curve] argument must not be null.
+  CurveTween({ this.curve }) {
+    assert(curve != null);
+  }
 
   /// The curve to use when transforming the value of the animation.
   Curve curve;

packages/flutter/lib/src/foundation/basic_types.dart

@@ -34,18 +34,36 @@ class BitField<T extends dynamic> {
   static const int _kSMIBits = 63; // see https://www.dartlang.org/articles/numeric-computation/#smis-and-mints
   static const int _kAllZeros = 0;
   static const int _kAllOnes = 0x7FFFFFFFFFFFFFFF; // 2^(_kSMIBits+1)-1
+
+  /// Creates a bit field of all zeros.
+  ///
+  /// The given length must be at most 63.
   BitField(this._length) : _bits = _kAllZeros {
     assert(_length <= _kSMIBits);
   }
+
+  /// Creates a bit field filled with a particular value.
+  ///
+  /// If the value argument is true, the bits are filled with ones. Otherwise,
+  /// the bits are filled with zeros.
+  ///
+  /// The given length must be at most 63.
   BitField.filled(this._length, bool value) : _bits = value ? _kAllOnes : _kAllZeros {
     assert(_length <= _kSMIBits);
   }
   final int _length;
   int _bits;
+
+  /// Returns whether the bit with the given index is set to one.
   bool operator [](T index) {
     assert(index.index < _length);
     return (_bits & 1 << index.index) > 0;
   }
+
+  /// Sets the bit with the given index to the given value.
+  ///
+  /// If value is true, the bit with the given index is set to one. Otherwise,
+  /// the bit is set to zero.
   void operator []=(T index, bool value) {
     assert(index.index < _length);
     if (value)
@@ -53,6 +71,11 @@ class BitField<T extends dynamic> {
     else
       _bits = _bits & ~(1 << index.index);
   }
+
+  /// Sets all the bits to the given value.
+  ///
+  /// If the value is true, the bits are all set to one. Otherwise, the bits are
+  /// all set to zero. Defaults to setting all the bits to zero.
   void reset([ bool value = false ]) {
     _bits = value ? _kAllOnes : _kAllZeros;
   }