From fa22cf5337e2063041ddaefa9ce6d3152ebb3ecc Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Tue, 17 May 2016 10:49:20 -0700 Subject: [PATCH] Finish dartdocs for animation.dart and foundation.dart (#3963) Everything now has dartdocs except one setter whose getter already has docs. --- .../flutter/lib/src/animation/animation.dart | 8 ++ .../flutter/lib/src/animation/animations.dart | 33 ++++++- .../flutter/lib/src/animation/curves.dart | 97 ++++++++++++++++--- .../flutter/lib/src/animation/forces.dart | 4 + .../lib/src/animation/listener_helpers.dart | 31 ++++++ packages/flutter/lib/src/animation/tween.dart | 25 ++++- .../lib/src/foundation/basic_types.dart | 23 +++++ 7 files changed, 206 insertions(+), 15 deletions(-) diff --git a/packages/flutter/lib/src/animation/animation.dart b/packages/flutter/lib/src/animation/animation.dart index 4f8bb574676..3336b906965 100644 --- a/packages/flutter/lib/src/animation/animation.dart +++ b/packages/flutter/lib/src/animation/animation.dart @@ -44,15 +44,23 @@ abstract class Animation { // keep these next five dartdocs in sync with the dartdocs in AnimationWithParentMixin /// 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. diff --git a/packages/flutter/lib/src/animation/animations.dart b/packages/flutter/lib/src/animation/animations.dart index 8d7db84a3be..1eb11464f07 100644 --- a/packages/flutter/lib/src/animation/animations.dart +++ b/packages/flutter/lib/src/animation/animations.dart @@ -123,15 +123,23 @@ abstract class AnimationWithParentMixin { // keep these next five dartdocs in sync with the dartdocs in Animation /// 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 { /// its value. class ProxyAnimation extends Animation 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 animation]) { _parent = animation; if (_parent == null) { @@ -224,7 +237,13 @@ class ProxyAnimation extends Animation /// animation. class ReverseAnimation extends Animation 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 parent; @@ -296,9 +315,12 @@ class ReverseAnimation extends Animation /// /// If you want to apply a [Curve] to a [Tween], consider using [CurveTween]. class CurvedAnimation extends Animation with AnimationWithParentMixin { + /// 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 with AnimationWithParentMixin 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) { diff --git a/packages/flutter/lib/src/animation/curves.dart b/packages/flutter/lib/src/animation/curves.dart index 40b9082545f..3c2da02ad7d 100644 --- a/packages/flutter/lib/src/animation/curves.dart +++ b/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(); diff --git a/packages/flutter/lib/src/animation/forces.dart b/packages/flutter/lib/src/animation/forces.dart index e53c70435e3..700f9bfded8 100644 --- a/packages/flutter/lib/src/animation/forces.dart +++ b/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. diff --git a/packages/flutter/lib/src/animation/listener_helpers.dart b/packages/flutter/lib/src/animation/listener_helpers.dart index 6f2d9374270..cf125b74536 100644 --- a/packages/flutter/lib/src/animation/listener_helpers.dart +++ b/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 _listeners = []; + + /// 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 localListeners = new List.from(_listeners); for (VoidCallback listener in localListeners) @@ -73,14 +91,27 @@ abstract class AnimationLocalListenersMixin extends _ListenerMixin { /// invoked. abstract class AnimationLocalStatusListenersMixin extends _ListenerMixin { final List _statusListeners = []; + + /// 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 localListeners = new List.from(_statusListeners); for (AnimationStatusListener listener in localListeners) diff --git a/packages/flutter/lib/src/animation/tween.dart b/packages/flutter/lib/src/animation/tween.dart index 194b9038877..645903bf37f 100644 --- a/packages/flutter/lib/src/animation/tween.dart +++ b/packages/flutter/lib/src/animation/tween.dart @@ -82,6 +82,9 @@ class _ChainedEvaluation extends Animatable { /// different than calling the `animate()` method twice, which results in two [Animation] /// separate objects, each configured with a single [Tween]. class Tween extends Animatable { + /// 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 extends Animatable { /// This class specializes the interpolation of Tween to be /// appropriate for colors. class ColorTween extends Tween { + /// 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 { /// This class specializes the interpolation of Tween to be /// appropriate for rectangles. class SizeTween extends Tween { + /// 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 { /// This class specializes the interpolation of Tween to be /// appropriate for rectangles. class RectTween extends Tween { + /// 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 { /// This is the closest approximation to a linear tween that is /// possible with an integer. Compare to [StepTween]. class IntTween extends Tween { + /// 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 { /// 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 { + /// 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 { /// 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 { - 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; diff --git a/packages/flutter/lib/src/foundation/basic_types.dart b/packages/flutter/lib/src/foundation/basic_types.dart index 0d4a98e4f27..aee3576feb4 100644 --- a/packages/flutter/lib/src/foundation/basic_types.dart +++ b/packages/flutter/lib/src/foundation/basic_types.dart @@ -34,18 +34,36 @@ class BitField { 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 { 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; }