Merge pull request #953 from abarth/painting_docs

Add dartdoc for the painting code

packages/flutter/lib/painting/radial_reaction.dart

@@ -20,6 +20,9 @@ int _roundOpacity(double opacity) {
   return (255 * opacity).round();
 }
 
+/// A material design radial ink reaction
+///
+/// See [https://www.google.com/design/spec/animation/responsive-interaction.html#responsive-interaction-radial-action]
 class RadialReaction {
   RadialReaction({
     this.center,
@@ -41,7 +44,10 @@ class RadialReaction {
       ..duration =_kHideDuration;
   }
 
+  /// The center of the circle in which the reaction occurs
   final Point center;
+
+  /// The radius of the circle in which the reaction occurs
   final double radius;
 
   AnimationPerformance _showPerformance;
@@ -54,15 +60,22 @@ class RadialReaction {
   AnimationPerformance _hidePerformance;
   AnimatedValue<double> _fade;
 
-  void show() {
-    _showComplete = _showPerformance.forward();
+  /// Show the reaction
+  ///
+  /// Returns a future that resolves when the reaction is completely revealed.
+  Future show() {
+    return _showComplete = _showPerformance.forward();
   }
 
+  /// Hide the reaction
+  ///
+  /// Returns a future that resolves when the reaction is completely hidden.
   Future hide() async {
     await _showComplete;
     await _hidePerformance.forward();
   }
 
+  /// Call listener whenever the visual appearance of the reaction changes
   void addListener(Function listener) {
     _showPerformance.addListener(listener);
     _hidePerformance.addListener(listener);
@@ -71,6 +84,7 @@ class RadialReaction {
   final Paint _outerPaint = new Paint();
   final Paint _innerPaint = new Paint();
 
+  /// Paint the reaction onto the given canvas at the given offset
   void paint(sky.Canvas canvas, Offset offset) {
     _outerPaint.color = _kOuterColor.withAlpha(_roundOpacity(_outerOpacity.value * _fade.value));
     canvas.drawCircle(center + offset, radius, _outerPaint);

packages/flutter/lib/painting/shadows.dart

@@ -4,11 +4,11 @@
 
 import 'dart:sky' as sky;
 
-/// Helper class to build a Paint DrawLooper that adds shadows to the Paint's
-/// operation.
+/// A helper class to build a [sky.DrawLooper] for drawing shadows
 class ShadowDrawLooperBuilder {
   var builder_ = new sky.LayerDrawLooperBuilder();
 
+  /// Add a shadow with the given parameters
   void addShadow(sky.Offset offset, sky.Color color, double blur) {
     builder_.addLayerOnTop(
           new sky.DrawLooperLayerInfo()
@@ -20,6 +20,7 @@ class ShadowDrawLooperBuilder {
             ..setMaskFilter(new sky.MaskFilter.blur(sky.BlurStyle.normal, blur)));
   }
 
+  /// Returns the draw looper built for the added shadows
   sky.DrawLooper build() {
     builder_.addLayerOnTop(new sky.DrawLooperLayerInfo(), new sky.Paint());
     return builder_.build();

packages/flutter/lib/painting/text_painter.dart

@@ -8,8 +8,9 @@ import 'package:sky/painting/text_style.dart';
 
 export 'package:sky/painting/text_style.dart';
 
-// This must be immutable, because we won't notice when it changes
+/// An immutable span of text
 abstract class TextSpan {
+  // This class must be immutable, because we won't notice when it changes
   sky.Node _toDOM(sky.Document owner);
   String toString([String prefix = '']);
 
@@ -17,11 +18,13 @@ abstract class TextSpan {
   }
 }
 
+/// An immutable span of unstyled text
 class PlainTextSpan extends TextSpan {
   PlainTextSpan(this.text) {
     assert(text != null);
   }
 
+  /// The text contained in the span
   final String text;
 
   sky.Node _toDOM(sky.Document owner) {
@@ -34,13 +37,17 @@ class PlainTextSpan extends TextSpan {
   String toString([String prefix = '']) => '${prefix}${runtimeType}: "${text}"';
 }
 
+/// An immutable text span that applies a style to a list of children
 class StyledTextSpan extends TextSpan {
   StyledTextSpan(this.style, this.children) {
     assert(style != null);
     assert(children != null);
   }
 
+  /// The style to apply to the children
   final TextStyle style;
+
+  /// The children to which the style is applied
   final List<TextSpan> children;
 
   sky.Node _toDOM(sky.Document owner) {
@@ -90,6 +97,7 @@ class StyledTextSpan extends TextSpan {
   }
 }
 
+/// An object that paints a [TextSpan] into a canvas
 class TextPainter {
   TextPainter(TextSpan text) {
     _layoutRoot.rootElement = _document.createElement('p');
@@ -102,6 +110,7 @@ class TextPainter {
   bool _needsLayout = true;
 
   TextSpan _text;
+  /// The (potentially styled) text to paint
   TextSpan get text => _text;
   void set text(TextSpan value) {
     if (_text == value)
@@ -113,6 +122,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
+  /// The minimum width at which to layout the text
   double get minWidth => _layoutRoot.minWidth;
   void set minWidth(value) {
     if (_layoutRoot.minWidth == value)
@@ -121,6 +131,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
+  /// The maximum width at which to layout the text
   double get maxWidth => _layoutRoot.maxWidth;
   void set maxWidth(value) {
     if (_layoutRoot.maxWidth == value)
@@ -129,6 +140,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
+  /// The minimum height at which to layout the text
   double get minHeight => _layoutRoot.minHeight;
   void set minHeight(value) {
     if (_layoutRoot.minHeight == value)
@@ -137,6 +149,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
+  /// The maximum height at which to layout the text
   double get maxHeight => _layoutRoot.maxHeight;
   void set maxHeight(value) {
     if (_layoutRoot.maxHeight == value)
@@ -144,21 +157,25 @@ class TextPainter {
     _layoutRoot.maxHeight = value;
   }
 
+  /// The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds
   double get minContentWidth {
     assert(!_needsLayout);
     return _layoutRoot.rootElement.minContentWidth;
   }
 
+  /// The width at which increasing the width of the text no longer decreases the height
   double get maxContentWidth {
     assert(!_needsLayout);
     return _layoutRoot.rootElement.maxContentWidth;
   }
 
+  /// The height required to paint the text completely within its bounds
   double get height {
     assert(!_needsLayout);
     return _layoutRoot.rootElement.height;
   }
 
+  /// The distance from the top of the text to the first baseline of the given type
   double computeDistanceToActualBaseline(TextBaseline baseline) {
     assert(!_needsLayout);
     sky.Element root = _layoutRoot.rootElement;
@@ -168,6 +185,7 @@ class TextPainter {
     }
   }
 
+  /// Compute the visual position of the glyphs for painting the text
   void layout() {
     if (!_needsLayout)
       return;
@@ -175,6 +193,7 @@ class TextPainter {
     _needsLayout = false;
   }
 
+  /// Paint the text onto the given canvas at the given offset
   void paint(sky.Canvas canvas, sky.Offset offset) {
     assert(!_needsLayout && "Please call layout() before paint() to position the text before painting it." is String);
     // TODO(ianh): Make LayoutRoot support a paint offset so we don't

packages/flutter/lib/painting/text_style.dart

@@ -4,23 +4,118 @@
 
 import 'dart:sky';
 
-enum FontWeight { w100, w200, w300, w400, w500, w600, w700, w800, w900 }
+/// The thickness of the glyphs used to draw the text
+enum FontWeight {
+  /// Thin, the least thick
+  w100,
+
+  /// Extra-light
+  w200,
+
+  /// Light
+  w300,
+
+  /// Normal / regular / plain
+  w400,
+
+  /// Medium
+  w500,
+
+  /// Semi-bold
+  w600,
+
+  /// Bold
+  w700,
+
+  /// Extra-bold
+  w800,
+
+  /// Black, the most thick
+  w900
+}
+
+/// A normal font weight
 const normal = FontWeight.w400;
+
+/// A bold font weight
 const bold = FontWeight.w700;
 
-enum FontStyle { normal, italic, oblique }
+/// Whether to slant the glyphs in the font
+enum FontStyle {
+  /// Use the upright glyphs
+  normal,
+
+  /// Use glyphs designed for slanting
+  italic,
+
+  /// Use the upright glyphs but slant them during painting
+  oblique  // TODO(abarth): Remove. We don't really support this value.
+}
+
+/// Whether to align text horizontally
+enum TextAlign {
+  /// Align the text on the left edge of the container
+  left,
+
+  /// Align the text on the right edge of the container
+  right,
+
+  /// Align the text in the center of the container
+  center
+}
+
+/// A horizontal line used for aligning text
+enum TextBaseline {
+  // The horizontal line used to align the bottom of glyphs for alphabetic characters
+  alphabetic,
+
+  // The horizontal line used to align ideographic characters
+  ideographic
+}
 
-enum TextAlign { left, right, center }
+/// A linear decoration to draw near the text
+enum TextDecoration {
+  /// Do not draw a decoration
+  none,
 
-enum TextBaseline { alphabetic, ideographic }
+  /// Draw a line underneath each line of text
+  underline,
 
-enum TextDecoration { none, underline, overline, lineThrough }
+  /// Draw a line above each line of text
+  overline,
+
+  /// Draw a line through each line of text
+  lineThrough
+}
+
+/// Draw a line underneath each line of text
 const underline = const <TextDecoration>[TextDecoration.underline];
+
+/// Draw a line above each line of text
 const overline = const <TextDecoration>[TextDecoration.overline];
+
+/// Draw a line through each line of text
 const lineThrough = const <TextDecoration>[TextDecoration.lineThrough];
 
-enum TextDecorationStyle { solid, double, dotted, dashed, wavy }
+/// The style in which to draw a text decoration
+enum TextDecorationStyle {
+  /// Draw a solid line
+  solid,
+
+  /// Draw two lines
+  double,
+
+  /// Draw a dotted line
+  dotted,
+
+  /// Draw a dashed line
+  dashed,
+
+  /// Draw a sinusoidal line
+  wavy
+}
 
+/// An immutable style in which paint text
 class TextStyle {
   const TextStyle({
     this.color,
@@ -36,18 +131,42 @@ class TextStyle {
     this.decorationStyle
   });
 
+  /// The color to use when painting the text
   final Color color;
+
+  /// The name of the font to use when painting the text
   final String fontFamily;
-  final double fontSize; // in pixels
+
+  /// The size of gyphs (in logical pixels) to use when painting the text
+  final double fontSize;
+
+  /// The font weight to use when painting the text
   final FontWeight fontWeight;
+
+  /// The font style to use when painting the text
   final FontStyle fontStyle;
+
+  /// How the text should be aligned (applies only to the outermost
+  /// StyledTextSpan, which establishes the container for the text)
   final TextAlign textAlign;
+
+  /// The baseline to use for aligning the text
   final TextBaseline textBaseline;
-  final double height; // multiple of fontSize
+
+  /// The distance between the text baselines, as a multiple of the font size
+  final double height;
+
+  /// A list of decorations to paint near the text
   final List<TextDecoration> decoration; // TODO(ianh): Switch this to a Set<> once Dart supports constant Sets
+
+  /// The color in which to paint the text decorations
   final Color decorationColor;
+
+  /// The style in which to paint the text decorations
   final TextDecorationStyle decorationStyle;
 
+  /// Returns a new text style that matches this text style but with the given
+  /// values replaced
   TextStyle copyWith({
     Color color,
     String fontFamily,
@@ -76,6 +195,8 @@ class TextStyle {
     );
   }
 
+  /// Returns a new text style that matches this text style but with some values
+  /// replaced by the non-null parameters of the given text style
   TextStyle merge(TextStyle other) {
     return copyWith(
       color: other.color,
@@ -124,6 +245,10 @@ class TextStyle {
     return toCSS[decorationStyle];
   }
 
+  /// Program this text style into the engine
+  ///
+  /// Note: This function will likely be removed when we refactor the interface
+  /// between the framework and the engine
   void applyToCSSStyle(CSSStyleDeclaration cssStyle) {
     if (color != null) {
       cssStyle['color'] = _colorToCSSString(color);
@@ -163,6 +288,10 @@ class TextStyle {
     }
   }
 
+  /// Program the container aspects of this text style into the engine
+  ///
+  /// Note: This function will likely be removed when we refactor the interface
+  /// between the framework and the engine
   void applyToContainerCSSStyle(CSSStyleDeclaration cssStyle) {
     if (textAlign != null) {
       cssStyle['text-align'] = const {

packages/flutter/lib/widgets/README.md

@@ -131,7 +131,8 @@ import 'package:sky/widgets.dart';
 final BoxDecoration _decoration = new BoxDecoration(
   borderRadius: 5.0,
   gradient: new LinearGradient(
-    endPoints: [ Point.origin, const Point(0.0, 36.0) ],
+    start: Point.origin,
+    end: const Point(0.0, 36.0),
     colors: [ const Color(0xFFEEEEEE), const Color(0xFFCCCCCC) ]
   )
 );

packages/flutter/lib/widgets/animated_container.dart

@@ -25,7 +25,7 @@ class AnimatedBoxDecorationValue extends AnimatedValue<BoxDecoration> {
   AnimatedBoxDecorationValue(BoxDecoration begin, { BoxDecoration end, Curve curve: linear })
     : super(begin, end: end, curve: curve);
 
-  BoxDecoration lerp(double t) => lerpBoxDecoration(begin, end, t);
+  BoxDecoration lerp(double t) => BoxDecoration.lerp(begin, end, t);
 }
 
 class AnimatedEdgeDimsValue extends AnimatedValue<EdgeDims> {