A variety of trivial fixes. (#6752)

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

@@ -15,7 +15,8 @@ const double _kDrawerHeaderHeight = 160.0 + 1.0; // bottom edge
 ///
 /// Part of the material design [Drawer].
 ///
-/// Requires one of its ancestors to be a [Material] widget.
+/// Requires one of its ancestors to be a [Material] widget. This condition is
+/// satisfied by putting the [DrawerItem] in a [Drawer].
 ///
 /// See also:
 ///

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

@@ -18,7 +18,8 @@ import 'theme.dart';
 ///
 /// Part of the material design [Drawer].
 ///
-/// Requires one of its ancestors to be a [Material] widget.
+/// Requires one of its ancestors to be a [Material] widget. This condition is
+/// satisfied by putting the [DrawerItem] in a [Drawer].
 ///
 /// See also:
 ///
@@ -115,18 +116,20 @@ class DrawerItem extends StatelessWidget {
         )
       );
     }
-    children.add(
-      new Flexible(
-        child: new Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 16.0),
-          child: new AnimatedDefaultTextStyle(
-            style: _getTextStyle(themeData),
-            duration: kThemeChangeDuration,
-            child: child
+    if (child != null) {
+      children.add(
+        new Flexible(
+          child: new Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 16.0),
+            child: new AnimatedDefaultTextStyle(
+              style: _getTextStyle(themeData),
+              duration: kThemeChangeDuration,
+              child: child
+            )
           )
         )
-      )
-    );
+      );
+    }
 
     return new MergeSemantics(
       child: new Container(

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

@@ -247,14 +247,14 @@ class ThemeData {
   /// The background color for major parts of the app (toolbars, tab bars, etc)
   final Color primaryColor;
 
-  /// The brightness of the primaryColor. Used to determine the color of text and
+  /// The brightness of the [primaryColor]. Used to determine the color of text and
   /// icons placed on top of the primary color (e.g. toolbar text).
   final Brightness primaryColorBrightness;
 
   /// The foreground color for widgets (knobs, text, etc)
   final Color accentColor;
 
-  /// The brightness of the accentColor. Used to determine the color of text
+  /// The brightness of the [accentColor]. Used to determine the color of text
   /// and icons placed on top of the accent color (e.g. the icons on a floating
   /// action button).
   final Brightness accentColorBrightness;

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

@@ -967,7 +967,7 @@ class BackgroundImage {
     this.repeat: ImageRepeat.noRepeat,
     this.centerSlice,
     this.colorFilter,
-    this.alignment
+    this.alignment,
   });
 
   /// The image to be painted into the background.
@@ -999,6 +999,8 @@ class BackgroundImage {
   /// An alignment of (0.0, 0.0) aligns the image to the top-left corner of its
   /// layout bounds.  An alignment of (1.0, 0.5) aligns the image to the middle
   /// of the right edge of its layout bounds.
+  ///
+  /// Defaults to [FractionalOffset.center].
   final FractionalOffset alignment;
 
   @override
@@ -1024,6 +1026,25 @@ class BackgroundImage {
 }
 
 /// An immutable description of how to paint a box.
+///
+/// The following example uses the [Container] widget from the widgets layer to
+/// draw a background image with a border:
+///
+/// ```dart
+/// new Container(
+///   decoration: new BoxDecoration(
+///     backgroundColor: const Color(0xff7c94b6),
+///     backgroundImage: new BackgroundImage(
+///       image: new ExactAssetImage('images/flowers.jpeg'),
+///       fit: ImageFit.cover,
+///     ),
+///     border: new Border.all(
+///       color: Colors.black,
+///       width: 8.0,
+///     ),
+///   ),
+/// )
+/// ```
 class BoxDecoration extends Decoration {
   /// Creates a box decoration.
   ///

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

@@ -248,7 +248,7 @@ class AssetBundleImageKey {
   int get hashCode => hashValues(bundle, name, scale);
 
   @override
-  String toString() => '$runtimeType(bundle: $bundle, name: $name, scale: $scale)';
+  String toString() => '$runtimeType(bundle: $bundle, name: "$name", scale: $scale)';
 }
 
 /// A subclass of [ImageProvider] that knows about [AssetBundle]s.
@@ -432,5 +432,5 @@ class ExactAssetImage extends AssetBundleImageProvider {
   int get hashCode => hashValues(name, scale, bundle);
 
   @override
-  String toString() => '$runtimeType(name: $name, scale: $scale, bundle: $bundle)';
+  String toString() => '$runtimeType(name: "$name", scale: $scale, bundle: $bundle)';
 }

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

@@ -197,5 +197,5 @@ class AssetImage extends AssetBundleImageProvider {
   int get hashCode => hashValues(name, bundle);
 
   @override
-  String toString() => '$runtimeType(bundle: $bundle, name: $name)';
+  String toString() => '$runtimeType(bundle: $bundle, name: "$name")';
 }

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

@@ -53,9 +53,6 @@ export 'package:flutter/rendering.dart' show
     ViewportAnchor,
     ViewportDimensions,
     ViewportDimensionsChangeCallback;
-export 'package:flutter/services.dart' show
-    AssetImage,
-    NetworkImage;
 
 // PAINTING NODES
 

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

@@ -4,14 +4,18 @@
 
 import 'dart:io' show Platform;
 
-import 'package:meta/meta.dart';
-
 import 'package:flutter/services.dart';
+import 'package:meta/meta.dart';
 
 import 'basic.dart';
 import 'framework.dart';
 import 'media_query.dart';
 
+export 'package:flutter/services.dart' show
+    AssetImage,
+    ExactAssetImage,
+    NetworkImage;
+
 /// Creates an [ImageConfiguration] based on the given [BuildContext] (and
 /// optionally size).
 ///

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

@@ -6,7 +6,19 @@ import 'package:meta/meta.dart';
 
 import 'framework.dart';
 
-/// A widget that has exactly one inflated instance in the tree.
+/// Base class for stateful widgets that have exactly one inflated instance in
+/// the tree.
+///
+/// Such widgets must be given a [GlobalKey]. This key can be generated by the
+/// subclass from its [Type] object, e.g. by calling `super(key: new
+/// GlobalObjectKey(MyWidget))` where `MyWidget` is the name of the subclass.
+///
+/// Since only one instance can be inflated at a time, there is only ever one
+/// corresponding [State] object. That object is exposed, for convenience, via
+/// the [currentState] property.
+///
+/// When subclassing [UniqueWidget], provide the corresponding [State] subclass
+/// as the type argument.
 abstract class UniqueWidget<T extends State<StatefulWidget>> extends StatefulWidget {
   /// Creates a widget that has exactly one inflated instance in the tree.
   ///