More doc fixes. (#9848)

dev/bots/docs.sh

@@ -1,11 +1,14 @@
 #!/bin/bash
 set -e
 
+# If you want to run this script locally, make sure you run it from
+# the root of the flutter repository.
+
 # Install dartdoc.
 pub global activate dartdoc 0.11.0
 
 # This script generates a unified doc set, and creates
-# a custom index.html, placing everything into dev/docs/doc
+# a custom index.html, placing everything into dev/docs/doc.
 (cd dev/tools; pub get)
 FLUTTER_ROOT=$PWD dart dev/tools/dartdoc.dart
 FLUTTER_ROOT=$PWD dart dev/tools/javadoc.dart
@@ -13,8 +16,7 @@ FLUTTER_ROOT=$PWD dart dev/tools/javadoc.dart
 # Ensure google webmaster tools can verify our site.
 cp dev/docs/google2ed1af765c529f57.html dev/docs/doc
 
-# Upload new API docs when on Travis and branch is master
-
+# Upload new API docs when on Travis and branch is master.
 if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ "$TRAVIS_BRANCH" = "master" ]; then
   cd dev/docs
   firebase deploy --project docs-flutter-io

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

@@ -33,12 +33,12 @@ const Color _kBarrierColor = Colors.black54;
 ///    function.
 ///
 /// The [BottomSheet] widget itself is rarely used directly. Instead, prefer to
-/// create a persistent bottom sheet with [Scaffold.showBottomSheet] and a modal
+/// create a persistent bottom sheet with [ScaffoldState.showBottomSheet] and a modal
 /// bottom sheet with [showModalBottomSheet].
 ///
 /// See also:
 ///
-///  * [Scaffold.showBottomSheet]
+///  * [ScaffoldState.showBottomSheet]
 ///  * [showModalBottomSheet]
 ///  * <https://material.google.com/components/bottom-sheets.html>
 class BottomSheet extends StatefulWidget {
@@ -246,7 +246,7 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
 /// A closely related widget is a persistent bottom sheet, which shows
 /// information that supplements the primary content of the app without
 /// preventing the use from interacting with the app. Persistent bottom sheets
-/// can be created and displayed with the [Scaffold.showBottomSheet] function.
+/// can be created and displayed with the [ScaffoldState.showBottomSheet] function.
 ///
 /// Returns a `Future` that resolves to the value (if any) that was passed to
 /// [Navigator.pop] when the modal bottom sheet was closed.

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

@@ -13,7 +13,7 @@ import 'theme.dart';
 ///
 /// Dividers can be used in lists, [Drawer]s, and elsewhere to separate content
 /// vertically. To create a one-pixel divider between items in a list, consider
-/// using [ListTile.divideItems], which is optimized for this case.
+/// using [ListTile.divideTiles], which is optimized for this case.
 ///
 /// The box's total height is controlled by [height]. The appropriate padding is
 /// automatically computed from the height.

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

@@ -11,7 +11,8 @@ import 'dart:ui' as ui show lerpDouble;
 /// widget subtree.
 ///
 /// To obtain the current icon theme, use [IconTheme.of]. To convert an icon
-/// theme to a version with all the fields filled in, use [new fallback].
+/// theme to a version with all the fields filled in, use [new
+/// IconThemeData.fallback].
 class IconThemeData {
   /// Creates an icon theme data.
   ///

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

@@ -108,10 +108,11 @@ bool debugPrintMarkNeedsLayoutStacks = false;
 /// Check the intrinsic sizes of each [RenderBox] during layout.
 bool debugCheckIntrinsicSizes = false;
 
-/// Adds [Timeline] events for every RenderObject painted.
+/// Adds [dart:developer.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
+/// For details on how to use [dart:developer.Timeline] events in the Dart
+/// Observatory to optimize your app, see:
+/// <https://fuchsia.googlesource.com/sysui/+/master/docs/performance.md>
 bool debugProfilePaintsEnabled = false;
 
 

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

@@ -533,7 +533,7 @@ class PaintingContext {
 ///   [BoxConstraints.debugAssertIsValid] for an example of the detailed checks
 ///   that can be made.
 ///
-/// * The [operator ==] and [hashCode] members, so that constraints can be
+/// * The [==] operator and the [hashCode] getter, so that constraints can be
 ///   compared for equality. If a render object is given constraints that are
 ///   equal, then the rendering library will avoid laying the object out again
 ///   if it is not dirty.

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

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:ui' as ui;
+import 'dart:ui' as ui show Gradient, Shader, TextBox;
 
 import 'package:flutter/gestures.dart';
 import 'package:flutter/services.dart';
@@ -190,7 +190,8 @@ class RenderParagraph extends RenderBox {
   bool _hasVisualOverflow = false;
   ui.Shader _overflowShader;
 
-  /// Whether this paragraph currently has a [ui.Shader] for its overflow effect.
+  /// Whether this paragraph currently has a [ui.Shader] for its overflow
+  /// effect.
   ///
   /// Used to test this object. Not for use in production.
   @visibleForTesting

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

@@ -839,10 +839,11 @@ class RenderBackdropFilter extends RenderProxyBox {
     assert(filter != null);
   }
 
-  /// The image filter to apply to the existing painted content before painting the child.
+  /// 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
-  /// blur effect
+  /// For example, consider using [new ui.ImageFilter.blur] to create a backdrop
+  /// blur effect.
   ui.ImageFilter get filter => _filter;
   ui.ImageFilter _filter;
   set filter(ui.ImageFilter value) {

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

@@ -29,7 +29,7 @@ abstract class SemanticsActionHandler { // ignore: one_member_abstracts
   void performAction(SemanticsAction action);
 }
 
-/// The type of function returned by [RenderObject.getSemanticsAnnotators()].
+/// Signature for functions returned by [RenderObject.semanticsAnnotator].
 ///
 /// These callbacks are called with the [SemanticsNode] object that
 /// corresponds to the [RenderObject]. (One [SemanticsNode] can

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

@@ -451,8 +451,8 @@ 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.textBaseline] is not specified.
+  /// used is specified by [RenderTable.textBaseline]. It is not valid to use
+  /// the 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/services/http_client.dart

@@ -10,7 +10,8 @@ import 'package:http/http.dart' as http;
 /// This can be set to a new function to override the default logic for creating
 /// HTTP clients, for example so that all logic in the framework that triggers
 /// HTTP requests will use the same `UserAgent` header, or so that tests can
-/// provide an [http.MockClient].
+/// provide an [http.testing.MockClient].
+// TODO(ianh): Fix the link to MockClient once dartdoc has a solution.
 ValueGetter<http.Client> createHttpClient = () {
   return new http.Client();
 };

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

@@ -12,10 +12,10 @@ 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 [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.
+/// or raw [dart:ui.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.
 ///
 /// The [putIfAbsent] method is the main entry-point to the cache API. It
 /// returns the previously cached [ImageStreamCompleter] for the given key, if

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

@@ -143,8 +143,9 @@ class ImageConfiguration {
 ///
 /// The type argument `T` is the type of the object used to represent a resolved
 /// configuration. This is also the type used for the key in the image cache. It
-/// should be immutable and implement [operator ==] and [hashCode]. Subclasses should
-/// subclass a variant of [ImageProvider] with an explicit `T` type argument.
+/// should be immutable and implement the [==] operator and the [hashCode]
+/// getter. Subclasses should subclass a variant of [ImageProvider] with an
+/// explicit `T` type argument.
 ///
 /// The type argument does not have to be specified when using the type as an
 /// argument (where any image provider is acceptable).
@@ -197,7 +198,7 @@ abstract class ImageProvider<T> {
   /// method will fetch. Different [ImageProvider]s given the same constructor
   /// arguments and [ImageConfiguration] objects should return keys that are
   /// '==' to each other (possibly by using a class for the key that itself
-  /// implements [operator ==]).
+  /// implements [==]).
   @protected
   Future<T> obtainKey(ImageConfiguration configuration);
 

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 [Image.width] and [Image.height] properties) are double the
+  /// by the [ui.Image.width] and [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;

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

@@ -16,7 +16,7 @@ import 'platform_channel.dart';
 ///
 /// See also:
 ///
-/// * [MessageChannel], which use [MessageCodec]s for communication
+/// * [BasicMessageChannel], which use [MessageCodec]s for communication
 ///   between Flutter and platform plugins.
 abstract class MessageCodec<T> {
   /// Encodes the specified [message] in binary.

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

@@ -17,7 +17,7 @@ import 'platform_messages.dart';
 /// Messages are encoded into binary before being sent, and binary messages
 /// received are decoded into Dart values. The [MessageCodec] used must be
 /// compatible with the one used by the platform plugin. This can be achieved
-/// by creating a `BasicMessageChannel` counterpart of this channel on the
+/// by creating a [BasicMessageChannel] counterpart of this channel on the
 /// platform side. The Dart type of messages sent and received is [T],
 /// but only the values supported by the specified [MessageCodec] can be used.
 /// The use of unsupported values should be considered programming errors, and

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

@@ -58,13 +58,15 @@ class AnimatedCrossFade extends StatefulWidget {
        assert(sizeCurve != null),
        super(key: key);
 
-  /// The child that is visible when [crossFadeState] is [showFirst]. It fades
-  /// out when transitioning [crossFadeState] from [CrossFadeState.showFirst] to
+  /// The child that is visible when [crossFadeState] is
+  /// [CrossFadeState.showFirst]. It fades 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 [crossFadeState] from [CrossFadeState.showFirst] to
+  /// The child that is visible when [crossFadeState] is
+  /// [CrossFadeState.showSecond]. It fades in when transitioning
+  /// [crossFadeState] from [CrossFadeState.showFirst] to
   /// [CrossFadeState.showSecond] and vice versa.
   final Widget secondChild;
 

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 [window.onMetricsChanged].
+  /// See [Window.onMetricsChanged].
   @override
   void handleMetricsChanged() {
     super.handleMetricsChanged();
@@ -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 [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
-  /// [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:
   ///
@@ -331,7 +331,7 @@ abstract class WidgetsBinding extends BindingBase implements GestureBinding, Ren
   /// sent to the GPU.
   ///
   /// 8. 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/widgets/framework.dart

@@ -688,16 +688,16 @@ typedef void StateSetter(VoidCallback fn);
 ///    subtree.
 ///  * During this time, a parent widget might rebuild and request that this
 ///    location in the tree update to display a new widget with the same
-///    [runtimeType] and [key]. When this happens, the framework will update the
-///    [widget] property to refer to the new widget and then call the
-///    [didUpdateWidget] method with the previous widget as an argument.
-///    [State] objects should override [didUpdateWidget] to respond to changes
-///    in their associated wiget (e.g., to start implicit animations).
-///    The framework always calls [build] after calling [didUpdateWidget], which
-///    means any calls to [setState] in [didUpdateWidget] are redundant.
+///    [runtimeType] and [Widget.key]. When this happens, the framework will
+///    update the [widget] property to refer to the new widget and then call the
+///    [didUpdateWidget] method with the previous widget as an argument. [State]
+///    objects should override [didUpdateWidget] to respond to changes in their
+///    associated wiget (e.g., to start implicit animations). The framework
+///    always calls [build] after calling [didUpdateWidget], which means any
+///    calls to [setState] in [didUpdateWidget] are redundant.
 ///  * If the subtree containing the [State] object is removed from the tree
 ///    (e.g., because the parent built a widget with a different [runtimeType]
-///    or [key]), the framework calls the [deactivate] method. Subclasses
+///    or [Widget.key]), the framework calls the [deactivate] method. Subclasses
 ///    should override this method to clean up any links between this object
 ///    and other elements in the tree (e.g. if you have provided an ancestor
 ///    with a pointer to a descendant's [RenderObject]).
@@ -3614,8 +3614,8 @@ class InheritedElement extends ProxyElement {
 ///
 /// [updateChild] should be called for children in their logical order. The
 /// 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.
+/// `writeState` feature in their build method (and neither has a [Widget.key]),
+/// then the state written by the first will be overwritten by the second.
 ///
 /// #### Dynamically determining the children during the build phase
 ///
@@ -3629,7 +3629,7 @@ 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 [RenderOBject.performLayout] method can call back
+/// then the render object's [RenderObject.performLayout] method can call back
 /// to the element to have it generate the widgets and call [updateChild]
 /// accordingly.
 ///

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

@@ -70,7 +70,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 [Navigator.willPop].
+  /// called by [Navigator.maybePop].
   ///
   /// 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
@@ -586,7 +586,7 @@ class Navigator extends StatefulWidget {
     return Navigator.of(context).pop(result);
   }
 
-  /// Calls [pop()] repeatedly until the predicate returns true.
+  /// Calls [pop] repeatedly until the predicate returns true.
   ///
   /// The predicate may be applied to the same route more than once if
   /// [Route.willHandlePopInternally] is true.

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

@@ -764,9 +764,9 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
   Animation<double> get secondaryAnimation => _secondaryAnimationProxy;
   ProxyAnimation _secondaryAnimationProxy;
 
-  /// Return the value of the first callback added with
-  /// [addScopedWillPopCallback] that returns false. Otherwise return
-  /// [super.willPop()].
+  /// Returns the value of the first callback added with
+  /// [addScopedWillPopCallback] that returns false. If they all return true,
+  /// returns the inherited method's result (see [Route.willPop]).
   ///
   /// Typically this method is not overridden because applications usually
   /// don't create modal routes directly, they use higher level primitives

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

@@ -361,7 +361,7 @@ class DragScrollActivity extends ScrollActivity {
 ///
 /// [BallisticScrollActivity] is also used to restore a scroll view to a valid
 /// scroll offset when the geometry of the scroll view changes. In these
-/// situations, the [simulation] typically starts with a zero velocity.
+/// situations, the [Simulation] typically starts with a zero velocity.
 ///
 /// See also:
 ///

packages/flutter_driver/lib/flutter_driver.dart

@@ -33,8 +33,11 @@ export 'src/health.dart' show
 export 'src/message.dart' show
   Command,
   Result;
+export 'src/render_tree.dart' show
+  RenderTree;
 export 'src/timeline.dart' show
   Timeline,
   TimelineEvent;
 export 'src/timeline_summary.dart' show
-  TimelineSummary;
+  TimelineSummary,
+  kBuildBudget;

packages/flutter_test/lib/src/binding.dart

@@ -14,7 +14,6 @@ import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
 import 'package:http/http.dart' as http;
 import 'package:http/testing.dart' as http;
-import 'package:meta/meta.dart';
 import 'package:quiver/testing/async.dart';
 import 'package:quiver/time.dart';
 import 'package:test/test.dart' as test_package;
@@ -54,7 +53,7 @@ enum EnginePhase {
   flushSemantics,
 
   /// The final phase in the rendering library, wherein semantics information is
-  /// sent to the embedder. See [SemanticsNode.sendSemanticsUpdate].
+  /// sent to the embedder. See [SemanticsOwner.sendSemanticsUpdate].
   sendSemanticsUpdate,
 }
 

packages/flutter_test/pubspec.yaml

@@ -1,12 +1,13 @@
 name: flutter_test
 dependencies:
-  quiver: ^0.24.0
-
   # The flutter tools depend on very specific internal implementation
   # details of the 'test' package, which change between versions, so
   # here we pin it precisely to avoid version skew across our packages.
   test: 0.12.20
 
+  # We use FakeAsync and other testing utilities.
+  quiver: ^0.24.0
+
   flutter:
     sdk: flutter
 
@@ -14,3 +15,9 @@ dependencies:
   # need to be able to unmangle the stack traces that it passed to
   # stack_trace. See https://github.com/dart-lang/test/issues/590
   stack_trace: any # use version expected by test package
+
+  # We override the createHttpClient in flutter with a MockClient.
+  http: any # use version expected by flutter
+
+  # Used by globalToLocal et al.
+  vector_math: any # use version expected by flutter