Remove remaining "## Sample code" segments, and fix the snippet generator. (#27793) This converts all remaining "## Sample code" segments into snippets, and fixes the snippet generator to handle multiple snippets in the same dartdoc block properly. I also generated, compiled, and ran each of the existing application samples, and fixed them up to be more useful and/or just run without errors. This PR fixes these problems with examples: 1. Switching tabs in a snippet now works if there is more than one snippet in a single dartdoc block. 2. Generation of snippet code now works if there is more than one snippet. 3. Contrast of text and links in the code sample block has been improved to recommended levels. 4. Added five new snippet templates, including a "freeform" template to make it possible to show examples that need to change the app instantiation. 5. Fixed several examples to run properly, a couple by adding the "Scaffold" widget to the template, a couple by just fixing their code. 6. Fixed visual look of some of the samples when they run by placing many samples inside of a Scaffold. 7. In order to make it easier to run locally, changed the sample analyzer to remove the contents of the supplied temp directory before running, since having files that hang around is problematic (only a problem when running locally with the `--temp` argument). 8. Added a `SampleCheckerException` class, and handle sample checking exceptions more gracefully. 9. Deprecated the old "## Sample code" designation, and added enforcement for the deprecation. 10. Removed unnecessary `new` from templates (although they never appeared in the samples thanks to dartfmt, but still). Fixes #26398 Fixes #27411

diff --git a/dev/snippets/README.md b/dev/snippets/README.md
index 0606877..a1e7875 100644
--- a/dev/snippets/README.md
+++ b/dev/snippets/README.md

@@ -7,8 +7,9 @@
 This takes code in dartdocs, like this:
 
 ```dart
-/// The following is a skeleton of a stateless widget subclass called `GreenFrog`:
 /// {@tool snippet --template="stateless_widget"}
+/// The following is a skeleton of a stateless widget subclass called `GreenFrog`.
+/// ```dart
 /// class GreenFrog extends StatelessWidget {
 ///   const GreenFrog({ Key key }) : super(key: key);
 ///
@@ -17,6 +18,7 @@
 ///     return Container(color: const Color(0xFF2DBD3A));
 ///   }
 /// }
+/// ```
 /// {@end-tool}
 ```
 

diff --git a/dev/snippets/config/skeletons/application.html b/dev/snippets/config/skeletons/application.html
index afe9c4c..7d7e17b 100644
--- a/dev/snippets/config/skeletons/application.html
+++ b/dev/snippets/config/skeletons/application.html

@@ -1,26 +1,30 @@
 {@inject-html}
 <div class="snippet-buttons">
-  <button id="shortSnippetButton" onclick="showSnippet(shortSnippet);" selected>Sample</button>
-  <button id="longSnippetButton" onclick="showSnippet(longSnippet);">Sample in an App</button>
+  <script>var visibleSnippet{{serial}} = "shortSnippet{{serial}}";</script>
+  <button id="shortSnippet{{serial}}Button"
+          onclick="visibleSnippet{{serial}} = showSnippet('shortSnippet{{serial}}', visibleSnippet{{serial}});"
+          selected>Sample</button>
+  <button id="longSnippet{{serial}}Button"
+          onclick="visibleSnippet{{serial}} = showSnippet('longSnippet{{serial}}', visibleSnippet{{serial}});">Sample in an App</button>
 </div>
 <div class="snippet-container">
-  <div class="snippet" id="shortSnippet">
+  <div class="snippet" id="shortSnippet{{serial}}">
     {{description}}
     <div class="copyable-container">
       <button class="copy-button-overlay copy-button" title="Copy to clipboard"
-              onclick="copyTextToClipboard();">
+              onclick="copyTextToClipboard(visibleSnippet{{serial}});">
         <i class="material-icons copy-image">assignment</i>
       </button>
       <pre class="language-{{language}}"><code class="language-{{language}}">{{code}}</code></pre>
     </div>
   </div>
-  <div class="snippet" id="longSnippet" hidden>
+  <div class="snippet" id="longSnippet{{serial}}" hidden>
     <div class="snippet-description">To create a sample project with this code snippet, run:<br/>
       <span class="snippet-create-command">flutter create --sample={{id}} mysample</span>
     </div>
     <div class="copyable-container">
       <button class="copy-button-overlay copy-button" title="Copy to clipboard"
-              onclick="copyTextToClipboard();">
+              onclick="copyTextToClipboard(visibleSnippet{{serial}});">
         <i class="material-icons copy-image">assignment</i>
       </button>
       <pre class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>

diff --git a/dev/snippets/config/skeletons/sample.html b/dev/snippets/config/skeletons/sample.html
index fbdc5fe..66ae99b 100644
--- a/dev/snippets/config/skeletons/sample.html
+++ b/dev/snippets/config/skeletons/sample.html

@@ -1,6 +1,6 @@
 {@inject-html}
 <div class="snippet-buttons">
-  <button id="shortSnippetButton" selected>Sample</button>
+  <button id="shortSnippet{{serial}}Button" selected>Sample</button>
 </div>
 <div class="snippet-container">
   <div class="snippet">{{description}}

diff --git a/dev/snippets/config/templates/README.md b/dev/snippets/config/templates/README.md
index 66ab21b..8d7f260 100644
--- a/dev/snippets/config/templates/README.md
+++ b/dev/snippets/config/templates/README.md

@@ -49,6 +49,11 @@
 The templates available for using as an argument to the snippets tool are as
 follows:
 
+- [`freeform`](freeform.tmpl) :
+  This is a simple template for which you provide everything.  It has no code of
+  its own, just the sections for `imports`, `main`, and `preamble`. You must
+  provide the `main` section in order to have a `main()`.
+
 - [`stateful_widget`](stateful_widget.tmpl) :
   The default code block will be placed as the body of the `State` object of a
   StatefulWidget subclass. Because the default code block is placed as the body
@@ -58,8 +63,26 @@
   function calls are not allowed in the preamble.  It also has an `imports`
   section to import additional packages. Please only import things that are part
   of flutter or part of default dependencies for a `flutter create` project.
+  It creates a WidgetsApp around the child stateful widget.
 
 - [`stateless_widget`](stateless_widget.tmpl) :
   Identical to the `stateful_widget` template, except that the default code
-  block is inserted as the return value for a pre-existing `build` function in a
-  StatelessWidget, instead of being at the class level.
+  block is inserted as the `build` function in a
+  StatelessWidget. There is no need to include the @override before the build
+  funciton (the template adds this for you).
+
+- [`stateful_widget_material`](stateful_widget_material.tmpl) : Similar to
+  `stateful_widget`, except that it imports the material library, and uses
+  a MaterialApp instead of WidgetsApp.
+
+- [`stateless_widget_material`](stateless_widget_material.tmpl) : Similar to
+  `stateless_widget`, except that it imports the material library, and uses
+  a MaterialApp instead of WidgetsApp.
+
+- [`stateful_widget_scaffold`](stateful_widget_scaffold.tmpl) : Similar to
+  `stateful_widget_material`, except that it wraps the stateful widget with a
+  Scaffold.
+
+- [`stateless_widget_scaffold`](stateless_widget_scaffold.tmpl) : Similar to
+  `stateless_widget_material`, except that it wraps the stateless widget with a
+  Scaffold.

diff --git a/dev/snippets/config/templates/freeform.tmpl b/dev/snippets/config/templates/freeform.tmpl
new file mode 100644
index 0000000..82e2ec9
--- /dev/null
+++ b/dev/snippets/config/templates/freeform.tmpl

@@ -0,0 +1,11 @@
+// Flutter code sample for {{id}}
+
+{{description}}
+
+{{code-imports}}
+
+{{code-main}}
+
+{{code-preamble}}
+
+{{code}}

diff --git a/dev/snippets/config/templates/stateful_widget.tmpl b/dev/snippets/config/templates/stateful_widget.tmpl
index 0cac378..5f595ba 100644
--- a/dev/snippets/config/templates/stateful_widget.tmpl
+++ b/dev/snippets/config/templates/stateful_widget.tmpl

@@ -1,34 +1,36 @@
+// Flutter code sample for {{id}}
+
 {{description}}
 
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 
 {{code-imports}}
 
 void main() => runApp(new MyApp());
 
+/// This Widget is the main application widget.
 class MyApp extends StatelessWidget {
-  // This widget is the root of your application.
   @override
   Widget build(BuildContext context) {
-    return new MaterialApp(
-      title: 'Flutter Code Sample for {{id}}',
-      theme: new ThemeData(
-        primarySwatch: Colors.blue,
-      ),
-      home: new MyStatefulWidget(),
+    return WidgetsApp(
+      title: 'Flutter Code Sample',
+      home: MyStatefulWidget(),
+      color: const Color(0xffffffff),
     );
   }
 }
 
 {{code-preamble}}
 
+/// This is the stateful widget that the main application instantiates.
 class MyStatefulWidget extends StatefulWidget {
   MyStatefulWidget({Key key}) : super(key: key);
 
   @override
-  _MyStatefulWidgetState createState() => new _MyStatefulWidgetState();
+  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
 }
 
+// This is the private State class that goes with MyStatefulWidget.
 class _MyStatefulWidgetState extends State<MyStatefulWidget> {
   {{code}}
 }

diff --git a/dev/snippets/config/templates/stateful_widget_material.tmpl b/dev/snippets/config/templates/stateful_widget_material.tmpl
new file mode 100644
index 0000000..67881ea
--- /dev/null
+++ b/dev/snippets/config/templates/stateful_widget_material.tmpl

@@ -0,0 +1,35 @@
+// Flutter code sample for {{id}}
+
+{{description}}
+
+import 'package:flutter/material.dart';
+
+{{code-imports}}
+
+void main() => runApp(new MyApp());
+
+/// This Widget is the main application widget.
+class MyApp extends StatelessWidget {
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: _title,
+      home: MyStatefulWidget(),
+    );
+  }
+}
+
+{{code-preamble}}
+
+class MyStatefulWidget extends StatefulWidget {
+  MyStatefulWidget({Key key}) : super(key: key);
+
+  @override
+  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
+}
+
+class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+  {{code}}
+}

diff --git a/dev/snippets/config/templates/stateful_widget_scaffold.tmpl b/dev/snippets/config/templates/stateful_widget_scaffold.tmpl
new file mode 100644
index 0000000..f59ac3f
--- /dev/null
+++ b/dev/snippets/config/templates/stateful_widget_scaffold.tmpl

@@ -0,0 +1,38 @@
+// Flutter code sample for {{id}}
+
+{{description}}
+
+import 'package:flutter/material.dart';
+
+{{code-imports}}
+
+void main() => runApp(new MyApp());
+
+/// This Widget is the main application widget.
+class MyApp extends StatelessWidget {
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: _title,
+      home: Scaffold(
+        appBar: AppBar(title: Text(_title)),
+        body: MyStatefulWidget(),
+      ),
+    );
+  }
+}
+
+{{code-preamble}}
+
+class MyStatefulWidget extends StatefulWidget {
+  MyStatefulWidget({Key key}) : super(key: key);
+
+  @override
+  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
+}
+
+class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+  {{code}}
+}

diff --git a/dev/snippets/config/templates/stateless_widget.tmpl b/dev/snippets/config/templates/stateless_widget.tmpl
index 74fce8b..0cbaaea 100644
--- a/dev/snippets/config/templates/stateless_widget.tmpl
+++ b/dev/snippets/config/templates/stateless_widget.tmpl

@@ -1,32 +1,33 @@
+// Flutter code sample for {{id}}
+
 {{description}}
 
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 
 {{code-imports}}
 
 void main() => runApp(new MyApp());
 
+/// This Widget is the main application widget.
 class MyApp extends StatelessWidget {
-  // This widget is the root of your application.
   @override
   Widget build(BuildContext context) {
-    return new MaterialApp(
-      title: 'Flutter Code Sample for {{id}}',
-      theme: new ThemeData(
-        primarySwatch: Colors.blue,
-      ),
-      home: new MyStatelessWidget(),
+    return WidgetsApp(
+      title: 'Flutter Code Sample',
+      builder: (BuildContext context, Widget navigator) {
+        return MyStatelessWidget();
+      },
+      color: const Color(0xffffffff),
     );
   }
 }
 
 {{code-preamble}}
 
+/// This is the stateless widget that the main application instantiates.
 class MyStatelessWidget extends StatelessWidget {
   MyStatelessWidget({Key key}) : super(key: key);
 
   @override
-  Widget build(BuildContext context) {
-    return {{code}};
-  }
+  {{code}}
 }

diff --git a/dev/snippets/config/templates/stateless_widget_material.tmpl b/dev/snippets/config/templates/stateless_widget_material.tmpl
new file mode 100644
index 0000000..66c0bef
--- /dev/null
+++ b/dev/snippets/config/templates/stateless_widget_material.tmpl

@@ -0,0 +1,33 @@
+// Flutter code sample for {{id}}
+
+{{description}}
+
+import 'package:flutter/material.dart';
+
+{{code-imports}}
+
+void main() => runApp(new MyApp());
+
+/// This Widget is the main application widget.
+class MyApp extends StatelessWidget {
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: _title,
+      home: MyStatelessWidget(),
+    );
+  }
+}
+
+
+{{code-preamble}}
+
+/// This is the stateless widget that the main application instantiates.
+class MyStatelessWidget extends StatelessWidget {
+  MyStatelessWidget({Key key}) : super(key: key);
+
+  @override
+  {{code}}
+}

diff --git a/dev/snippets/config/templates/stateless_widget_scaffold.tmpl b/dev/snippets/config/templates/stateless_widget_scaffold.tmpl
new file mode 100644
index 0000000..1f62e41
--- /dev/null
+++ b/dev/snippets/config/templates/stateless_widget_scaffold.tmpl

@@ -0,0 +1,36 @@
+// Flutter code sample for {{id}}
+
+{{description}}
+
+import 'package:flutter/material.dart';
+
+{{code-imports}}
+
+void main() => runApp(new MyApp());
+
+/// This Widget is the main application widget.
+class MyApp extends StatelessWidget {
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: _title,
+      home: Scaffold(
+        appBar: AppBar(title: Text(_title)),
+        body: MyStatelessWidget(),
+      ),
+    );
+  }
+}
+
+
+{{code-preamble}}
+
+/// This is the stateless widget that the main application instantiates.
+class MyStatelessWidget extends StatelessWidget {
+  MyStatelessWidget({Key key}) : super(key: key);
+
+  @override
+  {{code}}
+}

diff --git a/dev/snippets/lib/main.dart b/dev/snippets/lib/main.dart
index 417fd4e..9c25637 100644
--- a/dev/snippets/lib/main.dart
+++ b/dev/snippets/lib/main.dart

@@ -11,6 +11,7 @@
 import 'configuration.dart';
 import 'snippets.dart';
 
+const String _kSerialOption = 'serial';
 const String _kElementOption = 'element';
 const String _kHelpOption = 'help';
 const String _kInputOption = 'input';
@@ -75,6 +76,11 @@
     defaultsTo: environment['ELEMENT_NAME'],
     help: 'The name of the element that this snippet belongs to.',
   );
+  parser.addOption(
+    _kSerialOption,
+    defaultsTo: environment['INVOCATION_INDEX'],
+    help: 'A unique serial number for this snippet tool invocation.',
+  );
   parser.addFlag(
     _kHelpOption,
     defaultsTo: false,
@@ -117,6 +123,7 @@
   final String packageName = args[_kPackageOption] != null && args[_kPackageOption].isNotEmpty ? args[_kPackageOption] : null;
   final String libraryName = args[_kLibraryOption] != null && args[_kLibraryOption].isNotEmpty ? args[_kLibraryOption] : null;
   final String elementName = args[_kElementOption] != null && args[_kElementOption].isNotEmpty ? args[_kElementOption] : null;
+  final String serial = args[_kSerialOption] != null && args[_kSerialOption].isNotEmpty ? args[_kSerialOption] : null;
   final List<String> id = <String>[];
   if (args[_kOutputOption] != null) {
     id.add(path.basename(path.basenameWithoutExtension(args[_kOutputOption])));
@@ -130,10 +137,13 @@
     if (elementName != null) {
       id.add(elementName);
     }
+    if (serial != null) {
+      id.add(serial);
+    }
     if (id.isEmpty) {
       errorExit('Unable to determine ID. At least one of --$_kPackageOption, '
-          '--$_kLibraryOption, --$_kElementOption, or the environment variables '
-          'PACKAGE_NAME, LIBRARY_NAME, or ELEMENT_NAME must be non-empty.');
+          '--$_kLibraryOption, --$_kElementOption, -$_kSerialOption, or the environment variables '
+          'PACKAGE_NAME, LIBRARY_NAME, ELEMENT_NAME, or INVOCATION_INDEX must be non-empty.');
     }
   }
 
@@ -149,6 +159,7 @@
       'sourceLine': environment['SOURCE_LINE'] != null
           ? int.tryParse(environment['SOURCE_LINE'])
           : null,
+      'serial': serial,
       'package': packageName,
       'library': libraryName,
       'element': elementName,

diff --git a/dev/snippets/lib/snippets.dart b/dev/snippets/lib/snippets.dart
index 0881694..e8764b1 100644
--- a/dev/snippets/lib/snippets.dart
+++ b/dev/snippets/lib/snippets.dart

@@ -31,7 +31,8 @@
   SnippetGenerator({Configuration configuration})
       : configuration = configuration ??
             // Flutter's root is four directories up from this script.
-            Configuration(flutterRoot: Directory(Platform.environment['FLUTTER_ROOT'] ?? path.canonicalize(path.join(path.dirname(path.fromUri(Platform.script)), '..', '..', '..')))) {
+            Configuration(flutterRoot: Directory(Platform.environment['FLUTTER_ROOT']
+                ?? path.canonicalize(path.join(path.dirname(path.fromUri(Platform.script)), '..', '..', '..')))) {
     this.configuration.createOutputDirectory();
   }
 
@@ -72,10 +73,10 @@
         // Remove any leading/trailing empty comment lines.
         // We don't want to remove ALL empty comment lines, only the ones at the
         // beginning and the end.
-        while (description.last == '// ') {
+        while (description.isNotEmpty && description.last == '// ') {
           description.removeLast();
         }
-        while (description.first == '// ') {
+        while (description.isNotEmpty && description.first == '// ') {
           description.removeAt(0);
         }
         return description.join('\n').trim();
@@ -98,7 +99,7 @@
   ///
   /// Takes into account the [type] and doesn't substitute in the id and the app
   /// if not a [SnippetType.application] snippet.
-  String interpolateSkeleton(SnippetType type, List<_ComponentTuple> injections, String skeleton) {
+  String interpolateSkeleton(SnippetType type, List<_ComponentTuple> injections, String skeleton, Map<String, Object> metadata) {
     final List<String> result = <String>[];
     const HtmlEscape htmlEscape = HtmlEscape();
     String language;
@@ -128,12 +129,13 @@
       'language': language ?? 'dart',
     }..addAll(type == SnippetType.application
         ? <String, String>{
+            'serial': metadata['serial'].toString() ?? '0',
             'id':
                 injections.firstWhere((_ComponentTuple tuple) => tuple.name == 'id').mergedContent,
             'app':
                 htmlEscape.convert(injections.firstWhere((_ComponentTuple tuple) => tuple.name == 'app').mergedContent),
           }
-        : <String, String>{'id': '', 'app': ''});
+        : <String, String>{'serial': '', 'id': '', 'app': ''});
     return skeleton.replaceAllMapped(RegExp('{{(${substitutions.keys.join('|')})}}'), (Match match) {
       return substitutions[match[1]];
     });
@@ -180,6 +182,16 @@
     return file.readAsStringSync(encoding: Encoding.getByName('utf-8'));
   }
 
+  String _addLineNumbers(String app) {
+    final StringBuffer buffer = StringBuffer();
+    int count = 0;
+    for (String line in app.split('\n')) {
+      count++;
+      buffer.writeln('${count.toString().padLeft(5, ' ')}: $line');
+    }
+    return buffer.toString();
+  }
+
   /// The main routine for generating snippets.
   ///
   /// The [input] is the file containing the dartdoc comments (minus the leading
@@ -220,7 +232,7 @@
         try {
           app = formatter.format(app);
         } on FormatterException catch (exception) {
-          stderr.write('Code to format:\n$app\n');
+          stderr.write('Code to format:\n${_addLineNumbers(app)}\n');
           errorExit('Unable to format snippet app template: $exception');
         }
 
@@ -250,6 +262,6 @@
         break;
     }
     final String skeleton = _loadFileAsUtf8(configuration.getHtmlSkeletonFile(type));
-    return interpolateSkeleton(type, snippetData, skeleton);
+    return interpolateSkeleton(type, snippetData, skeleton, metadata);
   }
 }