Convert existing '## Sample code' samples to '{@tool sample}...{@end-tool}' form. (#24077)

This converts existing ## Sample code samples to {@tool sample}...{@end-tool} form.

Also:
1. Fixed a minor bug in analyze-sample-code.dart
2. Made the snippet tool only insert descriptions if the description is non-empty.
3. Moved the Card diagram to before the code sample.

dev/bots/analyze-sample-code.dart

@@ -715,7 +715,7 @@ class Line {
   final String code;
 
   String toStringWithColumn(int column) {
-    if (column != null) {
+    if (column != null && indent != null) {
       return '$filename:$line:${column + indent}: $code';
     }
     return toString();

dev/snippets/config/skeletons/application.html

@@ -5,11 +5,7 @@
 </div>
 <div class="snippet-container">
   <div class="snippet" id="shortSnippet">
-    <div class="snippet-description">
-      {@end-inject-html}
     {{description}}
-      {@inject-html}
-    </div>
     <div class="copyable-container">
       <button class="copy-button-overlay copy-button" title="Copy to clipboard"
               onclick="copyTextToClipboard();">

dev/snippets/config/skeletons/sample.html

@@ -3,10 +3,7 @@
   <button id="shortSnippetButton" selected>Sample</button>
 </div>
 <div class="snippet-container">
-  <div class="snippet">
-    <div class="snippet-description">{@end-inject-html}
-{{description}}{@inject-html}
-    </div>
+  <div class="snippet">{{description}}
     <div class="copyable-container">
       <button class="copy-button-overlay copy-button" title="Copy to clipboard"
               onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">

dev/snippets/config/templates/stateless_widget.tmpl

@@ -25,6 +25,6 @@ class MyStatelessWidget extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return {{code}}
+    return {{code}};
   }
 }

dev/snippets/lib/snippets.dart

@@ -113,10 +113,15 @@ class SnippetGenerator {
     if (result.length > 3) {
       result.removeRange(result.length - 3, result.length);
     }
+    // Only insert a div for the description if there actually is some text there.
+    // This means that the {{description}} marker in the skeleton needs to
+    // be inside of an {@inject-html} block.
+    String description = injections.firstWhere((_ComponentTuple tuple) => tuple.name == 'description').mergedContent;
+    description = description.trim().isNotEmpty
+        ? '<div class="snippet-description">{@end-inject-html}$description{@inject-html}</div>'
+        : '';
     final Map<String, String> substitutions = <String, String>{
-      'description': injections
-          .firstWhere((_ComponentTuple tuple) => tuple.name == 'description')
-          .mergedContent,
+      'description': description,
       'code': htmlEscape.convert(result.join('\n')),
       'language': language ?? 'dart',
     }..addAll(type == SnippetType.application

dev/snippets/test/snippets_test.dart

@@ -106,7 +106,9 @@ void main() {
       expect(html, contains('<div>HTML Bits</div>'));
       expect(html, contains('<div>More HTML Bits</div>'));
       expect(html, contains('  print(&#39;The actual \$name.&#39;);'));
-      expect(html, contains('A description of the snippet.\n\nOn several lines.\n'));
+      expect(html, contains('<div class="snippet-description">'
+          '{@end-inject-html}A description of the snippet.\n\n'
+          'On several lines.{@inject-html}</div>\n'));
       expect(html, contains('main() {'));
     });
   });

packages/flutter/lib/src/animation/animation.dart

@@ -101,7 +101,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   /// argument to the method (`child`), whose value is derived by applying the
   /// given [Tween] to the value of this [Animation].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// Given an [AnimationController] `_controller`, the following code creates
   /// an `Animation<Alignment>` that swings from top left to top right as the
@@ -115,6 +115,8 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   ///   ),
   /// );
   /// ```
+  /// {@end-tool}
+  /// {@tool sample}
   ///
   /// The `_alignment.value` could then be used in a widget's build method, for
   /// instance, to position a child using an [Align] widget such that the
@@ -133,6 +135,8 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   /// // ...
   /// Animation<Alignment> _alignment2 = _controller.drive(_tween);
   /// ```
+  /// {@end-tool}
+  /// {@tool sample}
   ///
   /// The following code is exactly equivalent, and is typically clearer when
   /// the tweens are created inline, as might be preferred when the tweens have
@@ -146,6 +150,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   ///     end: Alignment.topRight,
   ///   ));
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

packages/flutter/lib/src/animation/animation_controller.dart

@@ -123,7 +123,7 @@ enum AnimationBehavior {
 /// This can be used to write code such as the `fadeOutAndUpdateState` method
 /// below.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Here is a stateful [Foo] widget. Its [State] uses the
 /// [SingleTickerProviderStateMixin] to implement the necessary
@@ -172,6 +172,8 @@ enum AnimationBehavior {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// The following method (for a [State] subclass) drives two animation
 /// controllers using Dart's asynchronous syntax for awaiting [Future] objects:
@@ -189,6 +191,7 @@ enum AnimationBehavior {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// The assumption in the code above is that the animation controllers are being
 /// disposed in the [State] subclass' override of the [State.dispose] method.

packages/flutter/lib/src/animation/animations.dart

@@ -328,7 +328,7 @@ class ReverseAnimation extends Animation<double>
 ///
 /// If you want to apply a [Curve] to a [Tween], consider using [CurveTween].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following code snippet shows how you can apply a curve to a linear
 /// animation produced by an [AnimationController] `controller`.
@@ -339,6 +339,8 @@ class ReverseAnimation extends Animation<double>
 ///   curve: Curves.ease,
 /// );
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// This second code snippet shows how to apply a different curve in the forward
 /// direction than in the reverse direction. This can't be done using a
@@ -352,6 +354,7 @@ class ReverseAnimation extends Animation<double>
 ///   reverseCurve: Curves.easeOut,
 /// );
 /// ```
+/// {@end-tool}
 ///
 /// By default, the [reverseCurve] matches the forward [curve].
 ///

packages/flutter/lib/src/animation/tween.dart

@@ -128,7 +128,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 /// which results in two separate [Animation] objects, each configured with a
 /// single [Tween].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Suppose `_controller` is an [AnimationController], and we want to create an
 /// [Animation<Offset>] that is controlled by that controller, and save it in
@@ -142,6 +142,8 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 ///   ),
 /// );
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// ```dart
 /// _animation = Tween<Offset>(
@@ -149,6 +151,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 ///   end: const Offset(200.0, 300.0),
 /// ).animate(_controller);
 /// ```
+/// {@end-tool}
 ///
 /// In both cases, the `_animation` variable holds an object that, over the
 /// lifetime of the `_controller`'s animation, returns a value
@@ -408,7 +411,7 @@ class ConstantTween<T> extends Tween<T> {
 /// curves when the animation is going forward vs when it is going backward,
 /// which can be useful in some scenarios.)
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following code snippet shows how you can apply a curve to a linear
 /// animation produced by an [AnimationController] `controller`:
@@ -418,6 +421,7 @@ class ConstantTween<T> extends Tween<T> {
 ///   CurveTween(curve: Curves.ease),
 /// );
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

packages/flutter/lib/src/animation/tween_sequence.dart

@@ -98,7 +98,7 @@ class TweenSequenceItem<T> {
   /// animation's duration indicated by [weight] and this item's position
   /// in the list of items.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The value of this item can be "curved" by chaining it to a [CurveTween].
   /// For example to create a tween that eases from 0.0 to 10.0:
@@ -107,6 +107,7 @@ class TweenSequenceItem<T> {
   /// Tween<double>(begin: 0.0, end: 10.0)
   ///   .chain(CurveTween(curve: Curves.ease))
   /// ```
+  /// {@end-tool}
   final Animatable<T> tween;
 
   /// An abitrary value that indicates the relative percentage of a

packages/flutter/lib/src/cupertino/segmented_control.dart

@@ -125,7 +125,7 @@ class CupertinoSegmentedControl<T> extends StatefulWidget {
   /// the parent [StatefulWidget] using the [State.setState] method, so that
   /// the parent gets rebuilt; for example:
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class SegmentedControlExample extends StatefulWidget {
@@ -157,6 +157,7 @@ class CupertinoSegmentedControl<T> extends StatefulWidget {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   final ValueChanged<T> onValueChanged;
 
   /// The color used to fill the backgrounds of unselected widgets and as the

packages/flutter/lib/src/cupertino/slider.dart

@@ -114,7 +114,7 @@ class CupertinoSlider extends StatefulWidget {
   /// The value passed will be the last [value] that the slider had before the
   /// change began.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// CupertinoSlider(
@@ -132,6 +132,7 @@ class CupertinoSlider extends StatefulWidget {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -145,7 +146,7 @@ class CupertinoSlider extends StatefulWidget {
   /// [onChanged] for that), but rather to know when the user has completed
   /// selecting a new [value] by ending a drag.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// CupertinoSlider(
@@ -163,6 +164,7 @@ class CupertinoSlider extends StatefulWidget {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

packages/flutter/lib/src/cupertino/switch.dart

@@ -26,7 +26,7 @@ import 'thumb_painter.dart';
 /// that use a switch will listen for the [onChanged] callback and rebuild the
 /// switch with a new [value] to update the visual appearance of the switch.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample shows how to use a [CupertinoSwitch] in a [ListTile]. The
 /// [MergeSemantics] is used to turn the entire [ListTile] into a single item
@@ -44,6 +44,7 @@ import 'thumb_painter.dart';
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

packages/flutter/lib/src/cupertino/tab_scaffold.dart

@@ -22,7 +22,7 @@ import 'bottom_tab_bar.dart';
 /// Use [CupertinoTabView] as the content of each tab to support tabs with parallel
 /// navigation state and history.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// A sample code implementing a typical iOS information architecture with tabs.
 ///
@@ -70,6 +70,7 @@ import 'bottom_tab_bar.dart';
 ///   },
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// To push a route above all tabs instead of inside the currently selected one
 /// (such as when showing a dialog on top of this scaffold), use

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

@@ -85,7 +85,7 @@ enum OverlayVisibilityMode {
 /// [controller]. For example, to set the initial value of the text field, use
 /// a [controller] that already contains some text such as:
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class MyPrefilledText extends StatefulWidget {
@@ -108,6 +108,7 @@ enum OverlayVisibilityMode {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// The [controller] can also control the selection and composing region (and to
 /// observe changes to the text, selection, and composing region).

packages/flutter/lib/src/foundation/annotations.dart

@@ -16,7 +16,7 @@
 ///
 /// A class can have multiple categories.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// /// A copper coffee pot, as desired by Ben Turpin.
@@ -29,6 +29,7 @@
 ///   // ...code...
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -53,7 +54,7 @@ class Category {
 ///
 /// Each class should only have one [DocumentationIcon].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// /// Utility class for beginning a dream-sharing sequence.
@@ -64,6 +65,7 @@ class Category {
 ///   // ...code...
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -85,7 +87,7 @@ class DocumentationIcon {
 /// for this purpose, but on occasion the first paragraph is either too short
 /// or too long for use in isolation, without the remainder of the documentation.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// /// A famous cat.
@@ -100,6 +102,7 @@ class DocumentationIcon {
 ///   // ...code...
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -1012,7 +1012,7 @@ abstract class DiagnosticsNode {
 
 /// Debugging message displayed like a property.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following two properties are better expressed using this
 /// [MessageProperty] class, rather than [StringProperty], as the intent is to
@@ -1020,18 +1020,19 @@ abstract class DiagnosticsNode {
 /// of an actual property of the object:
 ///
 /// ```dart
-/// MessageProperty('table size', '$columns\u00D7$rows')
-/// ```
-/// ```dart
-/// MessageProperty('usefulness ratio', 'no metrics collected yet (never painted)')
+/// var table = MessageProperty('table size', '$columns\u00D7$rows');
+/// var usefulness = MessageProperty('usefulness ratio', 'no metrics collected yet (never painted)');
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// On the other hand, [StringProperty] is better suited when the property has a
 /// concrete value that is a string:
 ///
 /// ```dart
-/// StringProperty('name', _name)
+/// var name = StringProperty('name', _name);
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -1324,7 +1325,7 @@ class PercentProperty extends DoubleProperty {
 /// when `visible` is false and nothing when visible is true, in contrast to
 /// `visible: true` or `visible: false`.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// FlagProperty(
@@ -1333,6 +1334,8 @@ class PercentProperty extends DoubleProperty {
 ///   ifFalse: 'hidden',
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// [FlagProperty] should also be used instead of [DiagnosticsProperty<bool>]
 /// if showing the bool value would not clearly indicate the meaning of the
@@ -1346,6 +1349,7 @@ class PercentProperty extends DoubleProperty {
 ///   ifFalse: '<no style specified>',
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -2044,7 +2048,7 @@ String describeIdentity(Object object) => '${object.runtimeType}#${shortHash(obj
 ///
 /// Strips off the enum class name from the `enumEntry.toString()`.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// enum Day {
@@ -2056,6 +2060,7 @@ String describeIdentity(Object object) => '${object.runtimeType}#${shortHash(obj
 ///   assert(describeEnum(Day.monday) == 'monday');
 /// }
 /// ```
+/// {@end-tool}
 String describeEnum(Object enumEntry) {
   final String description = enumEntry.toString();
   final int indexOfDot = description.indexOf('.');
@@ -2214,7 +2219,7 @@ abstract class Diagnosticable {
   /// `toString` method implementation works fine using [DiagnosticsProperty]
   /// directly.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// This example shows best practices for implementing [debugFillProperties]
   /// illustrating use of all common [DiagnosticsProperty] subclasses and all
@@ -2343,6 +2348,7 @@ abstract class Diagnosticable {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// Used by [toDiagnosticsNode] and [toString].
   @protected

packages/flutter/lib/src/foundation/licenses.dart

@@ -63,7 +63,7 @@ enum _LicenseEntryWithLineBreaksParserState {
 /// unless they start with the same number of spaces as the previous line, in
 /// which case it's assumed they are a continuation of an indented paragraph.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// For example, the BSD license in this format could be encoded as follows:
 ///
@@ -101,6 +101,7 @@ enum _LicenseEntryWithLineBreaksParserState {
 ///   });
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// This would result in a license with six [paragraphs], the third, fourth, and
 /// fifth being indented one level.

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

@@ -16,7 +16,7 @@ part of material_animated_icons;
 ///
 /// The available icons are specified in [AnimatedIcons].
 ///
-/// ### Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// AnimatedIcon(
@@ -25,6 +25,7 @@ part of material_animated_icons;
 ///   semanticLabel: 'Show menu',
 /// )
 /// ```
+/// {@end-tool}
 ///
 class AnimatedIcon extends StatelessWidget {
 

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

@@ -89,7 +89,7 @@ class _ToolbarContainerLayout extends SingleChildLayoutDelegate {
 /// to false. In that case a null leading widget will result in the middle/title widget
 /// stretching to start.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// AppBar(
@@ -113,6 +113,7 @@ class _ToolbarContainerLayout extends SingleChildLayoutDelegate {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -169,7 +170,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   /// there's no [Drawer] and the parent [Navigator] can go back, the [AppBar]
   /// will use a [BackButton] that calls [Navigator.maybePop].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The following code shows how the drawer button could be manually specified
   /// instead of relying on [automaticallyImplyLeading]:
@@ -187,6 +188,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   ///   ),
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// The [Builder] is used in this example to ensure that the `context` refers
   /// to that part of the subtree. That way this code snippet can be used even
@@ -237,7 +239,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   ///       ),
   ///     ],
   ///   ),
-  /// );
+  /// )
   /// ```
   /// {@end-tool}
   final List<Widget> actions;
@@ -722,7 +724,7 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
 /// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is
 /// specified then it is stacked behind the toolbar and the bottom widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This is an example that could be included in a [CustomScrollView]'s
 /// [CustomScrollView.slivers] list:
@@ -742,6 +744,7 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
 ///   ]
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -820,7 +823,7 @@ class SliverAppBar extends StatefulWidget {
   /// For less common operations, consider using a [PopupMenuButton] as the
   /// last action.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Scaffold(
@@ -844,6 +847,7 @@ class SliverAppBar extends StatefulWidget {
   ///   ),
   /// )
   /// ```
+  /// {@end-tool}
   final List<Widget> actions;
 
   /// This widget is stacked behind the toolbar and the tabbar. It's height will

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

@@ -19,8 +19,7 @@ import 'theme.dart';
 ///
 /// Typically used with a [Scaffold] and a [FloatingActionButton].
 ///
-/// ## Sample code
-///
+/// {@tool sample}
 /// ```dart
 /// Scaffold(
 ///   bottomNavigationBar: BottomAppBar(
@@ -30,6 +29,7 @@ import 'theme.dart';
 ///   floatingActionButton: FloatingActionButton(onPressed: null),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -12,13 +12,20 @@ import 'theme.dart';
 /// A card is a sheet of [Material] used to represent some related information,
 /// for example an album, a geographical location, a meal, contact details, etc.
 ///
+/// This is what it looks like when run:
+///
+/// ![A card with a slight shadow, consisting of two rows, one with an icon and
+/// some text describing a musical, and the other with buttons for buying
+/// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png)
+///
 /// {@tool snippet --template=stateless_widget}
 ///
 /// This sample shows creation of a [Card] widget that shows album information
 /// and two actions.
 ///
 /// ```dart
-/// Card(
+/// Center(
+///   child: Card(
 ///     child: Column(
 ///       mainAxisSize: MainAxisSize.min,
 ///       children: <Widget>[
@@ -43,16 +50,11 @@ import 'theme.dart';
 ///         ),
 ///       ],
 ///     ),
-/// );
+///   ),
+/// )
 /// ```
 /// {@end-tool}
 ///
-/// This is what it looks like when run:
-///
-/// ![A card with a slight shadow, consisting of two rows, one with an icon and
-/// some text describing a musical, and the other with buttons for buying
-/// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png)
-///
 /// See also:
 ///
 ///  * [ListTile], to display icons and text in a card.

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

@@ -37,11 +37,14 @@ import 'theme_data.dart';
 /// To show the [CheckboxListTile] as disabled, pass null as the [onChanged]
 /// callback.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This widget shows a checkbox that, when checked, slows down all animations
 /// (including the animation of the checkbox itself getting checked!).
 ///
+/// This sample requires that you also import 'package:flutter/scheduler.dart',
+/// so that you can reference [timeDilation].
+///
 /// ```dart
 /// CheckboxListTile(
 ///   title: const Text('Animate Slowly'),
@@ -52,9 +55,7 @@ import 'theme_data.dart';
 ///   secondary: const Icon(Icons.hourglass_empty),
 /// )
 /// ```
-///
-/// This sample requires that you also import 'package:flutter/scheduler.dart',
-/// so that you can reference [timeDilation].
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -377,7 +377,7 @@ abstract class TappableChipAttributes {
   /// taps on the label or avatar parts of the chip. If [onPressed] is null,
   /// then the chip will be disabled.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class Blacksmith extends StatelessWidget {
@@ -394,6 +394,7 @@ abstract class TappableChipAttributes {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   VoidCallback get onPressed;
 
   /// Elevation to be applied on the chip during the press motion.
@@ -418,7 +419,7 @@ abstract class TappableChipAttributes {
 /// Requires one of its ancestors to be a [Material] widget. The [label]
 /// and [clipBehavior] arguments must not be null.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// Chip(
@@ -429,6 +430,7 @@ abstract class TappableChipAttributes {
 ///   label: Text('Aaron Burr'),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -534,7 +536,7 @@ class Chip extends StatelessWidget implements ChipAttributes, DeletableChipAttri
 ///  * In a horizontally scrollable list, like a [ListView] whose
 ///    scrollDirection is [Axis.horizontal].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// InputChip(
@@ -548,6 +550,7 @@ class Chip extends StatelessWidget implements ChipAttributes, DeletableChipAttri
 ///   }
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -684,7 +687,7 @@ class InputChip extends StatelessWidget
 /// Requires one of its ancestors to be a [Material] widget. The [selected] and
 /// [label] arguments must not be null.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class MyThreeOptions extends StatefulWidget {
@@ -716,6 +719,7 @@ class InputChip extends StatelessWidget
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -830,7 +834,7 @@ class ChoiceChip extends StatelessWidget
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class ActorFilterEntry {
@@ -891,6 +895,7 @@ class ChoiceChip extends StatelessWidget
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -1012,7 +1017,7 @@ class FilterChip extends StatelessWidget
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// ActionChip(
@@ -1026,6 +1031,7 @@ class FilterChip extends StatelessWidget
 ///   }
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -60,7 +60,7 @@ class ChipTheme extends InheritedWidget {
   /// Defaults to the ambient [ThemeData.chipTheme] if there is no
   /// [ChipTheme] in the given build context.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class Spaceship extends StatelessWidget {
@@ -76,6 +76,7 @@ class ChipTheme extends InheritedWidget {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -111,7 +112,7 @@ class ChipTheme extends InheritedWidget {
 /// you get from [ChipTheme.of], or create an entirely new one with
 /// [ChipThemeData..fromDefaults].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class CarColor extends StatefulWidget {
@@ -139,6 +140,7 @@ class ChipTheme extends InheritedWidget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -17,7 +17,7 @@ import 'theme_data.dart';
 /// such an image, the user's initials. A given user's initials should
 /// always be paired with the same background color, for consistency.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// If the avatar is to have an image, the image should be specified in the
 /// [backgroundImage] property:
@@ -27,9 +27,12 @@ import 'theme_data.dart';
 ///   backgroundImage: NetworkImage(userAvatarUrl),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// The image will be cropped to have a circle shape.
 ///
+/// {@tool sample}
+///
 /// If the avatar is to just have the user's initials, they are typically
 /// provided using a [Text] widget as the [child] and a [backgroundColor]:
 ///
@@ -39,6 +42,7 @@ import 'theme_data.dart';
 ///   child: Text('AH'),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -133,7 +133,7 @@ class Dialog extends StatelessWidget {
 /// Typically passed as the child widget to [showDialog], which displays the
 /// dialog.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This snippet shows a method in a [State] which, when called, displays a dialog box
 /// and returns a [Future] that completes when the dialog is dismissed.
@@ -167,6 +167,7 @@ class Dialog extends StatelessWidget {
 ///   );
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -334,7 +335,7 @@ class AlertDialog extends StatelessWidget {
 /// title and the first option, and 24 pixels of spacing between the last option
 /// and the bottom of the dialog.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// SimpleDialogOption(
@@ -342,6 +343,7 @@ class AlertDialog extends StatelessWidget {
 ///   child: const Text('Treasury department'),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -398,7 +400,7 @@ class SimpleDialogOption extends StatelessWidget {
 /// Typically passed as the child widget to [showDialog], which displays the
 /// dialog.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// In this example, the user is asked to select between two options. These
 /// options are represented as an enum. The [showDialog] method here returns
@@ -441,6 +443,7 @@ class SimpleDialogOption extends StatelessWidget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -58,13 +58,14 @@ class Divider extends StatelessWidget {
   /// Defaults to the current theme's divider color, given by
   /// [ThemeData.dividerColor].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Divider(
   ///   color: Colors.deepOrange,
   /// )
   /// ```
+  /// {@end-tool}
   final Color color;
 
   /// Computes the [BorderSide] that represents a divider of the specified
@@ -74,7 +75,7 @@ class Divider extends StatelessWidget {
   /// The `width` argument can be used to override the default width of the
   /// divider border, which is usually 0.0 (a hairline border).
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// This example uses this method to create a box that has a divider above and
   /// below it. This is sometimes useful with lists, for instance, to separate a
@@ -91,6 +92,7 @@ class Divider extends StatelessWidget {
   ///   // child: ...
   /// )
   /// ```
+  /// {@end-tool}
   static BorderSide createBorderSide(BuildContext context, { Color color, double width = 0.0 }) {
     assert(width != null);
     return BorderSide(
@@ -164,13 +166,14 @@ class VerticalDivider extends StatelessWidget {
   /// Defaults to the current theme's divider color, given by
   /// [ThemeData.dividerColor].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Divider(
   ///   color: Colors.deepOrange,
   /// )
   /// ```
+  /// {@end-tool}
   final Color color;
 
   @override

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

@@ -28,7 +28,7 @@ import 'theme.dart';
 /// [StatelessWidget.build] method or from a [State]'s methods as you have to
 /// provide a [BuildContext].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// To trigger platform-specific feedback before executing the actual callback:
 ///
@@ -52,6 +52,8 @@ import 'theme.dart';
 ///   }
 /// }
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// Alternatively, you can also call [forTap] or [forLongPress] directly within
 /// your tap or long press handler:
@@ -76,6 +78,7 @@ import 'theme.dart';
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 class Feedback {
   Feedback._();
 

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

@@ -44,7 +44,7 @@ import 'material.dart';
 /// generally speaking will match the order they are given in the widget tree,
 /// but this order may appear to be somewhat random in more dynamic situations.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows how a [Material] widget can have a yellow rectangle drawn
 /// on it using [Ink], while still having ink effects over the yellow rectangle:
@@ -67,6 +67,8 @@ import 'material.dart';
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// The following example shows how an image can be printed on a [Material]
 /// widget with an [InkWell] above it:
@@ -94,6 +96,7 @@ import 'material.dart';
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -170,7 +170,7 @@ enum ListTileControlAffinity {
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Here is a simple tile with an icon and some text.
 ///
@@ -180,6 +180,8 @@ enum ListTileControlAffinity {
 ///   title: const Text('The seat for the narrator'),
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// Tiles can be much more elaborate. Here is a tile which can be tapped, but
 /// which is disabled when the `_act` variable is not 2. When the tile is
@@ -196,6 +198,7 @@ enum ListTileControlAffinity {
 ///   onTap: () { /* react to the tile being tapped */ }
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -135,7 +135,7 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
 /// [PopupMenuItem] is 48 pixels high. If you use a widget with a different
 /// height, it must be specified in the [height] property.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Here, a [Text] widget is used with a popup menu item. The `WhyFarther` type
 /// is an enum, not shown here.
@@ -146,6 +146,7 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
 ///   child: Text('Working a lot harder'),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See the example at [PopupMenuButton] for how this example could be used in a
 /// complete menu, and see the example at [CheckedPopupMenuItem] for one way to
@@ -286,7 +287,7 @@ class PopupMenuItemState<T, W extends PopupMenuItem<T>> extends State<W> {
 /// of a [PopupMenuItem]. The horizontal layout uses a [ListTile]; the checkmark
 /// is an [Icons.done] icon, shown in the [ListTile.leading] position.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Suppose a `Commands` enum exists that lists the possible commands from a
 /// particular popup menu, including `Commands.heroAndScholar` and
@@ -324,6 +325,7 @@ class PopupMenuItemState<T, W extends PopupMenuItem<T>> extends State<W> {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// In particular, observe how the second menu item uses a [ListTile] with a
 /// blank [Icon] in the [ListTile.leading] position to get the same alignment as
@@ -770,7 +772,7 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
 /// If both are null, then a standard overflow icon is created (depending on the
 /// platform).
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows a menu with four items, selecting between an enum's
 /// values and setting a `_selection` field based on the selection.
@@ -803,6 +805,7 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -40,7 +40,7 @@ import 'theme_data.dart';
 /// To show the [RadioListTile] as disabled, pass null as the [onChanged]
 /// callback.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This widget shows a pair of radio buttons that control the `_character`
 /// field. The field is of the type `SingingCharacter`, an enum.
@@ -70,6 +70,7 @@ import 'theme_data.dart';
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -25,9 +25,7 @@ import 'material_localizations.dart';
 /// [ReorderableListView] will need to account for this when inserting before
 /// [newIndex].
 ///
-/// ## Sample code
-///
-/// Example implementation:
+/// {@tool sample}
 ///
 /// ```dart
 /// final List<MyDataObject> backingList = <MyDataObject>[/* ... */];
@@ -41,6 +39,7 @@ import 'material_localizations.dart';
 ///   backingList.insert(newIndex, element);
 /// }
 /// ```
+/// {@end-tool}
 typedef ReorderCallback = void Function(int oldIndex, int newIndex);
 
 /// A list whose items the user can interactively reorder by dragging.

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

@@ -657,7 +657,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
 /// [ScaffoldState] for the current [BuildContext] via [Scaffold.of] and use the
 /// [ScaffoldState.showSnackBar] and [ScaffoldState.showBottomSheet] functions.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows a [Scaffold] with an [AppBar], a [BottomAppBar]
 /// and a [FloatingActionButton]. The [body] is a [Text] placed in a [Center]
@@ -684,6 +684,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
 ///   floatingActionButtonLocation: FloatingActionButtonLocation.centerDocked,
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -146,7 +146,7 @@ class Slider extends StatefulWidget {
   /// [StatefulWidget] using the [State.setState] method, so that the parent
   /// gets rebuilt; for example:
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Slider(
@@ -162,6 +162,7 @@ class Slider extends StatefulWidget {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -180,7 +181,7 @@ class Slider extends StatefulWidget {
   /// The value passed will be the last [value] that the slider had before the
   /// change began.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Slider(
@@ -199,6 +200,7 @@ class Slider extends StatefulWidget {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -212,7 +214,7 @@ class Slider extends StatefulWidget {
   /// [onChanged] for that), but rather to know when the user has completed
   /// selecting a new [value] by ending a drag or a click.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// Slider(
@@ -231,6 +233,7 @@ class Slider extends StatefulWidget {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -305,7 +308,7 @@ class Slider extends StatefulWidget {
   /// This is used by accessibility frameworks like TalkBack on Android to
   /// inform users what the currently selected value is with more context.
   ///
-  /// ## Sample code:
+  /// {@tool sample}
   ///
   /// In the example below, a slider for currency values is configured to
   /// announce a value with a currency label.
@@ -326,6 +329,7 @@ class Slider extends StatefulWidget {
   ///   }
   ///  )
   /// ```
+  /// {@end-tool}
   final SemanticFormatterCallback semanticFormatterCallback;
 
   @override

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

@@ -48,7 +48,7 @@ class SliderTheme extends InheritedWidget {
   /// Defaults to the ambient [ThemeData.sliderTheme] if there is no
   /// [SliderTheme] in the given build context.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class Launch extends StatefulWidget {
@@ -71,6 +71,7 @@ class SliderTheme extends InheritedWidget {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -155,7 +156,7 @@ class SliderThemeData extends Diagnosticable {
   /// [copyWith] on the one you get from [SliderTheme.of], or create an
   /// entirely new one with [SliderThemeData.fromPrimaryColors].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class Blissful extends StatefulWidget {
@@ -178,6 +179,7 @@ class SliderThemeData extends Diagnosticable {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   const SliderThemeData({
     @required this.activeTrackColor,
     @required this.inactiveTrackColor,

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

@@ -39,7 +39,7 @@ import 'theme_data.dart';
 /// To show the [SwitchListTile] as disabled, pass null as the [onChanged]
 /// callback.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This widget shows a switch that, when toggled, changes the state of a [bool]
 /// member field called `_lights`.
@@ -52,6 +52,7 @@ import 'theme_data.dart';
 ///   secondary: const Icon(Icons.lightbulb_outline),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -19,7 +19,7 @@ import 'constants.dart';
 /// ancestor, a [TabController] can be shared by providing a
 /// [DefaultTabController] inherited widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This widget introduces a [Scaffold] with an [AppBar] and a [TabBar].
 ///
@@ -69,6 +69,7 @@ import 'constants.dart';
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 class TabController extends ChangeNotifier {
   /// Creates an object that manages the state required by [TabBar] and a [TabBarView].
   ///

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

@@ -39,7 +39,7 @@ import 'theme.dart';
 ///  * [InputDecorator], which shows the labels and other visual elements that
 ///    surround the actual text editing widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Creates a [TextFormField] with an [InputDecoration] and validator function.
 ///
@@ -59,6 +59,7 @@ import 'theme.dart';
 ///   },
 /// )
 /// ```
+/// {@end-tool}
 class TextFormField extends FormField<String> {
   /// Creates a [FormField] that contains a [TextField].
   ///

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

@@ -176,7 +176,7 @@ class TextTheme extends Diagnosticable {
   /// the typography styles in the material design specification, as a starting
   /// point.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// /// A Widget that sets the ambient theme's title text color for its
@@ -203,6 +203,7 @@ class TextTheme extends Diagnosticable {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///
@@ -259,7 +260,7 @@ class TextTheme extends Diagnosticable {
   /// [TextTheme] has only some fields defined, and you want to define the rest
   /// by merging it with a default theme.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// /// A Widget that sets the ambient theme's title text color for its
@@ -284,6 +285,7 @@ class TextTheme extends Diagnosticable {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

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

@@ -29,13 +29,14 @@ enum DayPeriod {
 /// minute or using [DateTime] object.
 /// Hours are specified between 0 and 23, as in a 24-hour clock.
 ///
-/// ### Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// TimeOfDay now = TimeOfDay.now();
 /// TimeOfDay releaseTime = TimeOfDay(hour: 15, minute: 0); // 3:00pm
 /// TimeOfDay roomBooked = TimeOfDay.fromDateTime(DateTime.parse('2018-10-20 16:30:04Z')); // 4:30pm
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -26,7 +26,7 @@ enum BorderStyle {
 /// A [Border] consists of four [BorderSide] objects: [Border.top],
 /// [Border.left], [Border.right], and [Border.bottom].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample shows how [BorderSide] objects can be used in a [Container], via
 /// a [BoxDecoration] and a [Border], to decorate some [Text]. In this example,
@@ -45,6 +45,7 @@ enum BorderStyle {
 ///   child: Text('Flutter in the sky', textAlign: TextAlign.center),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -239,19 +239,23 @@ abstract class BoxBorder extends ShapeBorder {
 ///
 /// The sides are represented by [BorderSide] objects.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// All four borders the same, two-pixel wide solid white:
 ///
 /// ```dart
 /// Border.all(width: 2.0, color: const Color(0xFFFFFFFF))
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// The border for a material design divider:
 ///
 /// ```dart
 /// Border(bottom: BorderSide(color: Theme.of(context).dividerColor))
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// A 1990s-era "OK" button:
 ///
@@ -284,6 +288,7 @@ abstract class BoxBorder extends ShapeBorder {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -32,7 +32,7 @@ import 'image_provider.dart';
 ///
 /// The [border] paints over the body; the [boxShadow], naturally, paints below it.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following example uses the [Container] widget from the widgets layer to
 /// draw an image with a border:
@@ -52,6 +52,7 @@ import 'image_provider.dart';
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -102,7 +102,7 @@ class FittedSizes {
 /// convenience function, [Alignment.inscribe], for resolving the sizes to
 /// rects, as shown in the example below.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This function paints a [dart:ui.Image] `image` onto the [Rect] `outputRect` on a
 /// [Canvas] `canvas`, using a [Paint] `paint`, applying the [BoxFit] algorithm
@@ -117,6 +117,7 @@ class FittedSizes {
 ///   canvas.drawImageRect(image, inputSubrect, outputSubrect, paint);
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -282,7 +282,7 @@ abstract class EdgeInsetsGeometry {
 /// _start_, top, _end_, and bottom, where start and end are resolved in terms
 /// of a [TextDirection] (typically obtained from the ambient [Directionality]).
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Here are some examples of how to create [EdgeInsets] instances:
 ///
@@ -291,18 +291,23 @@ abstract class EdgeInsetsGeometry {
 /// ```dart
 /// const EdgeInsets.all(8.0)
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// Eight pixel margin above and below, no horizontal margins:
 ///
 /// ```dart
 /// const EdgeInsets.symmetric(vertical: 8.0)
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// Left margin indent of 40 pixels:
 ///
 /// ```dart
 /// const EdgeInsets.only(left: 40.0)
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -316,25 +321,27 @@ class EdgeInsets extends EdgeInsetsGeometry {
 
   /// Creates insets where all the offsets are `value`.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// Typical eight-pixel margin on all sides:
   ///
   /// ```dart
   /// const EdgeInsets.all(8.0)
   /// ```
+  /// {@end-tool}
   const EdgeInsets.all(double value)
       : left = value, top = value, right = value, bottom = value;
 
   /// Creates insets with only the given values non-zero.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// Left margin indent of 40 pixels:
   ///
   /// ```dart
   /// const EdgeInsets.only(left: 40.0)
   /// ```
+  /// {@end-tool}
   const EdgeInsets.only({
     this.left = 0.0,
     this.top = 0.0,
@@ -344,13 +351,14 @@ class EdgeInsets extends EdgeInsetsGeometry {
 
   /// Creates insets with symmetrical vertical and horizontal offsets.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// Eight pixel margin above and below, no horizontal margins:
   ///
   /// ```dart
   /// const EdgeInsets.symmetric(vertical: 8.0)
   /// ```
+  /// {@end-tool}
   const EdgeInsets.symmetric({ double vertical = 0.0,
                              double horizontal = 0.0 })
     : left = horizontal, top = vertical, right = horizontal, bottom = vertical;
@@ -600,13 +608,14 @@ class EdgeInsetsDirectional extends EdgeInsetsGeometry {
 
   /// Creates insets with only the given values non-zero.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// A margin indent of 40 pixels on the leading side:
   ///
   /// ```dart
   /// const EdgeInsetsDirectional.only(start: 40.0)
   /// ```
+  /// {@end-tool}
   const EdgeInsetsDirectional.only({
     this.start = 0.0,
     this.top = 0.0,

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

@@ -226,7 +226,7 @@ abstract class Gradient {
 /// Typically this class is used with [BoxDecoration], which does the painting.
 /// To use a [LinearGradient] to paint on a canvas directly, see [createShader].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample draws a picture that looks like vertical window shades by having
 /// a [Container] display a [BoxDecoration] with a [LinearGradient].
@@ -243,6 +243,7 @@ abstract class Gradient {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -460,7 +461,7 @@ class LinearGradient extends Gradient {
 /// Typically this class is used with [BoxDecoration], which does the painting.
 /// To use a [RadialGradient] to paint on a canvas directly, see [createShader].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This function draws a gradient that looks like a sun in a blue sky.
 ///
@@ -481,6 +482,7 @@ class LinearGradient extends Gradient {
 ///   canvas.drawRect(rect, paint);
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -718,7 +720,7 @@ class RadialGradient extends Gradient {
 /// Typically this class is used with [BoxDecoration], which does the painting.
 /// To use a [SweepGradient] to paint on a canvas directly, see [createShader].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample draws a different color in each quadrant.
 ///
@@ -741,6 +743,7 @@ class RadialGradient extends Gradient {
 ///   ),
 ///  )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -170,7 +170,7 @@ class ImageConfiguration {
 ///
 /// The following image formats are supported: {@macro flutter.dart:ui.imageFormats}
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following shows the code required to write a widget that fully conforms
 /// to the [ImageProvider] and [Widget] protocols. (It is essentially a
@@ -244,6 +244,7 @@ class ImageConfiguration {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 @optionalTypeArgs
 abstract class ImageProvider<T> {
   /// Abstract const constructor. This constructor enables subclasses to provide
@@ -299,7 +300,7 @@ abstract class ImageProvider<T> {
   /// The [configuration] is optional and defaults to
   /// [ImageConfiguration.empty].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The following sample code shows how an image loaded using the [Image]
   /// widget can be evicted using a [NetworkImage] with a matching url.
@@ -322,6 +323,7 @@ abstract class ImageProvider<T> {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   Future<bool> evict({ImageCache cache, ImageConfiguration configuration = ImageConfiguration.empty}) async {
     cache ??= imageCache;
     final T key = await obtainKey(configuration);

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

@@ -23,7 +23,7 @@ import 'rounded_rectangle_border.dart';
 /// optionally filling it with a color or a gradient, optionally painting an
 /// image into it, and optionally casting a shadow.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following example uses the [Container] widget from the widgets layer to
 /// draw a white rectangle with a 24-pixel multicolor outline, with the text
@@ -47,6 +47,7 @@ import 'rounded_rectangle_border.dart';
 ///   child: const Text('RGB', textAlign: TextAlign.center),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -27,7 +27,7 @@ import 'text_style.dart';
 /// span in a widget, use a [RichText]. For text with a single style, consider
 /// using the [Text] widget.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The text "Hello world!", in black:
 ///
@@ -37,6 +37,7 @@ import 'text_style.dart';
 ///   style: TextStyle(color: Colors.black),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// _There is some more detailed sample code in the documentation for the
 /// [recognizer] property._
@@ -93,7 +94,7 @@ class TextSpan extends DiagnosticableTree {
   /// The code that owns the [GestureRecognizer] object must call
   /// [GestureRecognizer.dispose] when the [TextSpan] object is no longer used.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// This example shows how to manage the lifetime of a gesture recognizer
   /// provided to a [TextSpan] object. It defines a `BuzzingText` widget which
@@ -152,6 +153,7 @@ class TextSpan extends DiagnosticableTree {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   final GestureRecognizer recognizer;
 
   /// Apply the [style], [text], and [children] of this object to the

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

@@ -18,7 +18,7 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
 
 /// An immutable style in which paint text.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ### Bold
 ///
@@ -32,6 +32,8 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
 ///   style: TextStyle(fontWeight: FontWeight.bold),
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// ### Italics
 ///
@@ -44,6 +46,7 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
 ///   style: TextStyle(fontStyle: FontStyle.italic),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// ### Opacity and Color
 ///

packages/flutter/lib/src/physics/gravity_simulation.dart

@@ -12,7 +12,7 @@ import 'simulation.dart';
 /// Models a particle that follows Newton's second law of motion. The simulation
 /// ends when the position reaches a defined point.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This method triggers an [AnimationController] (a previously constructed
 /// `_controller` field) to simulate a fall of 300 pixels.
@@ -27,6 +27,7 @@ import 'simulation.dart';
 ///   ));
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// This [AnimationController] could be used with an [AnimatedBuilder] to
 /// animate the position of a child as if it was falling.

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

@@ -45,7 +45,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentData<RenderBox> {
 /// identifies it to the delegate. The [LayoutId.id] needs to be unique among
 /// the children that the [CustomMultiChildLayout] manages.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// Below is an example implementation of [performLayout] that causes one widget
 /// (the follower) to be the same size as another (the leader):
@@ -80,6 +80,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentData<RenderBox> {
 ///   bool shouldRelayout(MultiChildLayoutDelegate oldDelegate) => false;
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// The delegate gives the leader widget loose constraints, which means the
 /// child determines what size to be (subject to fitting within the given size).

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

@@ -62,7 +62,7 @@ typedef SemanticsBuilderCallback = List<CustomPainterSemantics> Function(Size si
 /// class is provided, to check if the new instance contains different
 /// information that affects the semantics tree.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample extends the same code shown for [RadialGradient] to create a
 /// custom painter that paints a sky.
@@ -117,6 +117,7 @@ typedef SemanticsBuilderCallback = List<CustomPainterSemantics> Function(Size si
 ///   bool shouldRebuildSemantics(Sky oldDelegate) => false;
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -48,7 +48,7 @@ class _OverflowRegionData {
 /// overflows. It will print on the first occurrence, and once after each time that
 /// [reassemble] is called.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class MyRenderObject extends RenderAligningShiftedBox with DebugOverflowIndicatorMixin {
@@ -81,6 +81,7 @@ class _OverflowRegionData {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -2232,7 +2232,7 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
   /// asynchronous computation) will at best have no useful effect and at worse
   /// will cause crashes as the data will be in an inconsistent state.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The following snippet will describe the node as a button that responds to
   /// tap actions.
@@ -2253,6 +2253,7 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   @protected
   void describeSemanticsConfiguration(SemanticsConfiguration config) {
     // Nothing to do by default.

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

@@ -2572,7 +2572,7 @@ class RenderRepaintBoundary extends RenderProxyBox {
   /// will give you a 1:1 mapping between logical pixels and the output pixels
   /// in the image.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The following is an example of how to go from a `GlobalKey` on a
   /// `RepaintBoundary` to a PNG:
@@ -2610,6 +2610,7 @@ class RenderRepaintBoundary extends RenderProxyBox {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

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

@@ -135,12 +135,14 @@ class MethodChannel {
   /// * a [MissingPluginException], if the method has not been implemented by a
   ///   platform plugin.
   ///
-  /// ## Sample code
-  ///
   /// The following code snippets demonstrate how to invoke platform methods
   /// in Dart using a MethodChannel and how to implement those methods in Java
-  /// (for Android) and Objective-C (for iOS). The code might be packaged up as
-  /// a musical plugin, see <https://flutter.io/developing-packages/>:
+  /// (for Android) and Objective-C (for iOS).
+  ///
+  /// {@tool sample}
+  ///
+  /// The code might be packaged up as a musical plugin, see
+  /// <https://flutter.io/developing-packages/>:
   ///
   /// ```dart
   /// class Music {
@@ -188,6 +190,11 @@ class MethodChannel {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
+  ///
+  /// {@tool sample}
+  ///
+  /// Java (for Android):
   ///
   /// ```java
   /// // Assumes existence of an Android MusicApi.
@@ -223,8 +230,13 @@ class MethodChannel {
   ///   // Other methods elided.
   /// }
   /// ```
+  /// {@end-tool}
+  ///
+  /// {@tool sample}
+  ///
+  /// Objective-C (for iOS):
   ///
-  /// ```objective-c
+  /// ```objectivec
   /// @interface MusicPlugin : NSObject<FlutterPlugin>
   /// @end
   ///
@@ -259,6 +271,7 @@ class MethodChannel {
   /// // Other methods elided.
   /// @end
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

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

@@ -38,7 +38,7 @@ enum CrossFadeState {
 /// top child and the bottom child should be keyed using the provided
 /// `topChildKey` and `bottomChildKey` keys respectively.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// Widget defaultLayoutBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey) {
@@ -60,6 +60,7 @@ enum CrossFadeState {
 ///   );
 /// }
 /// ```
+/// {@end-tool}
 typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey);
 
 /// A widget that cross-fades between two given children and animates itself
@@ -81,7 +82,7 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild
 /// [AnimatedCrossFade] is rebuilt with a different value for the
 /// [crossFadeState] property.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This code fades between two representations of the Flutter logo. It depends
 /// on a boolean field `_first`; when `_first` is true, the first logo is shown,
@@ -97,6 +98,7 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild
 ///   crossFadeState: _first ? CrossFadeState.showFirst : CrossFadeState.showSecond,
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -87,7 +87,7 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis
 /// progress indicator and the image will be fading out while a new progress
 /// indicator is fading in.)
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class ClickCounter extends StatefulWidget {
@@ -136,6 +136,7 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -342,7 +342,7 @@ typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnaps
 /// * [StreamBuilderBase], which supports widget building based on a computation
 /// that spans all interactions made with the stream.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample shows a [StreamBuilder] configuring a text label to show the
 /// latest bid received for a lot in an auction. Assume the `_lot` field is
@@ -364,6 +364,7 @@ typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnaps
 ///   },
 /// )
 /// ```
+/// {@end-tool}
 // TODO(ianh): remove unreachable code above once https://github.com/dart-lang/linter/issues/1141 is fixed
 class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
   /// Creates a new [StreamBuilder] that builds itself based on the latest
@@ -473,7 +474,7 @@ 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.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample shows a [FutureBuilder] configuring a text label to show the
 /// state of an asynchronous calculation returning a string. Assume the
@@ -498,6 +499,7 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
 ///   },
 /// )
 /// ```
+/// {@end-tool}
 // TODO(ianh): remove unreachable code above once https://github.com/dart-lang/linter/issues/1141 is fixed
 class FutureBuilder<T> extends StatefulWidget {
   /// Creates a widget that builds itself based on the latest snapshot of

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

@@ -32,7 +32,7 @@ export 'dart:ui' show AppLifecycleState, Locale;
 /// handlers must be implemented (and the analyzer will list those that have
 /// been omitted).
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This [StatefulWidget] implements the parts of the [State] and
 /// [WidgetsBindingObserver] protocols necessary to react to application
@@ -72,6 +72,7 @@ export 'dart:ui' show AppLifecycleState, Locale;
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// To respond to other notifications, replace the [didChangeAppLifecycleState]
 /// method above with other methods from this class.
@@ -109,7 +110,7 @@ abstract class WidgetsBindingObserver {
   ///
   /// This method exposes notifications from [Window.onMetricsChanged].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// This [StatefulWidget] implements the parts of the [State] and
   /// [WidgetsBindingObserver] protocols necessary to react when the device is
@@ -149,6 +150,7 @@ abstract class WidgetsBindingObserver {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// In general, this is unnecessary as the layout system takes care of
   /// automatically recomputing the application geometry when the application
@@ -168,7 +170,7 @@ abstract class WidgetsBindingObserver {
   ///
   /// This method exposes notifications from [Window.onTextScaleFactorChanged].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// class TextScaleFactorReactor extends StatefulWidget {
@@ -204,6 +206,7 @@ abstract class WidgetsBindingObserver {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   ///
   /// See also:
   ///

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

@@ -20,7 +20,7 @@ import 'image.dart';
 ///
 /// Commonly used with [BoxDecoration].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample shows a radial gradient that draws a moon on a night sky:
 ///
@@ -39,6 +39,7 @@ import 'image.dart';
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -178,7 +179,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
 /// [padding] (e.g. borders in a [BoxDecoration] contribute to the [padding]);
 /// see [Decoration.padding].
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows a 48x48 green square (placed inside a [Center] widget in
 /// case the parent widget has its own opinions regarding the size that the
@@ -195,6 +196,8 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// This example shows how to use many of the features of [Container] at once.
 /// The [constraints] are set to fit the font size plus ample headroom
@@ -223,6 +226,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
 ///   transform: Matrix4.rotationZ(0.1),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -49,7 +49,7 @@ import 'ticker_provider.dart';
 /// different image. This is known as "gapless playback" (see also
 /// [Image.gaplessPlayback]).
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// FadeInImage(
@@ -58,6 +58,7 @@ import 'ticker_provider.dart';
 ///   image: NetworkImage('https://backend.example.com/image.png'),
 /// )
 /// ```
+/// {@end-tool}
 class FadeInImage extends StatefulWidget {
   /// Creates a widget that displays a [placeholder] while an [image] is loading
   /// then cross-fades to display the [image].

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

@@ -498,7 +498,7 @@ abstract class Widget extends DiagnosticableTree {
 ///    widget, so that only the inner-most widget needs to be rebuilt when the
 ///    theme changes.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following is a skeleton of a stateless widget subclass called `GreenFrog`:
 ///
@@ -512,6 +512,8 @@ abstract class Widget extends DiagnosticableTree {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// Normally widgets have more constructor arguments, each of which corresponds
 /// to a `final` property. The next example shows the more generic widget `Frog`
@@ -535,6 +537,7 @@ abstract class Widget extends DiagnosticableTree {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// By convention, widget constructors only use named arguments. Named arguments
 /// can be marked as required using [@required]. Also by convention, the first
@@ -705,7 +708,7 @@ abstract class StatelessWidget extends Widget {
 ///    [KeyedSubtree] widget may be useful for this purpose if no other widget
 ///    can conveniently be assigned the key.)
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following is a skeleton of a stateful widget subclass called `YellowBird`:
 ///
@@ -724,6 +727,8 @@ abstract class StatelessWidget extends Widget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// In this example. the [State] has no actual state. State is normally
 /// represented as private member fields. Also, normally widgets have more
@@ -765,6 +770,7 @@ abstract class StatelessWidget extends Widget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// By convention, widget constructors only use named arguments. Named arguments
 /// can be marked as required using [@required]. Also by convention, the first
@@ -1366,7 +1372,7 @@ abstract class ProxyWidget extends Widget {
 /// thus also to a particular [RenderObjectWidget] class. That class is `T`, the
 /// [ParentDataWidget] type argument.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows how you would build a [ParentDataWidget] to configure a
 /// `FrogJar` widget's children by specifying a [Size] for each one.
@@ -1394,6 +1400,7 @@ abstract class ProxyWidget extends Widget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -1496,7 +1503,7 @@ abstract class ParentDataWidget<T extends RenderObjectWidget> extends ProxyWidge
 /// Inherited widgets, when referenced in this way, will cause the consumer to
 /// rebuild when the inherited widget itself changes state.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// The following is a skeleton of an inherited widget called `FrogColor`:
 ///
@@ -1520,6 +1527,7 @@ abstract class ParentDataWidget<T extends RenderObjectWidget> extends ProxyWidge
 ///   bool updateShouldNotify(FrogColor old) => color != old.color;
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// The convention is to provide a static method `of` on the [InheritedWidget]
 /// which does the call to [BuildContext.inheritFromWidgetOfExactType]. This
@@ -1988,13 +1996,14 @@ abstract class BuildContext {
   /// an ancestor from one of those methods, save a reference to the ancestor
   /// by calling [ancestorStateOfType] in [State.didChangeDependencies].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// ```dart
   /// ScrollableState scrollable = context.ancestorStateOfType(
   ///   const TypeMatcher<ScrollableState>(),
   /// );
   /// ```
+  /// {@end-tool}
   State ancestorStateOfType(TypeMatcher matcher);
 
   /// Returns the [State] object of the furthest ancestor [StatefulWidget] widget

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

@@ -113,7 +113,7 @@ 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.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example makes a rectangle react to being tapped by setting the
 /// `_lights` field:
@@ -129,6 +129,7 @@ class GestureRecognizerFactoryWithHandlers<T extends GestureRecognizer> extends
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// ## Debugging
 ///
@@ -453,7 +454,7 @@ class GestureDetector extends StatelessWidget {
 /// Configuring the gesture recognizers requires a carefully constructed map, as
 /// described in [gestures] and as shown in the example below.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows how to hook up a [TapGestureRecognizer]. It assumes that
 /// the code is being used inside a [State] object with a `_last` field that is
@@ -476,6 +477,7 @@ class GestureDetector extends StatelessWidget {
 ///   child: Container(width: 300.0, height: 300.0, color: Colors.yellow, child: Text(_last)),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -298,7 +298,7 @@ class Image extends StatefulWidget {
   /// which corresponds to bilinear interpolation, rather than the default
   /// [FilterQuality.none] which corresponds to nearest-neighbor.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// Suppose that the project's `pubspec.yaml` file contains the following:
   ///
@@ -309,6 +309,7 @@ class Image extends StatefulWidget {
   ///     - images/2x/cat.png
   ///     - images/3.5x/cat.png
   /// ```
+  /// {@end-tool}
   ///
   /// On a screen with a device pixel ratio of 2.0, the following widget would
   /// render the `images/2x/cat.png` file:
@@ -336,11 +337,13 @@ class Image extends StatefulWidget {
   /// must be provided. For instance, suppose a package called `my_icons` has
   /// `icons/heart.png` .
   ///
+  /// {@tool sample}
   /// Then to display the image, use:
   ///
   /// ```dart
   /// Image.asset('icons/heart.png', package: 'my_icons')
   /// ```
+  /// {@end-tool}
   ///
   /// Assets used by the package itself should also be displayed using the
   /// [package] argument as above.

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

@@ -1018,7 +1018,7 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState<Animat
 /// of [Curves.fastOutSlowIn].
 /// {@animation 250 266 https://flutter.github.io/assets-for-api-docs/assets/widgets/animated_opacity.mp4}
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// class LogoFade extends StatefulWidget {
@@ -1052,6 +1052,7 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState<Animat
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -297,7 +297,7 @@ class _LocalizationsScope extends InheritedWidget {
 /// `Localizations.of(context)` will be rebuilt after the resources
 /// for the new locale have been loaded.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This following class is defined in terms of the
 /// [Dart `intl` package](https://github.com/dart-lang/intl). Using the `intl`
@@ -324,6 +324,7 @@ class _LocalizationsScope extends InheritedWidget {
 ///   // ... more Intl.message() methods like title()
 /// }
 /// ```
+/// {@end-tool}
 /// A class based on the `intl` package imports a generated message catalog that provides
 /// the `initializeMessages()` function and the per-locale backing store for `Intl.message()`.
 /// The message catalog is produced by an `intl` tool that analyzes the source code for

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

@@ -60,7 +60,7 @@ typedef NestedScrollViewHeaderSliversBuilder = List<Widget> Function(BuildContex
 /// (those inside the [TabBarView], hooking them together so that they appear,
 /// to the user, as one coherent scroll view.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example shows a [NestedScrollView] whose header is the combination of a
 /// [TabBar] in a [SliverAppBar] and whose body is a [TabBarView]. It uses a
@@ -174,6 +174,7 @@ typedef NestedScrollViewHeaderSliversBuilder = List<Widget> Function(BuildContex
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 class NestedScrollView extends StatefulWidget {
   /// Creates a nested scroll view.
   ///

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

@@ -325,7 +325,7 @@ mixin LocalHistoryRoute<T> on Route<T> {
   /// The given local history entry must not already be part of another local
   /// history route.
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// The following example is an app with 2 pages: `HomePage` and `SecondPage`.
   /// The `HomePage` can navigate to the `SecondPage`.
@@ -442,6 +442,7 @@ mixin LocalHistoryRoute<T> on Route<T> {
   ///   }
   /// }
   /// ```
+  /// {@end-tool}
   void addLocalHistoryEntry(LocalHistoryEntry entry) {
     assert(entry._owner == null);
     entry._owner = this;
@@ -1267,7 +1268,7 @@ abstract class PopupRoute<T> extends ModalRoute<T> {
 /// than only specific subtypes. For example, to watch for all [PageRoute]
 /// variants, the `RouteObserver<PageRoute<dynamic>>` type may be used.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// To make a [StatefulWidget] aware of its current [Route] state, implement
 /// [RouteAware] in its [State] and subscribe it to a [RouteObserver]:
@@ -1316,6 +1317,7 @@ abstract class PopupRoute<T> extends ModalRoute<T> {
 ///
 /// }
 /// ```
+/// {@end-tool}
 class RouteObserver<R extends Route<dynamic>> extends NavigatorObserver {
   final Map<R, Set<RouteAware>> _listeners = <R, Set<RouteAware>>{};
 

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

@@ -283,7 +283,7 @@ class ScrollController extends ChangeNotifier {
 /// It tracks the most recently updated scroll position and reports it as its
 /// `initialScrollOffset`.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// In this example each [PageView] page contains a [ListView] and all three
 /// [ListView]'s share a [TrackingScrollController]. The scroll offsets of all
@@ -308,6 +308,7 @@ class ScrollController extends ChangeNotifier {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// In this example the `_trackingController` would have been created by the
 /// stateful widget that built the widget tree.

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

@@ -284,7 +284,7 @@ abstract class ScrollView extends StatelessWidget {
 /// To control the initial scroll offset of the scroll view, provide a
 /// [controller] with its [ScrollController.initialScrollOffset] property set.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample code shows a scroll view that contains a flexible pinned app
 /// bar, a grid, and an infinite list.
@@ -332,6 +332,7 @@ abstract class ScrollView extends StatelessWidget {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// ## Accessibility
 ///
@@ -539,7 +540,7 @@ abstract class BoxScrollView extends ScrollView {
 /// extremities to avoid partial obstructions indicated by [MediaQuery]'s
 /// padding. To avoid this behavior, override with a zero [padding] property.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// An infinite list of children:
 ///
@@ -552,6 +553,7 @@ abstract class BoxScrollView extends ScrollView {
 ///   },
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// ## Child elements' lifecycle
 ///
@@ -648,7 +650,7 @@ abstract class BoxScrollView extends ScrollView {
 /// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
 /// list.
 ///
-/// ### Sample code
+/// {@tool sample}
 ///
 /// Here are two brief snippets showing a [ListView] and its equivalent using
 /// [CustomScrollView]:
@@ -665,6 +667,8 @@ abstract class BoxScrollView extends ScrollView {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// ```dart
 /// CustomScrollView(
@@ -686,6 +690,7 @@ abstract class BoxScrollView extends ScrollView {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -836,7 +841,7 @@ class ListView extends BoxScrollView {
   /// advance, or all at once when the [ListView] itself is created, it is more
   /// efficient to use [new ListView].
   ///
-  /// ## Sample code
+  /// {@tool sample}
   ///
   /// This example shows how to create [ListView] whose [ListTile] list items
   /// are separated by [Divider]s.
@@ -852,6 +857,7 @@ class ListView extends BoxScrollView {
   ///   },
   /// )
   /// ```
+  /// {@end-tool}
   ///
   /// The `addAutomaticKeepAlives` argument corresponds to the
   /// [SliverChildBuilderDelegate.addAutomaticKeepAlives] property. The
@@ -1047,7 +1053,7 @@ class ListView extends BoxScrollView {
 /// [SliverList] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
 /// list.
 ///
-/// ### Sample code
+/// {@tool sample}
 ///
 /// Here are two brief snippets showing a [GridView] and its equivalent using
 /// [CustomScrollView]:
@@ -1068,6 +1074,8 @@ class ListView extends BoxScrollView {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
+/// {@tool sample}
 ///
 /// ```dart
 /// CustomScrollView(
@@ -1091,6 +1099,7 @@ class ListView extends BoxScrollView {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -220,7 +220,7 @@ abstract class SliverChildDelegate {
 /// delegates where the first has 10 children contributing semantics, then the
 /// second delegate should offset its children by 10.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample code shows how to use `semanticIndexOffset` to handle multiple
 /// delegates in a single scroll view.
@@ -251,6 +251,7 @@ abstract class SliverChildDelegate {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// In certain cases, only a subset of child widgets should be annotated
 /// with a semantic index. For example, in [new ListView.separated()] the
@@ -258,7 +259,7 @@ abstract class SliverChildDelegate {
 /// providing a `semanticIndexCallback` which returns null for separators
 /// indexes and rounds the non-separator indexes down by half.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This sample code shows how to use `semanticIndexCallback` to handle
 /// annotating a subset of child nodes with a semantic index. There is
@@ -290,6 +291,7 @@ abstract class SliverChildDelegate {
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -677,7 +679,7 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
 /// [SliverFixedExtentList] does not need to perform layout on its children to
 /// obtain their extent in the main axis.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example, which would be inserted into a [CustomScrollView.slivers]
 /// list, shows an infinite number of items in varying shades of blue:
@@ -696,6 +698,7 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// {@macro flutter.widgets.sliverChildDelegate.lifecycle}
 ///
@@ -741,7 +744,7 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
 /// The main axis direction of a grid is the direction in which it scrolls; the
 /// cross axis direction is the orthogonal direction.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This example, which would be inserted into a [CustomScrollView.slivers]
 /// list, shows twenty boxes in a pretty teal grid:
@@ -766,6 +769,7 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// {@macro flutter.widgets.sliverChildDelegate.lifecycle}
 ///

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

@@ -17,7 +17,7 @@ import 'framework.dart';
 /// [Spacer] has taken up all of the additional space, therefore there is none
 /// left to redistribute.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// Row(
@@ -31,6 +31,7 @@ import 'framework.dart';
 ///   ],
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// See also:
 ///

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

@@ -167,7 +167,7 @@ class DefaultTextStyle extends InheritedWidget {
 /// behavior is useful, for example, to make the text bold while using the
 /// default font family and size.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// Text(
@@ -177,13 +177,14 @@ class DefaultTextStyle extends InheritedWidget {
 ///   style: TextStyle(fontWeight: FontWeight.bold),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// Using the [Text.rich] constructor, the [Text] widget can
 /// display a paragraph with differently styled [TextSpan]s. The sample
 /// that follows displays "Hello beautiful world" with different styles
 /// for each word.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// ```dart
 /// const Text.rich(
@@ -196,6 +197,7 @@ class DefaultTextStyle extends InheritedWidget {
 ///   ),
 /// )
 /// ```
+/// {@end-tool}
 ///
 /// ## Interactivity
 ///

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

@@ -760,7 +760,7 @@ class DefaultTextStyleTransition extends AnimatedWidget {
 /// Using this pre-built child is entirely optional, but can improve
 /// performance significantly in some cases and is therefore a good practice.
 ///
-/// ## Sample code
+/// {@tool sample}
 ///
 /// This code defines a widget called `Spinner` that spins a green square
 /// continually. It is built with an [AnimatedBuilder] and makes use of the
@@ -805,6 +805,7 @@ class DefaultTextStyleTransition extends AnimatedWidget {
 ///   }
 /// }
 /// ```
+/// {@end-tool}
 class AnimatedBuilder extends AnimatedWidget {
   /// Creates an animated builder.
   ///