Complete dartdocs for painting.dart (#4003)

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

@@ -38,6 +38,9 @@ enum BorderStyle {
 
 /// A side of a border of a box.
 class BorderSide {
+  /// Creates the side of a border.
+  ///
+  /// By default, the border is 1.0 logical pixels wide and solid black.
   const BorderSide({
     this.color: const Color(0xFF000000),
     this.width: 1.0,
@@ -134,6 +137,9 @@ class BorderSide {
 
 /// A border of a box, comprised of four sides.
 class Border {
+  /// Creates a border.
+  ///
+  /// All the sides of the border default to [BorderSide.none].
   const Border({
     this.top: BorderSide.none,
     this.right: BorderSide.none,
@@ -222,6 +228,7 @@ class Border {
     );
   }
 
+  /// Paints the border within the given rect on the given canvas.
   void paint(Canvas canvas, Rect rect, {
     BoxShape shape: BoxShape.rectangle,
     double borderRadius: null
@@ -373,14 +380,19 @@ class Border {
 
 /// A shadow cast by a box.
 ///
-/// Note: BoxShadow can cast non-rectangular shadows if the box is
-/// non-rectangular (e.g., has a border radius or a circular shape).
+/// BoxShadow can cast non-rectangular shadows if the box is non-rectangular
+/// (e.g., has a border radius or a circular shape).
+///
 /// This class is similar to CSS box-shadow.
 class BoxShadow {
+  /// Creates a box shadow.
+  ///
+  /// By default, the shadow is solid black with zero [offset], [blurRadius],
+  /// and [spreadRadius].
   const BoxShadow({
-    this.color,
-    this.offset,
-    this.blurRadius,
+    this.color: const Color(0xFF000000),
+    this.offset: Offset.zero,
+    this.blurRadius: 0.0,
     this.spreadRadius: 0.0
   });
 
@@ -393,6 +405,7 @@ class BoxShadow {
   /// The standard deviation of the Gaussian to convolve with the box's shape.
   final double blurRadius;
 
+  /// The amount the box should be inflated prior to applying the blur.
   final double spreadRadius;
 
   /// The [blurRadius] in sigmas instead of logical pixels.
@@ -479,11 +492,17 @@ abstract class Gradient {
   /// Abstract const constructor. This constructor enables subclasses to provide
   /// const constructors so that they can be used in const expressions.
   const Gradient();
+
+  /// Creates a [Shader] for this gradient to fill the given rect.
   Shader createShader(Rect rect);
 }
 
 /// A 2D linear gradient.
 class LinearGradient extends Gradient {
+  /// Creates a linear graident.
+  ///
+  /// The [colors] argument must not be null. If [stops] is non-null, it must
+  /// have the same length as [colors].
   const LinearGradient({
     this.begin: FractionalOffset.centerLeft,
     this.end: FractionalOffset.centerRight,
@@ -510,13 +529,14 @@ class LinearGradient extends Gradient {
 
   /// The colors the gradient should obtain at each of the stops.
   ///
-  /// Note: This list must have the same length as [stops].
+  /// If [stops] is non-null, this list must have the same length as [stops].
   final List<Color> colors;
 
-  /// A list of values from 0.0 to 1.0 that denote fractions of the vector from start to end.
+  /// A list of values from 0.0 to 1.0 that denote fractions of the vector from
+  /// start to end.
   ///
-  /// Note: If specified, this list must have the same length as [colors]. Otherwise the colors
-  /// are distributed evenly between [begin] and [end].
+  /// If non-null, this list must have the same length as [colors]. Otherwise
+  /// the colors are distributed evenly between [begin] and [end].
   final List<double> stops;
 
   /// How this gradient should tile the plane.
@@ -573,6 +593,10 @@ class LinearGradient extends Gradient {
 
 /// A 2D radial gradient.
 class RadialGradient extends Gradient {
+  /// Creates a radial graident.
+  ///
+  /// The [colors] argument must not be null. If [stops] is non-null, it must
+  /// have the same length as [colors].
   const RadialGradient({
     this.center: FractionalOffset.center,
     this.radius: 0.5,
@@ -598,7 +622,7 @@ class RadialGradient extends Gradient {
 
   /// The colors the gradient should obtain at each of the stops.
   ///
-  /// Note: This list must have the same length as [stops].
+  /// If [stops] is non-null, this list must have the same length as [stops].
   final List<Color> colors;
 
   /// A list of values from 0.0 to 1.0 that denote concentric rings.
@@ -606,7 +630,9 @@ class RadialGradient extends Gradient {
   /// The rings are centered at [center] and have a radius equal to the value of
   /// the stop times [radius].
   ///
-  /// Note: This list must have the same length as [colors].
+  /// If non-null, this list must have the same length as [colors]. Otherwise
+  /// the colors are distributed evenly between the [center] and the ring at
+  /// [radius].
   final List<double> stops;
 
   /// How this gradient should tile the plane.
@@ -855,51 +881,96 @@ void paintImage({
 /// FractionalOffset(1.0, 0.0) represents the top right of the Size,
 /// FractionalOffset(0.0, 1.0) represents the bottom left of the Size,
 class FractionalOffset {
+  /// Creates a fractional offset.
+  ///
+  /// The [dx] and [dy] arguments must not be null.
   const FractionalOffset(this.dx, this.dy);
 
+  /// The distance fraction in the horizontal direction.
+  ///
+  /// A value of 0.0 cooresponds to the leftmost edge. A value of 1.0
+  /// cooresponds to the rightmost edge.
   final double dx;
+
+  /// The distance fraction in the vertical direction.
+  ///
+  /// A value of 0.0 cooresponds to the topmost edge. A value of 1.0
+  /// cooresponds to the bottommost edge.
   final double dy;
 
+  /// The top left corner.
   static const FractionalOffset topLeft = const FractionalOffset(0.0, 0.0);
+
+  /// The center point along the top edge.
   static const FractionalOffset topCenter = const FractionalOffset(0.5, 0.0);
+
+  /// The top right corner.
   static const FractionalOffset topRight = const FractionalOffset(1.0, 0.0);
 
+  /// The bottom left corner.
   static const FractionalOffset bottomLeft = const FractionalOffset(0.0, 1.0);
+
+  /// The center point along the bottom edge.
   static const FractionalOffset bottomCenter = const FractionalOffset(0.5, 1.0);
+
+  /// The bottom right corner.
   static const FractionalOffset bottomRight = const FractionalOffset(1.0, 1.0);
 
+  /// The center point along the left edge.
   static const FractionalOffset centerLeft = const FractionalOffset(0.0, 0.5);
+
+  /// The center point along the right edge.
   static const FractionalOffset centerRight = const FractionalOffset(1.0, 0.5);
 
+  /// The center point, both horizontally and vertically.
   static const FractionalOffset center = const FractionalOffset(0.5, 0.5);
 
+  /// Returns the negation of the given fractional offset.
   FractionalOffset operator -() {
     return new FractionalOffset(-dx, -dy);
   }
+
+  /// Returns the difference between two fractional offsets.
   FractionalOffset operator -(FractionalOffset other) {
     return new FractionalOffset(dx - other.dx, dy - other.dy);
   }
+
+  /// Returns the sum of two fractional offsets.
   FractionalOffset operator +(FractionalOffset other) {
     return new FractionalOffset(dx + other.dx, dy + other.dy);
   }
+
+  /// Scales the fractional offset in each dimension by the given factor.
   FractionalOffset operator *(double other) {
     return new FractionalOffset(dx * other, dy * other);
   }
+
+  /// Divides the fractional offset in each dimension by the given factor.
   FractionalOffset operator /(double other) {
     return new FractionalOffset(dx / other, dy / other);
   }
+
+  /// Integer divides the fractional offset in each dimension by the given factor.
   FractionalOffset operator ~/(double other) {
     return new FractionalOffset((dx ~/ other).toDouble(), (dy ~/ other).toDouble());
   }
+
+  /// Computes the remainder in each dimension by the given factor.
   FractionalOffset operator %(double other) {
     return new FractionalOffset(dx % other, dy % other);
   }
+
+  /// Returns the offset that is this fraction in the direction of the given offset.
   Offset alongOffset(Offset other) {
     return new Offset(dx * other.dx, dy * other.dy);
   }
+
+  /// Returns the offset that is this fraction within the given size.
   Offset alongSize(Size other) {
     return new Offset(dx * other.width, dy * other.height);
   }
+
+  /// Returns the point that is this fraction within the given rect.
   Point withinRect(Rect rect) {
     return new Point(rect.left + dx * rect.width, rect.top + dy * rect.height);
   }
@@ -915,6 +986,12 @@ class FractionalOffset {
 
   @override
   int get hashCode => hashValues(dx, dy);
+
+  /// Linearly interpolate between two EdgeInsets.
+  ///
+  /// If either is null, this function interpolates from [FractionalOffset.topLeft].
+  // TODO(abarth): Consider interpolating from [FractionalOffset.center] instead
+  // to remove upper-left bias.
   static FractionalOffset lerp(FractionalOffset a, FractionalOffset b, double t) {
     if (a == null && b == null)
       return null;
@@ -931,6 +1008,9 @@ class FractionalOffset {
 
 /// A background image for a box.
 class BackgroundImage {
+  /// Creates a background image.
+  ///
+  /// The [image] argument must not be null.
   BackgroundImage({
     ImageResource image,
     this.fit,
@@ -1041,13 +1121,23 @@ enum BoxShape {
 
 /// An immutable description of how to paint a box.
 class BoxDecoration extends Decoration {
+  /// Creates a box decoration.
+  ///
+  /// * If [backgroundColor] is null, this decoration does not paint a background color.
+  /// * If [backgroundImage] is null, this decoration does not paint a background image.
+  /// * If [border] is null, this decoration does not paint a border.
+  /// * If [borderRadius] is null, this decoration use more efficient background
+  ///   painting commands. The [borderRadius] argument must be be null if [shape] is
+  ///   [BoxShape.circle].
+  /// * If [boxShadow] is null, this decoration does not paint a shadow.
+  /// * If [gradient] is null, this decoration does not paint gradients.
   const BoxDecoration({
-    this.backgroundColor, // null = don't draw background color
-    this.backgroundImage, // null = don't draw background image
-    this.border, // null = don't draw border
-    this.borderRadius, // null = use more efficient background drawing; note that this must be null for circles
-    this.boxShadow, // null = don't draw shadows
-    this.gradient, // null = don't allocate gradient objects
+    this.backgroundColor,
+    this.backgroundImage,
+    this.border,
+    this.borderRadius,
+    this.boxShadow,
+    this.gradient,
     this.shape: BoxShape.rectangle
   });
 

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

@@ -4,7 +4,16 @@
 
 import 'dart:ui' show Color, lerpDouble, hashValues;
 
+/// A color represented using [alpha], [hue], [saturation], and [value].
+///
+/// An [HSVColor] is represented in a parameter space that's motivated by human
+/// perception. The representation is useful for some color computations (e.g.,
+/// rotating the hue through the colors of the rainbow).
 class HSVColor {
+  /// Creates a color.
+  ///
+  /// All the arguments must not be null and be in their respective ranges. See
+  /// the fields for each parameter for a description of their ranges.
   const HSVColor.fromAHSV(this.alpha, this.hue, this.saturation, this.value);
 
   /// Alpha, from 0.0 to 1.0.
@@ -19,18 +28,22 @@ class HSVColor {
   /// Value, from 0.0 to 1.0.
   final double value;
 
+  /// Returns a copy of this color with the alpha parameter replaced with the given value.
   HSVColor withAlpha(double alpha) {
     return new HSVColor.fromAHSV(alpha, hue, saturation, value);
   }
 
+  /// Returns a copy of this color with the hue parameter replaced with the given value.
   HSVColor withHue(double hue) {
     return new HSVColor.fromAHSV(alpha, hue, saturation, value);
   }
 
+  /// Returns a copy of this color with the saturation parameter replaced with the given value.
   HSVColor withSaturation(double saturation) {
     return new HSVColor.fromAHSV(alpha, hue, saturation, value);
   }
 
+  /// Returns a copy of this color with the value parameter replaced with the given value.
   HSVColor withValue(double value) {
     return new HSVColor.fromAHSV(alpha, hue, saturation, value);
   }

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

@@ -11,14 +11,14 @@ import 'basic_types.dart';
 /// Typically used for an offset from each of the four sides of a box. For
 /// example, the padding inside a box can be represented using this class.
 class EdgeInsets {
-  /// Constructs insets from offsets from the left, top, right, and bottom.
+  /// Creates insets from offsets from the left, top, right, and bottom.
   const EdgeInsets.fromLTRB(this.left, this.top, this.right, this.bottom);
 
-  /// Constructs insets where all the offsets are value.
+  /// Creates insets where all the offsets are value.
   const EdgeInsets.all(double value)
       : left = value, top = value, right = value, bottom = value;
 
-  /// Constructs insets with only the given values non-zero.
+  /// Creates insets with only the given values non-zero.
   const EdgeInsets.only({
     this.left: 0.0,
     this.top: 0.0,
@@ -26,11 +26,12 @@ class EdgeInsets {
     this.bottom: 0.0
   });
 
-  /// Constructs insets with symmetrical vertical and horizontal offsets.
+  /// Creates insets with symmetrical vertical and horizontal offsets.
   const EdgeInsets.symmetric({ double vertical: 0.0,
                              double horizontal: 0.0 })
     : left = horizontal, top = vertical, right = horizontal, bottom = vertical;
 
+  /// Creates insets that match the given window padding.
   EdgeInsets.fromWindowPadding(ui.WindowPadding padding)
     : left = padding.left, top = padding.top, right = padding.right, bottom = padding.bottom;
 
@@ -61,10 +62,16 @@ class EdgeInsets {
   /// An EdgeInsets with top and bottom as well as left and right flipped.
   EdgeInsets get flipped => new EdgeInsets.fromLTRB(left, top, right, bottom);
 
+  /// Returns a new rect that is bigger than the given rect in each direction by
+  /// the amount of inset in each direction. Specifically, the left edge of the
+  /// rect is moved left by [left], the top edge of the rect is moved up by
+  /// [top], the right edge of the rect is moved right by [right], and the
+  /// bottom edge of the rect is moved down by [bottom].
   Rect inflateRect(Rect rect) {
     return new Rect.fromLTRB(rect.left - left, rect.top - top, rect.right + right, rect.bottom + bottom);
   }
 
+  /// Returns the difference between two EdgeInsets.
   EdgeInsets operator -(EdgeInsets other) {
     return new EdgeInsets.fromLTRB(
       left - other.left,
@@ -74,6 +81,7 @@ class EdgeInsets {
     );
   }
 
+  /// Returns the sum of two EdgeInsets.
   EdgeInsets operator +(EdgeInsets other) {
     return new EdgeInsets.fromLTRB(
       left + other.left,
@@ -83,6 +91,7 @@ class EdgeInsets {
     );
   }
 
+  /// Scales the EdgeInsets in each dimension by the given factor.
   EdgeInsets operator *(double other) {
     return new EdgeInsets.fromLTRB(
       left * other,
@@ -92,6 +101,7 @@ class EdgeInsets {
     );
   }
 
+  /// Divides the EdgeInsets in each dimension by the given factor.
   EdgeInsets operator /(double other) {
     return new EdgeInsets.fromLTRB(
       left / other,
@@ -101,6 +111,7 @@ class EdgeInsets {
     );
   }
 
+  /// Integer divides the EdgeInsets in each dimension by the given factor.
   EdgeInsets operator ~/(double other) {
     return new EdgeInsets.fromLTRB(
       (left ~/ other).toDouble(),
@@ -110,6 +121,7 @@ class EdgeInsets {
     );
   }
 
+  /// Computes the remainder in each dimension by the given factor.
   EdgeInsets operator %(double other) {
     return new EdgeInsets.fromLTRB(
       left % other,

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

@@ -8,6 +8,13 @@ export 'dart:ui' show TextAffinity, TextPosition;
 
 /// A range of characters in a string of text.
 class TextRange {
+  /// Creates a text range.
+  ///
+  /// The [start] and [end] arguments must not be null. Both the [start] and
+  /// [end] must either be greater than or equal to zero or both exactly -1.
+  ///
+  /// Instead of creating an empty text range, consider using the [empty]
+  /// constant.
   const TextRange({ this.start, this.end });
 
   /// A text range that starts and ends at offset.
@@ -19,9 +26,13 @@ class TextRange {
   static const TextRange empty = const TextRange(start: -1, end: -1);
 
   /// The index of the first character in the range.
+  ///
+  /// If [start] and [end] are both -1, the text range is empty.
   final int start;
 
   /// The next index after the characters in this range.
+  ///
+  /// If [start] and [end] are both -1, the text range is empty.
   final int end;
 
   /// Whether this range represents a valid position in the text.
@@ -74,6 +85,9 @@ class TextRange {
 
 /// A range of text that represents a selection.
 class TextSelection extends TextRange {
+  /// Creates a text selection.
+  ///
+  /// The [baseOffset] and [extentOffset] arguments must not be null.
   const TextSelection({
     int baseOffset,
     int extentOffset,
@@ -86,11 +100,23 @@ class TextSelection extends TextRange {
          end: baseOffset < extentOffset ? extentOffset : baseOffset
        );
 
+  /// Creates a collapsed selection at the given offset.
+  ///
+  /// A collapsed selection starts and ends at the same offset, which means it
+  /// contains zero characters but instead serves as an insertion point in the
+  /// text.
+  ///
+  /// The [offset] argument must not be null.
   const TextSelection.collapsed({
     int offset,
     this.affinity: TextAffinity.downstream
   }) : baseOffset = offset, extentOffset = offset, isDirectional = false, super.collapsed(offset);
 
+  /// Creates a collapsed selection at the given text position.
+  ///
+  /// A collapsed selection starts and ends at the same offset, which means it
+  /// contains zero characters but instead serves as an insertion point in the
+  /// text.
   TextSelection.fromPosition(TextPosition position)
     : baseOffset = position.offset,
       extentOffset = position.offset,

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

@@ -229,6 +229,13 @@ class TextPainter {
     return _paragraph.getPositionForOffset(offset);
   }
 
+  /// Returns the text range of the word at the given offset. Characters not
+  /// part of a word, such as spaces, symbols, and punctuation, have word breaks
+  /// on both sides. In such cases, this method will return a text range that
+  /// contains the given text position.
+  ///
+  /// Word boundaries are defined more precisely in Unicode Standard Annex #29
+  /// <http://www.unicode.org/reports/tr29/#Word_Boundaries>.
   TextRange getWordBoundary(TextPosition position) {
     assert(!_needsLayout);
     List<int> indices = _paragraph.getWordBoundary(position.offset);

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

@@ -9,6 +9,7 @@ import 'package:vector_math/vector_math_64.dart';
 
 import 'basic_types.dart';
 
+/// Utility functions for working with matrices.
 class MatrixUtils {
   MatrixUtils._();
 
@@ -68,6 +69,7 @@ class MatrixUtils {
         && a.storage[15] == b.storage[15];
   }
 
+  /// Whether the given matrix is the identity matrix.
   static bool isIdentity(Matrix4 a) {
     assert(a != null);
     return a.storage[0] == 1.0 // col 1
@@ -88,6 +90,10 @@ class MatrixUtils {
         && a.storage[15] == 1.0;
   }
 
+  /// Applies the given matrix as a perspective transform to the given point.
+  ///
+  /// This function assumes the given point has a z-coordinate of 0.0. The
+  /// z-coordinate of the result is ignored.
   static Point transformPoint(Matrix4 transform, Point point) {
     Vector3 position3 = new Vector3(point.x, point.y, 0.0);
     Vector3 transformed3 = transform.perspectiveTransform(position3);
@@ -101,6 +107,12 @@ class MatrixUtils {
     return math.max(a, math.max(b, math.max(c, d)));
   }
 
+  /// Returns a rect that bounds the result of applying the given matrix as a
+  /// perspective transform to the given rect.
+  ///
+  /// This function assumes the given rect is in the plane with z equals 0.0.
+  /// The transformed rect is then projected back into the plane with z equals
+  /// 0.0 before computing its bounding rect.
   static Rect transformRect(Rect rect, Matrix4 transform) {
     assert(rect != null);
     assert(transform.determinant != 0.0);

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

@@ -41,9 +41,9 @@ enum Axis {
 /// * `0.0 <= minWidth <= maxWidth <= double.INFINITY`
 /// * `0.0 <= minHeight <= maxHeight <= double.INFINITY`
 ///
-/// Note: `double.INFINITY` is a legal value for each constraint.
+/// [double.INFINITY] is a legal value for each constraint.
 class BoxConstraints extends Constraints {
-  /// Constructs box constraints with the given constraints
+  /// Creates box constraints with the given constraints.
   const BoxConstraints({
     this.minWidth: 0.0,
     this.maxWidth: double.INFINITY,
@@ -51,19 +51,30 @@ class BoxConstraints extends Constraints {
     this.maxHeight: double.INFINITY
   });
 
+  /// The minimum width that satisfies the constraints.
   final double minWidth;
+
+  /// The maximum width that satisfies the constraints.
+  ///
+  /// Might be [double.INFINITY].
   final double maxWidth;
+
+  /// The minimum height that satisfies the constraints.
   final double minHeight;
+
+  /// The maximum height that satisfies the constraints.
+  ///
+  /// Might be [double.INFINITY].
   final double maxHeight;
 
-  /// Constructs box constraints that is respected only by the given size.
+  /// Creates box constraints that is respected only by the given size.
   BoxConstraints.tight(Size size)
     : minWidth = size.width,
       maxWidth = size.width,
       minHeight = size.height,
       maxHeight = size.height;
 
-  /// Constructs box constraints that require the given width or height.
+  /// Creates box constraints that require the given width or height.
   const BoxConstraints.tightFor({
     double width,
     double height
@@ -72,14 +83,14 @@ class BoxConstraints extends Constraints {
       minHeight = height != null ? height : 0.0,
       maxHeight = height != null ? height : double.INFINITY;
 
-  /// Constructs box constraints that forbid sizes larger than the given size.
+  /// Creates box constraints that forbid sizes larger than the given size.
   BoxConstraints.loose(Size size)
     : minWidth = 0.0,
       maxWidth = size.width,
       minHeight = 0.0,
       maxHeight = size.height;
 
-  /// Constructs box constraints that expand to fill another box contraints.
+  /// Creates box constraints that expand to fill another box contraints.
   ///
   /// If width or height is given, the constraints will require exactly the
   /// given value in the given dimension.

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

@@ -25,7 +25,7 @@ const double _kMaxHeight = 100000.0;
 /// Again to help simplify the class, this box tries to be 100000.0 pixels wide
 /// and high, to approximate being infinitely high but without using infinities.
 class RenderErrorBox extends RenderBox {
-  /// Constructs a RenderErrorBox render object.
+  /// Creates a RenderErrorBox render object.
   ///
   /// A message can optionally be provided. If a message is provided, an attempt
   /// will be made to render the message when the box paints.

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

@@ -1316,7 +1316,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   /// Subclasses that set [sizedByParent] to true should override this function
   /// to compute their size.
   ///
-  /// Note: This function is called only if [sizedByParent] is true.
+  /// This function is called only if [sizedByParent] is true.
   void performResize();
 
   /// Do the work of computing the layout for this render object.

packages/flutter/lib/src/widgets/framework.dart

@@ -115,7 +115,7 @@ typedef void GlobalKeyRemoveListener(GlobalKey key);
 /// [UniqueKey] instead.
 @optionalTypeArgs
 abstract class GlobalKey<T extends State<StatefulWidget>> extends Key {
-  /// Constructs a LabeledGlobalKey, which is a GlobalKey with a label used for debugging.
+  /// Creates a LabeledGlobalKey, which is a GlobalKey with a label used for debugging.
   /// The label is not used for comparing the identity of the key.
   factory GlobalKey({ String debugLabel }) => new LabeledGlobalKey<T>(debugLabel); // the label is purely for debugging purposes and is otherwise ignored
 
@@ -564,7 +564,7 @@ abstract class RenderObjectWidget extends Widget {
   @override
   RenderObjectElement createElement();
 
-  /// Constructs an instance of the RenderObject class that this
+  /// Creates an instance of the RenderObject class that this
   /// RenderObjectWidget represents, using the configuration described by this
   /// RenderObjectWidget.
   RenderObject createRenderObject(BuildContext context);