Merge pull request #1644 from abarth/doc_widget2

Add more dartdoc to widgets.dart

examples/rendering/lib/sector_layout.dart

@@ -91,7 +91,7 @@ abstract class RenderSector extends RenderObject {
     assert(deltaTheta <= math.max(constraints.minDeltaTheta, constraints.maxDeltaTheta));
   }
   void performResize() {
-    // default behaviour for subclasses that have sizedByParent = true
+    // default behavior for subclasses that have sizedByParent = true
     deltaRadius = constraints.constrainDeltaRadius(0.0);
     deltaTheta = constraints.constrainDeltaTheta(0.0);
   }

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

@@ -395,7 +395,7 @@ class RenderBlockViewport extends RenderBlockBase {
   }
 
   // We don't override computeDistanceToActualBaseline(), because we
-  // want the default behaviour (returning null). Otherwise, as you
+  // want the default behavior (returning null). Otherwise, as you
   // scroll the RenderBlockViewport, it would shift in its parent if
   // the parent was baseline-aligned, which makes no sense.
 

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

@@ -670,7 +670,7 @@ abstract class RenderBox extends RenderObject {
     super.markNeedsLayout();
   }
   void performResize() {
-    // default behaviour for subclasses that have sizedByParent = true
+    // default behavior for subclasses that have sizedByParent = true
     size = constraints.constrain(Size.zero);
     assert(!size.isInfinite);
   }

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

@@ -810,7 +810,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   void debugAssertDoesMeetConstraints();
 
   /// When true, debugAssertDoesMeetConstraints() is currently
-  /// executing asserts for verifying the consistent behaviour of
+  /// executing asserts for verifying the consistent behavior of
   /// intrinsic dimensions methods.
   ///
   /// This should only be set by debugAssertDoesMeetConstraints()

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

@@ -158,7 +158,7 @@ class SemanticsNode extends AbstractNode {
     _newChildren ??= <SemanticsNode>[];
     _newChildren.addAll(children);
     // we do the asserts afterwards because children is an Iterable
-    // and doing the asserts before would mean the behaviour is
+    // and doing the asserts before would mean the behavior is
     // different in checked mode vs release mode (if you walk an
     // iterator after having reached the end, it'll just start over;
     // the values are not cached).

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

@@ -216,7 +216,7 @@ class RenderPadding extends RenderShiftedBox {
 /// By default, sizes to be as big as possible in both axes. If either axis is
 /// unconstrained, then in that direction it will be sized to fit the child's
 /// dimensions. Using widthFactor and heightFactor you can force this latter
-/// behaviour in all cases.
+/// behavior in all cases.
 class RenderPositionedBox extends RenderShiftedBox {
   RenderPositionedBox({
     RenderBox child,
@@ -371,7 +371,7 @@ class RenderPositionedBox extends RenderShiftedBox {
 /// For example, if you wanted a box to always render 50 pixels high, regardless
 /// of where it was rendered, you would wrap it in a RenderOverflow with
 /// minHeight and maxHeight set to 50.0. Generally speaking, to avoid confusing
-/// behaviour around hit testing, a RenderOverflowBox should usually be wrapped
+/// behavior around hit testing, a RenderOverflowBox should usually be wrapped
 /// in a RenderClipRect.
 ///
 /// The child is positioned at the top left of the box. To position a smaller

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

@@ -115,7 +115,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
   }
 
   // We don't override computeDistanceToActualBaseline(), because we
-  // want the default behaviour (returning null). Otherwise, as you
+  // want the default behavior (returning null). Otherwise, as you
   // scroll the RenderViewport, it would shift in its parent if the
   // parent was baseline-aligned, which makes no sense.
 

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

@@ -364,7 +364,7 @@ class Padding extends OneChildRenderObjectWidget {
 /// By default, sizes to be as big as possible in both axes. If either axis is
 /// unconstrained, then in that direction it will be sized to fit the child's
 /// dimensions. Using widthFactor and heightFactor you can force this latter
-/// behaviour in all cases.
+/// behavior in all cases.
 class Align extends OneChildRenderObjectWidget {
   Align({
     Key key,

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

@@ -1834,7 +1834,7 @@ typedef void WidgetsExceptionHandler(String context, dynamic exception, StackTra
 /// the exception occurred, and may include additional details such as
 /// descriptions of the objects involved. The 'exception' argument contains the
 /// object that was thrown, and the 'stack' argument contains the stack trace.
-/// If no callback is set, then a default behaviour consisting of dumping the
+/// If no callback is set, then a default behavior consisting of dumping the
 /// context, exception, and stack trace to the console is used instead.
 WidgetsExceptionHandler debugWidgetsExceptionHandler;
 void _debugReportException(String context, dynamic exception, StackTrace stack) {

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

@@ -13,9 +13,15 @@ import 'basic.dart';
 import 'framework.dart';
 import 'gesture_detector.dart';
 
+/// Visualizes the semantics for the child.
+///
+/// This widget is useful for understand how an app presents itself to
+/// accessibility technology.
 class SemanticsDebugger extends StatefulComponent {
   const SemanticsDebugger({ Key key, this.child }) : super(key: key);
+
   final Widget child;
+
   _SemanticsDebuggerState createState() => new _SemanticsDebuggerState();
 }
 

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

@@ -6,6 +6,7 @@ import 'package:flutter/animation.dart';
 
 import 'framework.dart';
 
+/// A component that rebuilds when the given animation changes status.
 abstract class StatusTransitionComponent extends StatefulComponent {
   StatusTransitionComponent({
     Key key,
@@ -14,6 +15,7 @@ abstract class StatusTransitionComponent extends StatefulComponent {
     assert(animation != null);
   }
 
+  /// The animation to which this component is listening.
   final Animation<double> animation;
 
   Widget build(BuildContext context);

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

@@ -7,18 +7,23 @@ import 'package:flutter/widgets.dart';
 
 /// Controls the description of this app in the operating system.
 class Title extends StatelessComponent {
-  Title({ this.title, this.child, this.color }) {
+  Title({
+    Key key,
+    this.title,
+    this.child,
+    this.color
+  }) : super(key: key) {
     assert(color == null || color.alpha == 0xFF);
   }
 
-  final Widget child;
-
   /// A one-line description of this app for use in the window manager.
   final String title;
 
   /// A color that the window manager should use to identify this app.
   final Color color;
 
+  final Widget child;
+
   Widget build(BuildContext context) {
     updateTaskDescription(label: title, color: color);
     return child;

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

@@ -14,6 +14,13 @@ import 'framework.dart';
 export 'package:flutter/animation.dart' show AnimationDirection;
 export 'package:flutter/rendering.dart' show RelativeRect;
 
+/// A component that rebuilds when the given animation changes value.
+///
+/// AnimatedComponent is most useful for stateless animated widgets. To use
+/// AnimatedComponent, simply subclass it and implement the build function.
+///
+/// For more complex case involving additional state, consider using
+/// [AnimatedBuilder].
 abstract class AnimatedComponent extends StatefulComponent {
   AnimatedComponent({
     Key key,
@@ -22,8 +29,11 @@ abstract class AnimatedComponent extends StatefulComponent {
     assert(animation != null);
   }
 
+  /// The animation to which this component is listening.
   final Animation<Object> animation;
 
+  /// Override this function to build widgets that depend on the current value
+  /// of the animation.
   Widget build(BuildContext context);
 
   /// Subclasses typically do not override this method.
@@ -64,6 +74,7 @@ class _AnimatedComponentState extends State<AnimatedComponent> {
   }
 }
 
+/// Animates the position of a widget relative to its normal position.
 class SlideTransition extends AnimatedComponent {
   SlideTransition({
     Key key,
@@ -72,8 +83,21 @@ class SlideTransition extends AnimatedComponent {
     this.child
   }) : position = position, super(key: key, animation: position);
 
+  /// The animation that controls the position of the child.
+  ///
+  /// If the current value of the position animation is (dx, dy), the child will
+  /// be translated horizontally by width * dx and vertically by height * dy.
   final Animation<FractionalOffset> position;
+
+
+  /// Whether hit testing should be affected by the slide animation.
+  ///
+  /// If false, hit testing will proceed as if the child was not translated at
+  /// all. Setting this value to false is useful for fast animations where you
+  /// expect the user to commonly interact with the child widget in its final
+  /// location and you want the user to benefit from "muscle memory".
   final bool transformHitTests;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -85,6 +109,7 @@ class SlideTransition extends AnimatedComponent {
   }
 }
 
+/// Animates the size of a widget.
 class ScaleTransition extends AnimatedComponent {
   ScaleTransition({
     Key key,
@@ -93,8 +118,19 @@ class ScaleTransition extends AnimatedComponent {
     this.child
   }) : scale = scale, super(key: key, animation: scale);
 
+  /// The animation that controls the scale of the child.
+  ///
+  /// If the current value of the scale animation is v, the child will be
+  /// painted v times its normal size.
   final Animation<double> scale;
+
+  /// The alignment of the origin of the coordainte system in which the scale
+  /// takes place, relative to the size of the box.
+  ///
+  /// For example, to set the origin of the scale to bottom middle, you can use
+  /// an alignment of (0.5, 1.0).
   final FractionalOffset alignment;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -109,6 +145,7 @@ class ScaleTransition extends AnimatedComponent {
   }
 }
 
+/// Animates the rotation of a widget.
 class RotationTransition extends AnimatedComponent {
   RotationTransition({
     Key key,
@@ -116,7 +153,12 @@ class RotationTransition extends AnimatedComponent {
     this.child
   }) : turns = turns, super(key: key, animation: turns);
 
+  /// The animation that controls the rotation of the child.
+  ///
+  /// If the current value of the turns animation is v, the child will be
+  /// rotated v * 2 * pi radians before being painted.
   final Animation<double> turns;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -130,6 +172,7 @@ class RotationTransition extends AnimatedComponent {
   }
 }
 
+/// Animates the opacity of a widget.
 class FadeTransition extends AnimatedComponent {
   FadeTransition({
     Key key,
@@ -137,7 +180,14 @@ class FadeTransition extends AnimatedComponent {
     this.child
   }) : opacity = opacity, super(key: key, animation: opacity);
 
+  /// The animation that controls the opacity of the child.
+  ///
+  /// If the current value of the opacity animation is v, the child will be
+  /// painted with an opacity of v. For example, if v is 0.5, the child will be
+  /// blended 50% with its background. Similarly, if v is 0.0, the child will be
+  /// completely transparent.
   final Animation<double> opacity;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -145,6 +195,7 @@ class FadeTransition extends AnimatedComponent {
   }
 }
 
+/// Animates the background color of a widget.
 class ColorTransition extends AnimatedComponent {
   ColorTransition({
     Key key,
@@ -152,7 +203,12 @@ class ColorTransition extends AnimatedComponent {
     this.child
   }) : color = color, super(key: key, animation: color);
 
+  /// The animation that controls the color of the background.
+  ///
+  /// If the current value of the color animation is c, this widget will paint
+  /// a rectangular background behind the child widget of color c.
   final Animation<Color> color;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -163,10 +219,10 @@ class ColorTransition extends AnimatedComponent {
   }
 }
 
-/// An animated variable containing a RelativeRectangle
+/// An interpolation between two relative rects.
 ///
-/// This class specializes the interpolation of AnimatedValue<RelativeRect> to
-/// be appropriate for rectangles that are described in terms of offsets from
+/// This class specializes the interpolation of Tween<RelativeRect> to be
+/// appropriate for rectangles that are described in terms of offsets from
 /// other rectangles.
 class RelativeRectTween extends Tween<RelativeRect> {
   RelativeRectTween({ RelativeRect begin, RelativeRect end })
@@ -189,7 +245,9 @@ class PositionedTransition extends AnimatedComponent {
     assert(rect != null);
   }
 
+  /// The animation that controls the child's size and position.
   final Animation<RelativeRect> rect;
+
   final Widget child;
 
   Widget build(BuildContext context) {
@@ -203,8 +261,28 @@ class PositionedTransition extends AnimatedComponent {
   }
 }
 
+/// A builder that builds a widget given a child.
 typedef Widget TransitionBuilder(BuildContext context, Widget child);
 
+/// A general-purpose widget for building animations.
+///
+/// AnimatedBuilder is useful for more complex components that wish to include
+/// an animation as part of a larger build function. To use AnimatedBuilder,
+/// simply construct the widget and pass it a builder function.
+///
+/// If your [builder] function contains a subtree that does not depend on the
+/// animation, it's more efficient to build that subtree once instead of
+/// rebuilding it on every animation tick.
+///
+/// If you pass the pre-built subtree as the [child] parameter, the
+/// AnimatedBuilder will pass it back to your builder function so that you
+/// can incorporate it into your build.
+///
+/// Using this pre-built child is entirely optional, but can improve
+/// performance significantly in some cases and is therefore a good practice.
+///
+/// For simple cases without additional state, consider using
+/// [AnimatedComponent].
 class AnimatedBuilder extends AnimatedComponent {
   AnimatedBuilder({
     Key key,
@@ -213,7 +291,19 @@ class AnimatedBuilder extends AnimatedComponent {
     this.child
   }) : super(key: key, animation: animation);
 
+  /// Called every time the animation changes value.
   final TransitionBuilder builder;
+
+  /// If your builder function contains a subtree that does not depend on the
+  /// animation, it's more efficient to build that subtree once instead of
+  /// rebuilding it on every animation tick.
+  ///
+  /// If you pass the pre-built subtree as the [child] parameter, the
+  /// AnimatedBuilder will pass it back to your builder function so that you
+  /// can incorporate it into your build.
+  ///
+  /// Using this pre-built child is entirely optional, but can improve
+  /// performance significantly in some cases and is therefore a good practice.
   final Widget child;
 
   Widget build(BuildContext context) {