[flutter_releases] Flutter stable 3.22.0 Framework Cherrypicks (#147950)

# Flutter stable 3.22.0 Framework

## Scheduled Cherrypicks

bin/internal/engine.version

-b4bfd459865a8d636f26aca0d330ae297c006c3c
+f6344b75dcf861d8bf1f1322780b8811f982e31a

dartdoc_options.yaml

@@ -5,13 +5,13 @@ dartdoc:
   # The dev/bots/docs.sh script does this automatically.
   tools:
     snippet:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=snippet"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=snippet"]
       description: "Creates sample code documentation output from embedded documentation samples."
     sample:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=sample"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=sample"]
       description: "Creates full application sample code documentation output from embedded documentation samples."
     dartpad:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=dartpad"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=dartpad"]
       description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
   errors:
     ## Default errors of dartdoc:

dev/bots/docs.sh

@@ -107,16 +107,25 @@ function parse_args() {
   fi
 }
 
+function build_snippets_tool() (
+  local snippets_dir="$FLUTTER_ROOT/dev/snippets"
+  local output_dir="$FLUTTER_BIN/cache/artifacts/snippets"
+  echo "Building snippets tool executable."
+  command cd "$snippets_dir"
+  mkdir -p "$output_dir"
+  dart pub get
+  dart compile exe -o "$output_dir/snippets" bin/snippets.dart
+)
+
 function generate_docs() {
     # Install and activate dartdoc.
     # When updating to a new dartdoc version, please also update
     # `dartdoc_options.yaml` to include newly introduced error and warning types.
     "$DART" pub global activate dartdoc 8.0.6
 
-    # Install and activate the snippets tool, which resides in the
-    # assets-for-api-docs repo:
-    # https://github.com/flutter/assets-for-api-docs/tree/main/packages/snippets
-    "$DART" pub global activate snippets 0.4.3
+    # Build and install the snippets tool, which resides in
+    # the dev/docs/snippets directory.
+    build_snippets_tool
 
     # This script generates a unified doc set, and creates
     # a custom index.html, placing everything into DOC_DIR.

dev/snippets/README.md

+# Dartdoc Sample Generation
+
+The Flutter API documentation contains code blocks that help provide context or
+a good starting point when learning to use any of Flutter's APIs.
+
+To generate these code blocks, Flutter uses dartdoc tools to turn documentation
+in the source code into API documentation, as seen on [https://api.flutter.dev/]
+
+## Table of Contents
+
+- [Types of code blocks](#types-of-code-blocks)
+  - [Snippet tool](#snippet-tool)
+  - [Sample tool](#sample-tool)
+- [Skeletons](#skeletons)
+- [Test Doc Generation Workflow](#test-doc-generation-workflow)
+
+## Types of code blocks
+
+There are three kinds of code blocks.
+
+- A `snippet`, which is a more or less context-free code snippet that we
+  magically determine how to analyze.
+
+- A `dartpad` sample, which gets placed into a full-fledged application, and can
+  be executed inline in the documentation on the web page using
+  DartPad.
+
+- A `sample`, which gets placed into a full-fledged application, but isn't
+  placed into DartPad in the documentation because it doesn't make sense to do
+  so.
+
+Ideally, every sample is a DartPad sample, but some samples don't have any visual
+representation and some just don't make sense that way (for example, sample
+code for setting the system UI's notification area color on Android won't do
+anything on the web).
+
+### Snippet Tool
+
+![Code snippet image](assets/code_snippet.png)
+
+The code `snippet` tool generates a block containing a description and example
+code. Here is an example of the code `snippet` tool in use:
+
+```dart
+/// {@tool snippet}
+///
+/// If the avatar is to have an image, the image should be specified in the
+/// [backgroundImage] property:
+///
+/// ```dart
+/// CircleAvatar(
+///   backgroundImage: NetworkImage(userAvatarUrl),
+/// )
+/// ```
+/// {@end-tool}
+```
+
+This will generate sample code that can be copied to the clipboard and added to
+existing applications.
+
+This uses the skeleton for `snippet` snippets when generating the HTML to put
+into the Dart docs. You can find this [template in the Flutter
+repo](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/snippet.html).
+
+#### Analysis
+
+The
+[`analyze_sample_code.dart`](https://github.com/flutter/flutter/blob/main/dev/bots/analyze_sample_code.dart)
+script finds code inside the `@tool
+snippet` sections and uses the Dart analyzer to check them.
+
+There are several kinds of sample code you can specify:
+
+- Constructor calls, typically showing what might exist in a build method. These
+  will be inserted into an assignment expression assigning to a variable of type
+  "dynamic" and followed by a semicolon, for analysis.
+
+- Class definitions. These start with "class", and are analyzed verbatim.
+
+- Other code. It gets included verbatim, though any line that says `// ...` is
+  considered to separate the block into multiple blocks to be processed
+  individually.
+
+The above means that it's tricky to include verbatim imperative code (e.g. a
+call to a method) since it won't be valid to have such code at the top level.
+Instead, wrap it in a function or even a whole class, or make it a valid
+variable declaration.
+
+You can declare code that should be included in the analysis but not shown in
+the API docs by adding a comment "// Examples can assume:" to the file (usually
+at the top of the file, after the imports), following by one or more
+commented-out lines of code. That code is included verbatim in the analysis. For
+example:
+
+```dart
+// Examples can assume:
+// final BuildContext context;
+// final String userAvatarUrl;
+```
+
+You can assume that the entire Flutter framework and most common
+`dart:*` packages are imported and in scope; `dart:math` as `math` and
+`dart:ui` as `ui`.
+
+### Sample Tool
+
+![Code sample image](assets/code_sample.png)
+
+The code `sample` and `dartpad` tools can expand sample code into full Flutter
+applications. These sample applications can be directly copied and used to
+demonstrate the API's functionality in a sample application, or used with the
+`flutter create` command to create a local project with the sample code. The
+`dartpad` samples are embedded into the API docs web page and are live
+applications in the API documentation.
+
+This uses the skeleton for [application](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/sample.html)
+snippets in the Flutter repo.
+
+The `sample` and `dartpad` tools also allow for quick Flutter app generation
+using the following command:
+
+```bash
+flutter create --sample=[directory.File.sampleNumber] [name_of_project_directory]
+```
+
+This command is displayed as part of the sample in the API docs.
+
+#### Sample Analysis
+
+The [`../bots/analyze_sample_code.dart`](../bots/analyze_sample_code.dart)
+script finds code inside the `@tool sample` sections and uses the Dart analyzer
+to check the sample code.
+
+## Skeletons
+
+A skeleton (concerning this tool) is an HTML template into which the Dart
+code blocks and descriptions are interpolated.
+
+There is currently one skeleton for
+[application](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/sample.html)
+samples, one for
+[dartpad](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/dartpad-sample.html),
+and one for
+[snippet](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/snippet.html)
+code samples, but there could be more.
+
+Skeletons use mustache notation (e.g. `{{code}}`) to mark where components will
+be interpolated into the template. It doesn't use the mustache
+package since these are simple string substitutions, but it uses the same
+syntax.
+
+The code block generation tools that process the source input and emit HTML for
+output, which dartdoc places back into the documentation. Any options given to
+the `{@tool ...}` directive are passed on verbatim to the tool.
+
+The `snippets` tool renders these examples through a combination of markdown
+and HTML using the `{@inject-html}` dartdoc directive.
+
+## Test Doc Generation Workflow
+
+If you are making changes to an existing code block or are creating a new code
+block, follow these steps to generate a local copy of the API docs and verify
+that your code blocks are showing up correctly:
+
+1. Make an update to a code block or create a new code block.
+2. From the root directory, run `./dev/bots/docs.sh`. This should start
+   generating a local copy of the API documentation.
+   Supplying the "--output" argument allows you to specify the output zip file
+   for the completed documentation. Defaults to `api_docs.zip`` in the current
+   directory.
+3. Once complete, unzip the files to the desired location and open the `index.html`
+   within.
+
+Note that generating the sample output will not allow you to run your code in
+DartPad, because DartPad pulls the code it runs from the appropriate docs server
+(main or stable).
+
+Copy the generated code and paste it into a regular DartPad instance to test if
+it runs in DartPad. To get the code that will be produced by your documentation
+changes, run sample analysis locally (see the next section) and paste the output
+into a DartPad at [https://dartpad.dartlang.org].
+
+## Running sample analysis locally
+
+If all you want to do is analyze the sample code you have written locally, then
+generating the entire docs output takes a long time.
+
+Instead, you can run the analysis locally with this command from the Flutter root:
+
+```bash
+TMPDIR=/tmp bin/cache/dart-sdk/bin/dart dev/bots/analyze_sample_code.dart --temp=samples
+```
+
+This will analyze the samples, and leave the generated files in `/tmp/samples`
+
+You can find the sample you are working on in `/tmp/samples`. It is named using the
+path to the file it is in, and the line of the file that the `{@tool ...}` directive
+is on.
+
+For example, the file `sample.src.widgets.animated_list.52.dart` points to the sample
+in `packages/flutter/src/widgets/animated_list.dart` at line 52. You can then take the
+contents of that file, and paste it into [Dartpad](https://dartpad.dev) and see if it
+works. If the sample relies on new features that have just landed, it may not work
+until the features make it into the `dev` branch.

dev/snippets/bin/snippets.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:io' show ProcessResult, exitCode, stderr;
+
+import 'package:args/args.dart';
+import 'package:file/file.dart';
+import 'package:file/local.dart';
+import 'package:path/path.dart' as path;
+import 'package:platform/platform.dart';
+import 'package:process/process.dart';
+import 'package:snippets/snippets.dart';
+
+const String _kElementOption = 'element';
+const String _kFormatOutputOption = 'format-output';
+const String _kHelpOption = 'help';
+const String _kInputOption = 'input';
+const String _kLibraryOption = 'library';
+const String _kOutputDirectoryOption = 'output-directory';
+const String _kOutputOption = 'output';
+const String _kPackageOption = 'package';
+const String _kSerialOption = 'serial';
+const String _kTypeOption = 'type';
+
+class GitStatusFailed implements Exception {
+  GitStatusFailed(this.gitResult);
+
+  final ProcessResult gitResult;
+
+  @override
+  String toString() {
+    return 'git status exited with a non-zero exit code: '
+        '${gitResult.exitCode}:\n${gitResult.stderr}\n${gitResult.stdout}';
+  }
+}
+
+/// A singleton filesystem that can be set by tests to a memory filesystem.
+FileSystem filesystem = const LocalFileSystem();
+
+/// A singleton snippet generator that can be set by tests to a mock, so that
+/// we can test the command line parsing.
+SnippetGenerator snippetGenerator = SnippetGenerator();
+
+/// A singleton platform that can be set by tests for use in testing command line
+/// parsing.
+Platform platform = const LocalPlatform();
+
+/// A singleton process manager that can be set by tests for use in testing.
+ProcessManager processManager = const LocalProcessManager();
+
+/// Get the name of the channel these docs are from.
+///
+/// First check env variable LUCI_BRANCH, then refer to the currently
+/// checked out git branch.
+String getChannelName({
+  Platform platform = const LocalPlatform(),
+  ProcessManager processManager = const LocalProcessManager(),
+}) {
+  final String? envReleaseChannel = platform.environment['LUCI_BRANCH']?.trim();
+  if (<String>['master', 'stable', 'main'].contains(envReleaseChannel)) {
+    // Backward compatibility: Still support running on "master", but pretend it is "main".
+    if (envReleaseChannel == 'master') {
+      return 'main';
+    }
+    return envReleaseChannel!;
+  }
+
+  final RegExp gitBranchRegexp = RegExp(r'^## (?<branch>.*)');
+  final ProcessResult gitResult = processManager.runSync(
+      <String>['git', 'status', '-b', '--porcelain'],
+      // Use the FLUTTER_ROOT, if defined.
+      workingDirectory: platform.environment['FLUTTER_ROOT']?.trim() ??
+          filesystem.currentDirectory.path,
+      // Adding extra debugging output to help debug why git status inexplicably fails
+      // (random non-zero error code) about 2% of the time.
+      environment: <String, String>{'GIT_TRACE': '2', 'GIT_TRACE_SETUP': '2'});
+  if (gitResult.exitCode != 0) {
+    throw GitStatusFailed(gitResult);
+  }
+
+  final RegExpMatch? gitBranchMatch = gitBranchRegexp
+      .firstMatch((gitResult.stdout as String).trim().split('\n').first);
+  return gitBranchMatch == null
+      ? '<unknown>'
+      : gitBranchMatch.namedGroup('branch')!.split('...').first;
+}
+
+const List<String> sampleTypes = <String>[
+  'snippet',
+  'sample',
+  'dartpad',
+];
+
+// This is a hack to workaround the fact that git status inexplicably fails
+// (with random non-zero error code) about 2% of the time.
+String getChannelNameWithRetries({
+  Platform platform = const LocalPlatform(),
+  ProcessManager processManager = const LocalProcessManager(),
+}) {
+  int retryCount = 0;
+
+  while (retryCount < 2) {
+    try {
+      return getChannelName(platform: platform, processManager: processManager);
+    } on GitStatusFailed catch (e) {
+      retryCount += 1;
+      stderr.write(
+          'git status failed, retrying ($retryCount)\nError report:\n$e');
+    }
+  }
+
+  return getChannelName(platform: platform, processManager: processManager);
+}
+
+/// Generates snippet dartdoc output for a given input, and creates any sample
+/// applications needed by the snippet.
+void main(List<String> argList) {
+  final Map<String, String> environment = platform.environment;
+  final ArgParser parser = ArgParser();
+
+  parser.addOption(
+    _kTypeOption,
+    defaultsTo: 'dartpad',
+    allowed: sampleTypes,
+    allowedHelp: <String, String>{
+      'dartpad':
+          'Produce a code sample application for using in Dartpad.',
+      'sample':
+          'Produce a code sample application.',
+      'snippet':
+          'Produce a nicely formatted piece of sample code.',
+    },
+    help: 'The type of snippet to produce.',
+  );
+  parser.addOption(
+    _kOutputOption,
+    help: 'The output name for the generated sample application. Overrides '
+        'the naming generated by the --$_kPackageOption/--$_kLibraryOption/--$_kElementOption '
+        'arguments. Metadata will be written alongside in a .json file. '
+        'The basename of this argument is used as the ID. If this is a '
+        'relative path, will be placed under the --$_kOutputDirectoryOption location.',
+  );
+  parser.addOption(
+    _kOutputDirectoryOption,
+    defaultsTo: '.',
+    help: 'The output path for the generated sample application.',
+  );
+  parser.addOption(
+    _kInputOption,
+    defaultsTo: environment['INPUT'],
+    help: 'The input file containing the sample code to inject.',
+  );
+  parser.addOption(
+    _kPackageOption,
+    defaultsTo: environment['PACKAGE_NAME'],
+    help: 'The name of the package that this sample belongs to.',
+  );
+  parser.addOption(
+    _kLibraryOption,
+    defaultsTo: environment['LIBRARY_NAME'],
+    help: 'The name of the library that this sample belongs to.',
+  );
+  parser.addOption(
+    _kElementOption,
+    defaultsTo: environment['ELEMENT_NAME'],
+    help: 'The name of the element that this sample belongs to.',
+  );
+  parser.addOption(
+    _kSerialOption,
+    defaultsTo: environment['INVOCATION_INDEX'],
+    help: 'A unique serial number for this snippet tool invocation.',
+  );
+  parser.addFlag(
+    _kFormatOutputOption,
+    defaultsTo: true,
+    help: 'Applies the Dart formatter to the published/extracted sample code.',
+  );
+  parser.addFlag(
+    _kHelpOption,
+    negatable: false,
+    help: 'Prints help documentation for this command',
+  );
+
+  final ArgResults args = parser.parse(argList);
+
+  if (args[_kHelpOption]! as bool) {
+    stderr.writeln(parser.usage);
+    exitCode = 0;
+    return;
+  }
+
+  final String sampleType = args[_kTypeOption]! as String;
+
+  if (args[_kInputOption] == null) {
+    stderr.writeln(parser.usage);
+    errorExit(
+        'The --$_kInputOption option must be specified, either on the command '
+        'line, or in the INPUT environment variable.');
+    return;
+  }
+
+  final File input = filesystem.file(args['input']! as String);
+  if (!input.existsSync()) {
+    errorExit('The input file ${input.path} does not exist.');
+    return;
+  }
+
+  final bool formatOutput = args[_kFormatOutputOption]! as bool;
+  final String packageName = args[_kPackageOption] as String? ?? '';
+  final String libraryName = args[_kLibraryOption] as String? ?? '';
+  final String elementName = args[_kElementOption] as String? ?? '';
+  final String serial = args[_kSerialOption] as String? ?? '';
+  late String id;
+  File? output;
+  final Directory outputDirectory =
+      filesystem.directory(args[_kOutputDirectoryOption]! as String).absolute;
+
+  if (args[_kOutputOption] != null) {
+    id = path.basenameWithoutExtension(args[_kOutputOption]! as String);
+    final File outputPath = filesystem.file(args[_kOutputOption]! as String);
+    if (outputPath.isAbsolute) {
+      output = outputPath;
+    } else {
+      output =
+          filesystem.file(path.join(outputDirectory.path, outputPath.path));
+    }
+  } else {
+    final List<String> idParts = <String>[];
+    if (packageName.isNotEmpty && packageName != 'flutter') {
+      idParts.add(packageName.replaceAll(RegExp(r'\W'), '_').toLowerCase());
+    }
+    if (libraryName.isNotEmpty) {
+      idParts.add(libraryName.replaceAll(RegExp(r'\W'), '_').toLowerCase());
+    }
+    if (elementName.isNotEmpty) {
+      idParts.add(elementName);
+    }
+    if (serial.isNotEmpty) {
+      idParts.add(serial);
+    }
+    if (idParts.isEmpty) {
+      errorExit('Unable to determine ID. At least one of --$_kPackageOption, '
+          '--$_kLibraryOption, --$_kElementOption, -$_kSerialOption, or the environment variables '
+          'PACKAGE_NAME, LIBRARY_NAME, ELEMENT_NAME, or INVOCATION_INDEX must be non-empty.');
+      return;
+    }
+    id = idParts.join('.');
+    output = outputDirectory.childFile('$id.dart');
+  }
+  output.parent.createSync(recursive: true);
+
+  final int? sourceLine = environment['SOURCE_LINE'] != null
+      ? int.tryParse(environment['SOURCE_LINE']!)
+      : null;
+  final String sourcePath = environment['SOURCE_PATH'] ?? 'unknown.dart';
+  final SnippetDartdocParser sampleParser = SnippetDartdocParser(filesystem);
+  final SourceElement element = sampleParser.parseFromDartdocToolFile(
+    input,
+    startLine: sourceLine,
+    element: elementName,
+    sourceFile: filesystem.file(sourcePath),
+    type: sampleType,
+  );
+  final Map<String, Object?> metadata = <String, Object?>{
+    'channel': getChannelNameWithRetries(
+        platform: platform, processManager: processManager),
+    'serial': serial,
+    'id': id,
+    'package': packageName,
+    'library': libraryName,
+    'element': elementName,
+  };
+
+  for (final CodeSample sample in element.samples) {
+    sample.metadata.addAll(metadata);
+    snippetGenerator.generateCode(
+      sample,
+      output: output,
+      formatOutput: formatOutput,
+    );
+    print(snippetGenerator.generateHtml(sample));
+  }
+
+  exitCode = 0;
+}

dev/snippets/lib/snippets.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+export 'src/analysis.dart';
+export 'src/configuration.dart';
+export 'src/data_types.dart';
+export 'src/import_sorter.dart';
+export 'src/snippet_generator.dart';
+export 'src/snippet_parser.dart';
+export 'src/util.dart';

dev/snippets/lib/src/configuration.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:file/file.dart';
+import 'package:file/local.dart';
+import 'package:path/path.dart' as path;
+
+// Represents the locations of all of the data for snippets.
+class SnippetConfiguration {
+  const SnippetConfiguration({
+    required this.configDirectory,
+    required this.skeletonsDirectory,
+    this.filesystem = const LocalFileSystem(),
+  });
+
+  final FileSystem filesystem;
+
+  /// This is the configuration directory for the snippets system, containing
+  /// the skeletons and templates.
+  final Directory configDirectory;
+
+  /// The directory containing the HTML skeletons to be filled out with metadata
+  /// and returned to dartdoc for insertion in the output.
+  final Directory skeletonsDirectory;
+
+  /// Gets the skeleton file to use for the given [SampleType] and DartPad
+  /// preference.
+  File getHtmlSkeletonFile(String type) {
+    final String filename =
+        type == 'dartpad' ? 'dartpad-sample.html' : '$type.html';
+    return filesystem.file(path.join(skeletonsDirectory.path, filename));
+  }
+}
+
+/// A class to compute the configuration of the snippets input and output
+/// locations based in the current location of the snippets main.dart.
+class FlutterRepoSnippetConfiguration extends SnippetConfiguration {
+  FlutterRepoSnippetConfiguration({required this.flutterRoot, super.filesystem})
+      : super(
+          configDirectory: _underRoot(filesystem, flutterRoot,
+              const <String>['dev', 'snippets', 'config']),
+          skeletonsDirectory: _underRoot(filesystem, flutterRoot,
+              const <String>['dev', 'snippets', 'config', 'skeletons']),
+        );
+
+  final Directory flutterRoot;
+
+  static Directory _underRoot(
+          FileSystem fs, Directory flutterRoot, List<String> dirs) =>
+      fs.directory(path.canonicalize(
+          path.joinAll(<String>[flutterRoot.absolute.path, ...dirs])));
+}

dev/snippets/lib/src/util.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:convert';
+import 'dart:io' as io;
+
+import 'package:file/file.dart';
+import 'package:file/local.dart';
+import 'package:meta/meta.dart';
+import 'package:platform/platform.dart' show LocalPlatform, Platform;
+import 'package:process/process.dart' show LocalProcessManager, ProcessManager;
+import 'package:pub_semver/pub_semver.dart';
+
+import 'data_types.dart';
+
+/// An exception class to allow capture of exceptions generated by the Snippets
+/// package.
+class SnippetException implements Exception {
+  SnippetException(this.message, {this.file, this.line});
+  final String message;
+  final String? file;
+  final int? line;
+
+  @override
+  String toString() {
+    if (file != null || line != null) {
+      final String fileStr = file == null ? '' : '$file:';
+      final String lineStr = line == null ? '' : '$line:';
+      return '$runtimeType: $fileStr$lineStr: $message';
+    } else {
+      return '$runtimeType: $message';
+    }
+  }
+}
+
+/// Gets the number of whitespace characters at the beginning of a line.
+int getIndent(String line) => line.length - line.trimLeft().length;
+
+/// Contains information about the installed Flutter repo.
+class FlutterInformation {
+  FlutterInformation({
+    this.platform = const LocalPlatform(),
+    this.processManager = const LocalProcessManager(),
+    this.filesystem = const LocalFileSystem(),
+  });
+
+  final Platform platform;
+  final ProcessManager processManager;
+  final FileSystem filesystem;
+
+  static FlutterInformation? _instance;
+
+  static FlutterInformation get instance => _instance ??= FlutterInformation();
+
+  @visibleForTesting
+  static set instance(FlutterInformation? value) => _instance = value;
+
+  Directory getFlutterRoot() {
+    if (platform.environment['FLUTTER_ROOT'] != null) {
+      return filesystem.directory(platform.environment['FLUTTER_ROOT']);
+    }
+    return getFlutterInformation()['flutterRoot'] as Directory;
+  }
+
+  Version getFlutterVersion() =>
+      getFlutterInformation()['frameworkVersion'] as Version;
+
+  Version getDartSdkVersion() =>
+      getFlutterInformation()['dartSdkVersion'] as Version;
+
+  Map<String, dynamic>? _cachedFlutterInformation;
+
+  Map<String, dynamic> getFlutterInformation() {
+    if (_cachedFlutterInformation != null) {
+      return _cachedFlutterInformation!;
+    }
+
+    String flutterVersionJson;
+    if (platform.environment['FLUTTER_VERSION'] != null) {
+      flutterVersionJson = platform.environment['FLUTTER_VERSION']!;
+    } else {
+      String flutterCommand;
+      if (platform.environment['FLUTTER_ROOT'] != null) {
+        flutterCommand = filesystem
+            .directory(platform.environment['FLUTTER_ROOT'])
+            .childDirectory('bin')
+            .childFile('flutter')
+            .absolute
+            .path;
+      } else {
+        flutterCommand = 'flutter';
+      }
+      io.ProcessResult result;
+      try {
+        result = processManager.runSync(
+            <String>[flutterCommand, '--version', '--machine'],
+            stdoutEncoding: utf8);
+      } on io.ProcessException catch (e) {
+        throw SnippetException(
+            'Unable to determine Flutter information. Either set FLUTTER_ROOT, or place flutter command in your path.\n$e');
+      }
+      if (result.exitCode != 0) {
+        throw SnippetException(
+            'Unable to determine Flutter information, because of abnormal exit to flutter command.');
+      }
+      flutterVersionJson = (result.stdout as String).replaceAll(
+          'Waiting for another flutter command to release the startup lock...',
+          '');
+    }
+
+    final Map<String, dynamic> flutterVersion =
+        json.decode(flutterVersionJson) as Map<String, dynamic>;
+    if (flutterVersion['flutterRoot'] == null ||
+        flutterVersion['frameworkVersion'] == null ||
+        flutterVersion['dartSdkVersion'] == null) {
+      throw SnippetException(
+          'Flutter command output has unexpected format, unable to determine flutter root location.');
+    }
+
+    final Map<String, dynamic> info = <String, dynamic>{};
+    info['flutterRoot'] =
+        filesystem.directory(flutterVersion['flutterRoot']! as String);
+    info['frameworkVersion'] =
+        Version.parse(flutterVersion['frameworkVersion'] as String);
+
+    final RegExpMatch? dartVersionRegex =
+        RegExp(r'(?<base>[\d.]+)(?:\s+\(build (?<detail>[-.\w]+)\))?')
+            .firstMatch(flutterVersion['dartSdkVersion'] as String);
+    if (dartVersionRegex == null) {
+      throw SnippetException(
+          'Flutter command output has unexpected format, unable to parse dart SDK version ${flutterVersion['dartSdkVersion']}.');
+    }
+    info['dartSdkVersion'] = Version.parse(
+        dartVersionRegex.namedGroup('detail') ??
+            dartVersionRegex.namedGroup('base')!);
+    _cachedFlutterInformation = info;
+
+    return info;
+  }
+}
+
+/// Injects the [injections] into the [template], while turning the
+/// "description" injection into a comment.
+String interpolateTemplate(
+  List<SkeletonInjection> injections,
+  String template,
+  Map<String, Object?> metadata, {
+  bool addCopyright = false,
+}) {
+  String wrapSectionMarker(Iterable<String> contents, {required String name}) {
+    if (contents.join().trim().isEmpty) {
+      // Skip empty sections.
+      return '';
+    }
+    // We don't wrap some sections, because otherwise they generate invalid files.
+    final String result = <String>[
+      ...contents,
+    ].join('\n');
+    final RegExp wrappingNewlines = RegExp(r'^\n*(.*)\n*$', dotAll: true);
+    return result.replaceAllMapped(
+        wrappingNewlines, (Match match) => match.group(1)!);
+  }
+
+  return '${addCopyright ? '{{copyright}}\n\n' : ''}$template'
+      .replaceAllMapped(RegExp(r'{{([^}]+)}}'), (Match match) {
+    final String name = match[1]!;
+    final int componentIndex = injections
+        .indexWhere((SkeletonInjection injection) => injection.name == name);
+    if (metadata[name] != null && componentIndex == -1) {
+      // If the match isn't found in the injections, then just return the
+      // metadata entry.
+      return wrapSectionMarker((metadata[name]! as String).split('\n'),
+          name: name);
+    }
+    return wrapSectionMarker(
+        componentIndex >= 0
+            ? injections[componentIndex].stringContents
+            : <String>[],
+        name: name);
+  }).replaceAll(RegExp(r'\n\n+'), '\n\n');
+}
+
+class SampleStats {
+  const SampleStats({
+    this.totalSamples = 0,
+    this.dartpadSamples = 0,
+    this.snippetSamples = 0,
+    this.applicationSamples = 0,
+    this.wordCount = 0,
+    this.lineCount = 0,
+    this.linkCount = 0,
+    this.description = '',
+  });
+
+  final int totalSamples;
+  final int dartpadSamples;
+  final int snippetSamples;
+  final int applicationSamples;
+  final int wordCount;
+  final int lineCount;
+  final int linkCount;
+  final String description;
+  bool get allOneKind =>
+      totalSamples == snippetSamples ||
+      totalSamples == applicationSamples ||
+      totalSamples == dartpadSamples;
+
+  @override
+  String toString() {
+    return description;
+  }
+}
+
+Iterable<CodeSample> getSamplesInElements(Iterable<SourceElement>? elements) {
+  return elements
+          ?.expand<CodeSample>((SourceElement element) => element.samples) ??
+      const <CodeSample>[];
+}
+
+SampleStats getSampleStats(SourceElement element) {
+  if (element.comment.isEmpty) {
+    return const SampleStats();
+  }
+  final int total = element.sampleCount;
+  if (total == 0) {
+    return const SampleStats();
+  }
+  final int dartpads = element.dartpadSampleCount;
+  final int snippets = element.snippetCount;
+  final int applications = element.applicationSampleCount;
+  final String sampleCount = <String>[
+    if (snippets > 0) '$snippets snippet${snippets != 1 ? 's' : ''}',
+    if (applications > 0)
+      '$applications application sample${applications != 1 ? 's' : ''}',
+    if (dartpads > 0) '$dartpads dartpad sample${dartpads != 1 ? 's' : ''}'
+  ].join(', ');
+  final int wordCount = element.wordCount;
+  final int lineCount = element.lineCount;
+  final int linkCount = element.referenceCount;
+  final String description = <String>[
+    'Documentation has $wordCount ${wordCount == 1 ? 'word' : 'words'} on ',
+    '$lineCount ${lineCount == 1 ? 'line' : 'lines'}',
+    if (linkCount > 0 && element.hasSeeAlso) ', ',
+    if (linkCount > 0 && !element.hasSeeAlso) ' and ',
+    if (linkCount > 0)
+      'refers to $linkCount other ${linkCount == 1 ? 'symbol' : 'symbols'}',
+    if (linkCount > 0 && element.hasSeeAlso) ', and ',
+    if (linkCount == 0 && element.hasSeeAlso) 'and ',
+    if (element.hasSeeAlso) 'has a "See also:" section',
+    '.',
+  ].join();
+  return SampleStats(
+    totalSamples: total,
+    dartpadSamples: dartpads,
+    snippetSamples: snippets,
+    applicationSamples: applications,
+    wordCount: wordCount,
+    lineCount: lineCount,
+    linkCount: linkCount,
+    description: 'Has $sampleCount. $description',
+  );
+}
+
+/// Exit the app with a message to stderr.
+/// Can be overridden by tests to avoid exits.
+// ignore: prefer_function_declarations_over_variables
+void Function(String message) errorExit = (String message) {
+  io.stderr.writeln(message);
+  io.exit(1);
+};

dev/snippets/pubspec.yaml

+name: snippets
+description: A package for parsing and manipulating code samples in Flutter repo dartdoc comments.
+
+environment:
+  sdk: '>=3.2.0-0 <4.0.0'
+
+dependencies:
+  analyzer: 6.4.1
+  args: 2.4.2
+  dart_style: 2.3.6
+  file: 7.0.0
+  meta: 1.12.0
+  path: 1.9.0
+  platform: 3.1.4
+  process: 5.0.2
+
+  _fe_analyzer_shared: 67.0.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  async: 2.11.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  boolean_selector: 2.1.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  collection: 1.18.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  convert: 3.1.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  coverage: 1.7.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  crypto: 3.0.3 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  frontend_server_client: 3.2.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  glob: 2.1.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  http_multi_server: 3.2.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  http_parser: 4.0.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  io: 1.0.4 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  js: 0.7.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  logging: 1.2.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  matcher: 0.12.16+1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  mime: 1.0.5 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  node_preamble: 2.0.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  package_config: 2.1.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  pool: 1.5.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  pub_semver: 2.1.4 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  shelf: 1.4.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  shelf_packages_handler: 3.0.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  shelf_static: 1.1.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  shelf_web_socket: 1.0.4 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  source_map_stack_trace: 2.1.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  source_maps: 0.10.12 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  source_span: 1.10.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  stack_trace: 1.11.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  stream_channel: 2.1.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  string_scanner: 1.2.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  term_glyph: 1.2.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  test_api: 0.7.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  test_core: 0.6.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  typed_data: 1.3.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  vm_service: 14.2.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  watcher: 1.1.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  web: 0.5.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  web_socket_channel: 2.4.4 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  webkit_inspection_protocol: 1.2.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+  yaml: 3.1.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
+
+dev_dependencies:
+  test: 1.25.2
+
+executables:
+  snippets:
+
+# PUBSPEC CHECKSUM: 94f5

dev/snippets/test/configuration_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:file/memory.dart';
+import 'package:snippets/snippets.dart';
+import 'package:test/test.dart' hide TypeMatcher, isInstanceOf;
+
+void main() {
+  group('Configuration', () {
+    final MemoryFileSystem memoryFileSystem = MemoryFileSystem();
+    late SnippetConfiguration config;
+
+    setUp(() {
+      config = FlutterRepoSnippetConfiguration(
+        flutterRoot: memoryFileSystem.directory('/flutter sdk'),
+        filesystem: memoryFileSystem,
+      );
+    });
+    test('config directory is correct', () async {
+      expect(config.configDirectory.path,
+          matches(RegExp(r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config')));
+    });
+    test('skeleton directory is correct', () async {
+      expect(
+          config.skeletonsDirectory.path,
+          matches(RegExp(
+              r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons')));
+    });
+    test('html skeleton file for sample is correct', () async {
+      expect(
+          config.getHtmlSkeletonFile('snippet').path,
+          matches(RegExp(
+              r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]snippet.html')));
+    });
+    test('html skeleton file for app with no dartpad is correct', () async {
+      expect(
+          config.getHtmlSkeletonFile('sample').path,
+          matches(RegExp(
+              r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]sample.html')));
+    });
+    test('html skeleton file for app with dartpad is correct', () async {
+      expect(
+          config.getHtmlSkeletonFile('dartpad').path,
+          matches(RegExp(
+              r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]dartpad-sample.html')));
+    });
+  });
+}

dev/snippets/test/fake_process_manager.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:process/process.dart';
+
+class FakeProcessManager extends LocalProcessManager {
+  FakeProcessManager(
+      {this.stdout = '', this.stderr = '', this.exitCode = 0, this.pid = 1});
+
+  int runs = 0;
+  String stdout;
+  String stderr;
+  int exitCode;
+  int pid;
+
+  @override
+  ProcessResult runSync(
+    List<Object> command, {
+    String? workingDirectory,
+    Map<String, String>? environment,
+    bool includeParentEnvironment = true,
+    bool runInShell = false,
+    Encoding? stdoutEncoding = systemEncoding,
+    Encoding? stderrEncoding = systemEncoding,
+  }) {
+    runs++;
+    return ProcessResult(pid, exitCode, stdout, stderr);
+  }
+}

dev/snippets/test/import_sorter_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:file/file.dart';
+import 'package:file/memory.dart';
+import 'package:path/path.dart' as path;
+import 'package:pub_semver/pub_semver.dart';
+import 'package:snippets/snippets.dart';
+import 'package:test/test.dart' hide TypeMatcher, isInstanceOf;
+
+class FakeFlutterInformation extends FlutterInformation {
+  FakeFlutterInformation(this.flutterRoot);
+
+  final Directory flutterRoot;
+
+  @override
+  Map<String, dynamic> getFlutterInformation() {
+    return <String, dynamic>{
+      'flutterRoot': flutterRoot,
+      'frameworkVersion': Version(2, 10, 0),
+      'dartSdkVersion': Version(2, 12, 1),
+    };
+  }
+}
+
+void main() {
+  late MemoryFileSystem memoryFileSystem = MemoryFileSystem();
+  late Directory tmpDir;
+
+  setUp(() {
+    // Create a new filesystem.
+    memoryFileSystem = MemoryFileSystem();
+    tmpDir = memoryFileSystem.systemTempDirectory
+        .createTempSync('flutter_snippets_test.');
+    final Directory flutterRoot =
+        memoryFileSystem.directory(path.join(tmpDir.absolute.path, 'flutter'));
+    FlutterInformation.instance = FakeFlutterInformation(flutterRoot);
+  });
+
+  test('Sorting packages works', () async {
+    final String result = sortImports('''
+// Unit comment
+
+// third import
+import 'packages:gamma/gamma.dart'; // third
+
+// second import
+import 'packages:beta/beta.dart'; // second
+
+// first import
+import 'packages:alpha/alpha.dart'; // first
+
+void main() {}
+''');
+    expect(result, equals('''
+// Unit comment
+
+// first import
+import 'packages:alpha/alpha.dart'; // first
+// second import
+import 'packages:beta/beta.dart'; // second
+// third import
+import 'packages:gamma/gamma.dart'; // third
+
+void main() {}
+'''));
+  });
+  test('Sorting dart and packages works', () async {
+    final String result = sortImports('''
+// Unit comment
+
+// third import
+import 'packages:gamma/gamma.dart'; // third
+
+// second import
+import 'packages:beta/beta.dart'; // second
+
+// first import
+import 'packages:alpha/alpha.dart'; // first
+
+// first dart
+import 'dart:async';
+
+void main() {}
+''');
+    expect(result, equals('''
+// Unit comment
+
+// first dart
+import 'dart:async';
+
+// first import
+import 'packages:alpha/alpha.dart'; // first
+// second import
+import 'packages:beta/beta.dart'; // second
+// third import
+import 'packages:gamma/gamma.dart'; // third
+
+void main() {}
+'''));
+  });
+}

dev/snippets/test/snippet_parser_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:file/file.dart';
+import 'package:file/memory.dart';
+import 'package:path/path.dart' as path;
+import 'package:pub_semver/pub_semver.dart';
+import 'package:snippets/snippets.dart';
+import 'package:test/test.dart' hide TypeMatcher, isInstanceOf;
+
+import 'filesystem_resource_provider.dart';
+
+class FakeFlutterInformation extends FlutterInformation {
+  FakeFlutterInformation(this.flutterRoot);
+
+  final Directory flutterRoot;
+
+  @override
+  Directory getFlutterRoot() {
+    return flutterRoot;
+  }
+
+  @override
+  Map<String, dynamic> getFlutterInformation() {
+    return <String, dynamic>{
+      'flutterRoot': flutterRoot,
+      'frameworkVersion': Version(2, 10, 0),
+      'dartSdkVersion': Version(2, 12, 1),
+    };
+  }
+}
+
+void main() {
+  group('Parser', () {
+    late MemoryFileSystem memoryFileSystem = MemoryFileSystem();
+    late FlutterRepoSnippetConfiguration configuration;
+    late SnippetGenerator generator;
+    late Directory tmpDir;
+    late Directory flutterRoot;
+
+    void writeSkeleton(String type) {
+      switch (type) {
+        case 'dartpad':
+          configuration.getHtmlSkeletonFile('dartpad').writeAsStringSync('''
+<div>HTML Bits (DartPad-style)</div>
+<iframe class="snippet-dartpad" src="https://dartpad.dev/embed-flutter.html?split=60&run=true&sample_id={{id}}&sample_channel={{channel}}"></iframe>
+<div>More HTML Bits</div>
+''');
+        case 'sample':
+        case 'snippet':
+          configuration.getHtmlSkeletonFile(type).writeAsStringSync('''
+<div>HTML Bits</div>
+{{description}}
+<pre>{{code}}</pre>
+<pre>{{app}}</pre>
+<div>More HTML Bits</div>
+''');
+      }
+    }
+
+    setUp(() {
+      // Create a new filesystem.
+      memoryFileSystem = MemoryFileSystem();
+      tmpDir = memoryFileSystem.systemTempDirectory
+          .createTempSync('flutter_snippets_test.');
+      flutterRoot = memoryFileSystem
+          .directory(path.join(tmpDir.absolute.path, 'flutter'));
+      configuration = FlutterRepoSnippetConfiguration(
+          flutterRoot: flutterRoot, filesystem: memoryFileSystem);
+      configuration.skeletonsDirectory.createSync(recursive: true);
+      <String>['dartpad', 'sample', 'snippet'].forEach(writeSkeleton);
+      FlutterInformation.instance = FakeFlutterInformation(flutterRoot);
+      generator = SnippetGenerator(
+          configuration: configuration,
+          filesystem: memoryFileSystem,
+          flutterRoot: configuration.skeletonsDirectory.parent);
+    });
+
+    test('parses from comments', () async {
+      final File inputFile = _createSnippetSourceFile(tmpDir, memoryFileSystem);
+      final Iterable<SourceElement> elements = getFileElements(inputFile,
+          resourceProvider: FileSystemResourceProvider(memoryFileSystem));
+      expect(elements, isNotEmpty);
+      final SnippetDartdocParser sampleParser =
+          SnippetDartdocParser(memoryFileSystem);
+      sampleParser.parseFromComments(elements);
+      sampleParser.parseAndAddAssumptions(elements, inputFile);
+      expect(elements.length, equals(7));
+      int sampleCount = 0;
+      for (final SourceElement element in elements) {
+        expect(element.samples.length, greaterThanOrEqualTo(1));
+        sampleCount += element.samples.length;
+        final String code = generator.generateCode(element.samples.first);
+        expect(code, contains('// Description'));
+        expect(
+            code,
+            contains(RegExp(
+                '''^String elementName = '${element.elementName}';\$''',
+                multiLine: true)));
+        final String html = generator.generateHtml(element.samples.first);
+        expect(
+            html,
+            contains(RegExp(
+                '''^<pre>String elementName = &#39;${element.elementName}&#39;;.*\$''',
+                multiLine: true)));
+        expect(
+            html,
+            contains(
+                '<div class="snippet-description">{@end-inject-html}Description{@inject-html}</div>\n'));
+      }
+      expect(sampleCount, equals(8));
+    });
+    test('parses dartpad samples from linked file', () async {
+      final File inputFile = _createDartpadSourceFile(
+          tmpDir, memoryFileSystem, flutterRoot,
+          linked: true);
+      final Iterable<SourceElement> elements = getFileElements(inputFile,
+          resourceProvider: FileSystemResourceProvider(memoryFileSystem));
+      expect(elements, isNotEmpty);
+      final SnippetDartdocParser sampleParser =
+          SnippetDartdocParser(memoryFileSystem);
+      sampleParser.parseFromComments(elements);
+      expect(elements.length, equals(1));
+      int sampleCount = 0;
+      for (final SourceElement element in elements) {
+        expect(element.samples.length, greaterThanOrEqualTo(1));
+        sampleCount += element.samples.length;
+        final String code =
+            generator.generateCode(element.samples.first, formatOutput: false);
+        expect(code, contains('// Description'));
+        expect(
+            code,
+            contains(RegExp('^void ${element.name}Sample\\(\\) \\{.*\$',
+                multiLine: true)));
+        final String html = generator.generateHtml(element.samples.first);
+        expect(
+            html,
+            contains(RegExp(
+                '''^<iframe class="snippet-dartpad" src="https://dartpad.dev/.*sample_id=${element.name}.0.*></iframe>.*\$''',
+                multiLine: true)));
+      }
+      expect(sampleCount, equals(1));
+    });
+    test('parses assumptions', () async {
+      final File inputFile = _createSnippetSourceFile(tmpDir, memoryFileSystem);
+      final SnippetDartdocParser sampleParser =
+          SnippetDartdocParser(memoryFileSystem);
+      final List<SourceLine> assumptions =
+          sampleParser.parseAssumptions(inputFile);
+      expect(assumptions.length, equals(1));
+      expect(assumptions.first.text, equals('int integer = 3;'));
+    });
+  });
+}
+
+File _createSnippetSourceFile(Directory tmpDir, FileSystem filesystem) {
+  return filesystem.file(path.join(tmpDir.absolute.path, 'snippet_in.dart'))
+    ..createSync(recursive: true)
+    ..writeAsStringSync(r'''
+// Copyright
+
+// @dart = 2.12
+
+import 'foo.dart';
+
+// Examples can assume:
+// int integer = 3;
+
+/// Top level variable comment
+///
+/// {@tool snippet}
+/// Description
+/// ```dart
+/// String elementName = 'topLevelVariable';
+/// ```
+/// {@end-tool}
+int topLevelVariable = 4;
+
+/// Top level function comment
+///
+/// {@tool snippet}
+/// Description
+/// ```dart
+/// String elementName = 'topLevelFunction';
+/// ```
+/// {@end-tool}
+int topLevelFunction() {
+  return integer;
+}
+
+/// Class comment
+///
+/// {@tool snippet}
+/// Description
+/// ```dart
+/// String elementName = 'DocumentedClass';
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet}
+/// Description2
+/// ```dart
+/// String elementName = 'DocumentedClass';
+/// ```
+/// {@end-tool}
+class DocumentedClass {
+  /// Constructor comment
+  /// {@tool snippet}
+  /// Description
+  /// ```dart
+  /// String elementName = 'DocumentedClass';
+  /// ```
+  /// {@end-tool}
+  const DocumentedClass();
+
+  /// Named constructor comment
+  /// {@tool snippet}
+  /// Description
+  /// ```dart
+  /// String elementName = 'DocumentedClass.name';
+  /// ```
+  /// {@end-tool}
+  const DocumentedClass.name();
+
+  /// Member variable comment
+  /// {@tool snippet}
+  /// Description
+  /// ```dart
+  /// String elementName = 'DocumentedClass.intMember';
+  /// ```
+  /// {@end-tool}
+  int intMember;
+
+  /// Member comment
+  /// {@tool snippet}
+  /// Description
+  /// ```dart
+  /// String elementName = 'DocumentedClass.member';
+  /// ```
+  /// {@end-tool}
+  void member() {}
+}
+''');
+}
+
+File _createDartpadSourceFile(
+    Directory tmpDir, FileSystem filesystem, Directory flutterRoot,
+    {bool linked = false}) {
+  final File linkedFile =
+      filesystem.file(path.join(flutterRoot.absolute.path, 'linked_file.dart'))
+        ..createSync(recursive: true)
+        ..writeAsStringSync('''
+// Copyright
+
+import 'foo.dart';
+
+// Description
+
+void DocumentedClassSample() {
+  String elementName = 'DocumentedClass';
+}
+''');
+
+  final String source = linked
+      ? '''
+/// ** See code in ${path.relative(linkedFile.path, from: flutterRoot.absolute.path)} **'''
+      : '''
+/// ```dart
+/// void DocumentedClassSample() {
+///   String elementName = 'DocumentedClass';
+/// }
+/// ```''';
+
+  return filesystem.file(path.join(tmpDir.absolute.path, 'snippet_in.dart'))
+    ..createSync(recursive: true)
+    ..writeAsStringSync('''
+// Copyright
+
+// @dart = 2.12
+
+import 'foo.dart';
+
+/// Class comment
+///
+/// {@tool dartpad --template=template}
+/// Description
+$source
+/// {@end-tool}
+class DocumentedClass {}
+''');
+}

dev/snippets/test/util_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:file/memory.dart';
+import 'package:platform/platform.dart';
+import 'package:pub_semver/pub_semver.dart';
+import 'package:snippets/snippets.dart';
+import 'package:test/test.dart' hide TypeMatcher, isInstanceOf;
+
+import 'fake_process_manager.dart';
+
+const String testVersionInfo = r'''
+{
+  "frameworkVersion": "2.5.0-2.0.pre.63",
+  "channel": "master",
+  "repositoryUrl": "git@github.com:flutter/flutter.git",
+  "frameworkRevision": "9b2f6f7f9ab96bb3302f81b814a094f33023e79a",
+  "frameworkCommitDate": "2021-07-28 13:03:40 -0700",
+  "engineRevision": "0ed62a16f36348e97b2baadd8ccfec3825f80c5d",
+  "dartSdkVersion": "2.14.0 (build 2.14.0-360.0.dev)",
+  "flutterRoot": "/home/user/flutter"
+}
+''';
+
+void main() {
+  group('FlutterInformation', () {
+    late FakeProcessManager fakeProcessManager;
+    late FakePlatform fakePlatform;
+    late MemoryFileSystem memoryFileSystem;
+    late FlutterInformation flutterInformation;
+
+    setUp(() {
+      fakeProcessManager = FakeProcessManager();
+      memoryFileSystem = MemoryFileSystem();
+      fakePlatform = FakePlatform(environment: <String, String>{});
+      flutterInformation = FlutterInformation(
+        filesystem: memoryFileSystem,
+        processManager: fakeProcessManager,
+        platform: fakePlatform,
+      );
+    });
+
+    test('calls out to flutter if FLUTTER_VERSION is not set', () async {
+      fakeProcessManager.stdout = testVersionInfo;
+      final Map<String, dynamic> info =
+          flutterInformation.getFlutterInformation();
+      expect(fakeProcessManager.runs, equals(1));
+      expect(
+          info['frameworkVersion'], equals(Version.parse('2.5.0-2.0.pre.63')));
+    });
+    test("doesn't call out to flutter if FLUTTER_VERSION is set", () async {
+      fakePlatform.environment['FLUTTER_VERSION'] = testVersionInfo;
+      final Map<String, dynamic> info =
+          flutterInformation.getFlutterInformation();
+      expect(fakeProcessManager.runs, equals(0));
+      expect(
+          info['frameworkVersion'], equals(Version.parse('2.5.0-2.0.pre.63')));
+    });
+    test('getFlutterRoot calls out to flutter if FLUTTER_ROOT is not set',
+        () async {
+      fakeProcessManager.stdout = testVersionInfo;
+      final Directory root = flutterInformation.getFlutterRoot();
+      expect(fakeProcessManager.runs, equals(1));
+      expect(root.path, equals('/home/user/flutter'));
+    });
+    test("getFlutterRoot doesn't call out to flutter if FLUTTER_ROOT is set",
+        () async {
+      fakePlatform.environment['FLUTTER_ROOT'] = '/home/user/flutter';
+      final Directory root = flutterInformation.getFlutterRoot();
+      expect(fakeProcessManager.runs, equals(0));
+      expect(root.path, equals('/home/user/flutter'));
+    });
+    test('parses version properly', () async {
+      fakePlatform.environment['FLUTTER_VERSION'] = testVersionInfo;
+      final Map<String, dynamic> info =
+          flutterInformation.getFlutterInformation();
+      expect(info['frameworkVersion'], isNotNull);
+      expect(
+          info['frameworkVersion'], equals(Version.parse('2.5.0-2.0.pre.63')));
+      expect(info['dartSdkVersion'], isNotNull);
+      expect(info['dartSdkVersion'], equals(Version.parse('2.14.0-360.0.dev')));
+    });
+  });
+}

dev/tools/create_api_docs.dart

@@ -521,8 +521,8 @@ class DartdocGenerator {
 
     final Version version = FlutterInformation.instance.getFlutterVersion();
 
-    // Verify which version of snippets and dartdoc we're using.
-    final ProcessResult snippetsResult = processManager.runSync(
+    // Verify which version of the global activated packages we're using.
+    final ProcessResult versionResults = processManager.runSync(
       <String>[
         FlutterInformation.instance.getFlutterBinaryPath().path,
         'pub',
@@ -535,8 +535,8 @@ class DartdocGenerator {
     );
     print('');
     final Iterable<RegExpMatch> versionMatches =
-        RegExp(r'^(?<name>snippets|dartdoc) (?<version>[^\s]+)', multiLine: true)
-            .allMatches(snippetsResult.stdout as String);
+        RegExp(r'^(?<name>dartdoc) (?<version>[^\s]+)', multiLine: true)
+            .allMatches(versionResults.stdout as String);
     for (final RegExpMatch match in versionMatches) {
       print('${match.namedGroup('name')} version: ${match.namedGroup('version')}');
     }