More documentation (#10426)

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

@@ -27,6 +27,13 @@ abstract class Curve {
 
   /// Returns a new curve that is the reversed inversion of this one.
   /// This is often useful as the reverseCurve of an [Animation].
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_flipped.png)
+  ///
+  /// See also:
+  ///
+  ///  * [FlippedCurve], the class that is used to implement this getter.
   Curve get flipped => new FlippedCurve(this);
 
   @override
@@ -49,6 +56,8 @@ class _Linear extends Curve {
 ///
 /// The curve rises linearly from 0.0 to 1.0 and then falls discontinuously back
 /// to 0.0 each iteration.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_sawtooth.png)
 class SawTooth extends Curve {
   /// Creates a sawtooth curve.
   ///
@@ -80,6 +89,8 @@ class SawTooth extends Curve {
 /// animation that uses an [Interval] with its [begin] set to 0.5 and its [end]
 /// set to 1.0 will essentially become a three-second animation that starts
 /// three seconds later.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_interval.png)
 class Interval extends Curve {
   /// Creates an interval curve.
   ///
@@ -127,6 +138,8 @@ class Interval extends Curve {
 }
 
 /// A curve that is 0.0 until it hits the threshold, then it jumps to 1.0.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_threshold.png)
 class Threshold extends Curve {
   /// Creates a threshold curve.
   ///
@@ -151,14 +164,17 @@ class Threshold extends Curve {
 
 /// A cubic polynomial mapping of the unit interval.
 ///
-/// See [Curves] for a number of commonly used cubic curves.
-///
-/// See also:
+/// The [Curves] class contains some commonly used cubic curves:
 ///
 ///  * [Curves.ease]
 ///  * [Curves.easeIn]
 ///  * [Curves.easeOut]
 ///  * [Curves.easeInOut]
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_out.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in_out.png)
 class Cubic extends Curve {
   /// Creates a cubic curve.
   ///
@@ -232,6 +248,11 @@ class Cubic extends 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).
+///
+/// This is the class used to implement the [flipped] getter on curves.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_flipped_curve.png)
 class FlippedCurve extends Curve {
   /// Creates a flipped curve.
   ///
@@ -334,6 +355,11 @@ class _BounceInOutCurve extends Curve {
 // ELASTIC CURVES
 
 /// An oscillating curve that grows in magnitude while overshooting its bounds.
+///
+/// An instance of this class using the default period of 0.4 is available as
+/// [Curves.elasticIn].
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in.png)
 class ElasticInCurve extends Curve {
   /// Creates an elastic-in curve.
   ///
@@ -358,6 +384,11 @@ class ElasticInCurve extends Curve {
 }
 
 /// An oscillating curve that shrinks in magnitude while overshooting its bounds.
+///
+/// An instance of this class using the default period of 0.4 is available as
+/// [Curves.elasticOut].
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_out.png)
 class ElasticOutCurve extends Curve {
   /// Creates an elastic-out curve.
   ///
@@ -380,7 +411,13 @@ class ElasticOutCurve extends Curve {
   }
 }
 
-/// An oscillating curve that grows and then shrinks in magnitude while overshooting its bounds.
+/// An oscillating curve that grows and then shrinks in magnitude while
+/// overshooting its bounds.
+///
+/// An instance of this class using the default period of 0.4 is available as
+/// [Curves.elasticInOut].
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in_out.png)
 class ElasticInOutCurve extends Curve {
   /// Creates an elastic-in-out curve.
   ///
@@ -419,6 +456,8 @@ class Curves {
   /// This is the identity map over the unit interval: its [Curve.transform]
   /// method returns its input unmodified. This is useful as a default curve for
   /// cases where a [Curve] is required but no actual curve is desired.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_linear.png)
   static const Curve linear = const _Linear._();
 
   /// A curve where the rate of change starts out quickly and then decelerates; an
@@ -426,18 +465,28 @@ class Curves {
   ///
   /// This is equivalent to the Android `DecelerateInterpolator` class with a unit
   /// factor (the default factor).
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_decelerate.png)
   static const Curve decelerate = const _DecelerateCurve._();
 
   /// A cubic animation curve that speeds up quickly and ends slowly.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease.png)
   static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0);
 
   /// A cubic animation curve that starts slowly and ends quickly.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in.png)
   static const Cubic easeIn = const Cubic(0.42, 0.0, 1.0, 1.0);
 
   /// A cubic animation curve that starts quickly and ends slowly.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_out.png)
   static const Cubic easeOut = const Cubic(0.0, 0.0, 0.58, 1.0);
 
   /// A cubic animation curve that starts slowly, speeds up, and then and ends slowly.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_ease_in_out.png)
   static const Cubic easeInOut = const Cubic(0.42, 0.0, 0.58, 1.0);
 
   /// A curve that starts quickly and eases into its final position.
@@ -445,23 +494,37 @@ class Curves {
   /// Over the course of the animation, the object spends more time near its
   /// final destination. As a result, the user isn’t left waiting for the
   /// animation to finish, and the negative effects of motion are minimized.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_fast_out_slow_in.png)
   static const Cubic fastOutSlowIn = const Cubic(0.4, 0.0, 0.2, 1.0);
 
   /// An oscillating curve that grows in magnitude.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in.png)
   static const Curve bounceIn = const _BounceInCurve._();
 
   /// An oscillating curve that first grows and then shrink in magnitude.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_out.png)
   static const Curve bounceOut = const _BounceOutCurve._();
 
   /// An oscillating curve that first grows and then shrink in magnitude.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_bounce_in_out.png)
   static const Curve bounceInOut = const _BounceInOutCurve._();
 
   /// An oscillating curve that grows in magnitude while overshootings its bounds.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in.png)
   static const ElasticInCurve elasticIn = const ElasticInCurve();
 
   /// An oscillating curve that shrinks in magnitude while overshootings its bounds.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_out.png)
   static const ElasticOutCurve elasticOut = const ElasticOutCurve();
 
   /// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/animation/curve_elastic_in_out.png)
   static const ElasticInOutCurve elasticInOut = const ElasticInOutCurve();
 }

packages/flutter/lib/src/painting/box_fit.dart

@@ -13,22 +13,6 @@ import 'basic_types.dart';
 ///
 /// See also [applyBoxFit], which applies the sizing semantics of these values
 /// (though not the alignment semantics).
-///
-/// The following diagrams show the effects of each value:
-///
-/// ![`fill`: Fill the target box by distorting the source's aspect ratio.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fill.png)
-///
-/// ![`contain`: As large as possible while still containing the source entirely within the target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_contain.png)
-///
-/// ![`cover`: As small as possible while still covering the entire target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_cover.png)
-///
-/// ![`fitWidth`: Make sure the full width of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitWidth.png)
-///
-/// ![`fitHeight`: Make sure the full height of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitHeight.png)
-///
-/// ![`none`: Do not resize the source.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_none.png)
-///
-/// ![`scaleDown`: Same as `contain` if that would shrink the image, otherwise same as `none`.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_scaleDown.png)
 enum BoxFit {
   /// Fill the target box by distorting the source's aspect ratio.
   ///

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -773,7 +773,7 @@ class RenderOpacity extends RenderProxyBox {
 
 /// Signature for a function that creates a [Shader] for a given [Rect].
 ///
-/// Used by [RenderShaderMask].
+/// Used by [RenderShaderMask] and the [ShaderMask] widget.
 typedef Shader ShaderCallback(Rect bounds);
 
 /// Applies a mask generated by a [Shader] to its child.
@@ -1868,7 +1868,14 @@ class RenderFractionalTranslation extends RenderProxyBox {
 ///   }
 ///
 ///   @override
-///   bool shouldRepaint(CustomPainter oldDelegate) => false;
+///   bool shouldRepaint(Sky oldDelegate) {
+///     // Since this Sky painter has no fields, it always paints
+///     // the same thing, and therefore we return false here. If
+///     // we had fields (set from the constructor) then we would
+///     // return true if any of them differed from the same
+///     // fields on the oldDelegate.
+///     return false;
+///   }
 /// }
 /// ```
 ///