Complete dartdocs for painting.dart (#4003)

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);