Add more dartdoc to widgets.dart

Making progress documenting the widget library.

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

@@ -69,6 +69,28 @@ class _FocusScope extends InheritedWidget {
   }
 }
 
+/// A scope for managing the focus state of descendant widgets.
+///
+/// The focus represents where the user's attention is directed. If the use
+/// interacts with the system in a way that isn't visually directed at a
+/// particular widget (e.g., by typing on a keyboard), the interaction is
+/// directed to the currently focused widget.
+///
+/// The focus system consists of a tree of Focus widgets, which is embedded in
+/// the widget tree. Focus widgets themselves can be focused in their enclosing
+/// Focus widget, which means that their subtree is the one that has the current
+/// focus. For example, a dialog creates a Focus widget to maintain focus
+/// within the dialog.  When the dialog closes, its Focus widget is removed from
+/// the tree and focus is restored to whichever other part of the Focus tree
+/// previously had focus.
+///
+/// In addition to tracking which enclosed Focus widget has focus, each Focus
+/// widget also tracks a GlobalKey, which represents the currently focused
+/// widget in this part of the focus tree. If this Focus widget is the currently
+/// focused subtree of the focus system (i.e., the path from it to the root is
+/// focused at each level and it hasn't focused any of its enclosed Focus
+/// widgets), then the widget this this global key actually has the focus in the
+/// entire system.
 class Focus extends StatefulComponent {
   Focus({
     GlobalKey key,
@@ -79,8 +101,15 @@ class Focus extends StatefulComponent {
 
   final Widget child;
 
+  /// The key that currently has focus globally in the entire focus tree.
+  ///
+  /// This field is always null except in checked mode.
   static GlobalKey debugOnlyFocusedKey;
 
+  /// Whether the focus is current at the given context.
+  ///
+  /// If autofocus is true, the given context will become focused if no other
+  /// widget is already focused.
   static bool at(BuildContext context, { bool autofocus: false }) {
     assert(context != null);
     assert(context.widget != null);
@@ -134,6 +163,8 @@ class Focus extends StatefulComponent {
     }
   }
 
+  /// Unfocuses the currently focused widget (if any) in the Focus that most
+  /// tightly encloses the given context.
   static void clear(BuildContext context) {
     _FocusScope focusScope = context.ancestorWidgetOfExactType(_FocusScope);
     if (focusScope != null)

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

@@ -56,10 +56,18 @@ class GridPaper extends StatelessComponent {
     this.child
   }) : super(key: key);
 
+  /// The color to draw the lines in the grid.
   final Color color;
+
+  /// The distance between the primary lines in the grid, in logical pixels.
   final double interval;
+
+  /// The number of major divisions within each primary grid cell.
   final int divisions;
+
+  /// The number of minor divisions within each major division.
   final int subDivisions;
+
   final Widget child;
 
   Widget build(BuildContext context) {

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

@@ -9,14 +9,14 @@ import 'framework.dart';
 
 import 'package:vector_math/vector_math_64.dart';
 
-/// An animated value that interpolates [BoxConstraint]s.
+/// An interpolation between two [BoxConstraint]s.
 class BoxConstraintsTween extends Tween<BoxConstraints> {
   BoxConstraintsTween({ BoxConstraints begin, BoxConstraints end }) : super(begin: begin, end: end);
 
   BoxConstraints lerp(double t) => BoxConstraints.lerp(begin, end, t);
 }
 
-/// An animated value that interpolates [Decoration]s.
+/// An interpolation between two [Decoration]s.
 class DecorationTween extends Tween<Decoration> {
   DecorationTween({ Decoration begin, Decoration end }) : super(begin: begin, end: end);
 
@@ -29,14 +29,14 @@ class DecorationTween extends Tween<Decoration> {
   }
 }
 
-/// An animated value that interpolates [EdgeDims].
+/// An interpolation between two [EdgeDims]s.
 class EdgeDimsTween extends Tween<EdgeDims> {
   EdgeDimsTween({ EdgeDims begin, EdgeDims end }) : super(begin: begin, end: end);
 
   EdgeDims lerp(double t) => EdgeDims.lerp(begin, end, t);
 }
 
-/// An animated value that interpolates [Matrix4]s.
+/// An interpolation between two [Matrix4]s.
 ///
 /// Currently this class works only for translations.
 class Matrix4Tween extends Tween<Matrix4> {
@@ -78,12 +78,17 @@ abstract class AnimatedWidgetBase extends StatefulComponent {
   }
 }
 
+/// Used by [AnimatedWidgetBaseState].
 typedef Tween<T> TweenConstructor<T>(T targetValue);
+
+/// Used by [AnimatedWidgetBaseState].
 typedef Tween<T> TweenVisitor<T>(Tween<T> tween, T targetValue, TweenConstructor<T> constructor);
 
+/// A base class for widgets with implicit animations.
 abstract class AnimatedWidgetBaseState<T extends AnimatedWidgetBase> extends State<T> {
   AnimationController _controller;
 
+  /// The animation driving this widget's implicit animations.
   Animation<double> get animation => _animation;
   Animation<double> _animation;
 

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

@@ -7,6 +7,7 @@ import 'framework.dart';
 /// Superclass for locale-specific data provided by the application.
 class LocaleQueryData { }
 
+/// Establishes a subtree in which locale queries resolve to the given data.
 class LocaleQuery<T extends LocaleQueryData> extends InheritedWidget {
   LocaleQuery({
     Key key,
@@ -16,6 +17,7 @@ class LocaleQuery<T extends LocaleQueryData> extends InheritedWidget {
     assert(child != null);
   }
 
+  /// The locale data for this subtree.
   final T data;
 
   /// The data from the closest instance of this class that encloses the given context.

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

@@ -144,6 +144,9 @@ class Mimicable extends StatefulComponent {
   MimicableState createState() => new MimicableState();
 }
 
+/// The state for a [Mimicable].
+///
+/// Exposes an API for starting and stopping mimicking.
 class MimicableState extends State<Mimicable> {
   Size _size;
   bool _beingMimicked = false;

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

@@ -7,7 +7,9 @@ import 'framework.dart';
 /// Return true to cancel the notification bubbling.
 typedef bool NotificationListenerCallback<T extends Notification>(T notification);
 
+/// A notification that can bubble up the widget tree.
 abstract class Notification {
+  /// Start bubbling this notification at the given build context.
   void dispatch(BuildContext target) {
     target.visitAncestorElements((Element element) {
       if (element is StatelessComponentElement &&
@@ -21,6 +23,7 @@ abstract class Notification {
   }
 }
 
+/// Listens for [Notification]s bubbling up the tree.
 class NotificationListener<T extends Notification> extends StatelessComponent {
   NotificationListener({
     Key key,
@@ -29,6 +32,8 @@ class NotificationListener<T extends Notification> extends StatelessComponent {
   }) : super(key: key);
 
   final Widget child;
+
+  /// Called when a notification of the appropriate type arrives at this location in the tree.
   final NotificationListenerCallback<T> onNotification;
 
   bool _dispatch(Notification notification) {

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

@@ -37,6 +37,10 @@ class _StorageEntryIdentifier {
   }
 }
 
+/// A storage bucket associated with a page in an app.
+///
+/// Useful for storing per-page state that persists across navigations from one
+/// page to another.
 class PageStorageBucket {
   _StorageEntryIdentifier _computeStorageIdentifier(BuildContext context) {
     _StorageEntryIdentifier result = new _StorageEntryIdentifier();
@@ -62,15 +66,22 @@ class PageStorageBucket {
   }
 
   Map<_StorageEntryIdentifier, dynamic> _storage;
+
+  /// Write the given data into this page storage bucket using an identifier
+  /// computed from the given context.
   void writeState(BuildContext context, dynamic data) {
     _storage ??= <_StorageEntryIdentifier, dynamic>{};
     _storage[_computeStorageIdentifier(context)] = data;
   }
+
+  /// Read given data from into this page storage bucket using an identifier
+  /// computed from the given context.
   dynamic readState(BuildContext context) {
     return _storage != null ? _storage[_computeStorageIdentifier(context)] : null;
   }
 }
 
+/// Establishes a page storage bucket for this widget subtree.
 class PageStorage extends StatelessComponent {
   PageStorage({
     Key key,
@@ -79,6 +90,8 @@ class PageStorage extends StatelessComponent {
   }) : super(key: key);
 
   final Widget child;
+
+  /// The page storage bucket to use for this subtree.
   final PageStorageBucket bucket;
 
   /// The bucket from the closest instance of this class that encloses the given context.