ImageFit.fitWidth/fitHeight and minor docs fixes

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

@@ -669,6 +669,14 @@ enum ImageFit {
   /// As small as possible while still covering the entire box.
   cover,
 
+  /// Make sure the full width of the image is shown, regardless of
+  /// whether this means the image overflows the box vertically.
+  fitWidth,
+
+  /// Make sure the full height of the image is shown, regardless of
+  /// whether this means the image overflows the box horizontally.
+  fitHeight,
+
   /// Center the image within the box and discard any portions of the image that
   /// lie outside the box.
   none,
@@ -773,6 +781,16 @@ void paintImage({
       }
       destinationSize = outputSize;
       break;
+    case ImageFit.fitWidth:
+      sourceSize = new Size(inputSize.width, inputSize.width * outputSize.height / outputSize.width);
+      sourcePosition = new Point(0.0, (inputSize.height - sourceSize.height) * (alignment?.dy ?? 0.5));
+      destinationSize = new Size(outputSize.width, sourceSize.height * outputSize.width / sourceSize.width);
+      break;
+    case ImageFit.fitHeight:
+      sourceSize = new Size(inputSize.height * outputSize.width / outputSize.height, inputSize.height);
+      sourcePosition = new Point((inputSize.width - sourceSize.width) * (alignment?.dx ?? 0.5), 0.0);
+      destinationSize = new Size(sourceSize.width * outputSize.height / sourceSize.height, outputSize.height);
+      break;
     case ImageFit.none:
       sourceSize = new Size(math.min(inputSize.width, outputSize.width),
                             math.min(inputSize.height, outputSize.height));

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

@@ -410,7 +410,7 @@ class BoxHitTestEntry extends HitTestEntry {
 
 /// Parent data used by [RenderBox] and its subclasses.
 class BoxParentData extends ParentData {
-  /// The offset at which to paint the child in the parent's coordinate system
+  /// The offset at which to paint the child in the parent's coordinate system.
   Offset offset = Offset.zero;
 
   @override

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

@@ -567,11 +567,14 @@ int _getAlphaFromOpacity(double opacity) => (opacity * 255).round();
 /// This class paints its child into an intermediate buffer and then blends the
 /// child back into the scene partially transparent.
 ///
-/// This class is relatively expensive because it requires painting the child
-/// into an intermediate buffer.
+/// For values of opacity other than 0.0 and 1.0, this class is relatively
+/// expensive because it requires painting the child into an intermediate
+/// buffer. For the value 0.0, the child is simply not painted at all. For the
+/// value 1.0, the child is painted immediately without an intermediate buffer.
 class RenderOpacity extends RenderProxyBox {
   RenderOpacity({ RenderBox child, double opacity: 1.0 })
     : _opacity = opacity, _alpha = _getAlphaFromOpacity(opacity), super(child) {
+    assert(opacity != null);
     assert(opacity >= 0.0 && opacity <= 1.0);
   }
 
@@ -582,6 +585,12 @@ class RenderOpacity extends RenderProxyBox {
   ///
   /// An opacity of 1.0 is fully opaque. An opacity of 0.0 is fully transparent
   /// (i.e., invisible).
+  ///
+  /// The opacity must not be null.
+  ///
+  /// Values 1.0 and 0.0 are painted with a fast path. Other values
+  /// require painting the child into an intermediate buffer, which is
+  /// expensive.
   double get opacity => _opacity;
   double _opacity;
   void set opacity (double newOpacity) {