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/scrollable.dart

@@ -25,6 +25,7 @@ const double _kMillisecondsPerSecond = 1000.0;
 const double _kMinFlingVelocity = -kMaxFlingVelocity * _kMillisecondsPerSecond;
 const double _kMaxFlingVelocity = kMaxFlingVelocity * _kMillisecondsPerSecond;
 
+/// The accuracy to which scrolling is computed.
 final Tolerance kPixelScrollTolerance = new Tolerance(
   velocity: 1.0 / (0.050 * ui.window.devicePixelRatio),  // logical pixels per second
   distance: 1.0 / ui.window.devicePixelRatio  // logical pixels
@@ -33,8 +34,13 @@ final Tolerance kPixelScrollTolerance = new Tolerance(
 typedef void ScrollListener(double scrollOffset);
 typedef double SnapOffsetCallback(double scrollOffset);
 
-/// A base class for scrollable widgets that reacts to user input and generates
-/// a scrollOffset.
+/// A base class for scrollable widgets.
+///
+/// Commonly used subclasses include [ScrollableList], [ScrollableGrid], and
+/// [ScrollableViewport].
+///
+/// Widgets that subclass [Scrollable] typically use state objects that subclass
+/// [ScrollableState].
 abstract class Scrollable extends StatefulComponent {
   Scrollable({
     Key key,
@@ -50,13 +56,25 @@ abstract class Scrollable extends StatefulComponent {
            scrollDirection == Axis.horizontal);
   }
 
+  /// The scroll offset this widget should use when first created.
   final double initialScrollOffset;
+
+  /// The axis along which this widget should scroll.
   final Axis scrollDirection;
+
+  /// Called whenever this widget starts to scroll.
   final ScrollListener onScrollStart;
+
+  /// Called whenever this widget's scroll offset changes.
   final ScrollListener onScroll;
+
+  /// Called whenever this widget stops scrolling.
   final ScrollListener onScrollEnd;
+
+  /// Called to determine the offset to which scrolling should snap.
   final SnapOffsetCallback snapOffsetCallback;
-  final double snapAlignmentOffset;
+
+  final double snapAlignmentOffset; // What does this do?
 
   /// The state from the closest instance of this class that encloses the given context.
   static ScrollableState of(BuildContext context) {
@@ -130,6 +148,10 @@ abstract class Scrollable extends StatefulComponent {
   ScrollableState createState();
 }
 
+/// Contains the state for common scrolling behaviors.
+///
+/// Widgets that subclass [Scrollable] typically use state objects that subclass
+/// [ScrollableState].
 abstract class ScrollableState<T extends Scrollable> extends State<T> {
   void initState() {
     super.initState();
@@ -139,21 +161,21 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
 
   AnimationController _controller;
 
+  /// The current scroll offset.
+  ///
+  /// The scroll offset is applied to the child widget along the scroll
+  /// direction before painting. A positive scroll offset indicates that
+  /// more content in the preferred reading direction is visible.
   double get scrollOffset => _scrollOffset;
   double _scrollOffset;
 
-  Offset get scrollOffsetVector {
-    if (config.scrollDirection == Axis.horizontal)
-      return new Offset(scrollOffset, 0.0);
-    return new Offset(0.0, scrollOffset);
-  }
-
   /// Convert a position or velocity measured in terms of pixels to a scrollOffset.
   /// Scrollable gesture handlers convert their incoming values with this method.
   /// Subclasses that define scrollOffset in units other than pixels must
   /// override this method.
   double pixelToScrollOffset(double pixelValue) => pixelValue;
 
+  /// Returns the component of the given velocity in the scroll direction.
   double scrollDirectionVelocity(Offset scrollVelocity) {
     return config.scrollDirection == Axis.horizontal
       ? -scrollVelocity.dx
@@ -161,7 +183,16 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
   }
 
   ScrollBehavior _scrollBehavior;
+
+  /// Subclasses should override this function to create the [ScrollBehavior]
+  /// they desire.
   ScrollBehavior createScrollBehavior();
+
+  /// The current scroll behavior of this widget.
+  ///
+  /// Scroll behaviors control where the boundaries of the scrollable are placed
+  /// and how the scrolling physics should behave near those boundaries and
+  /// after the user stops directly manipulating the scrollable.
   ScrollBehavior get scrollBehavior {
     if (_scrollBehavior == null)
       _scrollBehavior = createScrollBehavior();
@@ -202,6 +233,10 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     );
   }
 
+  /// Subclasses should override this function to build the interior of their
+  /// scrollable widget. Scrollable wraps the returned widget in a
+  /// [GestureDetector] to observe the user's interaction with this widget and
+  /// to adjust the scroll offset accordingly.
   Widget buildContent(BuildContext context);
 
   Future _animateTo(double newScrollOffset, Duration duration, Curve curve) {
@@ -227,10 +262,12 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     return simulation;
   }
 
-  double snapScrollOffset(double value) {
-    return config.snapOffsetCallback == null ? value : config.snapOffsetCallback(value);
+  /// Returns the snapped offset closest to the given scroll offset.
+  double snapScrollOffset(double scrollOffset) {
+    return config.snapOffsetCallback == null ? scrollOffset : config.snapOffsetCallback(scrollOffset);
   }
 
+  /// Whether this scrollable should attempt to snap scroll offsets.
   bool get snapScrollOffsetChanges => config.snapOffsetCallback != null;
 
   Simulation _createSnapSimulation(double velocity) {
@@ -291,6 +328,10 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     dispatchOnScroll();
   }
 
+  /// Scroll this widget to the given scroll offset.
+  ///
+  /// If a non-null [duration] is provided, the widget will animate to the new
+  /// scroll offset over the given duration with the given curve.
   Future scrollTo(double newScrollOffset, { Duration duration, Curve curve: Curves.ease }) {
     if (newScrollOffset == _scrollOffset)
       return new Future.value();
@@ -304,11 +345,20 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     return _animateTo(newScrollOffset, duration, curve);
   }
 
+  /// Scroll this widget by the given scroll delta.
+  ///
+  /// If a non-null [duration] is provided, the widget will animate to the new
+  /// scroll offset over the given duration with the given curve.
   Future scrollBy(double scrollDelta, { Duration duration, Curve curve: Curves.ease }) {
     double newScrollOffset = scrollBehavior.applyCurve(_scrollOffset, scrollDelta);
     return scrollTo(newScrollOffset, duration: duration, curve: curve);
   }
 
+  /// Fling the scroll offset with the given velocity.
+  ///
+  /// Calling this function starts a physics-based animation of the scroll
+  /// offset with the given value as the initial velocity. The physics
+  /// simulation used is determined by the scroll behavior.
   Future fling(Offset scrollVelocity) {
     if (scrollVelocity != Offset.zero)
       return _startToEndAnimation(scrollVelocity);
@@ -317,21 +367,34 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     return new Future.value();
   }
 
+  /// Animate the scroll offset to a value with a local minima of energy.
+  ///
+  /// Calling this function starts a physics-based animation of the scroll
+  /// offset either to a snap point or to within the scrolling bounds. The
+  /// physics simulation used is determined by the scroll behavior.
   Future settleScrollOffset() {
     return _startToEndAnimation(Offset.zero);
   }
 
+  /// Calls the onScrollStart callback.
+  ///
+  /// Subclasses can override this function to hook the scroll start callback.
   void dispatchOnScrollStart() {
     if (config.onScrollStart != null)
       config.onScrollStart(_scrollOffset);
   }
 
-  // Derived classes can override this method and call super.dispatchOnScroll()
+  /// Calls the onScroll callback.
+  ///
+  /// Subclasses can override this function to hook the scroll callback.
   void dispatchOnScroll() {
     if (config.onScroll != null)
       config.onScroll(_scrollOffset);
   }
 
+  /// Calls the dispatchOnScrollEnd callback.
+  ///
+  /// Subclasses can override this function to hook the scroll end callback.
   void dispatchOnScrollEnd() {
     if (config.onScrollEnd != null)
       config.onScrollEnd(_scrollOffset);
@@ -363,10 +426,15 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
   }
 }
 
+/// Indicates that a descendant scrollable has scrolled.
 class ScrollNotification extends Notification {
-  ScrollNotification(this.scrollable, this.position);
+  ScrollNotification(this.scrollable, this.scrollOffset);
+
+  /// The scrollable that scrolled.
   final ScrollableState scrollable;
-  final double position;
+
+  /// The new scroll offset that the scrollable obtained.
+  final double scrollOffset;
 }
 
 /// A simple scrollable widget that has a single child. Use this component if
@@ -391,10 +459,10 @@ class ScrollableViewport extends Scrollable {
 
   final Widget child;
 
-  ScrollableViewportState createState() => new ScrollableViewportState();
+  ScrollableState createState() => new _ScrollableViewportState();
 }
 
-class ScrollableViewportState extends ScrollableState<ScrollableViewport> {
+class _ScrollableViewportState extends ScrollableState<ScrollableViewport> {
   ScrollBehavior createScrollBehavior() => new OverscrollWhenScrollableBehavior();
   OverscrollWhenScrollableBehavior get scrollBehavior => super.scrollBehavior;
 
@@ -421,11 +489,17 @@ class ScrollableViewportState extends ScrollableState<ScrollableViewport> {
     ));
   }
 
+  Offset get _scrollOffsetVector {
+    if (config.scrollDirection == Axis.horizontal)
+      return new Offset(scrollOffset, 0.0);
+    return new Offset(0.0, scrollOffset);
+  }
+
   Widget buildContent(BuildContext context) {
     return new SizeObserver(
       onSizeChanged: _handleViewportSizeChanged,
       child: new Viewport(
-        scrollOffset: scrollOffsetVector,
+        scrollOffset: _scrollOffsetVector,
         scrollDirection: config.scrollDirection,
         child: new SizeObserver(
           onSizeChanged: _handleChildSizeChanged,

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