Merge pull request #836 from abarth/update_docs

Update documentation based on comments in previous patch

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

@@ -1103,15 +1103,16 @@ typedef void PointerCancelEventListener(PointerCancelEvent event);
 
 /// How to behave during hit tests.
 enum HitTestBehavior {
-  /// Consider this target hit if, and only if, its child was hit.
+  /// Targets that defer to their children receive events within their bounds
+  /// only if one of their children is hit by the hit test.
   deferToChild,
 
-  /// Consider this target hit whenever the position being hit tested is within its bounds.
+  /// Opaque targets can be hit by hit tests, causing them to both receive
+  /// events within their bounds and prevent targets visually behind them from
+  /// also receiving events.
   opaque,
 
-  /// Never consider this target hit but always add the target to the event path anyway.
-  ///
-  /// Translucent targets both receive events at a given location and permit
+  /// Translucent targets both receive events within their bounds and permit
   /// targets visually behind them to also receive events.
   translucent,
 }

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

@@ -100,7 +100,7 @@ class AnimatedContainer extends StatefulComponent {
   /// Empty space to inscribe inside the decoration.
   final EdgeDims padding;
 
-  /// The tranformation matrix to apply before painting the container.
+  /// The transformation matrix to apply before painting the container.
   final Matrix4 transform;
 
   /// If non-null, requires the decoration to have this width.

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

@@ -806,7 +806,7 @@ class Container extends StatelessComponent {
   /// Empty space to inscribe inside the decoration.
   final EdgeDims padding;
 
-  /// The tranformation matrix to apply before painting the container.
+  /// The transformation matrix to apply before painting the container.
   final Matrix4 transform;
 
   /// If non-null, requires the decoration to have this width.

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

@@ -24,6 +24,12 @@ class WidgetFlutterBinding extends FlutterBinding {
   }
 
   /// The one static instance of this class.
+  ///
+  /// Only valid after ensureInitialized() (or the WidgetFlutterBinding
+  /// constructor) has been called.  If another FlutterBinding subclass is
+  /// instantiated before this one (e.g. bindings from other frameworks based on
+  /// the Flutter "rendering" library), then WidgetFlutterBinding.instance will
+  /// not be valid (and will throw in checked mode).
   static WidgetFlutterBinding get instance => FlutterBinding.instance;
 
   void beginFrame() {

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

@@ -29,7 +29,7 @@ export 'package:flutter/gestures.dart' show
 
 /// A widget that detects gestures.
 ///
-/// Attempts to recognize gestures that coorespond to its non-null callbacks.
+/// Attempts to recognize gestures that correspond to its non-null callbacks.
 ///
 /// See http://flutter.io/gestures/ for additional information.
 class GestureDetector extends StatefulComponent {

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

@@ -52,7 +52,11 @@ class MediaQuery extends InheritedWidget {
   /// The result of media queries in this subtree.
   final MediaQueryData data;
 
-  /// Queries the current media for the given context.
+  /// Returns the media query data for the given context.
+  ///
+  /// You can use this function to query the size an orientation of the screen.
+  /// When that information changes, your widget will be scheduled to be rebuilt,
+  /// keeping your widget up-to-date.
   static MediaQueryData of(BuildContext context) {
     MediaQuery query = context.inheritFromWidgetOfType(MediaQuery);
     return query == null ? null : query.data;

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

@@ -49,7 +49,7 @@ class MimicOverlayEntry {
   /// The animation will take place over the given duration and will apply the
   /// given curve.
   ///
-  /// Currently we don't support calling this function more than once per overlay entry.
+  /// This function can only be called once per overlay entry.
   Future animateTo({
     GlobalKey targetKey,
     Duration duration,

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

@@ -110,8 +110,9 @@ class OverlayState extends State<Overlay> {
 
   /// (DEBUG ONLY) Check whether a given entry is visible (i.e., not behind an opaque entry).
   ///
-  /// This is an O(N) algorithm, and should not be necessary except for debug asserts.
-  /// To avoid people depending on it, we only implement it in checked mode.
+  /// This is an O(N) algorithm, and should not be necessary except for debug
+  /// asserts. To avoid people depending on it, this function is implemented
+  /// only in checked mode.
   bool debugIsVisible(OverlayEntry entry) {
     bool result = false;
     assert(_entries.contains(entry));

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

@@ -28,7 +28,7 @@ abstract class PageRoute<T> extends ModalRoute<T> {
     return performance;
   }
 
-  /// Subclasses can override this method to customize way heroes are inserted
+  /// Subclasses can override this method to customize how heroes are inserted.
   void insertHeroOverlayEntry(OverlayEntry entry, Object tag, OverlayState overlay) {
     overlay.insert(entry);
   }

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

@@ -33,6 +33,14 @@ abstract class OverlayRoute<T> extends Route<T> {
     navigator.overlay?.insertAll(_overlayEntries, above: insertionPoint);
   }
 
+  /// A request was made to pop this route. If the route can handle it
+  /// internally (e.g. because it has its own stack of internal state) then
+  /// return false, otherwise return true. Returning false will prevent the
+  /// default behavior of NavigatorState.pop().
+  ///
+  /// If this is called, the Navigator will not call dispose(). It is the
+  /// responsibility of the Route to later call dispose().
+  ///
   /// Subclasses shouldn't call this if they want to delay the finished() call.
   bool didPop(T result) {
     finished();

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

@@ -38,6 +38,8 @@ enum StatisticsOption {
 
 /// Displays performance statistics.
 class StatisticsOverlay extends LeafRenderObjectWidget {
+  // TODO(abarth): We should have a page on the web site with a screenshot and
+  // an explanation of all the various readouts.
 
   /// Create a statistics overlay that only displays specific statistics. The
   /// mask is created by shifting 1 by the index of the specific StatisticOption