Fix many dartdoc typos (#9822)

packages/flutter/lib/src/animation/animation_controller.dart

@@ -350,7 +350,7 @@ class AnimationController extends Animation<double>
   ///
   /// Defaults to repeating between the lower and upper bounds.
   ///
-  /// Returns a [TickerFuture] that never completes. The [TickerFuture.onCancel] future
+  /// Returns a [TickerFuture] that never completes. The [TickerFuture.orCancel] future
   /// completes with an error when the animation is stopped (e.g. with [stop]).
   ///
   /// The most recently returned [TickerFuture], if any, is marked as having been

packages/flutter/lib/src/foundation/binding.dart

@@ -280,7 +280,7 @@ abstract class BindingBase {
   /// extension method is called. The callback must return a [Future]
   /// that either eventually completes to a return value in the form
   /// of a name/value map where the values can all be converted to
-  /// JSON using [JSON.encode], or fails. In case of failure, the
+  /// JSON using `JSON.encode()` (see [JsonCodec.encode]), or fails. In case of failure, the
   /// failure is reported to the remote caller and is dumped to the
   /// logs.
   ///

packages/flutter/lib/src/gestures/velocity_tracker.dart

@@ -125,7 +125,7 @@ class _PointAtTime {
   String toString() => '_PointAtTime($point at $time)';
 }
 
-/// Computes a pointer's velocity based on data from [PointerMove] events.
+/// Computes a pointer's velocity based on data from [PointerMoveEvent]s.
 ///
 /// The input data is provided by calling [addPosition]. Adding data is cheap.
 ///

packages/flutter/lib/src/material/bottom_navigation_bar.dart

@@ -59,7 +59,7 @@ class BottomNavigationBarItem {
 
   /// The icon of the item.
   ///
-  /// Typically the icon is an [Icon] or an [IconImage] widget. If another type
+  /// Typically the icon is an [Icon] or an [ImageIcon] widget. If another type
   /// of widget is provided then it should configure itself to match the current
   /// [IconTheme] size and color.
   final Widget icon;

packages/flutter/lib/src/material/bottom_sheet.dart

@@ -25,7 +25,7 @@ const Color _kBarrierColor = Colors.black54;
 ///    supplements the primary content of the app. A persistent bottom sheet
 ///    remains visible even when the user interacts with other parts of the app.
 ///    Persistent bottom sheets can be created and displayed with the
-///    [Scaffold.showBottomSheet] function.
+///    [ScaffoldState.showBottomSheet] function.
 ///
 ///  * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and
 ///    prevents the user from interacting with the rest of the app. Modal bottom
@@ -45,7 +45,7 @@ class BottomSheet extends StatefulWidget {
   /// Creates a bottom sheet.
   ///
   /// Typically, bottom sheets are created implicitly by
-  /// [Scaffold.showBottomSheet], for persistent bottom sheets, or by
+  /// [ScaffoldState.showBottomSheet], for persistent bottom sheets, or by
   /// [showModalBottomSheet], for modal bottom sheets.
   const BottomSheet({
     Key key,
@@ -253,10 +253,14 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
 ///
 /// See also:
 ///
-///  * [BottomSheet]
-///  * [Scaffold.showBottomSheet]
+///  * [BottomSheet], which is the widget normally returned by the function
+///    passed as the `builder` argument to [showModalBottomSheet].
+///  * [ScaffoldState.showBottomSheet], for showing non-modal bottom sheets.
 ///  * <https://material.google.com/components/bottom-sheets.html#bottom-sheets-modal-bottom-sheets>
-Future<T> showModalBottomSheet<T>({ @required BuildContext context, @required WidgetBuilder builder }) {
+Future<T> showModalBottomSheet<T>({
+  @required BuildContext context,
+  @required WidgetBuilder builder,
+}) {
   assert(context != null);
   assert(builder != null);
   return Navigator.push(context, new _ModalBottomSheetRoute<T>(

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

@@ -17,7 +17,7 @@ class ColorSwatch extends Color {
 
   final Map<int, Color> _swatch;
 
-  /// Returns an element of the [swatch] table.
+  /// Returns an element of the swatch table.
   Color operator [](int index) => _swatch[index];
 
   @override
@@ -927,7 +927,7 @@ class Colors {
   ///
   /// See also:
   ///
-  /// * [yellowAccentAccent], the corresponding accent colors.
+  /// * [yellowAccent], the corresponding accent colors.
   /// * [Theme.of], which allows you to select colors from the current theme
   ///   rather than hard-coding colors in your build methods.
   static const MaterialColor yellow = const MaterialColor(

packages/flutter/lib/src/material/data_table.dart

@@ -157,7 +157,7 @@ class DataCell {
   /// Creates an object to hold the data for a cell in a [DataTable].
   ///
   /// The first argument is the widget to show for the cell, typically
-  /// a [Text] or [DropdownButton] widget; this becomes the [widget]
+  /// a [Text] or [DropdownButton] widget; this becomes the [child]
   /// property and must not be null.
   ///
   /// If the cell has no data, then a [Text] widget with placeholder
@@ -166,7 +166,7 @@ class DataCell {
   const DataCell(this.child, {
     this.placeholder: false,
     this.showEditIcon: false,
-    this.onTap
+    this.onTap,
   });
 
   /// A cell that has no content and has zero width and height.
@@ -201,7 +201,7 @@ class DataCell {
   ///
   /// If non-null, tapping the cell will call this callback. If
   /// null, tapping the cell will attempt to select the row (if
-  /// [TableRow.onSelectChanged] is provided).
+  /// [DataRow.onSelectChanged] is provided).
   final VoidCallback onTap;
 
   bool get _debugInteractive => onTap != null;

packages/flutter/lib/src/material/debug.dart

@@ -12,7 +12,7 @@ import 'material.dart';
 /// only used in contexts where they can print ink onto some material.
 ///
 /// To call this function, use the following pattern, typically in the
-/// relevant Widget's [build] method:
+/// relevant Widget's build method:
 ///
 /// ```dart
 /// assert(debugCheckHasMaterial(context));

packages/flutter/lib/src/material/dialog.dart

@@ -71,7 +71,7 @@ class Dialog extends StatelessWidget {
 ///
 /// If the content is too large to fit on the screen vertically, the dialog will
 /// display the title and the actions and let the content overflow. Consider
-/// using a scrolling widget, such as [ScrollList], for [content] to avoid
+/// using a scrolling widget, such as [ListView], for [content] to avoid
 /// overflow.
 ///
 /// For dialogs that offer the user a choice between several options, consider
@@ -114,8 +114,8 @@ class AlertDialog extends StatelessWidget {
   /// The (optional) content of the dialog is displayed in the center of the
   /// dialog in a lighter font.
   ///
-  /// Typically, this is a [ScrollList] containing the contents of the dialog.
-  /// Using a [ScrollList] ensures that the contents can scroll if they are too
+  /// Typically, this is a [ListView] containing the contents of the dialog.
+  /// Using a [ListView] ensures that the contents can scroll if they are too
   /// big to fit on the display.
   final Widget content;
 
@@ -358,12 +358,13 @@ class _DialogRoute<T> extends PopupRoute<T> {
 /// This function typically receives a [Dialog] widget as its child argument.
 /// Content below the dialog is dimmed with a [ModalBarrier].
 ///
-/// Returns a `Future` that resolves to the value (if any) that was passed to
+/// Returns a [Future] that resolves to the value (if any) that was passed to
 /// [Navigator.pop] when the dialog was closed.
 ///
 /// See also:
-///  * [SimpleDialog], which handles the scrolling of the contents but has no [actions].
-///  * [AlertDialog], for dialogs that have a row of buttons below the body.
+///  * [AlertDialog], for dialogs that have a row of buttons below a body.
+///  * [SimpleDialog], which handles the scrolling of the contents and does
+///    not show buttons below its body.
 ///  * [Dialog], on which [SimpleDialog] and [AlertDialog] are based.
 ///  * <https://material.google.com/components/dialogs.html>
 Future<T> showDialog<T>({

packages/flutter/lib/src/material/divider.dart

@@ -21,7 +21,7 @@ import 'theme.dart';
 /// See also:
 ///
 ///  * [PopupMenuDivider], which is the equivalent but for popup menus.
-///  * [ListTile.divideItems], another approach to dividing widgets in a list.
+///  * [ListTile.divideTiles], another approach to dividing widgets in a list.
 ///  * <https://material.google.com/components/dividers.html>
 class Divider extends StatelessWidget {
   /// Creates a material design divider.

packages/flutter/lib/src/material/drawer.dart

@@ -233,7 +233,7 @@ class DrawerControllerState extends State<DrawerController> with SingleTickerPro
 
   /// Starts an animation to open the drawer.
   ///
-  /// Typically called by [Scaffold.openDrawer].
+  /// Typically called by [ScaffoldState.openDrawer].
   void open() {
     _controller.fling(velocity: 1.0);
   }

packages/flutter/lib/src/material/flutter_logo.dart

@@ -59,11 +59,11 @@ class FlutterLogo extends StatelessWidget {
   /// itself is drawn.
   final FlutterLogoStyle style;
 
-  /// The length of time for the animation if the [style], [swatch], or
+  /// The length of time for the animation if the [style], [colors], or
   /// [textColor] properties are changed.
   final Duration duration;
 
-  /// The curve for the logo animation if the [style], [swatch], or [textColor]
+  /// The curve for the logo animation if the [style], [colors], or [textColor]
   /// change.
   final Curve curve;
 

packages/flutter/lib/src/material/icon.dart

@@ -62,7 +62,7 @@ class Icon extends StatelessWidget {
   /// 24.0.
   ///
   /// If this [Icon] is being placed inside an [IconButton], then use
-  /// [IconButton.size] instead, so that the [IconButton] can make the splash
+  /// [IconButton.iconSize] instead, so that the [IconButton] can make the splash
   /// area the appropriate size as well. The [IconButton] uses an [IconTheme] to
   /// pass down the size to the [Icon].
   final double size;

packages/flutter/lib/src/material/icon_button.dart

@@ -96,9 +96,10 @@ class IconButton extends StatelessWidget {
 
   /// The icon to display inside the button.
   ///
-  /// The [size] and [color] of the icon is configured automatically based on
-  /// the properties of _this_ widget using an [IconTheme] and therefore should
-  /// not be explicitly given in the icon widget.
+  /// The [Icon.size] and [Icon.color] of the icon is configured automatically
+  /// based on the [iconSize] nad [color] properties of _this_ widget using an
+  /// [IconTheme] and therefore should not be explicitly given in the icon
+  /// widget.
   ///
   /// This property must not be null.
   ///

packages/flutter/lib/src/material/ink_well.dart

@@ -24,7 +24,7 @@ import 'theme.dart';
 /// Must have an ancestor [Material] widget in which to cause ink reactions.
 ///
 /// If a Widget uses this class directly, it should include the following line
-/// at the top of its [build] function to call [debugCheckHasMaterial]:
+/// at the top of its build function to call [debugCheckHasMaterial]:
 ///
 /// ```dart
 /// assert(debugCheckHasMaterial(context));
@@ -254,7 +254,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
 /// Must have an ancestor [Material] widget in which to cause ink reactions.
 ///
 /// If a Widget uses this class directly, it should include the following line
-/// at the top of its [build] function to call [debugCheckHasMaterial]:
+/// at the top of its build function to call [debugCheckHasMaterial]:
 ///
 /// ```dart
 /// assert(debugCheckHasMaterial(context));

packages/flutter/lib/src/material/list_tile.dart

@@ -136,7 +136,7 @@ class ListTileTheme extends InheritedWidget {
 /// height based on their contents. If you are looking for a widget that allows
 /// for arbitrary layout in a row, consider [Row].
 ///
-/// List tiles are typically used in [MaterialList]s or in [Card]s.
+/// List tiles are typically used in [ListView]s, [Drawer]s, and [Card]s.
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///

packages/flutter/lib/src/material/mergeable_material.dart

@@ -60,7 +60,7 @@ class MaterialGap extends MergeableMaterialItem {
   }) : assert(key != null),
        super(key);
 
-  /// The main axis extent of this gap. For example, if the [MergableMaterial]
+  /// The main axis extent of this gap. For example, if the [MergeableMaterial]
   /// is vertical, then this is the height of the gap.
   final double size;
 

packages/flutter/lib/src/material/refresh_indicator.dart

@@ -333,8 +333,8 @@ class RefreshIndicatorState extends State<RefreshIndicator> with TickerProviderS
   /// Creating the [RefreshIndicator] with a [GlobalKey<RefreshIndicatorState>]
   /// makes it possible to refer to the [RefreshIndicatorState].
   ///
-  /// The future returned from this method completes when the [onRefresh]
-  /// callback's future completes.
+  /// The future returned from this method completes when the
+  /// [RefreshIndicator.onRefresh] callback's future completes.
   ///
   /// If you await the future returned by this function from a [State], you
   /// should check that the state is still [mounted] before calling [setState].

packages/flutter/lib/src/material/scaffold.dart

@@ -314,7 +314,7 @@ class Scaffold extends StatefulWidget {
   ///
   /// If you have a column of widgets that should normally fit on the screen,
   /// but may overflow and would in such cases need to scroll, consider using a
-  /// [ScrollList] as the body of the scaffold. This is also a good choice for
+  /// [ListView] as the body of the scaffold. This is also a good choice for
   /// the case where your body is a scrollable list.
   final Widget body;
 
@@ -922,7 +922,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
 
 /// An interface for controlling a feature of a [Scaffold].
 ///
-/// Commonly obtained from [Scaffold.showSnackBar] or [Scaffold.showBottomSheet].
+/// Commonly obtained from [ScaffoldState.showSnackBar] or [ScaffoldState.showBottomSheet].
 class ScaffoldFeatureController<T extends Widget, U> {
   const ScaffoldFeatureController._(this._widget, this._completer, this.close, this.setState);
   final T _widget;
@@ -1005,7 +1005,7 @@ class _PersistentBottomSheetState extends State<_PersistentBottomSheet> {
 
 /// A [ScaffoldFeatureController] for persistent bottom sheets.
 ///
-/// This is the type of objects returned by [Scaffold.showBottomSheet].
+/// This is the type of objects returned by [ScaffoldState.showBottomSheet].
 class PersistentBottomSheetController<T> extends ScaffoldFeatureController<_PersistentBottomSheet, T> {
   const PersistentBottomSheetController._(
     _PersistentBottomSheet widget,

packages/flutter/lib/src/material/snack_bar.dart

@@ -32,10 +32,10 @@ const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOut
 
 /// Specify how a [SnackBar] was closed.
 ///
-/// The [showSnackBar] function returns a [ScaffoldFeatureController]. The value
-/// of the controller's closed property is a Future that resolves to a
-/// SnackBarClosedReason. Applications that need to know how a snackbar
-/// was closed can use this value.
+/// The [ScaffoldState.showSnackBar] function returns a
+/// [ScaffoldFeatureController]. The value of the controller's closed property
+/// is a Future that resolves to a SnackBarClosedReason. Applications that need
+/// to know how a snackbar was closed can use this value.
 ///
 /// Example:
 ///
@@ -54,10 +54,10 @@ enum SnackBarClosedReason {
   swipe,
 
   /// The snack bar was closed by the [ScaffoldFeatureController] close callback
-  /// or by calling [hideCurrentSnackBar] directly.
+  /// or by calling [ScaffoldState.hideCurrentSnackBar] directly.
   hide,
 
-  /// The snack bar was closed by an call to [removeCurrentSnackBar].
+  /// The snack bar was closed by an call to [ScaffoldState.removeCurrentSnackBar].
   remove,
 
   /// The snack bar was closed because its timer expired.

packages/flutter/lib/src/material/theme_data.dart

@@ -327,7 +327,7 @@ class ThemeData {
   // ...this should be the "50-value of secondary app color".
   final Color secondaryHeaderColor;
 
-  /// The color of text selections in text fields, such as [Input].
+  /// The color of text selections in text fields, such as [TextField].
   final Color textSelectionColor;
 
   /// The color of the handles used to adjust what part of the text is currently selected.
@@ -344,10 +344,10 @@ class ThemeData {
   final Color indicatorColor;
 
   /// The color to use for hint text or placeholder text, e.g. in
-  /// [Input] fields.
+  /// [TextField] fields.
   final Color hintColor;
 
-  /// The color to use for input validation errors, e.g. in [Input] fields.
+  /// The color to use for input validation errors, e.g. in [TextField] fields.
   final Color errorColor;
 
   /// Text with a color that contrasts with the card and canvas colors.

packages/flutter/lib/src/material/toggleable.dart

@@ -79,7 +79,7 @@ abstract class RenderToggleable extends RenderConstrainedBox implements Semantic
   /// The visual value of the control.
   ///
   /// When the control is inactive, the [value] is false and this animation has
-  /// the value 0.0. When the control is active, the value is [true] and this
+  /// the value 0.0. When the control is active, the value is true and this
   /// animation has the value 1.0. When the control is changing from inactive
   /// to active (or vice versa), [value] is the target value and this animation
   /// gradually updates from 0.0 to 1.0 (or vice versa).

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

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'dart:math' as math;
+import 'dart:ui' show Image; // to disambiguate mentions of Image in the dartdocs
 
 import 'package:flutter/foundation.dart';
 

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

@@ -95,9 +95,15 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// The string used to ellipsize overflowing text.  Setting this to a nonempty
+  /// The string used to ellipsize overflowing text. Setting this to a non-empty
   /// string will cause this string to be substituted for the remaining text
-  /// if the text can not fit within the specificed maximum width.
+  /// if the text can not fit within the specified maximum width.
+  ///
+  /// Specifically, the ellipsis is applied to the last line before the line
+  /// truncated by [maxLines], if [maxLines] is non-null and that line overflows
+  /// the width constraint, or to the first line that is wider than the width
+  /// constraint, if [maxLines] is null. The width constraint is the `maxWidth`
+  /// passed to [layout].
   ///
   /// After this is set, you must call [layout] before the next call to [paint].
   String get ellipsis => _ellipsis;
@@ -111,10 +117,11 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// An optional maximum number of lines for the text to span, wrapping if necessary.
+  /// An optional maximum number of lines for the text to span, wrapping if
+  /// necessary.
   ///
-  /// If the text exceeds the given number of lines, it will be truncated according
-  /// to [overflow].
+  /// If the text exceeds the given number of lines, it is truncated such that
+  /// subsequent lines are dropped.
   ///
   /// After this is set, you must call [layout] before the next call to [paint].
   int get maxLines => _maxLines;
@@ -129,10 +136,10 @@ class TextPainter {
 
   ui.Paragraph _layoutTemplate;
 
-  /// The height of a zero-width space in [style] in logical pixels.
+  /// The height of a zero-width space in [text] in logical pixels.
   ///
-  /// Not every line of text in [style] will have this height, but this height
-  /// is "typical" for text in [style] and useful for sizing other objects
+  /// Not every line of text in [text] will have this height, but this height
+  /// is "typical" for text in [text] and useful for sizing other objects
   /// relative a typical line of text.
   double get preferredLineHeight {
     assert(text != null);
@@ -198,7 +205,8 @@ class TextPainter {
     return new Size(width, height);
   }
 
-  /// Returns the distance from the top of the text to the first baseline of the given type.
+  /// Returns the distance from the top of the text to the first baseline of the
+  /// given type.
   ///
   /// Valid only after [layout] has been called.
   double computeDistanceToActualBaseline(TextBaseline baseline) {
@@ -213,10 +221,17 @@ class TextPainter {
     return null;
   }
 
-  /// Whether the previous call to [layout] attempted to produce more than
-  /// [maxLines] lines.
+  /// Whether any text was truncated or ellipsized.
+  ///
+  /// If [maxLines] is not null, this is true if there were more lines to be
+  /// drawn than the given [maxLines], and thus at least one line was omitted in
+  /// the output; otherwise it is false.
   ///
-  /// If [didExceedMaxLines] is true, then any overflow effect is operative.
+  /// If [maxLines] is null, this is true if [ellipsis] is not the empty string
+  /// and there was a line that overflowed the `maxWidth` argument passed to
+  /// [layout]; otherwise it is false.
+  ///
+  /// Valid only after [layout] has been called.
   bool get didExceedMaxLines {
     assert(!_needsLayout);
     return _paragraph.didExceedMaxLines;

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

@@ -113,7 +113,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
 
   /// Called when the system metrics change.
   ///
-  /// See [ui.window.onMetricsChanged].
+  /// See [Window.onMetricsChanged].
   void handleMetricsChanged() {
     assert(renderView != null);
     renderView.configuration = createViewConfiguration();
@@ -179,11 +179,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
   /// Each frame consists of the following phases:
   ///
   /// 1. The animation phase: The [handleBeginFrame] method, which is registered
-  /// with [ui.window.onBeginFrame], invokes all the transient frame callbacks
-  /// registered with [scheduleFrameCallback] and [addFrameCallback], in
-  /// registration order. This includes all the [Ticker] instances that are
-  /// driving [AnimationController] objects, which means all of the active
-  /// [Animation] objects tick at this point.
+  /// with [Window.onBeginFrame], invokes all the transient frame callbacks
+  /// registered with [scheduleFrameCallback], in registration order. This
+  /// includes all the [Ticker] instances that are driving [AnimationController]
+  /// objects, which means all of the active [Animation] objects tick at this
+  /// point.
   ///
   /// 2. Microtasks: After [handleBeginFrame] returns, any microtasks that got
   /// scheduled by transient frame callbacks get to run. This typically includes
@@ -191,7 +191,7 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
   /// completed this frame.
   ///
   /// After [handleBeginFrame], [handleDrawFrame], which is registered with
-  /// [ui.window.onDrawFrame], is called, which invokes all the persistent frame
+  /// [Window.onDrawFrame], is called, which invokes all the persistent frame
   /// callbacks, of which the most notable is this method, [drawFrame], which
   /// proceeds as follows:
   ///
@@ -208,11 +208,11 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
   /// [RenderObject.markNeedsPaint] for further details on marking an object
   /// dirty for paint.
   ///
-  /// 6. The compositing phase: The layer tree is turned into a [ui.Scene] and
+  /// 6. The compositing phase: The layer tree is turned into a [Scene] and
   /// sent to the GPU.
   ///
   /// 7. The semantics phase: All the dirty [RenderObject]s in the system have
-  /// their semantics updated (see [RenderObject.SemanticsAnnotator]). This
+  /// their semantics updated (see [RenderObject.semanticsAnnotator]). This
   /// generates the [SemanticsNode] tree. See
   /// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an
   /// object dirty for semantics.

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

@@ -935,7 +935,7 @@ class _IntrinsicDimensionsCacheEntry {
 ///
 /// For a render box to be accessible, implement the
 /// [describeApproximatePaintClip] and [visitChildrenForSemantics] methods, and
-/// the [semanticAnnotator] getter. The default implementations are sufficient
+/// the [semanticsAnnotator] getter. The default implementations are sufficient
 /// for objects that only affect layout, but nodes that represent interactive
 /// components or information (diagrams, text, images, etc) should provide more
 /// complete implementations. For more information, see the documentation for
@@ -1089,11 +1089,23 @@ abstract class RenderBox extends RenderObject {
   /// children. It is the size that is needed to paint the box's contents (in
   /// this case, the children) _without clipping_ that matters.
   ///
-  /// In many cases, viewports do not have efficient access to all the children,
-  /// and therefore cannot actually return a valid answer. In this case, when
-  /// [RenderObject.debugCheckingIntrinsics] is false and asserts are enabled,
-  /// the intrinsic functions should throw; in other cases, they should return
-  /// 0.0. See [RenderVirtualViewport.debugThrowIfNotCheckingIntrinsics].
+  /// ### When the intrinsic dimensions cannot be known
+  ///
+  /// There are cases where render objects do not have an efficient way to
+  /// compute their intrinsic dimensions. For example, it may be prohibitively
+  /// expensive to reify and measure every child of a lazy viewport (viewports
+  /// generally only instantiate the actually visible children), or the
+  /// dimensions may be computed by a callback about which the render object
+  /// cannot reason.
+  ///
+  /// In such cases, it may be impossible (or at least impractical) to actually
+  /// return a valid answer. In such cases, the intrinsic functions should throw
+  /// when [RenderObject.debugCheckingIntrinsics] is false and asserts are
+  /// enabled, and return 0.0 otherwise.
+  ///
+  /// See the implementations of [LayoutBuilder] or [RenderViewportBase] for
+  /// examples (in particular,
+  /// [RenderViewportBase.debugThrowIfNotCheckingIntrinsics]).
   ///
   /// ### Aspect-ratio-driven boxes
   ///

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

@@ -38,7 +38,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox>
 /// Override [shouldRelayout] to determine when the layout of the children needs
 /// to be recomputed when the delegate changes.
 ///
-/// Used with [MultiChildCustomLayout], the widget for the
+/// Used with [CustomMultiChildLayout], the widget for the
 /// [RenderCustomMultiChildLayoutBox] render object.
 ///
 /// ## Example

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

@@ -111,7 +111,7 @@ bool debugCheckIntrinsicSizes = false;
 /// Adds [Timeline] events for every RenderObject painted.
 ///
 /// For details on how to use [Timeline] events in the Dart Observatory to
-/// optimize your app, see https://fuchsia.googlesource.com/sysui/+/master/docs/performance.md
+/// optimize your app, see: https://fuchsia.googlesource.com/sysui/+/master/docs/performance.md
 bool debugProfilePaintsEnabled = false;
 
 

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

@@ -177,7 +177,7 @@ class RenderFlow extends RenderBox
   /// Creates a render object for a flow layout.
   ///
   /// For optimal performance, consider using children that return true from
-  /// [isRepaintBounday].
+  /// [isRepaintBoundary].
   RenderFlow({
     List<RenderBox> children,
     @required FlowDelegate delegate

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

@@ -22,10 +22,10 @@ import 'node.dart';
 /// different parents. The scene must be explicitly recomposited after such
 /// changes are made; the layer tree does not maintain its own dirty state.
 ///
-/// To composite the tree, create a [ui.SceneBuilder] object, pass it to the
+/// To composite the tree, create a [SceneBuilder] object, pass it to the
 /// root [Layer] object's [addToScene] method, and then call
-/// [ui.SceneBuilder.build] to obtain a [Scene]. A [Scene] can then be painted
-/// using [ui.window.render].
+/// [SceneBuilder.build] to obtain a [Scene]. A [Scene] can then be painted
+/// using [Window.render].
 ///
 /// See also:
 ///
@@ -334,7 +334,7 @@ class ContainerLayer extends Layer {
   ///
   /// This method is typically used by [addToScene] to insert the children into
   /// the scene. Subclasses of [ContainerLayer] typically override [addToScene]
-  /// to apply effects to the scene using the [ui.SceneBuilder] API, then insert
+  /// to apply effects to the scene using the [SceneBuilder] API, then insert
   /// their children using [addChildrenToScene], then reverse the aforementioned
   /// effects before returning from [addToScene].
   void addChildrenToScene(ui.SceneBuilder builder, Offset childOffset) {

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

@@ -556,23 +556,21 @@ abstract class Constraints {
   ///
   /// This might involve checks more detailed than [isNormalized].
   ///
-  /// For example, the [BoxConstraints] subclass verifies that the
-  /// constraints are not [NaN].
-  ///
-  /// If the `isAppliedConstraint` argument is true, then even
-  /// stricter rules are enforced. This argument is set to true when
-  /// checking constraints that are about to be applied to a
-  /// [RenderObject] during layout, as opposed to constraints that may
-  /// be further affected by other constraints. For example, the
-  /// asserts for verifying the validity of
-  /// [RenderConstrainedBox.additionalConstraints] do not set this
-  /// argument, but the asserts for verifying the argument passed to
-  /// the [layout] method do.
-  ///
-  /// The `informationCollector` argument takes an optional callback
-  /// which is called when an exception is to be thrown. The collected
-  /// information is then included in the message after the error
-  /// line.
+  /// For example, the [BoxConstraints] subclass verifies that the constraints
+  /// are not [double.NAN].
+  ///
+  /// If the `isAppliedConstraint` argument is true, then even stricter rules
+  /// are enforced. This argument is set to true when checking constraints that
+  /// are about to be applied to a [RenderObject] during layout, as opposed to
+  /// constraints that may be further affected by other constraints. For
+  /// example, the asserts for verifying the validity of
+  /// [RenderConstrainedBox.additionalConstraints] do not set this argument, but
+  /// the asserts for verifying the argument passed to the [RenderObject.layout]
+  /// method do.
+  ///
+  /// The `informationCollector` argument takes an optional callback which is
+  /// called when an exception is to be thrown. The collected information is
+  /// then included in the message after the error line.
   ///
   /// Returns the same as [isNormalized] if asserts are disabled.
   bool debugAssertIsValid({
@@ -1076,7 +1074,7 @@ class PipelineOwner {
   }
 
   final List<RenderObject> _nodesNeedingCompositingBitsUpdate = <RenderObject>[];
-  /// Updates the [needsCompositing] bits.
+  /// Updates the [RenderObject.needsCompositing] bits.
   ///
   /// Called as part of the rendering pipeline after [flushLayout] and before
   /// [flushPaint].
@@ -2102,8 +2100,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   bool _needsCompositing; // initialised in the constructor
   /// Whether we or one of our descendants has a compositing layer.
   ///
-  /// Only legal to call after [flushLayout] and [flushCompositingBits] have
-  /// been called.
+  /// Only legal to call after [PipelineOwner.flushLayout] and
+  /// [PipelineOwner.flushCompositingBits] have been called.
   bool get needsCompositing {
     assert(!_needsCompositingBitsUpdate); // make sure we don't use this bit when it is dirty
     return _needsCompositing;
@@ -2325,8 +2323,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   ///
   /// Do not call this function directly. If you wish to paint yourself, call
   /// [markNeedsPaint] instead to schedule a call to this function. If you wish
-  /// to paint one of your children, call one of the paint child functions on
-  /// the given context, such as [paintChild] or [paintChildWithClipRect].
+  /// to paint one of your children, call [PaintingContext.paintChild] on the
+  /// given `context`.
   ///
   /// When painting one of your children (via a paint child function on the
   /// given context), the current canvas held by the context might change
@@ -2374,7 +2372,12 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
     owner.requestVisualUpdate();
   }
 
-  /// Whether this RenderObject introduces a new box for accessibility purposes.
+  /// Whether this [RenderObject] introduces a new box for accessibility purposes.
+  ///
+  /// See also:
+  ///
+  ///  * [semanticsAnnotator], which fills in the [SemanticsNode] implied by
+  ///    setting [isSemanticBoundary] to true.
   bool get isSemanticBoundary => false;
 
   /// The bounding box, in the local coordinate system, of this
@@ -2388,8 +2391,8 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   /// The semantics of this render object.
   ///
   /// Exposed only for testing and debugging. To learn about the semantics of
-  /// render objects in production, register as a listener using
-  /// [SemanticsNode.addListener].
+  /// render objects in production, obtain a [SemanticsHandle] from
+  /// [PipelineOwner.ensureSemantics].
   ///
   /// Only valid when asserts are enabled. In release builds, always returns
   /// null.
@@ -2551,25 +2554,24 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   /// Returns a function that will annotate a [SemanticsNode] with the semantics
   /// of this [RenderObject].
   ///
-  /// To annotate a SemanticsNode for this node, return an annotator that
-  /// adds the annotations. When the behavior of the annotator would
-  /// change (e.g. the box is now checked rather than unchecked), call
-  /// [markNeedsSemanticsUpdate] to indicate to the rendering system
-  /// that the semantics tree needs to be rebuilt.
-  ///
-  /// To introduce a new SemanticsNode, set hasSemantics to true for
-  /// this object. The function returned by this function will be used
-  /// to annotate the SemanticsNode for this object.
-  ///
-  /// Semantic annotations are persistent. Values set in one pass will
-  /// still be set in the next pass. Therefore it is important to
-  /// explicitly set fields to false once they are no longer true;
-  /// setting them to true when they are to be enabled, and not
-  /// setting them at all when they are not, will mean they remain set
-  /// once enabled once and will never get unset.
-  ///
-  /// If the value return will change from null to non-null (or vice versa), and
-  /// [hasSemantics] isn't true, then the associated call to
+  /// To annotate a [SemanticsNode] for this node, return an annotator that adds
+  /// the annotations. When the behavior of the annotator would change (e.g. the
+  /// box is now checked rather than unchecked), call [markNeedsSemanticsUpdate]
+  /// to indicate to the rendering system that the semantics tree needs to be
+  /// rebuilt.
+  ///
+  /// To introduce a new [SemanticsNode], set [isSemanticBoundary] to true for
+  /// this object. The function returned by this function will be used to
+  /// annotate the [SemanticsNode] for this object.
+  ///
+  /// Semantic annotations are persistent. Values set in one pass will still be
+  /// set in the next pass. Therefore it is important to explicitly set fields
+  /// to false once they are no longer true; setting them to true when they are
+  /// to be enabled, and not setting them at all when they are not, will mean
+  /// they remain set once enabled once and will never get unset.
+  ///
+  /// If the return value will change from null to non-null (or vice versa), and
+  /// [isSemanticBoundary] isn't true, then the associated call to
   /// [markNeedsSemanticsUpdate] must not have `onlyChanges` set, as it is
   /// possible that the node should be entirely removed.
   SemanticsAnnotator get semanticsAnnotator => null;

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

@@ -769,7 +769,7 @@ typedef Shader ShaderCallback(Rect bounds);
 /// Applies a mask generated by a [Shader] to its child.
 ///
 /// For example, [RenderShaderMask] can be used to gradually fade out the edge
-/// of a child by using a [ui.Gradient.linear] mask.
+/// of a child by using a [new ui.Gradient.linear] mask.
 class RenderShaderMask extends RenderProxyBox {
   /// Creates a render object that applies a mask generated by a [Shader] to its child.
   ///
@@ -1885,8 +1885,8 @@ abstract class CustomPainter extends Listenable {
   ///
   /// If a custom delegate has a particularly expensive paint function such that
   /// repaints should be avoided as much as possible, a [RepaintBoundary] or
-  /// [RenderRepaintBoundary] (or other render object with [isRepaintBoundary]
-  /// set to true) might be helpful.
+  /// [RenderRepaintBoundary] (or other render object with
+  /// [RenderObject.isRepaintBoundary] set to true) might be helpful.
   bool shouldRepaint(covariant CustomPainter oldDelegate);
 
   /// Called whenever a hit test is being performed on an object that is using

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

@@ -17,10 +17,9 @@ export 'dart:ui' show SemanticsAction;
 /// Interface for [RenderObject]s to implement when they want to support
 /// being tapped, etc.
 ///
-/// These handlers will only be called if the relevant flag is set
-/// (e.g. [handleSemanticTap] will only be called if
-/// [SemanticsNode.canBeTapped] is true, [handleSemanticScrollDown] will only
-/// be called if [SemanticsNode.canBeScrolledVertically] is true, etc).
+/// The handler will only be called for a particular flag if that flag is set
+/// (e.g. [performAction] will only be called with [SemanticsAction.tap] if
+/// [SemanticsNode.addAction] was called for [SemanticsAction.tap].)
 abstract class SemanticsActionHandler { // ignore: one_member_abstracts
   /// Called when the object implementing this interface receives a
   /// [SemanticsAction]. For example, if the user of an accessibility tool
@@ -36,7 +35,7 @@ abstract class SemanticsActionHandler { // ignore: one_member_abstracts
 /// corresponds to the [RenderObject]. (One [SemanticsNode] can
 /// correspond to multiple [RenderObject] objects.)
 ///
-/// See [RenderObject.getSemanticsAnnotators()] for details on the
+/// See [RenderObject.semanticsAnnotator] for details on the
 /// contract that semantic annotators must follow.
 typedef void SemanticsAnnotator(SemanticsNode semantics);
 
@@ -74,7 +73,7 @@ class SemanticsData {
   /// A bit field of [SemanticsFlags] that apply to this node.
   final int flags;
 
-  /// A bit field of [SemanticsActions] that apply to this node.
+  /// A bit field of [SemanticsAction]s that apply to this node.
   final int actions;
 
   /// A textual description of this node.
@@ -606,8 +605,9 @@ class SemanticsNode extends AbstractNode {
 /// Owns [SemanticsNode] objects and notifies listeners of changes to the
 /// render tree semantics.
 ///
-/// To listen for semantic updates, call [PipelineOwner.addSemanticsListener],
-/// which will create a [SemanticsOwner] if necessary.
+/// To listen for semantic updates, call [PipelineOwner.ensureSemantics] to
+/// obtain a [SemanticsHandle]. This will create a [SemanticsOwner] if
+/// necessary.
 class SemanticsOwner extends ChangeNotifier {
   final Set<SemanticsNode> _dirtyNodes = new Set<SemanticsNode>();
   final Map<int, SemanticsNode> _nodes = <int, SemanticsNode>{};
@@ -626,7 +626,7 @@ class SemanticsOwner extends ChangeNotifier {
     super.dispose();
   }
 
-  /// Update the semantics using [ui.window.updateSemantics].
+  /// Update the semantics using [Window.updateSemantics].
   void sendSemanticsUpdate() {
     if (_dirtyNodes.isEmpty)
       return;
@@ -745,7 +745,7 @@ class SemanticsOwner extends ChangeNotifier {
     return node._canPerformAction(action) ? node._actionHandler : null;
   }
 
-  /// Asks the [SemanticsNode] with at the given position to perform the given action.
+  /// Asks the [SemanticsNode] at the given position to perform the given action.
   ///
   /// If the [SemanticsNode] has not indicated that it can perform the action,
   /// this function does nothing.

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

@@ -254,8 +254,17 @@ class SliverConstraints extends Constraints {
   ///
   /// For example, if [growthDirection] is [GrowthDirection.reverse] and
   /// [axisDirection] is [AxisDirection.down], then a
-  /// [userScrollDirection.forward] means that the user is scrolling up, in the
+  /// [ScrollDirection.forward] means that the user is scrolling up, in the
   /// positive [scrollOffset] direction.
+  ///
+  /// If the _user_ is not scrolling, this will return [ScrollDirection.idle]
+  /// even if there is (for example) a [ScrollActivity] currently animating the
+  /// position.
+  ///
+  /// This is used by some slivers to determine how to react to a change in
+  /// scroll offset. For example, [RenderSliverFloatingPersistentHeader] will
+  /// only expand a floating app bar when the [userScrollDirection] is in the
+  /// positive scroll offset direction.
   final ScrollDirection userScrollDirection;
 
   /// The scroll offset, in this sliver's coordinate system, that corresponds to

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

@@ -52,7 +52,8 @@ abstract class RenderSliverBoxChildManager {
   ///
   /// The index of the given child can be obtained using the
   /// [RenderSliverMultiBoxAdaptor.indexOf] method, which reads it from the
-  /// [SliverMultiBoxAdaptorParentData.index] field of the child's [parentData].
+  /// [SliverMultiBoxAdaptorParentData.index] field of the child's
+  /// [RenderObject.parentData].
   void removeChild(RenderBox child);
 
   /// Called to estimate the total scrollable extents of this object.
@@ -70,8 +71,8 @@ abstract class RenderSliverBoxChildManager {
   /// Called during [RenderSliverMultiBoxAdaptor.adoptChild].
   ///
   /// Subclasses must ensure that the [SliverMultiBoxAdaptorParentData.index]
-  /// field of the child's [parentData] accurately reflects the child's index in
-  /// the child list after this function returns.
+  /// field of the child's [RenderObject.parentData] accurately reflects the
+  /// child's index in the child list after this function returns.
   void didAdoptChild(RenderBox child);
 
   /// Called during layout to indicate whether this object provided insufficient

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

@@ -91,9 +91,9 @@ class RenderSliverPadding extends RenderSliver with RenderObjectWithChildMixin<R
     return null;
   }
 
-  /// The total padding in the [constraints.axisDirection]. (In other words, for
-  /// a vertical downwards-growing list, the sum of the padding on the top and
-  /// bottom.)
+  /// The total padding in the [SliverConstraints.axisDirection]. (In other
+  /// words, for a vertical downwards-growing list, the sum of the padding on
+  /// the top and bottom.)
   ///
   /// Only valid after layout has started, since before layout the render object
   /// doesn't know what direction it will be laid out in.

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

@@ -351,7 +351,7 @@ class RenderStack extends RenderBox
   /// Whether overflowing children should be clipped. See [Overflow].
   ///
   /// Some children in a stack might overflow its box. When this flag is set to
-  /// [Overflow.clipped], children cannot paint outside of the stack's box.
+  /// [Overflow.clip], children cannot paint outside of the stack's box.
   Overflow get overflow => _overflow;
   Overflow _overflow;
   set overflow(Overflow value) {

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

@@ -452,7 +452,7 @@ enum TableCellVerticalAlignment {
   /// Cells with this alignment are aligned such that they all share the same
   /// baseline. Cells with no baseline are top-aligned instead. The baseline
   /// used is specified by [RenderTable.baseline]. It is not valid to use the
-  /// baseline value if [RenderTable.baseline] is not specified.
+  /// baseline value if [RenderTable.textBaseline] is not specified.
   ///
   /// This vertial alignment is relatively expensive because it causes the table
   /// to compute the baseline for each cell in the row.

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

@@ -82,7 +82,7 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
     assert(offset != null);
   }
 
-  /// The direction in which the [scrollOffset] increases.
+  /// The direction in which the [SliverConstraints.scrollOffset] increases.
   ///
   /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
   /// offset of zero is at the top of the viewport and increases towards the
@@ -138,6 +138,56 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
     super.detach();
   }
 
+  /// Throws an exception saying that the object does not support returning
+  /// intrinsic dimensions if, in checked mode, we are not in the
+  /// [RenderObject.debugCheckingIntrinsics] mode.
+  ///
+  /// This is used by [computeMinIntrinsicWidth] et al because viewports do not
+  /// generally support returning intrinsic dimensions. See the discussion at
+  /// [computeMinIntrinsicWidth].
+  @protected
+  bool debugThrowIfNotCheckingIntrinsics() {
+    assert(() {
+      if (!RenderObject.debugCheckingIntrinsics) {
+        assert(this is! RenderShrinkWrappingViewport); // it has its own message
+        throw new FlutterError(
+          '$runtimeType does not support returning intrinsic dimensions.\n'
+          'Calculating the intrinsic dimensions would require instantiating every child of '
+          'the viewport, which defeats the point of viewports being lazy.\n'
+          'If you are merely trying to shrink-wrap the viewport in the main axis direction, '
+          'consider a RenderShrinkWrappingViewport render object (ShrinkWrappingViewport widget), '
+          'which achieves that effect without implementing the intrinsic dimension API.'
+        );
+      }
+      return true;
+    });
+    return true;
+  }
+
+  @override
+  double computeMinIntrinsicWidth(double height) {
+    assert(debugThrowIfNotCheckingIntrinsics());
+    return 0.0;
+  }
+
+  @override
+  double computeMaxIntrinsicWidth(double height) {
+    assert(debugThrowIfNotCheckingIntrinsics());
+    return 0.0;
+  }
+
+  @override
+  double computeMinIntrinsicHeight(double width) {
+    assert(debugThrowIfNotCheckingIntrinsics());
+    return 0.0;
+  }
+
+  @override
+  double computeMaxIntrinsicHeight(double width) {
+    assert(debugThrowIfNotCheckingIntrinsics());
+    return 0.0;
+  }
+
   @override
   bool get isRepaintBoundary => true;
 
@@ -161,8 +211,8 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
   ///  * `remainingPaintExtent` is [SliverConstraints.remainingPaintExtent] to
   ///    pass the first child. The remaining paint extent is updated by the
   ///    [SliverGeometry.layoutExtent] for subsequent children.
-  ///  * `mainAxisExtent` is the [SliverConstraints.mainAxisExtent] to pass to
-  ///    each child.
+  ///  * `mainAxisExtent` is the [SliverConstraints.viewportMainAxisExtent] to
+  ///    pass to each child.
   ///  * `crossAxisExtent` is the [SliverConstraints.crossAxisExtent] to pass to
   ///    each child.
   ///  * `growthDirection` is the [SliverConstraints.growthDirection] to pass to
@@ -1024,6 +1074,24 @@ class RenderShrinkWrappingViewport extends RenderViewportBase<SliverLogicalConta
       child.parentData = new SliverLogicalContainerParentData();
   }
 
+  @override
+  bool debugThrowIfNotCheckingIntrinsics() {
+    assert(() {
+      if (!RenderObject.debugCheckingIntrinsics) {
+        throw new FlutterError(
+          '$runtimeType does not support returning intrinsic dimensions.\n'
+          'Calculating the intrinsic dimensions would require instantiating every child of '
+          'the viewport, which defeats the point of viewports being lazy.\n'
+          'If you are merely trying to shrink-wrap the viewport in the main axis direction, '
+          'you should be able to achieve that effect by just giving the viewport loose '
+          'constraints, without needing to measure its intrinsic dimensions.'
+        );
+      }
+      return true;
+    });
+    return true;
+  }
+
   // Out-of-band data computed during layout.
   double _maxScrollExtent;
   double _shrinkWrapExtent;

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

@@ -55,7 +55,7 @@ ScrollDirection flipScrollDirection(ScrollDirection direction) {
 /// select which part of its content to display. As the user scrolls the
 /// viewport, this value changes, which changes the content that is displayed.
 ///
-/// This object is a [Listable] that notifies its listeners when [pixels]
+/// This object is a [Listenable] that notifies its listeners when [pixels]
 /// changes.
 ///
 /// See also:
@@ -155,13 +155,15 @@ abstract class ViewportOffset extends ChangeNotifier {
   /// The direction in which the user is trying to change [pixels], relative to
   /// the viewport's [RenderViewport.axisDirection].
   ///
-  /// If the user is not scrolling, this will return [ScrollDirection.idle] even
-  /// if there is an [activity] currently animating the position.
+  /// If the _user_ is not scrolling, this will return [ScrollDirection.idle]
+  /// even if there is (for example) a [ScrollActivity] currently animating the
+  /// position.
   ///
-  /// This is used by some slivers to determine how to react to a change in
-  /// scroll offset. For example, [RenderSliverFloatingPersistentHeader] will
-  /// only expand a floating app bar when the [userScrollDirection] is in the
-  /// positive scroll offset direction.
+  /// This is exposed in [SliverConstraints.userScrollDirection], which is used
+  /// by some slivers to determine how to react to a change in scroll offset.
+  /// For example, [RenderSliverFloatingPersistentHeader] will only expand a
+  /// floating app bar when the [userScrollDirection] is in the positive scroll
+  /// offset direction.
   ScrollDirection get userScrollDirection;
 
   @override

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

@@ -214,7 +214,7 @@ class RenderWrap extends RenderBox with ContainerRenderObjectMixin<RenderBox, Wr
   /// the cross axis.
   ///
   /// For example, if this is set to [WrapCrossAlignment.end], and the
-  /// [direction] is [WrapDirection.horizontal], then the children within each
+  /// [direction] is [Axis.horizontal], then the children within each
   /// run will have their bottom edges aligned to the bottom edge of the run.
   ///
   /// Defaults to [WrapCrossAlignment.start].

packages/flutter/lib/src/scheduler/binding.dart

@@ -98,7 +98,7 @@ class _FrameCallbackEntry {
 /// The values of this enum are ordered in the same order as the phases occur,
 /// so their relative index values can be compared to each other.
 ///
-/// See also [WidgetsBinding.beginFrame].
+/// See also the discussion at [WidgetsBinding.drawFrame].
 enum SchedulerPhase {
   /// No frame is being processed. Tasks (scheduled by
   /// [WidgetsBinding.scheduleTask]), microtasks (scheduled by
@@ -113,7 +113,7 @@ enum SchedulerPhase {
   /// Typically, these callbacks handle updating objects to new animation
   /// states.
   ///
-  /// See [handleBeginFrame].
+  /// See [SchedulerBinding.handleBeginFrame].
   transientCallbacks,
 
   /// Microtasks scheduled during the processing of transient callbacks are
@@ -127,7 +127,7 @@ enum SchedulerPhase {
   /// [WidgetsBinding.addPersistentFrameCallback]) are currently executing.
   ///
   /// Typically, this is the build/layout/paint pipeline. See
-  /// [WidgetsBinding.drawFrame] and [handleDrawFrame].
+  /// [WidgetsBinding.drawFrame] and [SchedulerBinding.handleDrawFrame].
   persistentCallbacks,
 
   /// The post-frame callbacks (scheduled by
@@ -136,24 +136,24 @@ enum SchedulerPhase {
   /// Typically, these callbacks handle cleanup and scheduling of work for the
   /// next frame.
   ///
-  /// See [handleDrawFrame].
+  /// See [SchedulerBinding.handleDrawFrame].
   postFrameCallbacks,
 }
 
 /// Scheduler for running the following:
 ///
-/// * _Transient callbacks_, triggered by the system's [ui.window.onBeginFrame]
+/// * _Transient callbacks_, triggered by the system's [Window.onBeginFrame]
 ///   callback, for synchronizing the application's behavior to the system's
 ///   display. For example, [Ticker]s and [AnimationController]s trigger from
 ///   these.
 ///
-/// * _Persistent callbacks_, triggered by the system's [ui.window.onDrawFrame]
+/// * _Persistent callbacks_, triggered by the system's [Window.onDrawFrame]
 ///   callback, for updating the system's display after transient callbacks have
 ///   executed. For example, the rendering layer uses this to drive its
 ///   rendering pipeline.
 ///
 /// * _Post-frame callbacks_, which are run after persistent callbacks, just
-///   before returning from the [ui.window.onDrawFrame] callback.
+///   before returning from the [Window.onDrawFrame] callback.
 ///
 /// * Non-rendering tasks, to be run between frames. These are given a
 ///   priority and are executed in priority order according to a
@@ -475,7 +475,7 @@ abstract class SchedulerBinding extends BindingBase {
   }
 
   /// If necessary, schedules a new frame by calling
-  /// [ui.window.scheduleFrame].
+  /// [Window.scheduleFrame].
   ///
   /// After this is called, the engine will (eventually) call
   /// [handleBeginFrame]. (This call might be delayed, e.g. if the device's

packages/flutter/lib/src/scheduler/debug.dart

@@ -21,7 +21,7 @@ import 'package:flutter/foundation.dart';
 /// intra-frame output from inter-frame output, set [debugPrintEndFrameBanner]
 /// to true as well.
 ///
-/// See [SchedulerBinding.beginFrame].
+/// See [SchedulerBinding.handleBeginFrame].
 bool debugPrintBeginFrameBanner = false;
 
 /// Print a banner at the end of each frame.
@@ -32,7 +32,7 @@ bool debugPrintEndFrameBanner = false;
 
 /// Log the call stacks that cause a frame to be scheduled.
 ///
-/// This is called whenever [Scheduler.scheduleFrame] schedules a frame. This
+/// This is called whenever [SchedulerBinding.scheduleFrame] schedules a frame. This
 /// can happen for various reasons, e.g. when a [Ticker] or
 /// [AnimationController] is started, or when [RenderObject.markNeedsLayout] is
 /// called, or when [State.setState] is called.

packages/flutter/lib/src/scheduler/ticker.dart

@@ -8,7 +8,7 @@ import 'package:flutter/foundation.dart';
 
 import 'binding.dart';
 
-/// Signature for the [onTick] constructor argument of the [Ticker] class.
+/// Signature for the callback passed to the [Ticker] class's constructor.
 ///
 /// The argument is the time that the object had spent enabled so far
 /// at the time of the callback being called.
@@ -54,7 +54,8 @@ abstract class TickerProvider {
 /// Tickers are driven by the [SchedulerBinding]. See
 /// [SchedulerBinding.scheduleFrameCallback].
 class Ticker {
-  /// Creates a ticker that will call [onTick] once per frame while running.
+  /// Creates a ticker that will call the provided callback once per frame while
+  /// running.
   ///
   /// An optional label can be provided for debugging purposes. That label
   /// will appear in the [toString] output in debug builds.

packages/flutter/lib/src/services/image_cache.dart

@@ -12,7 +12,7 @@ const int _kDefaultSize = 1000;
 /// size can be adjusted using [maximumSize]. Images that are actively in use
 /// (i.e. to which the application is holding references, either via
 /// [ImageStream] objects, [ImageStreamCompleter] objects, [ImageInfo] objects,
-/// or raw [ui.Image] objects) may get evicted from the cache (and thus need to
+/// or raw [Image] objects) may get evicted from the cache (and thus need to
 /// be refetched from the network if they are referenced in the [putIfAbsent]
 /// method), but the raw bits are kept in memory for as long as the application
 /// is using them.

packages/flutter/lib/src/services/image_decoder.dart

@@ -10,7 +10,7 @@ import 'dart:ui' as ui show Image, decodeImageFromList;
 ///
 /// This function attempts to interpret the given bytes an image. If successful,
 /// the returned [Future] resolves to the decoded image. Otherwise, the [Future]
-/// resolves to [null].
+/// resolves to null.
 Future<ui.Image> decodeImageFromList(Uint8List list) {
   final Completer<ui.Image> completer = new Completer<ui.Image>();
   ui.decodeImageFromList(list, completer.complete);

packages/flutter/lib/src/services/image_stream.dart

@@ -34,7 +34,7 @@ class ImageInfo {
   ///
   /// For example, if this is 2.0 it means that there are four image pixels for
   /// every one logical pixel, and the image's actual width and height (as given
-  /// by the [ui.Image.width] and [ui.Image.height] properties) are double the
+  /// by the [Image.width] and [Image.height] properties) are double the
   /// height and width that should be used when painting the image (e.g. in the
   /// arguments given to [Canvas.drawImage]).
   final double scale;

packages/flutter/lib/src/services/message_codec.dart

@@ -16,7 +16,7 @@ import 'platform_channel.dart';
 ///
 /// See also:
 ///
-/// * [PlatformMessageChannel], which use [MessageCodec]s for communication
+/// * [MessageChannel], which use [MessageCodec]s for communication
 ///   between Flutter and platform plugins.
 abstract class MessageCodec<T> {
   /// Encodes the specified [message] in binary.
@@ -99,9 +99,9 @@ class MethodCall {
 ///
 /// See also:
 ///
-/// * [PlatformMethodChannel], which use [MethodCodec]s for communication
+/// * [MethodChannel], which use [MethodCodec]s for communication
 ///   between Flutter and platform plugins.
-/// * [PlatformEventChannel], which use [MethodCodec]s for communication
+/// * [EventChannel], which use [MethodCodec]s for communication
 ///   between Flutter and platform plugins.
 abstract class MethodCodec {
   /// Encodes the specified [methodCall] into binary.

packages/flutter/lib/src/services/platform_messages.dart

@@ -55,7 +55,7 @@ class BinaryMessages {
   /// Calls the handler registered for the given channel.
   ///
   /// Typically called by [ServicesBinding] to handle platform messages received
-  /// from [ui.window.onPlatformMessage].
+  /// from [Window.onPlatformMessage].
   ///
   /// To register a handler for a given message channel, see [setMessageHandler].
   static Future<Null> handlePlatformMessage(

packages/flutter/lib/src/services/text_formatter.dart

@@ -133,7 +133,7 @@ class BlacklistingTextInputFormatter extends TextInputFormatter {
 class WhitelistingTextInputFormatter extends TextInputFormatter {
   /// Creates a formatter that allows only the insertion of whitelisted characters patterns.
   ///
-  /// The [blacklistedPattern] must not be null.
+  /// The [whitelistedPattern] must not be null.
   WhitelistingTextInputFormatter(this.whitelistedPattern) :
     assert(whitelistedPattern != null);
 

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

@@ -59,11 +59,13 @@ class AnimatedCrossFade extends StatefulWidget {
        super(key: key);
 
   /// The child that is visible when [crossFadeState] is [showFirst]. It fades
-  /// out when transitioning from [showFirst] to [showSecond] and vice versa.
+  /// out when transitioning [crossFadeState] from [CrossFadeState.showFirst] to
+  /// [CrossFadeState.showSecond] and vice versa.
   final Widget firstChild;
 
   /// The child that is visible when [crossFadeState] is [showSecond]. It fades
-  /// in when transitioning from [showFirst] to [showSecond] and vice versa.
+  /// in when transitioning [crossFadeState] from [CrossFadeState.showFirst] to
+  /// [CrossFadeState.showSecond] and vice versa.
   final Widget secondChild;
 
   /// The child that will be shown when the animation has completed.

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

@@ -178,8 +178,8 @@ class AnimatedList extends StatefulWidget {
 /// The state for a scrolling container that animates items when they are
 /// inserted or removed.
 ///
-/// When an item is inserted with [insertItem] an animation begins running.
-/// The animation is passed to [itemBuilder] whenever the item's widget
+/// When an item is inserted with [insertItem] an animation begins running. The
+/// animation is passed to [AnimatedList.itemBuilder] whenever the item's widget
 /// is needed.
 ///
 /// When an item is removed with [removeItem] its animation is reversed.
@@ -197,8 +197,8 @@ class AnimatedList extends StatefulWidget {
 /// listKey.currentState.insert(123);
 /// ```
 ///
-/// AnimatedList item input handlers can also refer to their [AnimatedListState]
-/// with the static [of] method.
+/// [AnimatedList] item input handlers can also refer to their [AnimatedListState]
+/// with the static [AnimatedList.of] method.
 class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixin {
   final List<_ActiveItem> _incomingItems = <_ActiveItem>[];
   final List<_ActiveItem> _outgoingItems = <_ActiveItem>[];
@@ -259,7 +259,7 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi
   }
 
   /// Insert an item at [index] and start an animation that will be passed
-  /// to [itemBuilder] when the item is visible.
+  /// to [AnimatedList.itemBuilder] when the item is visible.
   ///
   /// This method's semantics are the same as Dart's [List.insert] method:
   /// it increases the length of the list by one and shifts all items at or
@@ -300,9 +300,9 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi
   /// to [builder] when the item is visible.
   ///
   /// Items are removed immediately. After an item has been removed, its index
-  /// will no longer be passed to the [itemBuilder]. However the item will still
-  /// appear in the list for [duration] and during that time [builder] must
-  /// construct its widget as needed.
+  /// will no longer be passed to the [AnimatedList.itemBuilder]. However the
+  /// item will still appear in the list for [duration] and during that time
+  /// [builder] must construct its widget as needed.
   ///
   /// This method's semantics are the same as Dart's [List.remove] method:
   /// it decreases the length of the list by one and shifts all items at or

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

@@ -47,8 +47,8 @@ abstract class StreamBuilderBase<T, S> extends StatefulWidget {
 
   /// The asynchronous computation to which this builder is currently connected,
   /// possibly null. When changed, the current summary is updated using
-  /// [afterDisconnecting], if the previous stream was not null, followed by
-  /// [afterConnecting], if the new stream is not null.
+  /// [afterDisconnected], if the previous stream was not null, followed by
+  /// [afterConnected], if the new stream is not null.
   final Stream<T> stream;
 
   /// Returns the initial summary of stream interaction, typically representing
@@ -349,17 +349,17 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
 ///
 /// Widget rebuilding is scheduled by the completion of the future, using
 /// [State.setState], but is otherwise decoupled from the timing of the future.
-/// The [build] method is called at the discretion of the Flutter pipeline, and
+/// The [builder] callback is called at the discretion of the Flutter pipeline, and
 /// will thus receive a timing-dependent sub-sequence of the snapshots that
 /// represent the interaction with the future.
 ///
-/// For a future that completes successfully with data, the [build] method may
+/// For a future that completes successfully with data, the [builder] may
 /// be called with either both or only the latter of the following snapshots:
 ///
 /// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)`
 /// * `new AsyncSnapshot<String>(ConnectionState.done, 'some data', null)`
 ///
-/// For a future completing with an error, the [build] method may be called with
+/// For a future completing with an error, the [builder] may be called with
 /// either both or only the latter of:
 ///
 /// * `new AsyncSnapshot<String>(ConnectionState.waiting, null, null)`

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

@@ -103,7 +103,7 @@ class Opacity extends SingleChildRenderObjectWidget {
 /// A widget that applies a mask generated by a [Shader] to its child.
 ///
 /// For example, [ShaderMask] can be used to gradually fade out the edge
-/// of a child by using a [ui.Gradient.linear] mask.
+/// of a child by using a [new ui.Gradient.linear] mask.
 class ShaderMask extends SingleChildRenderObjectWidget {
   /// Creates a widget that applies a mask generated by a [Shader] to its child.
   ///
@@ -162,7 +162,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
 
   /// The image filter to apply to the existing painted content before painting the child.
   ///
-  /// For example, consider using [ui.ImageFilter.blur] to create a backdrop
+  /// For example, consider using [ImageFilter.blur] to create a backdrop
   /// blur effect
   final ui.ImageFilter filter;
 
@@ -1152,7 +1152,7 @@ class LimitedBox extends SingleChildRenderObjectWidget {
 /// A widget that imposes different constraints on its child than it gets
 /// from its parent, possibly allowing the child to overflow the parent.
 ///
-/// See [RenderOverflowBox] for details.
+/// See [RenderConstrainedOverflowBox] for details.
 class OverflowBox extends SingleChildRenderObjectWidget {
   /// Creates a widget that lets its child overflow itself.
   const OverflowBox({
@@ -1520,10 +1520,10 @@ class SliverToBoxAdapter extends SingleChildRenderObjectWidget {
 /// side.
 ///
 /// Applying padding to anything but the most mundane sliver is likely to have
-/// undesired effects. For example, wrapping a
-/// [SliverPinnedPersistentHeader] will cause the app bar to overlap
-/// earlier slivers (contrary to the normal behavior of pinned app bars), and
-/// while the app bar is pinned, the padding will scroll away.
+/// undesired effects. For example, wrapping a [SliverPersistentHeader] with
+/// `pinned:true` will cause the app bar to overlap earlier slivers (contrary to
+/// the normal behavior of pinned app bars), and while the app bar is pinned,
+/// the padding will scroll away.
 ///
 /// See also:
 ///
@@ -1671,7 +1671,7 @@ class Stack extends MultiChildRenderObjectWidget {
   /// Whether overflowing children should be clipped. See [Overflow].
   ///
   /// Some children in a stack might overflow its box. When this flag is set to
-  /// [Overflow.clipped], children cannot paint outside of the stack's box.
+  /// [Overflow.clip], children cannot paint outside of the stack's box.
   final Overflow overflow;
 
   @override
@@ -1921,7 +1921,7 @@ class Positioned extends ParentDataWidget<Stack> {
 /// The [Flex] widget does not scroll (and in general it is considered an error
 /// to have more children in a [Flex] than will fit in the available room). If
 /// you have some widgets and want them to be able to scroll if there is
-/// insufficient room, consider using a [ScrollList].
+/// insufficient room, consider using a [ListView].
 ///
 /// If you only have one child, then rather than using [Flex], [Row], or
 /// [Column], consider using [Align] or [Center] to position the child.
@@ -2050,7 +2050,7 @@ class Flex extends MultiChildRenderObjectWidget {
 /// The [Row] widget does not scroll (and in general it is considered an error
 /// to have more children in a [Row] than will fit in the available room). If
 /// you have a line of widgets and want them to be able to scroll if there is
-/// insufficient room, consider using a [ScrollList].
+/// insufficient room, consider using a [ListView].
 ///
 /// For a vertical variant, see [Column].
 ///
@@ -2121,7 +2121,7 @@ class Row extends Flex {
 /// The [Column] widget does not scroll (and in general it is considered an error
 /// to have more children in a [Column] than will fit in the available room). If
 /// you have a line of widgets and want them to be able to scroll if there is
-/// insufficient room, consider using a [ScrollList].
+/// insufficient room, consider using a [ListView].
 ///
 /// For a horizontal variant, see [Row].
 ///
@@ -2380,7 +2380,7 @@ class Wrap extends MultiChildRenderObjectWidget {
   /// the cross axis.
   ///
   /// For example, if this is set to [WrapCrossAlignment.end], and the
-  /// [direction] is [WrapDirection.horizontal], then the children within each
+  /// [direction] is [Axis.horizontal], then the children within each
   /// run will have their bottom edges aligned to the bottom edge of the run.
   ///
   /// Defaults to [WrapCrossAlignment.start].
@@ -2590,7 +2590,7 @@ class RichText extends LeafRenderObjectWidget {
   }
 }
 
-/// A widget that displays a [ui.Image] directly.
+/// A widget that displays a [dart:ui.Image] directly.
 ///
 /// The image is painted using [paintImage], which describes the meanings of the
 /// various fields on this class in more detail.
@@ -2937,7 +2937,7 @@ class RepaintBoundary extends SingleChildRenderObjectWidget {
 /// When [ignoring] is true, this widget (and its subtree) is invisible
 /// to hit testing. It still consumes space during layout and paints its child
 /// as usual. It just cannot be the target of located events, because it returns
-/// false from [hitTest].
+/// false from [RenderBox.hitTest].
 ///
 /// When [ignoringSemantics] is true, the subtree will be invisible to
 /// the semantics layer (and thus e.g. accessibility tools). If
@@ -3001,7 +3001,7 @@ class IgnorePointer extends SingleChildRenderObjectWidget {
 /// pointer events by terminating hit testing at itself. It still consumes space
 /// during layout and paints its child as usual. It just prevents its children
 /// from being the target of located events, because it returns true from
-/// [hitTest].
+/// [RenderBox.hitTest].
 ///
 /// See also:
 ///

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

@@ -154,7 +154,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   /// Notifies all the observers using
   /// [WidgetsBindingObserver.didChangeMetrics].
   ///
-  /// See [ui.window.onMetricsChanged].
+  /// See [window.onMetricsChanged].
   @override
   void handleMetricsChanged() {
     super.handleMetricsChanged();
@@ -166,7 +166,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   ///
   /// Calls [dispatchLocaleChanged] to notify the binding observers.
   ///
-  /// See [ui.window.onLocaleChanged].
+  /// See [Window.onLocaleChanged].
   void handleLocaleChanged() {
     dispatchLocaleChanged(ui.window.locale);
   }
@@ -293,7 +293,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   /// Each frame consists of the following phases:
   ///
   /// 1. The animation phase: The [handleBeginFrame] method, which is registered
-  /// with [ui.window.onBeginFrame], invokes all the transient frame callbacks
+  /// with [window.onBeginFrame], invokes all the transient frame callbacks
   /// registered with [scheduleFrameCallback], in
   /// registration order. This includes all the [Ticker] instances that are
   /// driving [AnimationController] objects, which means all of the active
@@ -305,7 +305,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   /// completed this frame.
   ///
   /// After [handleBeginFrame], [handleDrawFrame], which is registered with
-  /// [ui.window.onDrawFrame], is called, which invokes all the persistent frame
+  /// [window.onDrawFrame], is called, which invokes all the persistent frame
   /// callbacks, of which the most notable is this method, [drawFrame], which
   /// proceeds as follows:
   ///
@@ -327,7 +327,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   /// [RenderObject.markNeedsPaint] for further details on marking an object
   /// dirty for paint.
   ///
-  /// 7. The compositing phase: The layer tree is turned into a [ui.Scene] and
+  /// 7. The compositing phase: The layer tree is turned into a [Scene] and
   /// sent to the GPU.
   ///
   /// 8. The semantics phase: All the dirty [RenderObject]s in the system have

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

@@ -85,7 +85,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
 ///
 /// A container first surrounds the child with [padding] (inflated by any
 /// borders present in the [decoration]) and then applies additional
-/// [constraints] to the padded extent (incorporating the [width] and [height]
+/// [constraints] to the padded extent (incorporating the `width` and `height`
 /// as constraints, if either is non-null). The container is then surrounded by
 /// additional empty space described from the [margin].
 ///

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

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'dart:collection';
+import 'dart:developer' show Timeline; // to disambiguate reference in dartdocs below
 
 import 'package:flutter/foundation.dart';
 
@@ -18,10 +19,12 @@ import 'table.dart';
 /// Combined with [debugPrintBuildScope] or [debugPrintBeginFrameBanner], this
 /// allows you to distinguish builds triggered by the initial mounting of a
 /// widget tree (e.g. in a call to [runApp]) from the regular builds triggered
-/// by the pipeline (see [WidgetsBinding.beginFrame].
+/// by the pipeline.
 ///
 /// Combined with [debugPrintScheduleBuildForStacks], this lets you watch a
 /// widget's dirty/clean lifecycle.
+///
+/// See also the discussion at [WidgetsBinding.drawFrame].
 bool debugPrintRebuildDirtyWidgets = false;
 
 /// Log all calls to [BuildOwner.buildScope].
@@ -32,8 +35,9 @@ bool debugPrintRebuildDirtyWidgets = false;
 /// Combined with [debugPrintRebuildDirtyWidgets] or
 /// [debugPrintBeginFrameBanner], this allows you to distinguish builds
 /// triggered by the initial mounting of a widget tree (e.g. in a call to
-/// [runApp]) from the regular builds triggered by the pipeline (see
-/// [WidgetsBinding.beginFrame].
+/// [runApp]) from the regular builds triggered by the pipeline.
+///
+/// See also the discussion at [WidgetsBinding.drawFrame].
 bool debugPrintBuildScope = false;
 
 /// Log the call stacks that mark widgets as needing to be rebuilt.
@@ -44,7 +48,7 @@ bool debugPrintBuildScope = false;
 ///
 /// To see when a widget is rebuilt, see [debugPrintRebuildDirtyWidgets].
 ///
-/// To see when the dirty list is flushed, see [debugPrintBuildDirtyElements].
+/// To see when the dirty list is flushed, see [debugPrintBuildScope].
 ///
 /// To see when a frame is scheduled, see [debugPrintScheduleFrameStacks].
 bool debugPrintScheduleBuildForStacks = false;
@@ -132,7 +136,7 @@ bool debugItemsHaveDuplicateKeys(Iterable<Widget> items) {
 /// Used by [TableRowInkWell] to make sure that it is only used in an appropriate context.
 ///
 /// To invoke this function, use the following pattern, typically in the
-/// relevant Widget's [build] method:
+/// relevant Widget's build method:
 ///
 /// ```dart
 /// assert(debugCheckHasTable(context));
@@ -163,7 +167,7 @@ bool debugCheckHasTable(BuildContext context) {
 /// appropriate context.
 ///
 /// To invoke this function, use the following pattern, typically in the
-/// relevant Widget's [build] method:
+/// relevant Widget's build method:
 ///
 /// ```dart
 /// assert(debugCheckHasMediaQuery(context));

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

@@ -57,7 +57,7 @@ enum DismissDirection {
 /// is specified it is stacked behind the Dismissible's child and is exposed when
 /// the child moves.
 ///
-/// The widget calls the [onDimissed] callback either after its size has
+/// The widget calls the [onDismissed] callback either after its size has
 /// collapsed to zero (if [resizeDuration] is non-null) or immediately after
 /// the slide animation (if [resizeDuration] is null). If the Dismissible is a
 /// list item, it must have a key that distinguishes it from the other items and

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

@@ -171,7 +171,8 @@ class EditableText extends StatefulWidget {
   /// For example, if the text scale factor is 1.5, text will be 50% larger than
   /// the specified font size.
   ///
-  /// Defaults to [MediaQuery.textScaleFactor].
+  /// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
+  /// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
   final double textScaleFactor;
 
   /// The color to use when painting the cursor.

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

@@ -379,8 +379,8 @@ class FocusScopeNode extends Object with TreeDiagnosticsMixin {
 /// the root of the focus tree and tracking which [FocusNode] has the overall
 /// focus.
 ///
-/// The [FocusManager] is held by the [WidgetBinding] as
-/// [WidgetBinding.focusManager]. The [FocusManager] is rarely accessed
+/// The [FocusManager] is held by the [WidgetsBinding] as
+/// [WidgetsBinding.focusManager]. The [FocusManager] is rarely accessed
 /// directly. Instead, to find the [FocusScopeNode] for a given [BuildContext],
 /// use [FocusScope.of].
 ///
@@ -395,7 +395,7 @@ class FocusManager {
   /// Creates an object that manages the focus tree.
   ///
   /// This constructor is rarely called directly. To access the [FocusManager],
-  /// consider using [WidgetBinding.focusManager] instead.
+  /// consider using [WidgetsBinding.focusManager] instead.
   FocusManager() {
     rootScope._manager = this;
     assert(rootScope._firstChild == null);

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

@@ -9,7 +9,7 @@ import 'routes.dart';
 import 'will_pop_scope.dart';
 
 /// An optional container for grouping together multiple form field widgets
-/// (e.g. [Input] widgets).
+/// (e.g. [TextField] widgets).
 ///
 /// Each individual form field should be wrapped in a [FormField] widget, with
 /// the [Form] widget as a common ancestor of all of those. Call methods on

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

@@ -734,9 +734,10 @@ abstract class State<T extends StatefulWidget> {
   /// A [State] object's configuration is the corresponding [StatefulWidget]
   /// instance. This property is initialized by the framework before calling
   /// [initState]. If the parent updates this location in the tree to a new
-  /// widget with the same [runtimeType] and [key] as the current configuration,
-  /// the framework will update this property to refer to the new widget and
-  /// then call [didUpdateWidget], passing the old configuration as an argument.
+  /// widget with the same [runtimeType] and [Widget.key] as the current
+  /// configuration, the framework will update this property to refer to the new
+  /// widget and then call [didUpdateWidget], passing the old configuration as
+  /// an argument.
   T get widget => _widget;
   T _widget;
 
@@ -806,10 +807,10 @@ abstract class State<T extends StatefulWidget> {
   /// Called whenever the widget configuration changes.
   ///
   /// If the parent widget rebuilds and request that this location in the tree
-  /// update to display a new widget with the same [runtimeType] and [key], the
-  /// framework will update the [widget] property of this [State] object to
-  /// refer to the new widget and then call the this method with the previous
-  /// widget as an argument.
+  /// update to display a new widget with the same [runtimeType] and
+  /// [Widget.key], the framework will update the [widget] property of this
+  /// [State] object to refer to the new widget and then call the this method
+  /// with the previous widget as an argument.
   ///
   /// Override this method to respond to changes in the [widget] widget (e.g.,
   /// to start implicit animations).
@@ -1517,8 +1518,8 @@ abstract class BuildContext {
   /// [RenderObjectWidget].
   ///
   /// This method will only return a valid result after the build phase is
-  /// complete. It is therefore not valid to call this from the [build] function
-  /// itself. It should only be called from interaction event handlers (e.g.
+  /// complete. It is therefore not valid to call this from a build method.
+  /// It should only be called from interaction event handlers (e.g.
   /// gesture callbacks) or layout or paint callbacks.
   ///
   /// If the render object is a [RenderBox], which is the common case, then the
@@ -1527,8 +1528,8 @@ abstract class BuildContext {
   /// from paint callbacks or interaction event handlers (e.g. gesture
   /// callbacks).
   ///
-  /// For details on the different phases of a frame, see
-  /// [WidgetsBinding.beginFrame].
+  /// For details on the different phases of a frame, see the discussion at
+  /// [WidgetsBinding.drawFrame].
   ///
   /// Calling this method is theoretically relatively expensive (O(N) in the
   /// depth of the tree), but in practice is usually cheap because the tree
@@ -1539,12 +1540,12 @@ abstract class BuildContext {
   /// The size of the [RenderBox] returned by [findRenderObject].
   ///
   /// This getter will only return a valid result after the layout phase is
-  /// complete. It is therefore not valid to call this from the [build] function
-  /// itself. It should only be called from paint callbacks or interaction event
+  /// complete. It is therefore not valid to call this from a build method.
+  /// It should only be called from paint callbacks or interaction event
   /// handlers (e.g. gesture callbacks).
   ///
-  /// For details on the different phases of a frame, see
-  /// [WidgetsBinding.beginFrame].
+  /// For details on the different phases of a frame, see the discussion at
+  /// [WidgetsBinding.drawFrame].
   ///
   /// This getter will only return a valid result if [findRenderObject] actually
   /// returns a [RenderBox]. If [findRenderObject] returns a render object that
@@ -1750,7 +1751,7 @@ class BuildOwner {
   bool _dirtyElementsNeedsResorting; // null means we're not in a buildScope
 
   /// Adds an element to the dirty elements list so that it will be rebuilt
-  /// when [WidgetsBinding.beginFrame] calls [buildScope].
+  /// when [WidgetsBinding.drawFrame] calls [buildScope].
   void scheduleBuildFor(Element element) {
     assert(element != null);
     assert(element.owner == this);
@@ -1832,8 +1833,8 @@ class BuildOwner {
   /// `callback`, if any. Then, builds all the elements that were marked as
   /// dirty using [scheduleBuildFor], in depth order.
   ///
-  /// This mechanism prevents build functions from transitively requiring other
-  /// build functions to run, potentially causing infinite loops.
+  /// This mechanism prevents build methods from transitively requiring other
+  /// build methods to run, potentially causing infinite loops.
   ///
   /// The dirty list is processed after `callback` returns, building all the
   /// elements that were marked as dirty using [scheduleBuildFor], in depth
@@ -1843,11 +1844,16 @@ class BuildOwner {
   ///
   /// To flush the current dirty list without performing any other work, this
   /// function can be called with no callback. This is what the framework does
-  /// each frame, in [WidgetsBinding.beginFrame].
+  /// each frame, in [WidgetsBinding.drawFrame].
   ///
   /// Only one [buildScope] can be active at a time.
   ///
   /// A [buildScope] implies a [lockState] scope as well.
+  ///
+  /// To print a console message every time this method is called, set
+  /// [debugPrintBuildScope] to true. This is useful when debugging problems
+  /// involving widgets not getting marked dirty, or getting marked dirty too
+  /// often.
   void buildScope(Element context, [VoidCallback callback]) {
     if (callback == null && _dirtyElements.isEmpty)
       return;
@@ -1970,7 +1976,7 @@ class BuildOwner {
   /// Complete the element build pass by unmounting any elements that are no
   /// longer active.
   ///
-  /// This is called by [WidgetsBinding.beginFrame].
+  /// This is called by [WidgetsBinding.drawFrame].
   ///
   /// In debug mode, this also runs some sanity checks, for example checking for
   /// duplicate global keys.
@@ -3058,7 +3064,7 @@ abstract class Element implements BuildContext {
 
 /// A widget that renders an exception's message.
 ///
-/// This widget is used when a build function fails, to help with determining
+/// This widget is used when a build method fails, to help with determining
 /// where the problem lies. Exceptions are also logged to the console, which you
 /// can read using `flutter logs`. The console will also include additional
 /// information such as the stack trace for the exception.
@@ -3096,7 +3102,7 @@ typedef Widget WidgetBuilder(BuildContext context);
 /// Signature for a function that creates a widget for a given index, e.g., in a
 /// list.
 ///
-/// Used by [LazyBlockBuilder.builder].
+/// Used by [ListView.builder] and other APIs that use lazily-generated widgets.
 typedef Widget IndexedWidgetBuilder(BuildContext context, int index);
 
 /// An [Element] that composes other [Element]s.
@@ -3285,7 +3291,7 @@ class StatefulElement extends ComponentElement {
   void activate() {
     super.activate();
     // Since the State could have observed the deactivate() and thus disposed of
-    // resources allocated in the build function, we have to rebuild the widget
+    // resources allocated in the build method, we have to rebuild the widget
     // so that its State can reallocate its resources.
     assert(_active); // otherwise markNeedsBuild is a no-op
     markNeedsBuild();
@@ -3588,7 +3594,7 @@ class InheritedElement extends ProxyElement {
 /// ### Updating children
 ///
 /// Early in the lifecycle of an element, the framework calls the [mount]
-/// method. This method should call [inflateChild] for each child, passing in
+/// method. This method should call [updateChild] for each child, passing in
 /// the widget for that child, and the slot for that child, thus obtaining a
 /// list of child [Element]s.
 ///
@@ -3607,9 +3613,9 @@ class InheritedElement extends ProxyElement {
 /// method may be useful in this regard.
 ///
 /// [updateChild] should be called for children in their logical order. The
-/// order can matter; for example, if two of the children use [Focus.at]'s
-/// `autofocus` feature in their build method, then the first one to be updated
-/// will gain the focus.
+/// order can matter; for example, if two of the children use [PageStorage]'s
+/// `writeState` feature in their build method (and neither has a [key]), then
+/// the state written by the first will be overwritten by the second.
 ///
 /// #### Dynamically determining the children during the build phase
 ///
@@ -3623,8 +3629,9 @@ class InheritedElement extends ProxyElement {
 /// the [update] method won't work: layout of this element's render object
 /// hasn't started yet at that point. Instead, the [update] method can mark the
 /// render object as needing layout (see [RenderObject.markNeedsLayout]), and
-/// then the render object's [performLayout] method can call back to the element
-/// to have it generate the widgets and call [updateChild] accordingly.
+/// then the render object's [RenderOBject.performLayout] method can call back
+/// to the element to have it generate the widgets and call [updateChild]
+/// accordingly.
 ///
 /// For a render object to call an element during layout, it must use
 /// [RenderObject.invokeLayoutCallback]. For an element to call [updateChild]
@@ -4011,7 +4018,7 @@ abstract class RootRenderObjectElement extends RenderObjectElement {
   /// [WidgetsBinding.buildOwner], and assigns it to the widget tree in the call
   /// to [runApp]. The binding is responsible for driving the build pipeline by
   /// calling the build owner's [BuildOwner.buildScope] method. See
-  /// [WidgetsBinding.beginFrame].
+  /// [WidgetsBinding.drawFrame].
   void assignOwner(BuildOwner owner) {
     _owner = owner;
   }

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

@@ -91,7 +91,7 @@ class Hero extends StatefulWidget {
   final Object tag;
 
   /// The widget subtree that will "fly" from one route to another during a
-  /// [Naviator] push or pop transition.
+  /// [Navigator] push or pop transition.
   ///
   /// The appearance of this subtree should be similar to the appearance of
   /// the subtrees of any other heroes in the application with the same [tag].
@@ -398,7 +398,7 @@ class _HeroFlight {
 
 /// A [Navigator] observer that manages [Hero] transitions.
 ///
-/// An instance of [HeroController] should be used as the [Navigator.observer].
+/// An instance of [HeroController] should be used in [Navigator.observers].
 /// This is done automatically by [MaterialApp].
 class HeroController extends NavigatorObserver {
   /// Creates a hero controller with the given [RectTween] constructor if any.

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

@@ -243,10 +243,10 @@ abstract class AnimatedWidgetBaseState<T extends ImplicitlyAnimatedWidget> exten
 /// duration. Properties that are null are not animated.
 ///
 /// This class is useful for generating simple implicit transitions between
-/// different parameters to [Container] with its internal
-/// [AnimationController]. For more complex animations, you'll likely want to
-/// use a subclass of [Transition] such as the [DecoratedBoxTransition] or use
-/// your own [AnimationController].
+/// different parameters to [Container] with its internal [AnimationController].
+/// For more complex animations, you'll likely want to use a subclass of
+/// [AnimatedWidget] such as the [DecoratedBoxTransition] or use your own
+/// [AnimationController].
 class AnimatedContainer extends ImplicitlyAnimatedWidget {
   /// Creates a container that animates its parameters implicitly.
   ///

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

@@ -16,12 +16,12 @@ typedef Widget LayoutWidgetBuilder(BuildContext context, BoxConstraints constrai
 /// Similar to the [Builder] widget except that the framework calls the [builder]
 /// function at layout time and provides the parent widget's constraints. This
 /// is useful when the parent constrains the child's size and doesn't depend on
-/// the child's intrinsic size. The LayoutBuilder's final size will match its
+/// the child's intrinsic size. The [LayoutBuilder]'s final size will match its
 /// child's size.
 ///
 /// If the child should be smaller than the parent, consider wrapping the child
 /// in an [Align] widget. If the child might want to be bigger, consider
-/// wrapping it in a [ScrollableViewport].
+/// wrapping it in a [SingleChildScrollView].
 ///
 /// See also:
 ///
@@ -168,8 +168,8 @@ class _RenderLayoutBuilder extends RenderBox with RenderObjectWithChildMixin<Ren
       if (!RenderObject.debugCheckingIntrinsics) {
         throw new FlutterError(
           'LayoutBuilder does not support returning intrinsic dimensions.\n'
-          'Calculating the intrinsic dimensions would require running the layout callback speculatively, '
-          'which might mutate the live render object tree.'
+          'Calculating the intrinsic dimensions would require running the layout '
+          'callback speculatively, which might mutate the live render object tree.'
         );
       }
       return true;

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

@@ -35,7 +35,7 @@ class MediaQueryData {
   /// Creates data for a media query with explicit values.
   ///
   /// Consider using [MediaQueryData.fromWindow] to create data based on a
-  /// [ui.Window].
+  /// [Window].
   const MediaQueryData({
     this.size: Size.zero,
     this.devicePixelRatio: 1.0,
@@ -48,7 +48,7 @@ class MediaQueryData {
   /// If you use this, you should ensure that you also register for
   /// notifications so that you can update your [MediaQueryData] when the
   /// window's metrics change. For example, see
-  /// [WidgetsBindingObserver.didChangeMetrics] or [ui.window.onMetricsChanged].
+  /// [WidgetsBindingObserver.didChangeMetrics] or [Window.onMetricsChanged].
   MediaQueryData.fromWindow(ui.Window window)
     : size = window.physicalSize / window.devicePixelRatio,
       devicePixelRatio = window.devicePixelRatio,

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

@@ -64,7 +64,7 @@ abstract class Route<T> {
   void didReplace(Route<dynamic> oldRoute) { }
 
   /// Returns false if this route wants to veto a [Navigator.pop]. This method is
-  /// called by [Naviagtor.willPop].
+  /// called by [Navigator.willPop].
   ///
   /// By default, routes veto a pop if they're the first route in the history
   /// (i.e., if [isFirst]). This behavior prevents the user from popping the
@@ -72,7 +72,7 @@ abstract class Route<T> {
   ///
   /// See also:
   ///
-  /// * [Form], which provides an `onWillPop` callback that uses this mechanism.
+  /// * [Form], which provides a [Form.onWillPop] callback that uses this mechanism.
   Future<RoutePopDisposition> willPop() async {
     return isFirst ? RoutePopDisposition.bubble : RoutePopDisposition.pop;
   }
@@ -156,7 +156,7 @@ abstract class Route<T> {
   /// If attempts to dismiss this route might be vetoed, for example because
   /// a [WillPopCallback] was defined for the route, then it may make sense
   /// to disable the pop gesture. For example, the iOS back gesture is disabled
-  /// when [ModalRoute.hasScopedWillCallback] is true.
+  /// when [ModalRoute.hasScopedWillPopCallback] is true.
   NavigationGestureController startPopGesture() => null;
 
   /// Whether this route is the top-most route on the navigator.
@@ -426,7 +426,7 @@ typedef bool RoutePredicate(Route<dynamic> route);
 /// because they block input to the widgets below.
 ///
 /// There are functions which create and show popup routes. For
-/// example: [showDialog], [showMenu], and [showBottomSheet]. These
+/// example: [showDialog], [showMenu], and [showModalBottomSheet]. These
 /// functions return their pushed route's Future as described above.
 /// Callers can await the returned value to take an action when the
 /// route is popped, or to discover the route's value.
@@ -527,8 +527,8 @@ class Navigator extends StatefulWidget {
   /// encloses the given context, and transitions to it.
   ///
   /// The new route and the previous route (if any) are notified (see
-  /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has an
-  /// [Navigator.observer], it will be notified as well (see
+  /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has any
+  /// [Navigator.observers], they will be notified as well (see
   /// [NavigatorObserver.didPush]).
   ///
   /// Ongoing gestures within the current route are canceled when a new route is
@@ -540,9 +540,9 @@ class Navigator extends StatefulWidget {
     return Navigator.of(context).push(route);
   }
 
-  /// Returns the value of the current route's `willPop` method. This method is
-  /// typically called before a user-initiated [pop]. For example on Android it's
-  /// called by the binding for the system's back button.
+  /// Returns the value of the current route's [Route.willPop] method. This
+  /// method is typically called before a user-initiated [pop]. For example on
+  /// Android it's called by the binding for the system's back button.
   ///
   /// See also:
   ///
@@ -791,8 +791,8 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin {
   /// Adds the given route to the navigator's history, and transitions to it.
   ///
   /// The new route and the previous route (if any) are notified (see
-  /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has an
-  /// [Navigator.observer], it will be notified as well (see
+  /// [Route.didPush] and [Route.didChangeNext]). If the [Navigator] has any
+  /// [Navigator.observers], they will be notified as well (see
   /// [NavigatorObserver.didPush]).
   ///
   /// Ongoing gestures within the current route are canceled when a new route is
@@ -991,7 +991,7 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin {
   ///
   /// If there are any routes left on the history, the top remaining route is
   /// notified (see [Route.didPopNext]), and the method returns true. In that
-  /// case, if the [Navigator] has an [Navigator.observer], it will be notified
+  /// case, if the [Navigator] has any [Navigator.observers], they will be notified
   /// as well (see [NavigatorObserver.didPop]). Otherwise, if the popped route
   /// was the last route, the method returns false.
   ///

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

@@ -44,7 +44,7 @@ import 'ticker_provider.dart';
 /// overlay entry is still built even if it is not visible, set [maintainState]
 /// to true. This is more expensive, so should be done with care. In particular,
 /// if widgets in an overlay entry with [maintainState] set to true repeatedly
-/// call [setState], the user's battery will be drained unnecessarily.
+/// call [State.setState], the user's battery will be drained unnecessarily.
 ///
 /// See also:
 ///
@@ -99,7 +99,7 @@ class OverlayEntry {
   /// overlay entry is still built even if it is not visible, set [maintainState]
   /// to true. This is more expensive, so should be done with care. In particular,
   /// if widgets in an overlay entry with [maintainState] set to true repeatedly
-  /// call [setState], the user's battery will be drained unnecessarily.
+  /// call [State.setState], the user's battery will be drained unnecessarily.
   ///
   /// This is used by the [Navigator] and [Route] objects to ensure that routes
   /// are kept around even when in the background, so that [Future]s promised
@@ -123,8 +123,8 @@ class OverlayEntry {
   /// This should only be called once.
   ///
   /// If this method is called while the [SchedulerBinding.schedulerPhase] is
-  /// [SchedulerBinding.persistentCallbacks], i.e. during the build, layout, or
-  /// paint phases (see [WidgetsBinding.beginFrame]), then the removal is
+  /// [SchedulerPhase.persistentCallbacks], i.e. during the build, layout, or
+  /// paint phases (see [WidgetsBinding.drawFrame]), then the removal is
   /// delayed until the post-frame callbacks phase. Otherwise the removal is
   /// done synchronously. This means that it is safe to call during builds, but
   /// also that if you do call this during a build, the UI will not update until

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

@@ -15,7 +15,7 @@ import 'package:flutter/widgets.dart';
 ///
 /// A [GlowingOverscrollIndicator] listens for [ScrollNotification]s in order
 /// to control the overscroll indication. These notifications are typically
-/// generated by a [ScrolView], such as a [ListView] or a [GridView].
+/// generated by a [ScrollView], such as a [ListView] or a [GridView].
 ///
 /// [GlowingOverscrollIndicator] generates [OverscrollIndicatorNotification]
 /// before showing an overscroll indication. To prevent the indicator from

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

@@ -26,7 +26,7 @@ class PerformanceOverlay extends LeafRenderObjectWidget {
 
   /// Create a performance overlay that only displays specific statistics. The
   /// mask is created by shifting 1 by the index of the specific
-  /// [StatisticOption] to enable.
+  /// [PerformanceOverlayOption] to enable.
   const PerformanceOverlay({
     Key key,
     this.optionsMask: 0,

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

@@ -280,7 +280,7 @@ class LocalHistoryEntry {
 /// opportunity to handle the pop internally. A LocalHistoryRoute handles the
 /// pop internally if its list of local history entries is non-empty. Rather
 /// than being removed as the current route, the most recent [LocalHistoryEntry]
-/// is removed from the list and its [onRemove] is called.
+/// is removed from the list and its [LocalHistoryEntry.onRemove] is called.
 abstract class LocalHistoryRoute<T> extends Route<T> {
   List<LocalHistoryEntry> _localHistory;
 
@@ -304,7 +304,8 @@ abstract class LocalHistoryRoute<T> extends Route<T> {
 
   /// Remove a local history entry from this route.
   ///
-  /// The entry's [onRemove] callback, if any, will be called synchronously.
+  /// The entry's [LocalHistoryEntry.onRemove] callback, if any, will be called
+  /// synchronously.
   void removeLocalHistoryEntry(LocalHistoryEntry entry) {
     assert(entry != null);
     assert(entry._owner == this);
@@ -806,7 +807,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
   /// ```
   ///
   /// This callback runs asynchronously and it's possible that it will be called
-  /// after its route has been disposed. The callback should check [mounted]
+  /// after its route has been disposed. The callback should check [State.mounted]
   /// before doing anything.
   ///
   /// A typical application of this callback would be to warn the user about

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

@@ -25,6 +25,7 @@ import 'ticker_provider.dart';
 /// See also:
 ///
 ///  * [ScrollActivity], which uses this class as its delegate.
+///  * [ScrollPositionWithSingleContext], the main implementation of this interface.
 abstract class ScrollActivityDelegate {
   /// The direction in which the scroll view scrolls.
   AxisDirection get axisDirection;
@@ -353,7 +354,7 @@ class DragScrollActivity extends ScrollActivity {
   }
 }
 
-/// An activity that animates a scroll view based on a physics [simulation].
+/// An activity that animates a scroll view based on a physics [Simulation].
 ///
 /// A [BallisticScrollActivity] is typically used when the user lifts their
 /// finger off the screen to continue the scrolling gesture with the current velocity.

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

@@ -47,10 +47,10 @@ class ScrollBehavior {
     return null;
   }
 
-  /// The scroll physics to use for the given platform.
+  /// The scroll physics to use for the platform given by [getPlatform].
   ///
-  /// Used by [createScrollPosition] to get the scroll physics for newly created
-  /// scroll positions.
+  /// Defaults to [BouncingScrollPhysics] on iOS and [ClampingScrollPhysics] on
+  /// Android.
   ScrollPhysics getScrollPhysics(BuildContext context) {
     switch (getPlatform(context)) {
       case TargetPlatform.iOS:
@@ -93,6 +93,9 @@ class ScrollConfiguration extends InheritedWidget {
   final ScrollBehavior behavior;
 
   /// The [ScrollBehavior] for [Scrollable] widgets in the given [BuildContext].
+  ///
+  /// If no [ScrollConfiguration] widget is in scope of the given `context`,
+  /// a default [ScrollBehavior] instance is returned.
   static ScrollBehavior of(BuildContext context) {
     final ScrollConfiguration configuration = context.inheritFromWidgetOfExactType(ScrollConfiguration);
     return configuration?.behavior ?? const ScrollBehavior();

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

@@ -53,11 +53,11 @@ abstract class ViewportNotificationMixin extends Notification {
 ///    position to go outside its scroll bounds.
 ///  * Interspersed with the [ScrollUpdateNotification]s and
 ///    [OverscrollNotification]s are zero or more [UserScrollNotification]s,
-///    which indicate that the user has changed the direciton in which they are
+///    which indicate that the user has changed the direction in which they are
 ///    scrolling.
 ///  * A [ScrollEndNotification], which indicates that the widget has stopped
 ///    scrolling.
-///  * A [UserScrollNotification], with a [UserScrollNotification.direciton] of
+///  * A [UserScrollNotification], with a [UserScrollNotification.direction] of
 ///    [ScrollDirection.idle].
 ///
 /// Notifications bubble up through the tree, which means a given

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

@@ -47,7 +47,7 @@ class ScrollPhysics {
 
   /// Used by [DragScrollActivity] and other user-driven activities to
   /// convert an offset in logical pixels as provided by the [DragUpdateDetails]
-  /// into a delta to apply using [setPixels].
+  /// into a delta to apply using [ScrollActivityDelegate.setPixels].
   ///
   /// This is used by some [ScrollPosition] subclasses to apply friction during
   /// overscroll situations.
@@ -86,8 +86,8 @@ class ScrollPhysics {
   /// is updated, to determine how much of the offset is to be clamped off and
   /// sent to [ScrollPosition.didOverscrollBy].
   ///
-  /// The `value` argument is guaranteed to not equal [pixels] when this is
-  /// called.
+  /// The `value` argument is guaranteed to not equal the [ScrollMetrics.pixels]
+  /// of the `position` argument when this is called.
   ///
   /// It is possible for this method to be called when the `position` describes
   /// an already-out-of-bounds position. In that case, the boundary conditions
@@ -189,8 +189,8 @@ class ScrollPhysics {
 ///
 /// See also:
 ///
-///  * [ViewportScrollBehavior], which uses this to provide the iOS component of
-///    its scroll behavior.
+///  * [ScrollConfiguration], which uses this to provide the the default
+///    scroll behavior on iOS.
 ///  * [ClampingScrollPhysics], which is the analogous physics for Android's
 ///    clamping behavior.
 class BouncingScrollPhysics extends ScrollPhysics {
@@ -264,11 +264,11 @@ class BouncingScrollPhysics extends ScrollPhysics {
 ///
 /// See also:
 ///
-///  * [ViewportScrollBehavior], which uses this to provide the Android component
-///    of its scroll behavior.
+///  * [ScrollConfiguration], which uses this to provide the the default
+///    scroll behavior on Android.
 ///  * [BouncingScrollPhysics], which is the analogous physics for iOS' bouncing
 ///    behavior.
-///  * [GlowingOverscrollIndicator], which is used by [ViewportScrollBehavior] to
+///  * [GlowingOverscrollIndicator], which is used by [ScrollConfiguration] to
 ///    provide the glowing effect that is usually found with this clamping effect
 ///    on Android.
 class ClampingScrollPhysics extends ScrollPhysics {

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

@@ -36,7 +36,7 @@ export 'scroll_activity.dart' show ScrollHoldController;
 /// typically start activities in response to user input or instructions from a
 /// [ScrollController].
 ///
-/// This object is a [Listable] that notifies its listeners when [pixels]
+/// This object is a [Listenable] that notifies its listeners when [pixels]
 /// changes.
 ///
 /// ## Subclassing ScrollPosition
@@ -375,7 +375,7 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
   /// before.
   ///
   /// The default implementation informs the [activity] of the new dimensions by
-  /// calling [ScrollActivityDelegate.applyNewDimensions].
+  /// calling its [ScrollActivity.applyNewDimensions] method.
   ///
   /// See also:
   ///

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

@@ -127,6 +127,15 @@ abstract class ScrollView extends StatelessWidget {
   /// ```dart
   ///   physics: const ScrollPhysics(),
   /// ```
+  ///
+  /// The physics can be changed dynamically (by providing a new object in a
+  /// subsequent build), but new physics will only take effect if the _class_ of
+  /// the provided object changes. Merely constructing a new instance with a
+  /// different configuration is insufficient to cause the physics to be
+  /// reapplied. (This is because the final object used is generated
+  /// dynamically, which can be relatively expensive, and it would be
+  /// inefficient to speculatively create this object each frame to see if the
+  /// physics should be updated.)
   final ScrollPhysics physics;
 
   /// Whether the extent of the scroll view in the [scrollDirection] should be

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

@@ -107,7 +107,22 @@ class Scrollable extends StatefulWidget {
   /// For example, determines how the widget continues to animate after the
   /// user stops dragging the scroll view.
   ///
-  /// Defaults to matching platform conventions.
+  /// Defaults to matching platform conventions via the physics provided from
+  /// the ambient [ScrollConfiguration].
+  ///
+  /// The physics can be changed dynamically, but new physics will only take
+  /// effect if the _class_ of the provided object changes. Merely constructing
+  /// a new instance with a different configuration is insufficient to cause the
+  /// physics to be reapplied. (This is because the final object used is
+  /// generated dynamically, which can be relatively expensive, and it would be
+  /// inefficient to speculatively create this object each frame to see if the
+  /// physics should be updated.)
+  ///
+  /// See also:
+  ///
+  ///  * [AlwaysScrollableScrollPhysics], which can be used to indicate that the
+  ///    scrollable should react to scroll requests (and possible overscroll)
+  ///    even if the scrollable's contents fit without scrolling being necessary.
   final ScrollPhysics physics;
 
   /// Builds the viewport through which the scrollable content is displayed.

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

@@ -421,7 +421,8 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget {
 ///
 /// See also:
 ///
-///  * [SliverFixedExtentList], which has a configurable [itemExtent].
+///  * [SliverFixedExtentList], which has a configurable
+///    [SliverFixedExtentList.itemExtent].
 ///  * [SliverList], which does not require its children to have the same
 ///    extent in the main axis.
 class SliverFillViewport extends SliverMultiBoxAdaptorWidget {

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

@@ -185,7 +185,8 @@ class Text extends StatelessWidget {
   /// For example, if the text scale factor is 1.5, text will be 50% larger than
   /// the specified font size.
   ///
-  /// Defaults to [MediaQuery.textScaleFactor].
+  /// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
+  /// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
   final double textScaleFactor;
 
   /// An optional maximum number of lines the text is allowed to take up.

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

@@ -164,11 +164,11 @@ class TextSelectionOverlay implements TextSelectionDelegate {
     _toolbarController.forward(from: 0.0);
   }
 
-  /// Updates the overlay after the [selection] has changed.
+  /// Updates the overlay after the selection has changed.
   ///
   /// If this method is called while the [SchedulerBinding.schedulerPhase] is
-  /// [SchedulerBinding.persistentCallbacks], i.e. during the build, layout, or
-  /// paint phases (see [WidgetsBinding.beginFrame]), then the update is delayed
+  /// [SchedulerPhase.persistentCallbacks], i.e. during the build, layout, or
+  /// paint phases (see [WidgetsBinding.drawFrame]), then the update is delayed
   /// until the post-frame callbacks phase. Otherwise the update is done
   /// synchronously. This means that it is safe to call during builds, but also
   /// that if you do call this during a build, the UI will not update until the

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

@@ -61,7 +61,7 @@ class Viewport extends MultiChildRenderObjectWidget {
     assert(center == null || children.where((Widget child) => child.key == center).length == 1);
   }
 
-  /// The direction in which the [scrollOffset] increases.
+  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
   ///
   /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
   /// offset of zero is at the top of the viewport and increases towards the
@@ -207,7 +207,7 @@ class ShrinkWrappingViewport extends MultiChildRenderObjectWidget {
     assert(offset != null);
   }
 
-  /// The direction in which the [scrollOffset] increases.
+  /// The direction in which the [offset]'s [ViewportOffset.pixels] increases.
   ///
   /// For example, if the [axisDirection] is [AxisDirection.down], a scroll
   /// offset of zero is at the top of the viewport and increases towards the

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

@@ -12,7 +12,7 @@ import 'routes.dart';
 ///
 /// See also:
 ///
-///  * [ModalRoute.addScopedWillPopCallback] and [ModalScope.removeScopedWillPopCallback],
+///  * [ModalRoute.addScopedWillPopCallback] and [ModalRoute.removeScopedWillPopCallback],
 ///    which this widget uses to register and unregister [onWillPop].
 class WillPopScope extends StatefulWidget {
   /// Creates a widget that registers a callback to veto attempts by the user to

packages/flutter/test/rendering/rendering_tester.dart

@@ -32,7 +32,8 @@ class TestRenderingFlutterBinding extends BindingBase with SchedulerBinding, Ser
     pipelineOwner.flushSemantics();
     if (phase == EnginePhase.flushSemantics)
       return;
-    assert(phase == EnginePhase.flushSemantics || phase == EnginePhase.sendSemanticsTree);
+    assert(phase == EnginePhase.flushSemantics ||
+           phase == EnginePhase.sendSemanticsUpdate);
   }
 }
 

packages/flutter_markdown/lib/src/style_sheet.dart

@@ -80,7 +80,7 @@ class MarkdownStyleSheet {
   /// Creates a [MarkdownStyle] from the [TextStyle]s in the provided [ThemeData].
   ///
   /// This constructor uses larger fonts for the headings than in
-  /// [MarkdownStyle.fromTheme].
+  /// [new MarkdownStyle.fromTheme].
   factory MarkdownStyleSheet.largeFromTheme(ThemeData theme) {
     return new MarkdownStyleSheet(
       a: const TextStyle(color: Colors.blue),

packages/flutter_test/lib/src/binding.dart

@@ -54,8 +54,8 @@ enum EnginePhase {
   flushSemantics,
 
   /// The final phase in the rendering library, wherein semantics information is
-  /// sent to the embedder. See [SemanticsNode.sendSemanticsTree].
-  sendSemanticsTree,
+  /// sent to the embedder. See [SemanticsNode.sendSemanticsUpdate].
+  sendSemanticsUpdate,
 }
 
 /// Parts of the system that can generate pointer events that reach the test
@@ -162,7 +162,7 @@ abstract class TestWidgetsFlutterBinding extends BindingBase
   ///
   /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
   /// this method works when the test is run with `flutter run`.
-  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]);
+  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]);
 
   /// Artificially calls dispatchLocaleChanged on the Widget binding,
   /// then flushes microtasks.
@@ -512,7 +512,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
   int get microtaskCount => _fakeAsync.microtaskCount;
 
   @override
-  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]) {
+  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]) {
     return TestAsyncUtils.guard(() {
       assert(inTest);
       assert(_clock != null);
@@ -548,7 +548,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
     return result;
   }
 
-  EnginePhase _phase = EnginePhase.sendSemanticsTree;
+  EnginePhase _phase = EnginePhase.sendSemanticsUpdate;
 
   // Cloned from RendererBinding.drawFrame() but with early-exit semantics.
   @override
@@ -568,7 +568,8 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
               renderView.compositeFrame(); // this sends the bits to the GPU
               if (_phase != EnginePhase.composite) {
                 pipelineOwner.flushSemantics();
-                assert(_phase == EnginePhase.flushSemantics || _phase == EnginePhase.sendSemanticsTree);
+                assert(_phase == EnginePhase.flushSemantics ||
+                       _phase == EnginePhase.sendSemanticsUpdate);
               }
             }
           }
@@ -837,8 +838,8 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
   }
 
   @override
-  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsTree ]) {
-    assert(newPhase == EnginePhase.sendSemanticsTree);
+  Future<Null> pump([ Duration duration, EnginePhase newPhase = EnginePhase.sendSemanticsUpdate ]) {
+    assert(newPhase == EnginePhase.sendSemanticsUpdate);
     assert(inTest);
     assert(!_expectingFrame);
     assert(_pendingFrame == null);

packages/flutter_test/lib/src/matchers.dart

@@ -18,7 +18,7 @@ import 'finders.dart';
 /// See also:
 ///
 ///  * [findsWidgets], when you want the finder to find one or more widgets.
-///  * [findsOneWidgets], when you want the finder to find exactly one widget.
+///  * [findsOneWidget], when you want the finder to find exactly one widget.
 ///  * [findsNWidgets], when you want the finder to find a specific number of widgets.
 const Matcher findsNothing = const _FindsWidgetMatcher(null, 0);
 
@@ -33,7 +33,7 @@ const Matcher findsNothing = const _FindsWidgetMatcher(null, 0);
 /// See also:
 ///
 ///  * [findsNothing], when you want the finder to not find anything.
-///  * [findsOneWidgets], when you want the finder to find exactly one widget.
+///  * [findsOneWidget], when you want the finder to find exactly one widget.
 ///  * [findsNWidgets], when you want the finder to find a specific number of widgets.
 const Matcher findsWidgets = const _FindsWidgetMatcher(1, null);
 
@@ -64,7 +64,7 @@ const Matcher findsOneWidget = const _FindsWidgetMatcher(1, 1);
 ///
 ///  * [findsNothing], when you want the finder to not find anything.
 ///  * [findsWidgets], when you want the finder to find one or more widgets.
-///  * [findsOneWidgets], when you want the finder to find exactly one widget.
+///  * [findsOneWidget], when you want the finder to find exactly one widget.
 Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n);
 
 /// Asserts that the [Finder] locates the a single widget that has at
@@ -81,7 +81,7 @@ Matcher findsNWidgets(int n) => new _FindsWidgetMatcher(n, n);
 ///
 /// See also:
 ///
-///  * [isOnStage], the opposite.
+///  * [isOnstage], the opposite.
 const Matcher isOffstage = const _IsOffstage();
 
 /// Asserts that the [Finder] locates the a single widget that has no
@@ -89,7 +89,7 @@ const Matcher isOffstage = const _IsOffstage();
 ///
 /// See also:
 ///
-///  * [isOffStage], the opposite.
+///  * [isOffstage], the opposite.
 const Matcher isOnstage = const _IsOnstage();
 
 /// Asserts that the [Finder] locates the a single widget that has at
@@ -173,7 +173,7 @@ const Matcher isAssertionError = const isInstanceOf<AssertionError>();
 ///
 ///  * [closeTo], which is identical except that the epsilon argument is
 ///    required and not named.
-///  * [isInclusiveRange], which matches if the argument is in a specified
+///  * [inInclusiveRange], which matches if the argument is in a specified
 ///    range.
 Matcher moreOrLessEquals(double value, { double epsilon: 1e-10 }) {
   return new _MoreOrLessEquals(value, epsilon);

packages/flutter_test/lib/src/widget_tester.dart

@@ -181,7 +181,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   /// this method works when the test is run with `flutter run`.
   Future<Null> pumpWidget(Widget widget, [
     Duration duration,
-    EnginePhase phase = EnginePhase.sendSemanticsTree
+    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
   ]) {
     return TestAsyncUtils.guard(() {
       binding.attachRootWidget(widget);
@@ -204,7 +204,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   @override
   Future<Null> pump([
     Duration duration,
-    EnginePhase phase = EnginePhase.sendSemanticsTree
+    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
   ]) {
     return TestAsyncUtils.guard(() => binding.pump(duration, phase));
   }
@@ -235,7 +235,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   /// matches the expected number of pumps.
   Future<int> pumpAndSettle([
       Duration duration = const Duration(milliseconds: 100),
-      EnginePhase phase = EnginePhase.sendSemanticsTree,
+      EnginePhase phase = EnginePhase.sendSemanticsUpdate,
       Duration timeout = const Duration(minutes: 10),
     ]) {
     assert(duration != null);
@@ -448,7 +448,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   /// Returns the TestTextInput singleton.
   ///
   /// Typical app tests will not need to use this value. To add text to widgets
-  /// like [TextField] or [FormTextField], call [enterText].
+  /// like [TextField] or [TextFormField], call [enterText].
   TestTextInput get testTextInput => binding.testTextInput;
 
   /// Give the text input widget specified by [finder] the focus, as if the
@@ -456,10 +456,10 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   ///
   /// The widget specified by [finder] must be an [EditableText] or have
   /// an [EditableText] descendant. For example `find.byType(TextField)`
-  /// or `find.byType(FormTextField)`, or `find.byType(EditableText)`.
+  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
   ///
   /// Tests that just need to add text to widgets like [TextField]
-  /// or [FormTextField] only need to call [enterText].
+  /// or [TextFormField] only need to call [enterText].
   Future<Null> showKeyboard(Finder finder) async {
     return TestAsyncUtils.guard(() async {
       final EditableTextState editable = state(find.descendant(
@@ -479,7 +479,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   ///
   /// The widget specified by [finder] must be an [EditableText] or have
   /// an [EditableText] descendant. For example `find.byType(TextField)`
-  /// or `find.byType(FormTextField)`, or `find.byType(EditableText)`.
+  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
   ///
   /// To just give [finder] the focus without entering any text,
   /// see [showKeyboard].