More documentation fixes (#12290)

packages/flutter/lib/src/cupertino/bottom_tab_bar.dart

@@ -32,8 +32,8 @@ const Color _kDefaultTabBarBorderColor = const Color(0x4C000000);
 ///
 /// See also:
 ///
-///  * [CupertinoTabScaffold] which hosts the [CupertinoTabBar] at the bottom.
-///  * [BottomNavigationBarItem] typical item in a [CupertinoTabBar].
+///  * [CupertinoTabScaffold], which hosts the [CupertinoTabBar] at the bottom.
+///  * [BottomNavigationBarItem], an item in a [CupertinoTabBar].
 class CupertinoTabBar extends StatelessWidget implements PreferredSizeWidget {
   /// Creates a tab bar in the iOS style.
   CupertinoTabBar({
@@ -143,7 +143,7 @@ class CupertinoTabBar extends StatelessWidget implements PreferredSizeWidget {
   List<Widget> _buildTabItems() {
     final List<Widget> result = <Widget>[];
 
-    for (int index = 0; index < items.length; ++index) {
+    for (int index = 0; index < items.length; index += 1) {
       result.add(
         _wrapActiveItem(
           new Expanded(

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

@@ -187,7 +187,8 @@ class CupertinoAlertDialog extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [CupertinoAlertDialog]
+///  * [CupertinoAlertDialog], a dialog that informs the user about situations
+///    that require acknowledgement
 class CupertinoDialogAction extends StatelessWidget {
   /// Creates an action for an iOS-style dialog.
   const CupertinoDialogAction({

packages/flutter/lib/src/cupertino/page_scaffold.dart

@@ -15,9 +15,11 @@ import 'nav_bar.dart';
 ///
 /// See also:
 ///
-///  * [CupertinoPageRoute] a modal page route that typically hosts a [CupertinoPageRoute]
-///    with support for iOS style page transitions.
+///  * [CupertinoTabScaffold], a similar widget for tabbed applications.
+///  * [CupertinoPageRoute], a modal page route that typically hosts a
+///    [CupertinoPageScaffold] with support for iOS-style page transitions.
 class CupertinoPageScaffold extends StatelessWidget {
+  /// Creates a layout for pages with a navigation bar at the top.
   const CupertinoPageScaffold({
     Key key,
     this.navigationBar,

packages/flutter/lib/src/cupertino/route.dart

@@ -67,10 +67,12 @@ final DecorationTween _kGradientShadowTween = new DecorationTween(
 ///
 /// See also:
 ///
-///  * [MaterialPageRoute] for an adaptive [PageRoute] that uses a platform
-///    appropriate transition.
-///  * [CupertinoPageScaffold] typical content of a [CupertinoPageRoute] implementing
-///    iOS style layout with navigation bar on top.
+///  * [MaterialPageRoute], for an adaptive [PageRoute] that uses a
+///    platform-appropriate transition.
+///  * [CupertinoPageScaffold], for applications that have one page with a fixed
+///    navigation bar on top.
+///  * [CupertinoTabScaffold], for applications that have a tab bar at the
+///    bottom with multiple pages.
 class CupertinoPageRoute<T> extends PageRoute<T> {
   /// Creates a page route for use in an iOS designed app.
   ///
@@ -146,9 +148,9 @@ class CupertinoPageRoute<T> extends PageRoute<T> {
 
   /// Whether a pop gesture is currently underway.
   ///
-  /// This starts returning true when the [startPopGesture] method returns a new
-  /// [NavigationGestureController]. It returns false if that has not yet
-  /// occurred or if the most recent such gesture has completed.
+  /// This starts returning true when pop gesture is started by the user. It
+  /// returns false if that has not yet occurred or if the most recent such
+  /// gesture has completed.
   ///
   /// See also:
   ///
@@ -156,12 +158,14 @@ class CupertinoPageRoute<T> extends PageRoute<T> {
   ///    in the first place.
   bool get popGestureInProgress => _backGestureController != null;
 
-  /// Whether a pop gesture will be considered acceptable by [startPopGesture].
+  /// Whether a pop gesture can be started by the user.
   ///
   /// This returns true if the user can edge-swipe to a previous route,
   /// otherwise false.
   ///
-  /// This will return false if [popGestureInProgress] is true.
+  /// This will return false once [popGestureInProgress] is true, but
+  /// [popGestureInProgress] can only become true if [popGestureEnabled] was
+  /// true first.
   ///
   /// This should only be used between frames, not during build.
   bool get popGestureEnabled {

packages/flutter/lib/src/cupertino/tab_scaffold.dart

@@ -16,9 +16,9 @@ import 'bottom_tab_bar.dart';
 /// to change the active tab.
 ///
 /// Tabs' contents are built with the provided [tabBuilder] at the active
-/// tab index. [tabBuilder] must be able to build the same number of
-/// pages as the [tabBar.items.length]. Inactive tabs will be moved [Offstage]
-/// and its animations disabled.
+/// tab index. The [tabBuilder] must be able to build the same number of
+/// pages as there are [tabBar.items]. Inactive tabs will be moved [Offstage]
+/// and their animations disabled.
 ///
 /// Use [CupertinoTabView] as the content of each tab to support tabs with parallel
 /// navigation state and history.
@@ -74,13 +74,16 @@ import 'bottom_tab_bar.dart';
 ///
 /// See also:
 ///
-///  * [CupertinoTabBar] bottom tab bars inserted in the scaffold.
-///  * [CupertinoTabView] a typical root content of each tap that holds its own
+///  * [CupertinoTabBar], the bottom tab bar inserted in the scaffold.
+///  * [CupertinoTabView], the typical root content of each tab that holds its own
 ///    [Navigator] stack.
-///  * [CupertinoPageRoute] a route hosting modal pages with iOS style transitions.
-///  * [CupertinoPageScaffold] typical contents of an iOS modal page implementing
+///  * [CupertinoPageRoute], a route hosting modal pages with iOS style transitions.
+///  * [CupertinoPageScaffold], typical contents of an iOS modal page implementing
 ///    layout with a navigation bar on top.
 class CupertinoTabScaffold extends StatefulWidget {
+  /// Creates a layout for applications with a tab bar at the bottom.
+  ///
+  /// The [tabBar] and [tabBuilder] arguments must not be null.
   const CupertinoTabScaffold({
     Key key,
     @required this.tabBar,

packages/flutter/lib/src/cupertino/tab_view.dart

@@ -31,10 +31,11 @@ import 'route.dart';
 ///
 /// See also:
 ///
-///  * [CupertinoTabScaffold] a typical host that supports switching between tabs.
-///  * [CupertinoPageRoute] a typical modal page route pushed onto the [CupertinoTabView]'s
-///    [Navigator].
+///  * [CupertinoTabScaffold], a typical host that supports switching between tabs.
+///  * [CupertinoPageRoute], a typical modal page route pushed onto the
+///    [CupertinoTabView]'s [Navigator].
 class CupertinoTabView extends StatelessWidget {
+  /// Creates the content area for a tab in a [CupertinoTabScaffold].
   const CupertinoTabView({
     Key key,
     this.builder,

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

@@ -148,7 +148,7 @@ class MaterialApp extends StatefulWidget {
   /// If non-null this function is called to produce the app's
   /// title string, otherwise [title] is used.
   ///
-  /// The [onGenerateTitle] `context` parameter includes the [WidgetApp]'s
+  /// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s
   /// [Localizations] widget so that this callback can be used to produce a
   /// localized title.
   ///
@@ -260,9 +260,9 @@ class MaterialApp extends StatefulWidget {
   /// Delegates that produce [WidgetsLocalizations] and [MaterialLocalizations]
   /// are included automatically. Apps can provide their own versions of these
   /// localizations by creating implementations of
-  /// [LocalizationsDelegate<WidgetLocalizations>] or
+  /// [LocalizationsDelegate<WidgetsLocalizations>] or
   /// [LocalizationsDelegate<MaterialLocalizations>] whose load methods return
-  /// custom versions of [WidgetLocalizations] or [MaterialLocalizations].
+  /// custom versions of [WidgetsLocalizations] or [MaterialLocalizations].
   ///
   /// For example: to add support to [MaterialLocalizations] for a
   /// locale it doesn't already support, say `const Locale('foo', 'BR')`,

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

@@ -328,9 +328,9 @@ class MaterialRectArcTween extends RectTween {
   }
 }
 
-/// A [Tween] that interpolates a [Rect] by moving it along a circular
-/// arc from [begin.center] to [end.center] while interpoloting the rectangle's
-/// width and height.
+/// A [Tween] that interpolates a [Rect] by moving it along a circular arc from
+/// [begin]'s [Rect.center] to [end]'s [Rect.center] while interpolating the
+/// rectangle's width and height.
 ///
 /// The arc that defines that center of the interpolated rectangle as it morphs
 /// from [begin] to [end] is a [MaterialPointArcTween].
@@ -367,8 +367,8 @@ class MaterialRectCenterArcTween extends RectTween {
     _dirty = false;
   }
 
-  /// If [begin] and [end] are non-null, returns a tween that interpolates
-  /// along a circular arc between [begin.center] and [end.center].
+  /// If [begin] and [end] are non-null, returns a tween that interpolates along
+  /// a circular arc between [begin]'s [Rect.center] and [end]'s [Rect.center].
   MaterialPointArcTween get centerArc {
     if (begin == null || end == null)
       return null;

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

@@ -34,10 +34,10 @@ abstract class MaterialLocalizations {
   /// The tooltip for the [MonthPicker]'s "previous month" button.
   String get previousMonthTooltip;
 
-  /// The tooltip for the [PaginatedDataTables]'s "next page" button.
+  /// The tooltip for the [PaginatedDataTable]'s "next page" button.
   String get nextPageTooltip;
 
-  /// The tooltip for the [PaginatedDataTables]'s "previous page" button.
+  /// The tooltip for the [PaginatedDataTable]'s "previous page" button.
   String get previousPageTooltip;
 
   /// The default [PopupMenuButton] tooltip.
@@ -55,7 +55,7 @@ abstract class MaterialLocalizations {
   /// Title for the [PaginatedDataTable]'s "rows per page" footer.
   String get rowsPerPageTitle;
 
-  /// Title for the PaginatedDataTable's selected row count header.
+  /// Title for the [PaginatedDataTable]'s selected row count header.
   String selectedRowCountTitle(int selectedRowCount);
 
   /// Label for "cancel" buttons and menu items.
@@ -82,7 +82,7 @@ abstract class MaterialLocalizations {
   /// Label for "select all" edit buttons and menu items.
   String get selectAllButtonLabel;
 
-  /// Label for the [AboutBox] button that shows the [LicensePage].
+  /// Label for the [AboutDialog] button that shows the [LicensePage].
   String get viewLicensesButtonLabel;
 
   /// The abbreviation for ante meridiem (before noon) shown in the time picker.

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

@@ -34,7 +34,7 @@ import 'colors.dart';
 ///  * <http://material.google.com/style/typography.html>
 @immutable
 class TextTheme {
-  /// Create a text theme that uses the given values.
+  /// Creates a text theme that uses the given values.
   ///
   /// Rather than creating a new text theme, consider using [Typography.black]
   /// or [Typography.white], which implement the typography styles in the
@@ -131,6 +131,12 @@ class TextTheme {
     );
   }
 
+  /// Creates a new [TextTheme] where each text style from this object has been
+  /// merged with the matching text style from the `other` object.
+  ///
+  /// This is particularly useful if one [TextTheme] defines one set of
+  /// properties and another defines a different set, e.g. having colors defined
+  /// in one text theme and font sizes in another.
   TextTheme merge(TextTheme other) {
     if (other == null)
       return this;

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

@@ -27,7 +27,7 @@ abstract class Gradient {
   /// Creates a [Shader] for this gradient to fill the given rect.
   ///
   /// If the gradient's configuration is text-direction-dependent, for example
-  /// it uses [FractionalOffsetDirection] objects instead of [FractionalOffset]
+  /// it uses [FractionalOffsetDirectional] objects instead of [FractionalOffset]
   /// objects, then the `textDirection` argument must not be null.
   Shader createShader(Rect rect, { TextDirection textDirection });
 }

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

@@ -145,7 +145,7 @@ import 'basic_types.dart';
 ///
 /// The `family` property determines the name of the font, which you can use in
 /// the [fontFamily] argument. The `asset` property is a path to the font file,
-/// relative to the [pubspec.yaml] file. The `weight` property specifies the
+/// relative to the `pubspec.yaml` file. The `weight` property specifies the
 /// weight of the glyph outlines in the file as an integer multiple of 100
 /// between 100 and 900. This corresponds to the [FontWeight] class and can be
 /// used in the [fontWeight] argument. The `style` property specfies whether the

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

@@ -2560,31 +2560,31 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
 
   /// Mark this node as needing an update to its semantics description.
   ///
-  /// The parameters [onlyLocalUpdates] and [noGeometry] tell the framework
+  /// The parameters `onlyLocalUpdates` and `noGeometry` tell the framework
   /// how much of the semantics have changed. Bigger changes (indicated by
   /// setting one or both parameters to false) are more expansive to compute.
   ///
-  /// [onlyLocalUpdates] should be set to true to reduce cost if the semantics
+  /// `onlyLocalUpdates` should be set to true to reduce cost if the semantics
   /// update does not in any way change the shape of the semantics tree (e.g.
   /// [SemanticsNode]s will neither be added/removed from the tree nor be moved
-  /// within the tree). In other words, with [onlyLocalChanges] the
+  /// within the tree). In other words, with `onlyLocalUpdates` the
   /// [RenderObject] can indicate that it only wants to perform updates on the
   /// local [SemanticsNode] (e.g. changing a label or flag) without affecting
   /// other nodes in the tree.
   ///
-  /// [onlyLocalUpdates] has to be set to false in the following cases as they
+  /// `onlyLocalUpdates` has to be set to false in the following cases as they
   /// will change the shape of the tree:
   ///
   /// 1. [isSemanticBoundary] changed its value.
   /// 2. [semanticsAnnotator] changed from or to returning null and
   ///    [isSemanticBoundary] isn't true.
   ///
-  /// [noGeometry] should be set to true to reduce cost if the geometry (e.g.
+  /// `noGeometry` should be set to true to reduce cost if the geometry (e.g.
   /// size and position) of the corresponding [SemanticsNode] has not
   /// changed. Examples for such semantic updates that don't require a geometry
   /// update are changes to flags, labels, or actions.
   ///
-  /// If [onlyLocalUpdates] or [noGeometry] are incorrectly set to true, asserts
+  /// If `onlyLocalUpdates` or `noGeometry` are incorrectly set to true, asserts
   /// might throw or the computed semantics tree might be out-of-date without
   /// warning.
   void markNeedsSemanticsUpdate({ bool onlyLocalUpdates: false, bool noGeometry: false }) {
@@ -2778,9 +2778,9 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
   /// By default, the method will annotate [node] with the [semanticsAnnotator]
   /// and add the [children] to it.
   ///
-  /// Subclasses can override this method to add additional [SemanticNode]s
+  /// Subclasses can override this method to add additional [SemanticsNode]s
   /// to the tree. If a subclass adds additional nodes in this method, it also
-  /// needs to override [resetSemantics] to call [SemanticsNodes.reset] on those
+  /// needs to override [resetSemantics] to call [SemanticsNode.reset] on those
   /// additional [SemanticsNode]s.
   void assembleSemanticsNode(SemanticsNode node, Iterable<SemanticsNode> children) {
     assert(node == _semantics);

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

@@ -237,7 +237,7 @@ class RenderParagraph extends RenderBox {
   bool _hasVisualOverflow = false;
   ui.Shader _overflowShader;
 
-  /// Whether this paragraph currently has a [ui.Shader] for its overflow
+  /// Whether this paragraph currently has a [dart:ui.Shader] for its overflow
   /// effect.
   ///
   /// Used to test this object. Not for use in production.

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

@@ -2869,7 +2869,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticsA
   ///
   /// As an example, a [RenderSliver] that stays on the screen within a
   /// [Scrollable] even though the user has scrolled past it (e.g. a pinned app
-  /// bar) can tag its [SemanticNode] with [excludeFromScrolling] to indicate
+  /// bar) can tag its [SemanticsNode] with [excludeFromScrolling] to indicate
   /// that it should no longer be considered for semantic actions related to
   /// scrolling.
   static const SemanticsTag excludeFromScrolling = const SemanticsTag('RenderSemanticsGestureHandler.excludeFromScrolling');

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

@@ -7,7 +7,7 @@ import 'dart:ui' as ui show Image;
 
 import 'package:flutter/foundation.dart';
 
-/// A [ui.Image] object with its corresponding scale.
+/// A [dart:ui.Image] object with its corresponding scale.
 ///
 /// ImageInfo objects are used by [ImageStream] objects to represent the
 /// actual data of the image once it has been obtained.
@@ -33,7 +33,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 [dart:ui.Image.width] and [dart:ui.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;
@@ -56,7 +56,7 @@ typedef void ImageListener(ImageInfo image, bool synchronousCall);
 
 /// A handle to an image resource.
 ///
-/// ImageStream represents a handle to a [ui.Image] object and its scale
+/// ImageStream represents a handle to a [dart:ui.Image] object and its scale
 /// (together represented by an [ImageInfo] object). The underlying image object
 /// might change over time, either because the image is animating or because the
 /// underlying image resource was mutated.
@@ -164,7 +164,7 @@ class ImageStream extends Diagnosticable {
   }
 }
 
-/// Base class for those that manage the loading of [ui.Image] objects for
+/// Base class for those that manage the loading of [dart:ui.Image] objects for
 /// [ImageStream]s.
 ///
 /// This class is rarely used directly. Generally, an [ImageProvider] subclass
@@ -243,7 +243,7 @@ class ImageStreamCompleter extends Diagnosticable {
   }
 }
 
-/// Manages the loading of [ui.Image] objects for static [ImageStream]s (those
+/// Manages the loading of [dart:ui.Image] objects for static [ImageStream]s (those
 /// with only one frame).
 class OneFrameImageStreamCompleter extends ImageStreamCompleter {
   /// Creates a manager for one-frame [ImageStream]s.

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

@@ -31,13 +31,13 @@ export 'dart:ui' show Locale;
 ///
 /// The `locale` is the device's locale when the app started, or the device
 /// locale the user selected after the app was started. The `supportedLocales`
-/// parameter is just the value of [WidgetApp.supportedLocales].
+/// parameter is just the value of [WidgetsApp.supportedLocales].
 typedef Locale LocaleResolutionCallback(Locale locale, Iterable<Locale> supportedLocales);
 
 /// The signature of [WidgetsApp.onGenerateTitle].
 ///
 /// Used to generate a value for the app's [Title.title], which the device uses
-/// to identify the app for the user. The `context` includes the [WidgetApp]'s
+/// to identify the app for the user. The `context` includes the [WidgetsApp]'s
 /// [Localizations] widget so that this method can be used to produce a
 /// localized title.
 ///
@@ -123,7 +123,7 @@ class WidgetsApp extends StatefulWidget {
   /// If non-null this callback function is called to produce the app's
   /// title string, otherwise [title] is used.
   ///
-  /// The [onGenerateTitle] `context` parameter includes the [WidgetApp]'s
+  /// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s
   /// [Localizations] widget so that this callback can be used to produce a
   /// localized title.
   ///
@@ -208,7 +208,7 @@ class WidgetsApp extends StatefulWidget {
   /// If the callback is null or if it returns null then the resolved locale is:
   ///
   /// - The callback's `locale` parameter if it's equal to a supported locale.
-  /// - The first supported locale with the same [Locale.langaugeCode] as the
+  /// - The first supported locale with the same [Locale.languageCode] as the
   ///   callback's `locale` parameter.
   /// - The first locale in [supportedLocales].
   ///
@@ -240,7 +240,7 @@ class WidgetsApp extends StatefulWidget {
   ///  * [localeResolutionCallback], an app callback that resolves the app's locale
   ///    when the device's locale changes.
   ///
-  ///  * [localizationDelegates], which collectively define all of the localized
+  ///  * [localizationsDelegates], which collectively define all of the localized
   ///    resources used by this app.
   final Iterable<Locale> supportedLocales;
 

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

@@ -2330,7 +2330,7 @@ class Positioned extends ParentDataWidget<Stack> {
   /// See also:
   ///
   ///  * [Positioned.directional], which specifies the widget's horizontal
-  ///    position using [start] and [end] rather than [left] and [right].
+  ///    position using `start` and `end` rather than `left` and `right`.
   const Positioned({
     Key key,
     this.left,
@@ -3049,7 +3049,7 @@ class Row extends Flex {
   /// any. If there is no ambient directionality, and a text direction is going
   /// to be necessary to determine the layout order (which is always the case
   /// unless the row has no children or only one child) or to disambiguate
-  /// `start` or `end` values for the [mainAxisDirection], the [textDirection]
+  /// `start` or `end` values for the [mainAxisAlignment], the [textDirection]
   /// must not be null.
   Row({
     Key key,
@@ -3239,7 +3239,7 @@ class Column extends Flex {
   /// The [textDirection] argument defaults to the ambient [Directionality], if
   /// any. If there is no ambient directionality, and a text direction is going
   /// to be necessary to disambiguate `start` or `end` values for the
-  /// [crossAxisDirection], the [textDirection] must not be null.
+  /// [crossAxisAlignment], the [textDirection] must not be null.
   Column({
     Key key,
     MainAxisAlignment mainAxisAlignment: MainAxisAlignment.start,

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

@@ -1353,21 +1353,6 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   @mustCallSuper
   void didChangeDependencies() { }
 
-  /// Add additional properties to the given description used by
-  /// [toDiagnosticsNode], [toString] and [toStringDeep].
-  ///
-  /// This method makes it easier for subclasses to coordinate to provide
-  /// high-quality diagnostic data. The [toString] implementation on
-  /// the [State] base class calls [debugFillProperties] to collect useful
-  /// information from subclasses to incorporate into its return value.
-  ///
-  /// If you override this, make sure to start your method with a call to
-  /// `super.debugFillProperties(description)`.
-  ///
-  /// See also:
-  ///
-  ///  * [DiagnosticableTree.debugFillProperties], which provides detailed
-  ///    best practices for defining diagnostic properties.
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder description) {
     super.debugFillProperties(description);
@@ -3332,23 +3317,6 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
     return widget != null ? '${widget.toStringShort()}' : '[$runtimeType]';
   }
 
-  /// Add additional properties to the given description used by
-  /// [toDiagnosticsNode], [toString] and [toStringDeep].
-  ///
-  /// This method makes it easier for subclasses to coordinate to provide
-  /// high-quality diagnostic data. The [toString] implementation on
-  /// the [State] base class calls [debugFillProperties] to collect useful
-  /// information from subclasses to incorporate into its return value.
-  ///
-  /// If you override this, make sure to start your method with a call to
-  /// `super.debugFillProperties(description)`.
-  ///
-  /// See also:
-  ///
-  ///  * [DiagnosticableTree.debugFillProperties], which provides detailed
-  ///    best practices for defining diagnostic properties.
-  @protected
-  @mustCallSuper
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder description) {
     super.debugFillProperties(description);

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

@@ -567,7 +567,8 @@ class RawGestureDetectorState extends State<RawGestureDetector> {
   /// The event can be interpreted by assistive technologies to provide
   /// additional feedback to the user about the state of the UI.
   ///
-  /// The event will not be sent if [excludeFromSemantics] is set to true.
+  /// The event will not be sent if [RawGestureDetector.excludeFromSemantics] is
+  /// set to true.
   void sendSemanticsEvent(SemanticsEvent event) {
     if (!widget.excludeFromSemantics) {
       final RenderSemanticsGestureHandler semanticsGestureHandler = context.findRenderObject();

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

@@ -101,7 +101,7 @@ class Hero extends StatefulWidget {
   ///
   /// If this property is null, the default, then the value of
   /// [HeroController.createRectTween] is used. The [HeroController] created by
-  /// [MaterialApp] creates a [MaterialArcRectTween].
+  /// [MaterialApp] creates a [MaterialRectAreTween].
   final CreateRectTween createRectTween;
 
   /// The widget subtree that will "fly" from one route to another during a

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

@@ -12,6 +12,19 @@ import 'navigator.dart';
 import 'transitions.dart';
 
 /// A widget that prevents the user from interacting with widgets behind itself.
+///
+/// The modal barrier is the scrim that is rendered behind each route, which
+/// generally prevents the user from interacting with the route below the
+/// current route, and normally partially obscures such routes.
+///
+/// For example, when a dialog is on the screen, the page below the dialog is
+/// usually darkened by the modal barrier.
+///
+/// See also:
+///
+///  * [ModalRoute], which indirectly uses this widget.
+///  * [AnimatedModalBarrier], which is similar but takes an animated [color]
+///    instead of a single color value.
 class ModalBarrier extends StatelessWidget {
   /// Creates a widget that blocks user interaction.
   const ModalBarrier({
@@ -21,9 +34,19 @@ class ModalBarrier extends StatelessWidget {
   }) : super(key: key);
 
   /// If non-null, fill the barrier with this color.
+  ///
+  /// See also:
+  ///
+  ///  * [ModalRoute.barrierColor], which controls this property for the
+  ///    [ModalBarrier] built by [ModalRoute] pages.
   final Color color;
 
   /// Whether touching the barrier will pop the current route off the [Navigator].
+  ///
+  /// See also:
+  ///
+  ///  * [ModalRoute.barrierDismissible], which controls this property for the
+  ///    [ModalBarrier] built by [ModalRoute] pages.
   final bool dismissible;
 
   @override
@@ -55,7 +78,22 @@ class ModalBarrier extends StatelessWidget {
   }
 }
 
-/// A widget that prevents the user from interacting with widgets behind itself.
+/// A widget that prevents the user from interacting with widgets behind itself,
+/// and can be configured with an animated color value.
+///
+/// The modal barrier is the scrim that is rendered behind each route, which
+/// generally prevents the user from interacting with the route below the
+/// current route, and normally partially obscures such routes.
+///
+/// For example, when a dialog is on the screen, the page below the dialog is
+/// usually darkened by the modal barrier.
+///
+/// This widget is similar to [ModalBarrier] except that it takes an animated
+/// [color] instead of a single color.
+///
+/// See also:
+///
+///  * [ModalRoute], which uses this widget.
 class AnimatedModalBarrier extends AnimatedWidget {
   /// Creates a widget that blocks user interaction.
   const AnimatedModalBarrier({
@@ -65,16 +103,26 @@ class AnimatedModalBarrier extends AnimatedWidget {
   }) : super(key: key, listenable: color);
 
   /// If non-null, fill the barrier with this color.
+  ///
+  /// See also:
+  ///
+  ///  * [ModalRoute.barrierColor], which controls this property for the
+  ///    [AnimatedModalBarrier] built by [ModalRoute] pages.
   Animation<Color> get color => listenable;
 
   /// Whether touching the barrier will pop the current route off the [Navigator].
+  ///
+  /// See also:
+  ///
+  ///  * [ModalRoute.barrierDismissible], which controls this property for the
+  ///    [AnimatedModalBarrier] built by [ModalRoute] pages.
   final bool dismissible;
 
   @override
   Widget build(BuildContext context) {
     return new ModalBarrier(
       color: color?.value,
-      dismissible: dismissible
+      dismissible: dismissible,
     );
   }
 }

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

@@ -518,7 +518,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
   /// ```
   ///
   /// The given [BuildContext] will be rebuilt if the state of the route changes
-  /// (specifically, if [Route.isCurrent] or [Route.canPop] change value).
+  /// (specifically, if [isCurrent] or [canPop] change value).
   static ModalRoute<dynamic> of(BuildContext context) {
     final _ModalScopeStatus widget = context.inheritFromWidgetOfExactType(_ModalScopeStatus);
     return widget?.route;
@@ -736,13 +736,46 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
   // The API for subclasses to override - used by this class
 
   /// Whether you can dismiss this route by tapping the modal barrier.
+  ///
+  /// The modal barrier is the scrim that is rendered behind each route, which
+  /// generally prevents the user from interacting with the route below the
+  /// current route, and normally partially obscures such routes.
+  ///
+  /// For example, when a dialog is on the screen, the page below the dialog is
+  /// usually darkened by the modal barrier.
+  ///
+  /// If [barrierDismissible] is true, then tapping this barrier will cause the
+  /// current route to be popped (see [Navigator.pop]) with null as the value.
+  ///
+  /// If [barrierDismissible] is false, then tapping the barrier has no effect.
+  ///
+  /// See also:
+  ///
+  ///  * [barrierColor], which controls the color of the scrim for this route.
+  ///  * [ModalBarrier], the widget that implements this feature.
   bool get barrierDismissible;
 
   /// The color to use for the modal barrier. If this is null, the barrier will
   /// be transparent.
   ///
+  /// The modal barrier is the scrim that is rendered behind each route, which
+  /// generally prevents the user from interacting with the route below the
+  /// current route, and normally partially obscures such routes.
+  ///
+  /// For example, when a dialog is on the screen, the page below the dialog is
+  /// usually darkened by the modal barrier.
+  ///
   /// The color is ignored, and the barrier made invisible, when [offstage] is
   /// true.
+  ///
+  /// While the route is animating into position, the color is animated from
+  /// transparent to the specified color.
+  ///
+  /// See also:
+  ///
+  ///  * [barrierDismissible], which controls the behavior of the barrier when
+  ///    tapped.
+  ///  * [ModalBarrier], the widget that implements this feature.
   Color get barrierColor;
 
   /// Whether the route should remain in memory when it is inactive. If this is