BoxFit documentation (#10397)

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

@@ -13,33 +13,68 @@ import 'basic_types.dart';
 ///
 /// See also [applyBoxFit], which applies the sizing semantics of these values
 /// (though not the alignment semantics).
+///
+/// The following diagrams show the effects of each value:
+///
+/// ![`fill`: Fill the target box by distorting the source's aspect ratio.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fill.png)
+///
+/// ![`contain`: As large as possible while still containing the source entirely within the target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_contain.png)
+///
+/// ![`cover`: As small as possible while still covering the entire target box.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_cover.png)
+///
+/// ![`fitWidth`: Make sure the full width of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitWidth.png)
+///
+/// ![`fitHeight`: Make sure the full height of the source is shown.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitHeight.png)
+///
+/// ![`none`: Do not resize the source.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_none.png)
+///
+/// ![`scaleDown`: Same as `contain` if that would shrink the image, otherwise same as `none`.](https://flutter.github.io/assets-for-api-docs/painting/box_fit_scaleDown.png)
 enum BoxFit {
   /// Fill the target box by distorting the source's aspect ratio.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fill.png)
   fill,
 
   /// As large as possible while still containing the source entirely within the
   /// target box.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_contain.png)
   contain,
 
   /// As small as possible while still covering the entire target box.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_cover.png)
   cover,
 
   /// Make sure the full width of the source is shown, regardless of
   /// whether this means the source overflows the target box vertically.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitWidth.png)
   fitWidth,
 
   /// Make sure the full height of the source is shown, regardless of
   /// whether this means the source overflows the target box horizontally.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_fitHeight.png)
   fitHeight,
 
   /// Align the source within the target box (by default, centering) and discard
   /// any portions of the source that lie outside the box.
+  ///
+  /// The source image is not resized.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_none.png)
   none,
 
   /// Align the source within the target box (by default, centering) and, if
   /// necessary, scale the source down to ensure that the source fits within the
   /// box.
-  scaleDown
+  ///
+  /// This is the same as `contain` if that would shrink the image, otherwise it
+  /// is the same as `none`.
+  ///
+  /// ![](https://flutter.github.io/assets-for-api-docs/painting/box_fit_scaleDown.png)
+  scaleDown,
 }
 
 /// The pair of sizes returned by [applyBoxFit].
@@ -56,7 +91,7 @@ class FittedSizes {
   final Size destination;
 }
 
-/// Apply an [BoxFit] value.
+/// Apply a [BoxFit] value.
 ///
 /// The arguments to this method, in addition to the [BoxFit] value to apply,
 /// are two sizes, ostensibly the sizes of an input box and an output box.

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

@@ -330,7 +330,7 @@ class BorderSide {
 ///
 /// ```dart
 /// // All four borders the same, two-pixel wide solid white:
-/// const Border.all(width: 2.0, color: const Color(0xFFFFFFFF))
+/// new Border.all(width: 2.0, color: const Color(0xFFFFFFFF))
 /// ```
 ///
 /// ```dart