Diagrams and samples for Rank 20-30 popular api docs (#40089)

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

@@ -81,7 +81,7 @@ enum ThemeMode {
 /// This example shows how to create a [MaterialApp] that disables the "debug"
 /// banner with a [home] route that will be displayed when the app is launched.
 ///
-/// ![A screenshot of the MaterialApp class with a home Scaffold](https://flutter.github.io/assets-for-api-docs/assets/material/basic_material_app.png)
+/// ![The MaterialApp displays a Scaffold ](https://flutter.github.io/assets-for-api-docs/assets/material/basic_material_app.png)
 ///
 /// ```dart
 /// MaterialApp(
@@ -125,7 +125,7 @@ enum ThemeMode {
 /// This example shows how to create a [MaterialApp] that defines a [theme] that
 /// will be used for material widgets in the app.
 ///
-/// ![A screenshot of the MaterialApp class with a custom theme](https://flutter.github.io/assets-for-api-docs/assets/material/theme_material_app.png)
+/// ![The MaterialApp displays a Scaffold with a dark background and a blue / grey AppBar at the top](https://flutter.github.io/assets-for-api-docs/assets/material/theme_material_app.png)
 ///
 /// ```dart
 /// MaterialApp(

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

@@ -55,6 +55,59 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 /// drawer children are often constructed with [ListTile]s, often concluding
 /// with an [AboutListTile].
 ///
+/// The [AppBar] automatically displays an appropriate [IconButton] to show the
+/// [Drawer] when a [Drawer] is available in the [Scaffold]. The [Scaffold]
+/// automatically handles the edge-swipe gesture to show the drawer.
+///
+/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/drawer.mp4}
+///
+/// {@tool sample}
+/// This example shows how to create a [Scaffold] that contains an [AppBar] and
+/// a [Drawer]. A user taps the "menu" icon in the [AppBar] to open the
+/// [Drawer]. The [Drawer] displays four items: A header and three menu items.
+/// The [Drawer] displays the four items using a [ListView], which allows the
+/// user to scroll through the items if need be.
+///
+/// ```dart
+/// Scaffold(
+///   appBar: AppBar(
+///     title: const Text('Drawer Demo'),
+///   ),
+///   drawer: Drawer(
+///     child: ListView(
+///       padding: EdgeInsets.zero,
+///       children: const <Widget>[
+///         DrawerHeader(
+///           decoration: BoxDecoration(
+///             color: Colors.blue,
+///           ),
+///           child: Text(
+///             'Drawer Header',
+///             style: TextStyle(
+///               color: Colors.white,
+///               fontSize: 24,
+///             ),
+///           ),
+///         ),
+///         ListTile(
+///           leading: Icon(Icons.message),
+///           title: Text('Messages'),
+///         ),
+///         ListTile(
+///           leading: Icon(Icons.account_circle),
+///           title: Text('Profile'),
+///         ),
+///         ListTile(
+///           leading: Icon(Icons.settings),
+///           title: Text('Settings'),
+///         ),
+///       ],
+///     ),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
 /// An open drawer can be closed by calling [Navigator.pop]. For example
 /// a drawer item might close the drawer when tapped:
 ///
@@ -69,10 +122,6 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 /// );
 /// ```
 ///
-/// The [AppBar] automatically displays an appropriate [IconButton] to show the
-/// [Drawer] when a [Drawer] is available in the [Scaffold]. The [Scaffold]
-/// automatically handles the edge-swipe gesture to show the drawer.
-///
 /// See also:
 ///
 ///  * [Scaffold.drawer], where one specifies a [Drawer] so that it can be

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

@@ -534,10 +534,11 @@ class DropdownButtonHideUnderline extends InheritedWidget {
 ///
 /// {@tool snippet --template=stateful_widget_scaffold_center}
 ///
-/// This sample shows a `DropdownButton` with a customized icon, text style,
-/// and underline and whose value is one of "One", "Two", "Free", or "Four".
+/// This sample shows a `DropdownButton` with a large arrow icon,
+/// purple text style, and bold purple underline, whose value is one of "One",
+/// "Two", "Free", or "Four".
 ///
-/// ![A screenshot of the dropdown button](https://flutter.github.io/assets-for-api-docs/assets/material/dropdown_button.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/dropdown_button.png)
 ///
 /// ```dart
 /// String dropdownValue = 'One';

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

@@ -58,10 +58,10 @@ class _DefaultHeroTag {
 /// action button.
 ///
 /// {@tool snippet --template=stateless_widget_material}
-/// This example shows how to make a simple [FloatingActionButton] in a
+/// This example shows how to display a [FloatingActionButton] in a
 /// [Scaffold], with a pink [backgroundColor] and a thumbs up [Icon].
 ///
-/// ![A screenshot of a green floating action button with a navigation icon](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button.png)
 ///
 /// ```dart
 /// Widget build(BuildContext context) {
@@ -87,9 +87,9 @@ class _DefaultHeroTag {
 /// {@tool snippet --template=stateless_widget_material}
 /// This example shows how to make an extended [FloatingActionButton] in a
 /// [Scaffold], with a  pink [backgroundColor], a thumbs up [Icon] and a
-/// [Text] label.
+/// [Text] label that reads "Approve".
 ///
-/// ![A screenshot of a pink floating action button with a thumbs up icon and a label that reads "Approve"](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button_label.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button_label.png)
 ///
 /// ```dart
 /// Widget build(BuildContext context) {

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

@@ -43,6 +43,8 @@ const double _kMinButtonSize = kMinInteractiveDimension;
 /// This sample shows an `IconButton` that uses the Material icon "volume_up" to
 /// increase the volume.
 ///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/icon_button.png)
+///
 /// ```dart preamble
 /// double _volume = 0.0;
 /// ```
@@ -87,21 +89,22 @@ const double _kMinButtonSize = kMinInteractiveDimension;
 /// is a light shade of blue, it's a filled circle, and it's as big as the
 /// button is.
 ///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/icon_button_background.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
-///   return Center(
-///     child: Container(
+///   return Material(
+///     color: Colors.white,
+///     child: Center(
 ///       child: Ink(
-///         decoration: ShapeDecoration(
+///         decoration: const ShapeDecoration(
 ///           color: Colors.lightBlue,
 ///           shape: CircleBorder(),
 ///         ),
 ///         child: IconButton(
 ///           icon: Icon(Icons.android),
 ///           color: Colors.white,
-///           onPressed: () {
-///             print("filled background");
-///           },
+///           onPressed: () {},
 ///         ),
 ///       ),
 ///     ),

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

@@ -811,7 +811,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
 /// within the [Scaffold]. The [FloatingActionButton] is connected to a
 /// callback that increments a counter.
 ///
-/// ![A screenshot of the Scaffold widget with a body and floating action button](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold.png)
+/// ![The Scaffold has a white background with a blue AppBar at the top. A blue FloatingActionButton is positioned at the bottom right corner of the Scaffold.](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold.png)
 ///
 /// ```dart
 /// int _count = 0;
@@ -835,12 +835,12 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
 /// {@end-tool}
 ///
 /// {@tool snippet --template=stateful_widget_material}
-/// This example shows a [Scaffold] with a [backgroundColor], [body] and
-/// [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in order
-/// to center the text within the [Scaffold]. The [FloatingActionButton] is
-/// connected to a callback that increments a counter.
+/// This example shows a [Scaffold] with a blueGrey [backgroundColor], [body]
+/// and [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in
+/// order to center the text within the [Scaffold]. The [FloatingActionButton]
+/// is connected to a callback that increments a counter.
 ///
-/// ![A screenshot of the Scaffold widget example with a background color](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_background_color.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_background_color.png)
 ///
 /// ```dart
 /// int _count = 0;
@@ -872,7 +872,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
 /// [FloatingActionButtonLocation.centerDocked]. The [FloatingActionButton] is
 /// connected to a callback that increments a counter.
 ///
-/// ![A screenshot of the Scaffold widget with a bottom navigation bar and docked floating action button](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_bottom_app_bar.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_bottom_app_bar.png)
 ///
 /// ```dart
 /// int _count = 0;

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

@@ -175,7 +175,7 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete
 /// [InputDecoration] surrounds the field in a border using [OutlineInputBorder]
 /// and adds a label.
 ///
-/// ![A screenshot of the TextField widget](https://flutter.github.io/assets-for-api-docs/assets/material/text_field.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/text_field.png)
 ///
 /// ```dart
 /// TextField(

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

@@ -38,6 +38,10 @@ import 'theme.dart';
 ///
 /// Creates a [TextFormField] with an [InputDecoration] and validator function.
 ///
+/// ![If the user enters valid text, the TextField appears normally without any warnings to the user](https://flutter.github.io/assets-for-api-docs/assets/material/text_form_field.png)
+///
+/// ![If the user enters invalid text, the error message returned from the validator function is displayed in dark red underneath the input](https://flutter.github.io/assets-for-api-docs/assets/material/text_form_field_error.png)
+///
 /// ```dart
 /// TextFormField(
 ///   decoration: const InputDecoration(

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

@@ -92,9 +92,76 @@ enum MaterialTapTargetSize {
 
 /// Holds the color and typography values for a material design theme.
 ///
-/// Use this class to configure a [Theme] widget.
+/// Use this class to configure a [Theme] or [MaterialApp] widget.
 ///
 /// To obtain the current theme, use [Theme.of].
+///
+/// {@tool sample}
+///
+/// This sample creates a [Theme] widget that stores the `ThemeData`. The
+/// `ThemeData` can be accessed by descendant Widgets that use the correct
+/// `context`. This example uses the [Builder] widget to gain access to a
+/// descendant `context` that contains the `ThemeData`.
+///
+/// The [Container] widget uses [Theme.of] to retrieve the [primaryColor] from
+/// the `ThemeData` to draw an amber square.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/theme_data.png)
+///
+/// ```dart
+/// Theme(
+///   data: ThemeData(primaryColor: Colors.amber),
+///   child: Builder(
+///     builder: (BuildContext context) {
+///       return Container(
+///         width: 100,
+///         height: 100,
+///         color: Theme.of(context).primaryColor,
+///       );
+///     },
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
+/// In addition to using the [Theme] widget, you can provide `ThemeData` to a
+/// [MaterialApp]. The `ThemeData` will be used throughout the app to style
+/// material design widgets.
+///
+/// {@tool sample}
+///
+/// This sample creates a [MaterialApp] widget that stores `ThemeData` and
+/// passes the `ThemeData` to descendant widgets. The [AppBar] widget uses the
+/// [primaryColor] to create a blue background. The [Text] widget uses the
+/// [TextTheme.body1] to create purple text. The [FloatingActionButton] widget
+/// uses the [accentColor] to create a green background.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/material_app_theme_data.png)
+///
+/// ```dart
+/// MaterialApp(
+///   theme: ThemeData(
+///     primaryColor: Colors.blue,
+///     accentColor: Colors.green,
+///     textTheme: TextTheme(body1: TextStyle(color: Colors.purple)),
+///   ),
+///   home: Scaffold(
+///     appBar: AppBar(
+///       title: const Text('ThemeData Demo'),
+///     ),
+///     floatingActionButton: FloatingActionButton(
+///       child: const Icon(Icons.add),
+///       onPressed: () {},
+///     ),
+///     body: Center(
+///       child: Text(
+///         'Button pressed 0 times',
+///       ),
+///     ),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
 @immutable
 class ThemeData extends Diagnosticable {
   /// Create a [ThemeData] given a set of preferred values.

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

@@ -35,21 +35,24 @@ import 'image_provider.dart';
 ///
 /// {@tool sample}
 ///
-/// The following example uses the [Container] widget from the widgets layer to
-/// draw an image with a border:
+/// The following applies a [BoxDecoration] to a [Container] widget to draw an
+/// [image] of an owl with a thick black [border] and rounded corners.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/box_decoration.png)
 ///
 /// ```dart
 /// Container(
 ///   decoration: BoxDecoration(
 ///     color: const Color(0xff7c94b6),
-///     image: DecorationImage(
-///       image: ExactAssetImage('images/flowers.jpeg'),
+///     image: const DecorationImage(
+///       image: NetworkImage('https:///flutter.github.io/assets-for-api-docs/assets/widgets/owl-2.jpg'),
 ///       fit: BoxFit.cover,
 ///     ),
 ///     border: Border.all(
 ///       color: Colors.black,
-///       width: 8.0,
+///       width: 8,
 ///     ),
+///     borderRadius: BorderRadius.circular(12),
 ///   ),
 /// )
 /// ```

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

@@ -30,7 +30,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// override. The style is mixed with the ambient [DefaultTextStyle] by the
 /// [Text] widget.
 ///
-/// ![An example using TextStyle to create bold text](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_bold.png)
+/// ![Applying the style in this way creates bold text.](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_bold.png)
 ///
 /// ```dart
 /// Text(
@@ -46,7 +46,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// As in the previous example, the [Text] widget is given a specific style
 /// override which is implicitly mixed with the ambient [DefaultTextStyle].
 ///
-/// ![An example using TextStyle to create italic text](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_italics.png)
+/// ![This results in italicized text.](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_italics.png)
 ///
 /// ```dart
 /// Text(
@@ -72,7 +72,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// The [backgroundColor] is treated as a shorthand for
 /// `background: Paint()..color = backgroundColor`.
 ///
-/// ![An example using TextStyle to change the text opacity and color](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_opacity_and_color.png)
+/// ![This results in three lines of text that go from lighter to darker in color.](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_opacity_and_color.png)
 ///
 /// ```dart
 /// RichText(
@@ -102,7 +102,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// In this example, the ambient [DefaultTextStyle] is explicitly manipulated to
 /// obtain a [TextStyle] that doubles the default font size.
 ///
-/// ![An example using TextStyle to change the text size](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_size.png)
+/// ![This results in text that is twice as large as normal.](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_size.png)
 ///
 /// ```dart
 /// Text(
@@ -147,13 +147,13 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// ### Wavy red underline with black text
 ///
 /// {@tool sample}
-/// Styles can be combined. In this example, the misspelt word is drawn in black
-/// text and underlined with a wavy red line to indicate a spelling error. (The
-/// remainder is styled according to the Flutter default text styles, not the
-/// ambient [DefaultTextStyle], since no explicit style is given and [RichText]
-/// does not automatically use the ambient [DefaultTextStyle].)
+/// Styles can be combined. In this example, the misspelled word is drawn in
+/// black text and underlined with a wavy red line to indicate a spelling error.
+/// (The remainder is styled according to the Flutter default text styles, not
+/// the ambient [DefaultTextStyle], since no explicit style is given and
+/// [RichText] does not automatically use the ambient [DefaultTextStyle].)
 ///
-/// ![An example using TextStyle to highlight a word with a red wavy underline](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_wavy_red_underline.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_wavy_red_underline.png)
 ///
 /// ```dart
 /// RichText(
@@ -276,7 +276,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// argument as shown in the example below:
 ///
 /// {@tool sample}
-/// ![An example using TextStyle to change the font family](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_custom_fonts.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_custom_fonts.png)
 ///
 /// ```dart
 /// const TextStyle(fontFamily: 'Raleway')

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

@@ -489,30 +489,77 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
 /// `future?.asStream()`, except that snapshots with `ConnectionState.active`
 /// may appear for the latter, depending on how the stream is implemented.
 ///
-/// {@tool sample}
+/// {@animation 200 150 https://flutter.github.io/assets-for-api-docs/assets/widgets/future_builder.mp4}
+///
+/// {@animation 200 150 https://flutter.github.io/assets-for-api-docs/assets/widgets/future_builder_error.mp4}
 ///
-/// This sample shows a [FutureBuilder] configuring a text label to show the
-/// state of an asynchronous calculation returning a string. Assume the
-/// `_calculation` field is set by pressing a button elsewhere in the UI.
+/// {@tool snippet --template=stateful_widget_material}
+///
+/// This sample shows a [FutureBuilder] that displays a loading spinner while it
+/// loads data. It displays a success icon and text if the [Future] completes
+/// with a result, or an error icon and text if the [Future] completes with an
+/// error. Assume the `_calculation` field is set by pressing a button elsewhere
+/// in the UI.
 ///
 /// ```dart
-/// FutureBuilder<String>(
-///   future: _calculation, // a previously-obtained Future<String> or null
-///   builder: (BuildContext context, AsyncSnapshot<String> snapshot) {
-///     switch (snapshot.connectionState) {
-///       case ConnectionState.none:
-///         return Text('Press button to start.');
-///       case ConnectionState.active:
-///       case ConnectionState.waiting:
-///         return Text('Awaiting result...');
-///       case ConnectionState.done:
-///         if (snapshot.hasError)
-///           return Text('Error: ${snapshot.error}');
-///         return Text('Result: ${snapshot.data}');
-///     }
-///     return null; // unreachable
-///   },
-/// )
+/// Future<String> _calculation = Future<String>.delayed(
+///   Duration(seconds: 2),
+///   () => 'Data Loaded',
+/// );
+///
+/// Widget build(BuildContext context) {
+///   return FutureBuilder<String>(
+///     future: _calculation, // a previously-obtained Future<String> or null
+///     builder: (BuildContext context, AsyncSnapshot<String> snapshot) {
+///       List<Widget> children;
+///
+///       if (snapshot.hasData) {
+///         children = <Widget>[
+///           Icon(
+///             Icons.check_circle_outline,
+///             color: Colors.green,
+///             size: 60,
+///           ),
+///           Padding(
+///             padding: const EdgeInsets.only(top: 16),
+///             child: Text('Result: ${snapshot.data}'),
+///           )
+///         ];
+///       } else if (snapshot.hasError) {
+///         children = <Widget>[
+///           Icon(
+///             Icons.error_outline,
+///             color: Colors.red,
+///             size: 60,
+///           ),
+///           Padding(
+///             padding: const EdgeInsets.only(top: 16),
+///             child: Text('Error: ${snapshot.error}'),
+///           )
+///         ];
+///       } else {
+///         children = <Widget>[
+///           SizedBox(
+///             child: CircularProgressIndicator(),
+///             width: 60,
+///             height: 60,
+///           ),
+///           const Padding(
+///             padding: EdgeInsets.only(top: 16),
+///             child: Text('Awaiting result...'),
+///           )
+///         ];
+///       }
+///       return Center(
+///         child: Column(
+///           mainAxisAlignment: MainAxisAlignment.center,
+///           crossAxisAlignment: CrossAxisAlignment.center,
+///           children: children,
+///         ),
+///       );
+///     },
+///   );
+/// }
 /// ```
 /// {@end-tool}
 // TODO(ianh): remove unreachable code above once https://github.com/dart-lang/linter/issues/1141 is fixed

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

@@ -1563,13 +1563,17 @@ class RotatedBox extends SingleChildRenderObjectWidget {
 ///
 /// {@tool sample}
 ///
-/// This snippet indents the child (a [Card] with some [Text]) by eight pixels
-/// in each direction:
+/// This snippet creates "Hello World!" [Text] inside a [Card] that is indented
+/// by sixteen pixels in each direction.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/padding.png)
 ///
 /// ```dart
-/// Padding(
-///   padding: EdgeInsets.all(8.0),
-///   child: const Card(child: Text('Hello World!')),
+/// const Card(
+///   child: Padding(
+///     padding: EdgeInsets.all(16.0),
+///     child: Text('Hello World!'),
+///   ),
 /// )
 /// ```
 /// {@end-tool}
@@ -3088,7 +3092,7 @@ class ListBody extends MultiChildRenderObjectWidget {
 ///
 /// Using a [Stack] you can position widgets over one another.
 ///
-/// ![A screenshot of the Stack widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/stack.png)
+/// ![The sample creates a blue box that overlaps a larger green box, which itself overlaps an even larger red box.](https://flutter.github.io/assets-for-api-docs/assets/widgets/stack.png)
 ///
 /// ```dart
 /// Stack(
@@ -3118,7 +3122,7 @@ class ListBody extends MultiChildRenderObjectWidget {
 /// This example shows how [Stack] can be used to enhance text visibility
 /// by adding gradient backdrops.
 ///
-/// ![A screenshot of the Stack widget using a gradient to enhance text visibility](https://flutter.github.io/assets-for-api-docs/assets/widgets/stack_with_gradient.png)
+/// ![The gradient fades from transparent to dark grey at the bottom, with white text on top of the darker portion.](https://flutter.github.io/assets-for-api-docs/assets/widgets/stack_with_gradient.png)
 ///
 /// ```dart
 /// SizedBox(
@@ -3951,7 +3955,7 @@ class Flex extends MultiChildRenderObjectWidget {
 /// places text centered in the first two cells and the Flutter logo centered in
 /// the third:
 ///
-/// ![A screenshot of the Row widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/row.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/row.png)
 ///
 /// ```dart
 /// Row(
@@ -4140,7 +4144,7 @@ class Row extends Flex {
 /// This example uses a [Column] to arrange three widgets vertically, the last
 /// being made to fill all the remaining space.
 ///
-/// ![A screenshot of the Column widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/column.png)
+/// ![Using the Column in this way creates two short lines of text with a large Flutter underneath.](https://flutter.github.io/assets-for-api-docs/assets/widgets/column.png)
 ///
 /// ```dart
 /// Column(
@@ -4165,7 +4169,7 @@ class Row extends Flex {
 /// [mainAxisSize] is set to [MainAxisSize.min], so that the column shrinks to
 /// fit the children.
 ///
-/// ![A screenshot of the Column widget with a customized crossAxisAlignment and mainAxisSize](https://flutter.github.io/assets-for-api-docs/assets/widgets/column_properties.png)
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/column_properties.png)
 ///
 /// ```dart
 /// Column(
@@ -4416,7 +4420,7 @@ class Flexible extends ParentDataWidget<Flex> {
 /// This example shows how to use an [Expanded] widget in a [Column] so that
 /// it's middle child, a [Container] here, expands to fill the space.
 ///
-/// ![An example using Expanded widget in a Column](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_column.png)
+/// ![This results in two thin blue boxes with a larger amber box in between.](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_column.png)
 ///
 /// ```dart
 /// Widget build(BuildContext context) {
@@ -4455,7 +4459,7 @@ class Flexible extends ParentDataWidget<Flex> {
 /// This example shows how to use an [Expanded] widget in a [Row] with multiple
 /// children expanded, utilizing the [flex] factor to prioritize available space.
 ///
-/// ![An example using Expanded widget in a Row](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_row.png)
+/// ![This results in a wide amber box, followed by a thin blue box, with a medium width amber box at the end.](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_row.png)
 ///
 /// ```dart
 /// Widget build(BuildContext context) {

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

@@ -17,8 +17,11 @@ import 'will_pop_scope.dart';
 /// [Form] constructor and call [GlobalKey.currentState].
 ///
 /// {@tool snippet --template=stateful_widget_scaffold}
-/// This example shows a [Form] with one [TextFormField] and a [RaisedButton]. A
-/// [GlobalKey] is used here to identify the [Form] and validate input.
+/// This example shows a [Form] with one [TextFormField] to enter an email
+/// address and a [RaisedButton] to submit the form. A [GlobalKey] is used here
+/// to identify the [Form] and validate input.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/form.png)
 ///
 /// ```dart
 /// final _formKey = GlobalKey<FormState>();
@@ -31,6 +34,9 @@ import 'will_pop_scope.dart';
 ///       crossAxisAlignment: CrossAxisAlignment.start,
 ///       children: <Widget>[
 ///         TextFormField(
+///           decoration: const InputDecoration(
+///             hintText: 'Enter your email',
+///           ),
 ///           validator: (value) {
 ///             if (value.isEmpty) {
 ///               return 'Please enter some text';

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

@@ -126,19 +126,41 @@ class GestureRecognizerFactoryWithHandlers<T extends GestureRecognizer> extends
 /// effects. The [InkWell] class implements this effect and can be used in place
 /// of a [GestureDetector] for handling taps.
 ///
+/// {@animation 200 150 https://flutter.github.io/assets-for-api-docs/assets/widgets/gesture_detector.mp4}
+///
 /// {@tool sample}
 ///
-/// This example makes a rectangle react to being tapped by setting the
-/// `_lights` field:
+/// This example turns the light bulb yellow when the "turn lights on" button is
+/// tapped by setting the `_lights` field:
 ///
 /// ```dart
-/// GestureDetector(
-///   onTap: () {
-///     setState(() { _lights = true; });
-///   },
-///   child: Container(
-///     color: Colors.yellow,
-///     child: Text('TURN LIGHTS ON'),
+/// Container(
+///   alignment: FractionalOffset.center,
+///   color: Colors.white,
+///   child: Column(
+///     mainAxisAlignment: MainAxisAlignment.center,
+///     children: <Widget>[
+///       Padding(
+///         padding: const EdgeInsets.all(8.0),
+///         child: Icon(
+///           Icons.lightbulb_outline,
+///           color: _lights ? Colors.yellow.shade600 : Colors.black,
+///           size: 60,
+///         ),
+///       ),
+///       GestureDetector(
+///         onTap: () {
+///           setState(() {
+///             _lights = true;
+///           });
+///         },
+///         child: Container(
+///           color: Colors.yellow.shade600,
+///           padding: const EdgeInsets.all(8),
+///           child: const Text('TURN LIGHTS ON'),
+///         ),
+///       ),
+///     ],
 ///   ),
 /// )
 /// ```

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

@@ -1290,7 +1290,7 @@ class ListView extends BoxScrollView {
 /// children are spaced apart using the [crossAxisSpacing] and [mainAxisSpacing]
 /// properties.
 ///
-/// ![A screenshot of a GridView](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view.png)
+/// ![The GridView displays six children with different background colors arranged in two columns](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view.png)
 ///
 /// ```dart
 /// GridView.count(
@@ -1339,7 +1339,7 @@ class ListView extends BoxScrollView {
 /// This example shows how to create the same grid as the previous example
 /// using a [CustomScrollView] and a [SliverGrid].
 ///
-/// ![A screenshot of a CustomScrollView with a SliverGrid](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view_custom_scroll.png)
+/// ![The CustomScrollView contains a SliverGrid that displays six children with different background colors arranged in two columns](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view_custom_scroll.png)
 ///
 /// ```dart
 /// CustomScrollView(

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

@@ -204,12 +204,12 @@ class DefaultTextStyle extends InheritedTheme {
 ///
 /// {@tool sample}
 ///
-/// This example shows how to display text using the [Text] widget. If the text
-/// overflows, it truncates the text with an ellipsis.
+/// This example shows how to display text using the [Text] widget with the
+/// [overflow] set to [TextOverflow.ellipsis].
 ///
-/// ![A screenshot of the Text widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/text.png)
+/// ![If the text is shorter than the available space, it is displayed in full without an ellipsis.](https://flutter.github.io/assets-for-api-docs/assets/widgets/text.png)
 ///
-/// ![A screenshot of the Text widget displaying an ellipsis to trim the overflowing text](https://flutter.github.io/assets-for-api-docs/assets/widgets/text_ellipsis.png)
+/// ![If the text overflows, the Text widget displays an ellipsis to trim the overflowing text](https://flutter.github.io/assets-for-api-docs/assets/widgets/text_ellipsis.png)
 ///
 /// ```dart
 /// Text(
@@ -228,7 +228,7 @@ class DefaultTextStyle extends InheritedTheme {
 ///
 /// {@tool sample}
 ///
-/// ![A screenshot of the following rich text example](https://flutter.github.io/assets-for-api-docs/assets/widgets/text_rich.png)
+/// ![The word "Hello" is shown with the default text styles. The word "beautiful" is italicized. The word "world" is bold.](https://flutter.github.io/assets-for-api-docs/assets/widgets/text_rich.png)
 ///
 /// ```dart
 /// const Text.rich(