github/flutter
7
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2025-06-03 00:51:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reverse the sense of the terms snippet and sample. (#48254)

Browse Source
This commit is contained in:
Greg Spencer 2020-01-08 15:28:02 -08:00 committed by Flutter GitHub Bot
parent dbed575c01
commit fabf4e3d0d
156 changed files with 583 additions and 583 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
dartdoc_options.yaml
View File

@ -4,11 +4,11 @@ dartdoc:
# The dev/tools/dartdoc.dart script does this automatically.
tools:
snippet:
command: ["dev/snippets/lib/main.dart", "--type=application"]
description: "Creates application sample code documentation output from embedded documentation samples."
command: ["dev/snippets/lib/main.dart", "--type=snippet"]
description: "Creates sample code documentation output from embedded documentation samples."
sample:
command: ["dev/snippets/lib/main.dart", "--type=sample"]
description: "Creates sample code documentation output from embedded documentation samples."
description: "Creates full application sample code documentation output from embedded documentation samples."
dartpad:
command: ["dev/snippets/lib/main.dart", "--type=application", "--dartpad"]
description: "Creates sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"]
description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."

100
dev/bots/analyze-sample-code.dart
View File

@ -107,10 +107,10 @@ class SampleCheckerException implements Exception {
/// error output from the analyzer is parsed for details, and the problem
/// locations are translated back to the source location.
///
/// For snippets, the snippets are generated using the snippets tool, and they
/// are analyzed with the samples. If errors are found in snippets, then the
/// line number of the start of the snippet is given instead of the actual error
/// line, since snippets get reformatted when written, and the line numbers
/// For samples, the samples are generated using the snippets tool, and they
/// are analyzed with the snippets. If errors are found in samples, then the
/// line number of the start of the sample is given instead of the actual error
/// line, since samples get reformatted when written, and the line numbers
/// don't necessarily match. It does, however, print the source of the
/// problematic line.
class SampleChecker {
@ -209,7 +209,7 @@ class SampleChecker {
Map<String, List<AnalysisError>> errors = <String, List<AnalysisError>>{};
try {
final Map<String, Section> sections = <String, Section>{};
final Map<String, Snippet> snippets = <String, Snippet>{};
final Map<String, Sample> snippets = <String, Sample>{};
_extractSamples(sections, snippets);
errors = _analyze(_tempDirectory, sections, snippets);
} finally {
@ -242,10 +242,10 @@ class SampleChecker {
/// Creates a name for the snippets tool to use for the snippet ID from a
/// filename and starting line number.
String _createNameFromSource(String prefix, String filename, int start) {
String snippetId = path.split(filename).join('.');
snippetId = path.basenameWithoutExtension(snippetId);
snippetId = '$prefix.$snippetId.$start';
return snippetId;
String sampleId = path.split(filename).join('.');
sampleId = path.basenameWithoutExtension(sampleId);
sampleId = '$prefix.$sampleId.$start';
return sampleId;
}
// Precompiles the snippets tool if _snippetsSnapshotPath isn't set yet, and
@ -273,42 +273,42 @@ class SampleChecker {
}
}
/// Writes out the given [snippet] to an output file in the [_tempDirectory] and
/// Writes out the given sample to an output file in the [_tempDirectory] and
/// returns the output file.
File _writeSnippet(Snippet snippet) {
File _writeSample(Sample sample) {
// Generate the snippet.
final String snippetId = _createNameFromSource('snippet', snippet.start.filename, snippet.start.line);
final String inputName = '$snippetId.input';
final String sampleId = _createNameFromSource('sample', sample.start.filename, sample.start.line);
final String inputName = '$sampleId.input';
// Now we have a filename like 'lib.src.material.foo_widget.123.dart' for each snippet.
final File inputFile = File(path.join(_tempDirectory.path, inputName))..createSync(recursive: true);
inputFile.writeAsStringSync(snippet.input.join('\n'));
final File outputFile = File(path.join(_tempDirectory.path, '$snippetId.dart'));
inputFile.writeAsStringSync(sample.input.join('\n'));
final File outputFile = File(path.join(_tempDirectory.path, '$sampleId.dart'));
final List<String> args = <String>[
'--output=${outputFile.absolute.path}',
'--input=${inputFile.absolute.path}',
...snippet.args,
...sample.args,
];
if (verbose)
print('Generating snippet for ${snippet.start?.filename}:${snippet.start?.line}');
print('Generating sample for ${sample.start?.filename}:${sample.start?.line}');
final ProcessResult process = _runSnippetsScript(args);
if (verbose)
stderr.write('${process.stderr}');
if (process.exitCode != 0) {
throw SampleCheckerException(
'Unable to create snippet for ${snippet.start.filename}:${snippet.start.line} '
'Unable to create sample for ${sample.start.filename}:${sample.start.line} '
'(using input from ${inputFile.path}):\n${process.stdout}\n${process.stderr}',
file: snippet.start.filename,
line: snippet.start.line,
file: sample.start.filename,
line: sample.start.line,
);
}
return outputFile;
}
/// Extracts the samples from the Dart files in [_flutterPackage], writes them
/// to disk, and adds them to the appropriate [sectionMap] or [snippetMap].
void _extractSamples(Map<String, Section> sectionMap, Map<String, Snippet> snippetMap) {
/// to disk, and adds them to the appropriate [sectionMap] or [sampleMap].
void _extractSamples(Map<String, Section> sectionMap, Map<String, Sample> sampleMap) {
final List<Section> sections = <Section>[];
final List<Snippet> snippets = <Snippet>[];
final List<Sample> samples = <Sample>[];
for (final File file in _listDartFiles(_flutterPackage, recursive: true)) {
final String relativeFilePath = path.relative(file.path, from: _flutterPackage.path);
@ -334,12 +334,12 @@ class SampleChecker {
throw SampleCheckerException('Snippet section unterminated.', file: relativeFilePath, line: lineNumber);
}
if (_dartDocSampleEndRegex.hasMatch(trimmedLine)) {
snippets.add(
Snippet(
samples.add(
Sample(
start: startLine,
input: block,
args: snippetArgs,
serial: snippets.length,
serial: samples.length,
),
);
snippetArgs = <String>[];
@ -407,7 +407,7 @@ class SampleChecker {
startLine = Line('', filename: relativeFilePath, line: lineNumber + 1, indent: 3);
inPreamble = true;
} else if (sampleMatch != null) {
inSnippet = sampleMatch != null && (sampleMatch[1] == 'snippet' || sampleMatch[1] == 'dartpad');
inSnippet = sampleMatch != null && (sampleMatch[1] == 'sample' || sampleMatch[1] == 'dartpad');
if (inSnippet) {
startLine = Line(
'',
@ -425,7 +425,7 @@ class SampleChecker {
inSampleSection = !inSnippet;
} else if (RegExp(r'///\s*#+\s+[Ss]ample\s+[Cc]ode:?$').hasMatch(trimmedLine)) {
throw SampleCheckerException(
"Found deprecated '## Sample code' section: use {@tool sample}...{@end-tool} instead.",
"Found deprecated '## Sample code' section: use {@tool snippet}...{@end-tool} instead.",
file: relativeFilePath,
line: lineNumber,
);
@ -437,10 +437,10 @@ class SampleChecker {
for (final Section section in sections) {
sectionMap[_writeSection(section).path] = section;
}
for (final Snippet snippet in snippets) {
final File snippetFile = _writeSnippet(snippet);
snippet.contents = snippetFile.readAsLinesSync();
snippetMap[snippetFile.absolute.path] = snippet;
for (final Sample sample in samples) {
final File snippetFile = _writeSample(sample);
sample.contents = snippetFile.readAsLinesSync();
sampleMap[snippetFile.absolute.path] = sample;
}
}
@ -506,7 +506,7 @@ linter:
/// Writes out a sample section to the disk and returns the file.
File _writeSection(Section section) {
final String sectionId = _createNameFromSource('sample', section.start.filename, section.start.line);
final String sectionId = _createNameFromSource('snippet', section.start.filename, section.start.line);
final File outputFile = File(path.join(_tempDirectory.path, '$sectionId.dart'))..createSync(recursive: true);
final List<Line> mainContents = <Line>[
...headers,
@ -520,7 +520,7 @@ linter:
/// Invokes the analyzer on the given [directory] and returns the stdout.
List<String> _runAnalyzer(Directory directory) {
print('Starting analysis of samples.');
print('Starting analysis of code samples.');
_createConfigurationFiles(directory);
final ProcessResult result = Process.runSync(
_flutter,
@ -556,7 +556,7 @@ linter:
Map<String, List<AnalysisError>> _analyze(
Directory directory,
Map<String, Section> sections,
Map<String, Snippet> snippets,
Map<String, Sample> samples,
) {
final List<String> errors = _runAnalyzer(directory);
final Map<String, List<AnalysisError>> analysisErrors = <String, List<AnalysisError>>{};
@ -587,7 +587,7 @@ linter:
final String line = parts[4];
final String column = parts[5];
final String errorCode = parts[6];
final int lineNumber = int.parse(line, radix: 10) - (isSample ? headerLength : 0);
final int lineNumber = int.parse(line, radix: 10) - (isSnippet ? headerLength : 0);
final int columnNumber = int.parse(column, radix: 10);
if (lineNumber < 0 && errorCode == 'unused_import') {
// We don't care about unused imports.
@ -621,7 +621,7 @@ linter:
// We don't really care if sample code isn't used!
continue;
}
if (isSnippet) {
if (isSample) {
addAnalysisError(
file,
AnalysisError(
@ -630,7 +630,7 @@ linter:
message,
errorCode,
null,
snippet: snippets[file.path],
sample: samples[file.path],
),
);
} else {
@ -794,7 +794,7 @@ class Line {
String toString() => '$filename:$line: $code';
}
/// A class to represent a section of sample code, marked by "{@tool sample}...{@end-tool}".
/// A class to represent a section of sample code, marked by "{@tool snippet}...{@end-tool}".
class Section {
const Section(this.code);
factory Section.combine(List<Section> sections) {
@ -841,12 +841,12 @@ class Section {
final List<Line> code;
}
/// A class to represent a snippet in the dartdoc comments, marked by
/// "{@tool snippet ...}...{@end-tool}". Snippets are processed separately from
/// regular samples, because they must be injected into templates in order to be
/// A class to represent a sample in the dartdoc comments, marked by
/// "{@tool sample ...}...{@end-tool}". Samples are processed separately from
/// regular snippets, because they must be injected into templates in order to be
/// analyzed.
class Snippet {
Snippet({this.start, List<String> input, List<String> args, this.serial}) {
class Sample {
Sample({this.start, List<String> input, List<String> args, this.serial}) {
this.input = input.toList();
this.args = args.toList();
}
@ -858,7 +858,7 @@ class Snippet {
@override
String toString() {
final StringBuffer buf = StringBuffer('snippet ${args.join(' ')}\n');
final StringBuffer buf = StringBuffer('sample ${args.join(' ')}\n');
int count = start.line;
for (final String line in input) {
buf.writeln(' ${count.toString().padLeft(4, ' ')}: $line');
@ -878,7 +878,7 @@ class AnalysisError {
this.message,
this.errorCode,
this.source, {
this.snippet,
this.sample,
});
final int line;
@ -886,15 +886,15 @@ class AnalysisError {
final String message;
final String errorCode;
final Line source;
final Snippet snippet;
final Sample sample;
@override
String toString() {
if (source != null) {
return '${source.toStringWithColumn(column)}\n>>> $message ($errorCode)';
} else if (snippet != null) {
return 'In snippet starting at '
'${snippet.start.filename}:${snippet.start.line}:${snippet.contents[line - 1]}\n'
} else if (sample != null) {
return 'In sample starting at '
'${sample.start.filename}:${sample.start.line}:${sample.contents[line - 1]}\n'
'>>> $message ($errorCode)';
} else {
return '<source unknown>:$line:$column\n>>> $message ($errorCode)';

14
dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart
View File

@ -22,7 +22,7 @@
/// blabla 0.0, the penzance blabla is blabla not blabla at all. Bla the blabla
/// 1.0, the blabla is blabla blabla blabla an blabla blabla.
///
/// {@tool sample}
/// {@tool snippet}
/// Bla blabla blabla some [Text] when the `_blabla` blabla blabla is true, and
/// blabla it when it is blabla:
///
@ -54,7 +54,7 @@
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// Bla blabla blabla some [Text] when the `_blabla` blabla blabla is true, and
/// blabla finale blabla:
///
@ -66,7 +66,7 @@
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// regular const constructor
///
/// ```dart
@ -74,21 +74,21 @@
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// const private constructor
/// ```dart
/// const _Text('Poor wandering ones!')
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// yet another const private constructor
/// ```dart
/// const _Text.__('Poor wandering ones!')
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// const variable
///
/// ```dart
@ -96,7 +96,7 @@
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// more const variables
///
/// ```dart

2
dev/bots/test/analyze-sample-code_test.dart
View File

@ -27,7 +27,7 @@ void main() {
]);
expect(stdoutLines, <String>[
'Found 7 sample code sections.',
'Starting analysis of samples.',
'Starting analysis of code samples.',
'',
]);
}, skip: Platform.isWindows);

50
dev/snippets/README.md
View File

@ -9,8 +9,8 @@ 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)
- [Sample tool](#sample-tool)
- [Snippet tool](#snippet-tool)
- [Sample tool](#sample-tool)
- [Skeletons](#skeletons)
- [Test Doc Generation Workflow](#test-doc-generation-workflow)
@ -18,21 +18,21 @@ in the source code into API documentation, as seen on https://api.flutter.dev/.
There's two kinds of code blocks.
* samples, which are more or less context-free snippets that we
* snippets, which are more or less context-free code snippets that we
magically determine how to analyze, and
* snippets, which get placed into a full-fledged application, and can
* samples, which get placed into a full-fledged application, and can
be actually executed inline in the documentation using DartPad.
### Sample Tool
### Snippet Tool
![Code sample image](assets/code_sample.png)
![Code snippet image](assets/code_snippet.png)
The code `sample` tool generates a block containing a description and example
code. Here is an example of the code `sample` tool in use:
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 sample}
/// {@tool snippet}
///
/// If the avatar is to have an image, the image should be specified in the
/// [backgroundImage] property:
@ -48,13 +48,13 @@ code. Here is an example of the code `sample` tool in use:
This will generate sample code that can be copied to the clipboard and added
to existing applications.
This uses the skeleton for [sample](config/skeletons/sample.html)
This uses the skeleton for [snippet](config/skeletons/snippet.html)
snippets when generating the HTML to put into the Dart docs.
#### Analysis
The `../bots/analyze-sample-code.dart` script finds code inside the
`@tool sample` sections and uses the Dart analyzer to check them.
`@tool snippet` sections and uses the Dart analyzer to check them.
There are several kinds of sample code you can specify:
@ -91,16 +91,16 @@ 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`.
### Snippet Tool
### Sample Tool
![Code snippet image](assets/code_snippet.png)
![Code sample image](assets/code_sample.png)
The code `snippet` tool can expand sample code into full Flutter applications.
The code `sample` tool 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:
```dart
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
/// This example shows how to make a simple [FloatingActionButton] in a
/// [Scaffold], with a pink [backgroundColor] and a thumbs up [Icon].
///
@ -126,10 +126,10 @@ API's functionality in a sample application:
/// {@end-tool}
```
This uses the skeleton for [application](config/skeletons/application.html)
This uses the skeleton for [application](config/skeletons/sample.html)
snippets.
Code `snippets` also allow for quick Flutter app generation using the following command:
Code `sample` also allow for quick Flutter app generation using the following command:
```bash
flutter create --sample=[directory.File.sampleNumber] [name_of_project_directory]
@ -138,12 +138,12 @@ flutter create --sample=[directory.File.sampleNumber] [name_of_project_directory
#### Templates
In order to support showing an entire app when you click on the right tab of
the code snippet UI, we have to be able to insert the `snippet` into the template
and instantiate the right parts.
the code sample UI, we have to be able to insert the `sample` block into the
template and instantiate the right parts.
To do this, there is a [config/templates](config/templates) directory that
contains a list of templates. These templates represent an entire app that the
`snippet` can be placed into, basically a replacement for `lib/main.dart` in a
`sample` can be placed into, basically a replacement for `lib/main.dart` in a
flutter app package.
For more information about how to create, use, or update templates, see
@ -152,7 +152,7 @@ For more information about how to create, use, or update templates, see
#### Analysis
The `../bots/analyze-sample-code.dart` script finds code inside the
`@tool snippet` sections and uses the Dart analyzer to check them
`@tool sample` sections and uses the Dart analyzer to check them
after applying the specified template.
## Skeletons
@ -161,17 +161,17 @@ A skeleton (in relation to this tool) is an HTML template into which the Dart
code blocks and descriptions are interpolated.
There is currently one skeleton for
[application](config/skeletons/application.html) `snippets` and one for
[sample](config/skeletons/sample.html) `snippets`, but there could be more.
[application](config/skeletons/sample.html) samples and one for
[snippet](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 actually use the mustache
package, since these are simple string substitutions, but it uses the same
syntax.
The code block generation tools 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 code block generation tools 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.

BIN
dev/snippets/assets/code_sample.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 111 KiB

BIN
dev/snippets/assets/code_snippet.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 111 KiB

After

Width:  |  Height:  |  Size: 38 KiB

43
dev/snippets/config/skeletons/application.html
View File

@ -1,43 +0,0 @@
{@inject-html}
<a name="{{id}}"></a>
<div class="anchor-container">
<a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
onmouseenter="fixHref(this, '{{id}}');"
onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
href="#">
<i class="material-icons copy-image">link</i>
</a>
</div>
<div class="snippet-buttons">
<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{{serial}}">
{{description}}
<div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard"
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{{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(visibleSnippet{{serial}});">
<i class="material-icons copy-image">assignment</i>
</button>
<pre class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>
</div>
</div>
</div>
{@end-inject-html}

0
dev/snippets/config/skeletons/dartpad-application.html → dev/snippets/config/skeletons/dartpad-sample.html
View File

26
dev/snippets/config/skeletons/sample.html
View File

@ -9,16 +9,34 @@
</a>
</div>
<div class="snippet-buttons">
<button id="shortSnippet{{serial}}Button" selected>Sample</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">{{description}}
<div class="snippet" id="shortSnippet{{serial}}">
{{description}}
<div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard"
onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">
onclick="copyTextToClipboard(visibleSnippet{{serial}});">
<i class="material-icons copy-image">assignment</i>
</button>
<pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre>
<pre class="language-{{language}}"><code class="language-{{language}}">{{code}}</code></pre>
</div>
</div>
<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(visibleSnippet{{serial}});">
<i class="material-icons copy-image">assignment</i>
</button>
<pre class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>
</div>
</div>
</div>

25
dev/snippets/config/skeletons/snippet.html Normal file
View File

@ -0,0 +1,25 @@
{@inject-html}
<a name="{{id}}"></a>
<div class="anchor-container">
<a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
onmouseenter="fixHref(this, '{{id}}');"
onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
href="#">
<i class="material-icons copy-image">link</i>
</a>
</div>
<div class="snippet-buttons">
<button id="shortSnippet{{serial}}Button" selected>Sample</button>
</div>
<div class="snippet-container">
<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'));">
<i class="material-icons copy-image">assignment</i>
</button>
<pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre>
</div>
</div>
</div>
{@end-inject-html}

6
dev/snippets/lib/configuration.dart
View File

@ -11,10 +11,10 @@ import 'package:path/path.dart' as path;
enum SnippetType {
/// Produces a snippet that includes the code interpolated into an application
/// template.
application,
sample,
/// Produces a nicely formatted sample code, but no application.
sample,
snippet,
}
/// Return the name of an enum item.
@ -69,7 +69,7 @@ class Configuration {
/// Gets the skeleton file to use for the given [SnippetType] and DartPad preference.
File getHtmlSkeletonFile(SnippetType type, {bool showDartPad = false}) {
assert(!showDartPad || type == SnippetType.application,
assert(!showDartPad || type == SnippetType.sample,
'Only application snippets work with dartpad.');
final String filename =
'${showDartPad ? 'dartpad-' : ''}${getEnumName(type)}.html';

30
dev/snippets/lib/main.dart
View File

@ -32,13 +32,13 @@ void main(List<String> argList) {
SnippetType.values.map<String>((SnippetType type) => getEnumName(type)).toList();
parser.addOption(
_kTypeOption,
defaultsTo: getEnumName(SnippetType.application),
defaultsTo: getEnumName(SnippetType.sample),
allowed: snippetTypes,
allowedHelp: <String, String>{
getEnumName(SnippetType.application):
'Produce a code snippet complete with embedding the sample in an '
'application template.',
getEnumName(SnippetType.sample):
'Produce a code sample application complete with embedding the sample in an '
'application template.',
getEnumName(SnippetType.snippet):
'Produce a nicely formatted piece of sample code. Does not embed the '
'sample into an application template.',
},
@ -52,7 +52,7 @@ void main(List<String> argList) {
parser.addOption(
_kOutputOption,
defaultsTo: null,
help: 'The output path for the generated snippet application. Overrides '
help: 'The output path for the generated sample application. Overrides '
'the naming generated by the --package/--library/--element arguments. '
'Metadata will be written alongside in a .json file. '
'The basename of this argument is used as the ID',
@ -60,22 +60,22 @@ void main(List<String> argList) {
parser.addOption(
_kInputOption,
defaultsTo: environment['INPUT'],
help: 'The input file containing the snippet code to inject.',
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 snippet belongs to.',
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 snippet belongs to.',
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 snippet belongs to.',
help: 'The name of the element that this sample belongs to.',
);
parser.addOption(
_kSerialOption,
@ -92,9 +92,9 @@ void main(List<String> argList) {
_kShowDartPad,
defaultsTo: false,
negatable: false,
help: 'Indicates whether DartPad should be included in the snippet\'s '
help: 'Indicates whether DartPad should be included in the sample\'s '
'final HTML output. This flag only applies when the type parameter is '
'"application".',
'"sample".',
);
final ArgResults args = parser.parse(argList);
@ -108,9 +108,9 @@ void main(List<String> argList) {
.firstWhere((SnippetType type) => getEnumName(type) == args[_kTypeOption], orElse: () => null);
assert(snippetType != null, "Unable to find '${args[_kTypeOption]}' in SnippetType enum.");
if (args[_kShowDartPad] == true && snippetType != SnippetType.application) {
if (args[_kShowDartPad] == true && snippetType != SnippetType.sample) {
errorExit('${args[_kTypeOption]} was selected, but the --dartpad flag is only valid '
'for application snippets.');
'for application sample code.');
}
if (args[_kInputOption] == null) {
@ -125,12 +125,12 @@ void main(List<String> argList) {
}
String template;
if (snippetType == SnippetType.application) {
if (snippetType == SnippetType.sample) {
final String templateArg = args[_kTemplateOption] as String;
if (templateArg == null || templateArg.isEmpty) {
stderr.writeln(parser.usage);
errorExit('The --$_kTemplateOption option must be specified on the command '
'line for application snippets.');
'line for application samples.');
}
template = templateArg.replaceAll(RegExp(r'.tmpl$'), '');
}

24
dev/snippets/lib/snippets.dart
View File

@ -48,7 +48,7 @@ class SnippetGenerator {
static DartFormatter formatter = DartFormatter(pageWidth: 80, fixes: StyleFix.all);
/// This returns the output file for a given snippet ID. Only used for
/// [SnippetType.application] snippets.
/// [SnippetType.sample] snippets.
File getOutputFile(String id) => File(path.join(configuration.outputDirectory.path, '$id.dart'));
/// Gets the path to the template file requested.
@ -60,7 +60,7 @@ class SnippetGenerator {
/// Injects the [injections] into the [template], and turning the
/// "description" injection into a comment. Only used for
/// [SnippetType.application] snippets.
/// [SnippetType.sample] snippets.
String interpolateTemplate(List<_ComponentTuple> injections, String template, Map<String, Object> metadata) {
final RegExp moustacheRegExp = RegExp('{{([^}]+)}}');
return template.replaceAllMapped(moustacheRegExp, (Match match) {
@ -99,7 +99,7 @@ class SnippetGenerator {
/// components, and we care about the order of the injections.
///
/// Takes into account the [type] and doesn't substitute in the id and the app
/// if not a [SnippetType.application] snippet.
/// if not a [SnippetType.sample] snippet.
String interpolateSkeleton(SnippetType type, List<_ComponentTuple> injections, String skeleton, Map<String, Object> metadata) {
final List<String> result = <String>[];
const HtmlEscape htmlEscape = HtmlEscape();
@ -133,7 +133,7 @@ class SnippetGenerator {
'element': metadata['element'] as String ?? '',
'app': '',
};
if (type == SnippetType.application) {
if (type == SnippetType.sample) {
substitutions
..['serial'] = metadata['serial']?.toString() ?? '0'
..['app'] = htmlEscape.convert(injections.firstWhere((_ComponentTuple tuple) => tuple.name == 'app').mergedContent);
@ -201,20 +201,20 @@ class SnippetGenerator {
/// comment markers).
///
/// The [type] is the type of snippet to create: either a
/// [SnippetType.application] or a [SnippetType.sample].
/// [SnippetType.sample] or a [SnippetType.snippet].
///
/// [showDartPad] indicates whether DartPad should be shown where possible.
/// Currently, this value only has an effect if [type] is
/// [SnippetType.application], in which case an alternate skeleton file is
/// [SnippetType.sample], in which case an alternate skeleton file is
/// used to create the final HTML output.
///
/// The [template] must not be null if the [type] is
/// [SnippetType.application], and specifies the name of the template to use
/// [SnippetType.sample], and specifies the name of the template to use
/// for the application code.
///
/// The [id] is a string ID to use for the output file, and to tell the user
/// about in the `flutter create` hint. It must not be null if the [type] is
/// [SnippetType.application].
/// [SnippetType.sample].
String generate(
File input,
SnippetType type, {
@ -223,14 +223,14 @@ class SnippetGenerator {
File output,
@required Map<String, Object> metadata,
}) {
assert(template != null || type != SnippetType.application);
assert(template != null || type != SnippetType.sample);
assert(metadata != null && metadata['id'] != null);
assert(input != null);
assert(!showDartPad || type == SnippetType.application,
assert(!showDartPad || type == SnippetType.sample,
'Only application snippets work with dartpad.');
final List<_ComponentTuple> snippetData = parseInput(_loadFileAsUtf8(input));
switch (type) {
case SnippetType.application:
case SnippetType.sample:
final Directory templatesDir = configuration.templatesDirectory;
if (templatesDir == null) {
stderr.writeln('Unable to find the templates directory.');
@ -272,7 +272,7 @@ class SnippetGenerator {
});
metadataFile.writeAsStringSync(jsonEncoder.convert(metadata));
break;
case SnippetType.sample:
case SnippetType.snippet:
break;
}
final String skeleton =

16
dev/snippets/test/configuration_test.dart
View File

@ -32,22 +32,22 @@ void main() {
matches(RegExp(r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]templates')));
});
test('html skeleton file for sample is correct', () async {
expect(
config.getHtmlSkeletonFile(SnippetType.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(SnippetType.sample).path,
matches(RegExp(
r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]sample.html')));
});
test('html skeleton file for app with no dartpad is correct', () async {
expect(
config.getHtmlSkeletonFile(SnippetType.application).path,
matches(RegExp(
r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]application.html')));
});
test('html skeleton file for app with dartpad is correct', () async {
expect(
config.getHtmlSkeletonFile(SnippetType.application, showDartPad: true).path,
config.getHtmlSkeletonFile(SnippetType.sample, showDartPad: true).path,
matches(RegExp(
r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]dartpad-application.html')));
r'[/\\]flutter sdk[/\\]dev[/\\]snippets[/\\]config[/\\]skeletons[/\\]dartpad-sample.html')));
});
});
}

14
dev/snippets/test/snippets_test.dart
View File

@ -37,20 +37,20 @@ main() {
{{code}}
}
''');
configuration.getHtmlSkeletonFile(SnippetType.application).writeAsStringSync('''
configuration.getHtmlSkeletonFile(SnippetType.sample).writeAsStringSync('''
<div>HTML Bits</div>
{{description}}
<pre>{{code}}</pre>
<pre>{{app}}</pre>
<div>More HTML Bits</div>
''');
configuration.getHtmlSkeletonFile(SnippetType.sample).writeAsStringSync('''
configuration.getHtmlSkeletonFile(SnippetType.snippet).writeAsStringSync('''
<div>HTML Bits</div>
{{description}}
<pre>{{code}}</pre>
<div>More HTML Bits</div>
''');
configuration.getHtmlSkeletonFile(SnippetType.application, showDartPad: true).writeAsStringSync('''
configuration.getHtmlSkeletonFile(SnippetType.sample, showDartPad: true).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}}"></iframe>
<div>More HTML Bits</div>
@ -83,7 +83,7 @@ void main() {
final String html = generator.generate(
inputFile,
SnippetType.application,
SnippetType.sample,
template: 'template',
metadata: <String, Object>{
'id': 'id',
@ -126,7 +126,7 @@ void main() {
final String html = generator.generate(
inputFile,
SnippetType.sample,
SnippetType.snippet,
metadata: <String, Object>{'id': 'id'},
);
expect(html, contains('<div>HTML Bits</div>'));
@ -155,7 +155,7 @@ void main() {
final String html = generator.generate(
inputFile,
SnippetType.application,
SnippetType.sample,
showDartPad: true,
template: 'template',
metadata: <String, Object>{'id': 'id'},
@ -185,7 +185,7 @@ void main() {
generator.generate(
inputFile,
SnippetType.application,
SnippetType.sample,
template: 'template',
output: outputFile,
metadata: <String, Object>{'sourcePath': 'some/path.dart', 'id': 'id'},

6
packages/flutter/lib/src/animation/animation.dart
View File

@ -106,7 +106,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].
///
/// {@tool sample}
/// {@tool snippet}
///
/// Given an [AnimationController] `_controller`, the following code creates
/// an `Animation<Alignment>` that swings from top left to top right as the
@ -121,7 +121,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// 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
@ -141,7 +141,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// Animation<Alignment> _alignment2 = _controller.drive(_tween);
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// The following code is exactly equivalent, and is typically clearer when
/// the tweens are created inline, as might be preferred when the tweens have

4
packages/flutter/lib/src/animation/animation_controller.dart
View File

@ -124,7 +124,7 @@ enum AnimationBehavior {
/// This can be used to write code such as the `fadeOutAndUpdateState` method
/// below.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Here is a stateful `Foo` widget. Its [State] uses the
/// [SingleTickerProviderStateMixin] to implement the necessary
@ -175,7 +175,7 @@ enum AnimationBehavior {
/// }
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// The following method (for a [State] subclass) drives two animation
/// controllers using Dart's asynchronous syntax for awaiting [Future] objects:

4
packages/flutter/lib/src/animation/animations.dart
View File

@ -327,7 +327,7 @@ class ReverseAnimation extends Animation<double>
///
/// If you want to apply a [Curve] to a [Tween], consider using [CurveTween].
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following code snippet shows how you can apply a curve to a linear
/// animation produced by an [AnimationController] `controller`.
@ -339,7 +339,7 @@ class ReverseAnimation extends Animation<double>
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// 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

2
packages/flutter/lib/src/animation/curves.dart
View File

@ -318,7 +318,7 @@ class Cubic extends Curve {
/// part of the curve, or hardly at all in another part of the curve, depending
/// on the definition of the curve.
///
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
/// This example shows how to use a [Curve2D] to modify the position of a widget
/// so that it can follow an arbitrary path.
///

6
packages/flutter/lib/src/animation/tween.dart
View File

@ -128,7 +128,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// which results in two separate [Animation] objects, each configured with a
/// single [Tween].
///
/// {@tool sample}
/// {@tool snippet}
///
/// Suppose `_controller` is an [AnimationController], and we want to create an
/// [Animation<Offset>] that is controlled by that controller, and save it in
@ -143,7 +143,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// _animation = Tween<Offset>(
@ -413,7 +413,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.)
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following code snippet shows how you can apply a curve to a linear
/// animation produced by an [AnimationController] `controller`:

4
packages/flutter/lib/src/animation/tween_sequence.dart
View File

@ -17,7 +17,7 @@ import 'tween.dart';
/// animation's duration. Each tween defines the animation's value during the
/// interval indicated by its weight.
///
/// {@tool sample}
/// {@tool snippet}
/// This example defines an animation that uses an easing curve to interpolate
/// between 5.0 and 10.0 during the first 40% of the animation, remains at 10.0
/// for the next 20%, and then returns to 5.0 for the final 40%.
@ -136,7 +136,7 @@ class TweenSequenceItem<T> {
/// animation's duration indicated by [weight] and this item's position
/// in the list of items.
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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:

4
packages/flutter/lib/src/cupertino/app.dart
View File

@ -195,7 +195,7 @@ class CupertinoApp extends StatefulWidget {
final bool debugShowCheckedModeBanner;
/// {@macro flutter.widgets.widgetsApp.shortcuts}
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to add a single shortcut for
/// [LogicalKeyboardKey.select] to the default shortcuts without needing to
/// add your own [Shortcuts] widget.
@ -223,7 +223,7 @@ class CupertinoApp extends StatefulWidget {
final Map<LogicalKeySet, Intent> shortcuts;
/// {@macro flutter.widgets.widgetsApp.actions}
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to add a single action handling an
/// [ActivateAction] to the default actions without needing to
/// add your own [Actions] widget.

6
packages/flutter/lib/src/cupertino/colors.dart
View File

@ -592,7 +592,7 @@ class CupertinoColors {
/// [CupertinoDynamicColor.resolve] against its own [BuildContext], on a best-effort
/// basis.
///
/// {@tool sample}
/// {@tool snippet}
/// By default a [CupertinoButton] has no background color. The following sample
/// code shows how to build a [CupertinoButton] that appears white in light mode,
/// and changes automatically to black in dark mode.
@ -617,7 +617,7 @@ class CupertinoColors {
/// implicitly resolves all the colors used in the retrieved [CupertinoThemeData],
/// before returning it.
///
/// {@tool sample}
/// {@tool snippet}
/// The following code sample creates a [Container] with the `primaryColor` of the
/// current theme. If `primaryColor` is a [CupertinoDynamicColor], the container
/// will be adaptive, thanks to [CupertinoTheme.of]: it will switch to `primaryColor`'s
@ -643,7 +643,7 @@ class CupertinoColors {
/// the colors used in the [Border] have to be resolved manually before being passed
/// to [CupertinoNavigationBar]'s constructor.
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following code samples demonstrate two cases where you have to manually
/// resolve a [CupertinoDynamicColor].

2
packages/flutter/lib/src/cupertino/context_menu.dart
View File

@ -172,7 +172,7 @@ class CupertinoContextMenu extends StatefulWidget {
/// child parameter provides access to the child displayed when the
/// CupertinoContextMenu is closed.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Below is an example of using `previewBuilder` to show an image tile that's
/// similar to each tile in the iOS iPhoto app's context menu. Several of

2
packages/flutter/lib/src/cupertino/scrollbar.dart
View File

@ -86,7 +86,7 @@ class CupertinoScrollbar extends StatefulWidget {
/// Here is an example of using the `controller` parameter to enable
/// scrollbar dragging for multiple independent ListViews:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// final ScrollController _controllerOne = ScrollController();

2
packages/flutter/lib/src/cupertino/segmented_control.dart
View File

@ -122,7 +122,7 @@ class CupertinoSegmentedControl<T> extends StatefulWidget {
/// the parent [StatefulWidget] using the [State.setState] method, so that
/// the parent gets rebuilt; for example:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class SegmentedControlExample extends StatefulWidget {

4
packages/flutter/lib/src/cupertino/slider.dart
View File

@ -117,7 +117,7 @@ class CupertinoSlider extends StatefulWidget {
/// The value passed will be the last [value] that the slider had before the
/// change began.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// CupertinoSlider(
@ -149,7 +149,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// CupertinoSlider(

2
packages/flutter/lib/src/cupertino/sliding_segmented_control.dart
View File

@ -178,7 +178,7 @@ class CupertinoSlidingSegmentedControl<T> extends StatefulWidget {
/// the parent [StatefulWidget] using the [State.setState] method, so that
/// the parent gets rebuilt; for example:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class SegmentedControlExample extends StatefulWidget {

2
packages/flutter/lib/src/cupertino/switch.dart
View File

@ -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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample shows how to use a [CupertinoSwitch] in a [ListTile]. The
/// [MergeSemantics] is used to turn the entire [ListTile] into a single item

4
packages/flutter/lib/src/cupertino/tab_scaffold.dart
View File

@ -15,7 +15,7 @@ import 'theme.dart';
/// [CupertinoTabController] controls, as well as the currently selected tab item of
/// its [CupertinoTabBar].
///
/// {@tool sample}
/// {@tool snippet}
///
/// [CupertinoTabController] can be used to switch tabs:
///
@ -135,7 +135,7 @@ class CupertinoTabController extends ChangeNotifier {
/// (via [State.setState], for instance) from its descendant rather than from
/// its ancestor.
///
/// {@tool sample}
/// {@tool snippet}
///
/// A sample code implementing a typical iOS information architecture with tabs.
///

2
packages/flutter/lib/src/cupertino/text_field.dart
View File

@ -133,7 +133,7 @@ class _CupertinoTextFieldSelectionGestureDetectorBuilder extends TextSelectionGe
/// [controller]. For example, to set the initial value of the text field, use
/// a [controller] that already contains some text such as:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class MyPrefilledText extends StatefulWidget {

6
packages/flutter/lib/src/foundation/annotations.dart
View File

@ -16,7 +16,7 @@
///
/// A class can have multiple categories.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// /// A copper coffee pot, as desired by Ben Turpin.
@ -54,7 +54,7 @@ class Category {
///
/// Each class should only have one [DocumentationIcon].
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// /// Utility class for beginning a dream-sharing sequence.
@ -87,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// /// A famous cat.

4
packages/flutter/lib/src/foundation/binding.dart
View File

@ -453,7 +453,7 @@ abstract class BindingBase {
/// not wrapped in a guard that allows the tree shaker to remove it (see
/// sample code below).
///
/// {@tool sample}
/// {@tool snippet}
/// The following code registers a service extension that is only included in
/// debug builds.
///
@ -467,7 +467,7 @@ abstract class BindingBase {
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// A service extension registered with the following code snippet is
/// available in debug and profile mode.
///

12
packages/flutter/lib/src/foundation/diagnostics.dart
View File

@ -1716,7 +1716,7 @@ abstract class DiagnosticsNode {
/// Debugging message displayed like a property.
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following two properties are better expressed using this
/// [MessageProperty] class, rather than [StringProperty], as the intent is to
@ -1728,7 +1728,7 @@ abstract class DiagnosticsNode {
/// var usefulness = MessageProperty('usefulness ratio', 'no metrics collected yet (never painted)');
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// On the other hand, [StringProperty] is better suited when the property has a
/// concrete value that is a string:
@ -2055,7 +2055,7 @@ class PercentProperty extends DoubleProperty {
/// when `visible` is false and nothing when visible is true, in contrast to
/// `visible: true` or `visible: false`.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// FlagProperty(
@ -2065,7 +2065,7 @@ class PercentProperty extends DoubleProperty {
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// [FlagProperty] should also be used instead of [DiagnosticsProperty<bool>]
/// if showing the bool value would not clearly indicate the meaning of the
@ -2969,7 +2969,7 @@ String describeIdentity(Object object) => '${object.runtimeType}#${shortHash(obj
///
/// Strips off the enum class name from the `enumEntry.toString()`.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// enum Day {
@ -3189,7 +3189,7 @@ mixin DiagnosticableMixin {
/// `toString` method implementation works fine using [DiagnosticsProperty]
/// directly.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows best practices for implementing [debugFillProperties]
/// illustrating use of all common [DiagnosticsProperty] subclasses and all

2
packages/flutter/lib/src/foundation/licenses.dart
View File

@ -66,7 +66,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// For example, the BSD license in this format could be encoded as follows:
///

2
packages/flutter/lib/src/foundation/stack_frame.dart
View File

@ -8,7 +8,7 @@ import 'package:meta/meta.dart';
/// A object representation of a frame from a stack trace.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example creates a traversable list of parsed [StackFrame] objects from
/// the current [StackTrace].

2
packages/flutter/lib/src/material/about.dart
View File

@ -33,7 +33,7 @@ import 'theme.dart';
///
/// If your application does not have a [Drawer], you should provide an
/// affordance to call [showAboutDialog] or (at least) [showLicensePage].
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
///
/// This sample shows two ways to open [AboutDialog]. The first one
/// uses an [AboutListTile], and the second uses the [showAboutDialog] function.

2
packages/flutter/lib/src/material/animated_icons/animated_icons.dart
View File

@ -18,7 +18,7 @@ part of material_animated_icons;
///
/// {@youtube 560 315 https://www.youtube.com/watch?v=pJcbh8pbvJs}
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// AnimatedIcon(

10
packages/flutter/lib/src/material/app.dart
View File

@ -77,7 +77,7 @@ enum ThemeMode {
/// If [home], [routes], [onGenerateRoute], and [onUnknownRoute] are all null,
/// and [builder] is not null, then no [Navigator] is created.
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [MaterialApp] that disables the "debug"
/// banner with a [home] route that will be displayed when the app is launched.
///
@ -95,7 +95,7 @@ enum ThemeMode {
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [MaterialApp] that uses the [routes]
/// `Map` to define the "home" route and an "about" route.
///
@ -121,7 +121,7 @@ enum ThemeMode {
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [MaterialApp] that defines a [theme] that
/// will be used for material widgets in the app.
///
@ -458,7 +458,7 @@ class MaterialApp extends StatefulWidget {
final bool debugShowCheckedModeBanner;
/// {@macro flutter.widgets.widgetsApp.shortcuts}
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to add a single shortcut for
/// [LogicalKeyboardKey.select] to the default shortcuts without needing to
/// add your own [Shortcuts] widget.
@ -486,7 +486,7 @@ class MaterialApp extends StatefulWidget {
final Map<LogicalKeySet, Intent> shortcuts;
/// {@macro flutter.widgets.widgetsApp.actions}
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to add a single action handling an
/// [ActivateAction] to the default actions without needing to
/// add your own [Actions] widget.

6
packages/flutter/lib/src/material/app_bar.dart
View File

@ -214,7 +214,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].
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following code shows how the drawer button could be manually specified
/// instead of relying on [automaticallyImplyLeading]:
@ -835,7 +835,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This is an example that could be included in a [CustomScrollView]'s
/// [CustomScrollView.slivers] list:
@ -966,7 +966,7 @@ class SliverAppBar extends StatefulWidget {
/// For less common operations, consider using a [PopupMenuButton] as the
/// last action.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Scaffold(

2
packages/flutter/lib/src/material/bottom_app_bar.dart
View File

@ -21,7 +21,7 @@ import 'theme.dart';
///
/// Typically used with a [Scaffold] and a [FloatingActionButton].
///
/// {@tool sample}
/// {@tool snippet}
/// ```dart
/// Scaffold(
/// bottomNavigationBar: BottomAppBar(

2
packages/flutter/lib/src/material/bottom_navigation_bar.dart
View File

@ -62,7 +62,7 @@ enum BottomNavigationBarType {
/// case it's assumed that each item will have a different background color
/// and that background color will contrast well with white.
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// This example shows a [BottomNavigationBar] as it is used within a [Scaffold]
/// widget. The [BottomNavigationBar] has three [BottomNavigationBarItem]
/// widgets and the [currentIndex] is set to index 0. The selected item is

2
packages/flutter/lib/src/material/bottom_sheet.dart
View File

@ -457,7 +457,7 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_modal_bottom_sheet.mp4}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This example demonstrates how to use `showModalBottomSheet` to display a
/// bottom sheet that obscures the content behind it when a user taps a button.

4
packages/flutter/lib/src/material/card.dart
View File

@ -19,7 +19,7 @@ import 'theme.dart';
/// 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_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows creation of a [Card] widget that shows album information
/// and two actions.
@ -59,7 +59,7 @@ import 'theme.dart';
/// Sometimes the primary action area of a card is the card itself. Cards can be
/// one large touch target that shows a detail screen when tapped.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows creation of a [Card] widget that can be tapped. When
/// tapped this [Card]'s [InkWell] displays an "ink splash" that fills the

6
packages/flutter/lib/src/material/checkbox_list_tile.dart
View File

@ -37,7 +37,7 @@ import 'theme_data.dart';
/// To show the [CheckboxListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![CheckboxListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile.png)
///
@ -82,7 +82,7 @@ import 'theme_data.dart';
/// into one. Therefore, it may be necessary to create a custom radio tile
/// widget to accommodate similar use cases.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![Checkbox list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile_semantics.png)
///
@ -166,7 +166,7 @@ import 'theme_data.dart';
/// combining [Checkbox] with other widgets, such as [Text], [Padding] and
/// [InkWell].
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![Custom checkbox list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile_custom.png)
///

16
packages/flutter/lib/src/material/chip.dart
View File

@ -192,7 +192,7 @@ abstract class DeletableChipAttributes {
/// that the user tapped the delete button. In order to delete the chip, you
/// have to do something similar to the following sample:
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// This sample shows how to use [onDeleted] to remove an entry when the
/// delete button is tapped.
@ -341,7 +341,7 @@ abstract class SelectableChipAttributes {
/// The [onSelected] and [TappableChipAttributes.onPressed] callbacks must not
/// both be specified at the same time.
///
/// {@tool sample}
/// {@tool snippet}
///
/// A [StatefulWidget] that illustrates use of onSelected in an [InputChip].
///
@ -479,7 +479,7 @@ abstract class TappableChipAttributes {
/// taps on the label or avatar parts of the chip. If [onPressed] is null,
/// then the chip will be disabled.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class Blacksmith extends StatelessWidget {
@ -525,7 +525,7 @@ abstract class TappableChipAttributes {
/// [MaterialApp] and [Scaffold]. The [label] and [clipBehavior] arguments must
/// not be null.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Chip(
@ -665,7 +665,7 @@ class Chip extends StatelessWidget implements ChipAttributes, DeletableChipAttri
/// * In a horizontally scrollable list, like a [ListView] whose
/// scrollDirection is [Axis.horizontal].
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// InputChip(
@ -858,7 +858,7 @@ class InputChip extends StatelessWidget
/// Requires one of its ancestors to be a [Material] widget. The [selected] and
/// [label] arguments must not be null.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class MyThreeOptions extends StatefulWidget {
@ -1038,7 +1038,7 @@ class ChoiceChip extends StatelessWidget
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class ActorFilterEntry {
@ -1263,7 +1263,7 @@ class FilterChip extends StatelessWidget
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// ActionChip(

4
packages/flutter/lib/src/material/chip_theme.dart
View File

@ -62,7 +62,7 @@ class ChipTheme extends InheritedTheme {
/// Defaults to the ambient [ThemeData.chipTheme] if there is no
/// [ChipTheme] in the given build context.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class Spaceship extends StatelessWidget {
@ -120,7 +120,7 @@ class ChipTheme extends InheritedTheme {
/// you get from [ChipTheme.of], or create an entirely new one with
/// [ChipThemeData..fromDefaults].
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class CarColor extends StatefulWidget {

4
packages/flutter/lib/src/material/circle_avatar.dart
View File

@ -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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// If the avatar is to have an image, the image should be specified in the
/// [backgroundImage] property:
@ -31,7 +31,7 @@ import 'theme_data.dart';
///
/// The image will be cropped to have a circle shape.
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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]:

74
packages/flutter/lib/src/material/colors.dart
View File

@ -104,7 +104,7 @@ class MaterialAccentColor extends ColorSwatch<int> {
/// In addition, a series of blacks and whites with common opacities are
/// available. For example, [black54] is a pure black with 54% opacity.
///
/// {@tool sample}
/// {@tool snippet}
///
/// To select a specific color from one of the swatches, index into the swatch
/// using an integer for the specific color desired, as follows:
@ -113,7 +113,7 @@ class MaterialAccentColor extends ColorSwatch<int> {
/// Color selection = Colors.green[400]; // Selects a mid-range green.
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// Each [ColorSwatch] constant is a color and can used directly. For example:
///
@ -428,7 +428,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pink.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pinkAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -472,7 +472,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pink.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pinkAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -510,7 +510,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.purple.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.purpleAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -554,7 +554,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.purple.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.purpleAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -592,7 +592,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pink.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pinkAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -636,7 +636,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pink.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.pinkAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -674,7 +674,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.indigo.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.indigoAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -718,7 +718,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.indigo.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.indigoAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -756,7 +756,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepPurple.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepPurpleAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -800,7 +800,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepPurple.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepPurpleAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -840,7 +840,7 @@ class Colors {
///
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.blueGrey.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -884,7 +884,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lightBlue.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lightBlueAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -922,7 +922,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyan.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyanAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -966,7 +966,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyan.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyanAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1006,7 +1006,7 @@ class Colors {
///
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.blueGrey.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1050,7 +1050,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.teal.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.tealAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1088,7 +1088,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyan.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyanAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1132,7 +1132,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyan.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.cyanAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1173,7 +1173,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lime.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.limeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1220,7 +1220,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lime.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.limeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1258,7 +1258,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lime.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.limeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1302,7 +1302,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.lime.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.limeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1340,7 +1340,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.yellow.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.yellowAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1384,7 +1384,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.yellow.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.yellowAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1422,7 +1422,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.amber.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.amberAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1466,7 +1466,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.amber.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.amberAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1504,7 +1504,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.orange.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.orangeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1548,7 +1548,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.orange.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.orangeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1588,7 +1588,7 @@ class Colors {
///
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.brown.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1632,7 +1632,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepOrange.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.deepOrangeAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1672,7 +1672,7 @@ class Colors {
///
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.brown.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1716,7 +1716,7 @@ class Colors {
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.red.png)
/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/Colors.redAccent.png)
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1753,7 +1753,7 @@ class Colors {
///
/// This swatch has no corresponding accent color and swatch.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1800,7 +1800,7 @@ class Colors {
/// used for raised button while pressed in light themes, and 850 is used for
/// the background color of the dark theme. See [ThemeData.brightness].
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(
@ -1848,7 +1848,7 @@ class Colors {
///
/// This swatch has no corresponding accent swatch.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Icon(

2
packages/flutter/lib/src/material/data_table.dart
View File

@ -225,7 +225,7 @@ class DataCell {
/// [PaginatedDataTable] which automatically splits the data into
/// multiple pages.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to display a [DataTable] with three columns: name, age, and
/// role. The columns are defined by three [DataColumn] objects. The table

2
packages/flutter/lib/src/material/date_picker.dart
View File

@ -1094,7 +1094,7 @@ typedef SelectableDayPredicate = bool Function(DateTime day);
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_date_picker.mp4}
///
/// {@tool sample}
/// {@tool snippet}
/// Show a date picker with the dark theme.
///
/// ```dart

8
packages/flutter/lib/src/material/dialog.dart
View File

@ -161,7 +161,7 @@ class Dialog extends StatelessWidget {
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/alert_dialog.mp4}
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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.
@ -301,7 +301,7 @@ class AlertDialog extends StatelessWidget {
/// [buttonPadding] may contribute to the padding on the edges of [actions] as
/// well.
///
/// {@tool sample}
/// {@tool snippet}
/// This is an example of a set of actions aligned with the content widget.
/// ```dart
/// AlertDialog(
@ -488,7 +488,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// SimpleDialogOption(
@ -555,7 +555,7 @@ class SimpleDialogOption extends StatelessWidget {
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/simple_dialog.mp4}
///
/// {@tool sample}
/// {@tool snippet}
///
/// In this example, the user is asked to select between two options. These
/// options are represented as an enum. The [showDialog] method here returns

8
packages/flutter/lib/src/material/divider.dart
View File

@ -22,7 +22,7 @@ import 'theme.dart';
/// The box's total height is controlled by [height]. The appropriate
/// padding is automatically computed from the height.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to display a Divider between an orange and blue box
/// inside a column. The Divider is 20 logical pixels in height and contains a
@ -124,7 +124,7 @@ class Divider extends StatelessWidget {
/// If this is null, then the [DividerThemeData.color] is used. If that is
/// also null, then [ThemeData.dividerColor] is used.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Divider(
@ -145,7 +145,7 @@ class Divider extends StatelessWidget {
/// If [context] is null, the default color of [BorderSide] is used and the
/// default width of 0.0 is used.
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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
@ -274,7 +274,7 @@ class VerticalDivider extends StatelessWidget {
/// If this is null, then the [DividerThemeData.color] is used. If that is
/// also null, then [ThemeData.dividerColor] is used.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Divider(

2
packages/flutter/lib/src/material/drawer.dart
View File

@ -61,7 +61,7 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/drawer.mp4}
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [Scaffold] that contains an [AppBar] and
/// a [Drawer]. A user taps the "menu" icon in the [AppBar] to open the
/// [Drawer]. The [Drawer] displays four items: A header and three menu items.

6
packages/flutter/lib/src/material/dropdown.dart
View File

@ -707,7 +707,7 @@ class DropdownButtonHideUnderline extends InheritedWidget {
/// dropdown's value. It should also call [State.setState] to rebuild the
/// dropdown with the new value.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// This sample shows a `DropdownButton` with a large arrow icon,
/// purple text style, and bold purple underline, whose value is one of "One",
@ -865,7 +865,7 @@ class DropdownButton<T> extends StatefulWidget {
/// from the list corresponds to the [DropdownMenuItem] of the same index
/// in [items].
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// This sample shows a `DropdownButton` with a button with [Text] that
/// corresponds to but is unique from [DropdownMenuItem].
@ -916,7 +916,7 @@ class DropdownButton<T> extends StatefulWidget {
/// To use a separate text style for selected item when it's displayed within
/// the dropdown button,, consider using [selectedItemBuilder].
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// This sample shows a `DropdownButton` with a dropdown button text style
/// that is different than its menu items.

4
packages/flutter/lib/src/material/expansion_panel.dart
View File

@ -140,7 +140,7 @@ class ExpansionPanelRadio extends ExpansionPanel {
/// Note that [expansionCallback] behaves differently for [ExpansionPanelList]
/// and [ExpansionPanelList.radio].
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// Here is a simple example of how to implement ExpansionPanelList.
///
@ -242,7 +242,7 @@ class ExpansionPanelList extends StatefulWidget {
/// arguments must not be null. The [children] objects must be instances
/// of [ExpansionPanelRadio].
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// Here is a simple example of how to implement ExpansionPanelList.radio.
///

4
packages/flutter/lib/src/material/feedback.dart
View File

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

4
packages/flutter/lib/src/material/flat_button.dart
View File

@ -40,7 +40,7 @@ import 'theme_data.dart';
///
/// The [clipBehavior] argument must not be null.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows a simple [FlatButton].
///
@ -58,7 +58,7 @@ import 'theme_data.dart';
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows a [FlatButton] that is normally white-on-blue,
/// with splashes rendered in a different shade of blue.

2
packages/flutter/lib/src/material/flexible_space_bar.dart
View File

@ -50,7 +50,7 @@ enum StretchMode {
/// [FlexibleSpaceBar.createSettings], to convey sizing information down to the
/// [FlexibleSpaceBar].
///
/// {@tool snippet --template=freeform}
/// {@tool sample --template=freeform}
/// This sample application demonstrates the different features of the
/// [FlexibleSpaceBar] when used in a [SliverAppBar]. This app bar is configured
/// to stretch into the overscroll space, and uses the

4
packages/flutter/lib/src/material/floating_action_button.dart
View File

@ -57,7 +57,7 @@ class _DefaultHeroTag {
/// disabled. Consider changing the [backgroundColor] if disabling the floating
/// action button.
///
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
/// This example shows how to display a [FloatingActionButton] in a
/// [Scaffold], with a pink [backgroundColor] and a thumbs up [Icon].
///
@ -84,7 +84,7 @@ class _DefaultHeroTag {
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
/// This example shows how to make an extended [FloatingActionButton] in a
/// [Scaffold], with a pink [backgroundColor], a thumbs up [Icon] and a
/// [Text] label that reads "Approve".

4
packages/flutter/lib/src/material/icon_button.dart
View File

@ -39,7 +39,7 @@ const double _kMinButtonSize = kMinInteractiveDimension;
/// requirements in the Material Design specification. The [alignment] controls
/// how the icon itself is positioned within the hit region.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// This sample shows an `IconButton` that uses the Material icon "volume_up" to
/// increase the volume.
@ -83,7 +83,7 @@ const double _kMinButtonSize = kMinInteractiveDimension;
/// the underlying [Material] along with the splash and highlight
/// [InkResponse] contributed by descendant widgets.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// In this sample the icon button's background color is defined with an [Ink]
/// widget whose child is an [IconButton]. The icon button's filled background

2
packages/flutter/lib/src/material/icons.dart
View File

@ -21,7 +21,7 @@ import 'package:flutter/widgets.dart';
/// uses-material-design: true
/// ```
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [Row] of [Icon]s in different colors and
/// sizes. The first [Icon] uses a [Icon.semanticLabel] to announce in accessibility
/// modes like TalkBack and VoiceOver.

4
packages/flutter/lib/src/material/ink_decoration.dart
View File

@ -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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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:
@ -68,7 +68,7 @@ import 'material.dart';
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// The following example shows how an image can be printed on a [Material]
/// widget with an [InkWell] above it:

2
packages/flutter/lib/src/material/ink_well.dart
View File

@ -847,7 +847,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> with AutomaticKe
///
/// An example of this situation is as follows:
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// Tap the container to cause it to grow. Then, tap it again and hold before
/// the widget reaches its maximum size to observe the clipped ink splash.

8
packages/flutter/lib/src/material/input_decorator.dart
View File

@ -2305,7 +2305,7 @@ class _InputDecoratorState extends State<InputDecorator> with TickerProviderStat
/// to describe their decoration. (In fact, this class is merely the
/// configuration of an [InputDecorator], which does all the heavy lifting.)
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to style a `TextField` using an `InputDecorator`. The
/// TextField displays a "send message" icon to the left of the input area,
@ -2330,7 +2330,7 @@ class _InputDecoratorState extends State<InputDecorator> with TickerProviderStat
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to style a "collapsed" `TextField` using an
/// `InputDecorator`. The collapsed `TextField` surrounds the hint text and
@ -2350,7 +2350,7 @@ class _InputDecoratorState extends State<InputDecorator> with TickerProviderStat
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to create a `TextField` with hint text, a red border
/// on all sides, and an error message. To display a red border and error
@ -2371,7 +2371,7 @@ class _InputDecoratorState extends State<InputDecorator> with TickerProviderStat
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to style a `TextField` with a round border and
/// additional text before and after the input area. It displays "Prefix" before

10
packages/flutter/lib/src/material/list_tile.dart
View File

@ -195,7 +195,7 @@ enum ListTileControlAffinity {
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example uses a [ListView] to demonstrate different configurations of
/// [ListTile]s in [Card]s.
@ -254,7 +254,7 @@ enum ListTileControlAffinity {
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// 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
@ -285,7 +285,7 @@ enum ListTileControlAffinity {
/// that are large enough, but it is up to the developer to ensure that
/// their widgets follow the Material spec.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Here is an example of a one-line, non-[dense] ListTile with a
/// tappable leading widget that adheres to accessibility requirements and
@ -317,7 +317,7 @@ enum ListTileControlAffinity {
/// you're looking for, it's easy to create custom list items with a
/// combination of other widgets, such as [Row]s and [Column]s.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// Here is an example of a custom list item that resembles a Youtube related
/// video list item created with [Expanded] and [Container] widgets.
@ -438,7 +438,7 @@ enum ListTileControlAffinity {
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// Here is an example of an article list item with multiline titles and
/// subtitles. It utilizes [Row]s and [Column]s, as well as [Expanded] and

4
packages/flutter/lib/src/material/material_state.dart
View File

@ -85,7 +85,7 @@ typedef MaterialPropertyResolver<T> = T Function(Set<MaterialState> states);
/// This should only be used as parameters when they are documented to take
/// [MaterialStateColor], otherwise only the default state will be used.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows how you could pass a `MaterialStateColor` to `FlatButton.textColor`.
/// Here, the text color will be `Colors.blue[900]` when the button is being
@ -119,7 +119,7 @@ abstract class MaterialStateColor extends Color implements MaterialStateProperty
/// to provide a `defaultValue` to the super constructor, so that we can know
/// at compile-time what the value of the default [Color] is.
///
/// {@tool sample}
/// {@tool snippet}
///
/// In this next example, we see how you can create a `MaterialStateColor` by
/// extending the abstract class and overriding the `resolve` method.

6
packages/flutter/lib/src/material/popup_menu.dart
View File

@ -178,7 +178,7 @@ class _RenderMenuItem extends RenderShiftedBox {
/// [PopupMenuItem] is kMinInteractiveDimension pixels high. If you use a widget
/// with a different height, it must be specified in the [height] property.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Here, a [Text] widget is used with a popup menu item. The `WhyFarther` type
/// is an enum, not shown here.
@ -339,7 +339,7 @@ class PopupMenuItemState<T, W extends PopupMenuItem<T>> extends State<W> {
/// layout uses [ListTile]; the checkmark is an [Icons.done] icon, shown in the
/// [ListTile.leading] position.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Suppose a `Commands` enum exists that lists the possible commands from a
/// particular popup menu, including `Commands.heroAndScholar` and
@ -885,7 +885,7 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
/// If both are null, then a standard overflow icon is created (depending on the
/// platform).
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows a menu with four items, selecting between an enum's
/// values and setting a `_selection` field based on the selection.

2
packages/flutter/lib/src/material/radio.dart
View File

@ -29,7 +29,7 @@ const double _kInnerRadius = 4.5;
/// will respond to [onChanged] by calling [State.setState] to update the
/// radio button's [groupValue].
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// Here is an example of Radio widgets wrapped in ListTiles, which is similar
/// to what you could get with the RadioListTile widget.

6
packages/flutter/lib/src/material/radio_list_tile.dart
View File

@ -40,7 +40,7 @@ import 'theme_data.dart';
/// To show the [RadioListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// ![RadioListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile.png)
///
@ -92,7 +92,7 @@ import 'theme_data.dart';
/// into one. Therefore, it may be necessary to create a custom radio tile
/// widget to accommodate similar use cases.
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// ![Radio list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile_semantics.png)
///
@ -196,7 +196,7 @@ import 'theme_data.dart';
/// combining [Radio] with other widgets, such as [Text], [Padding] and
/// [InkWell].
///
/// {@tool snippet --template=stateful_widget_scaffold}
/// {@tool sample --template=stateful_widget_scaffold}
///
/// ![Custom radio list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile_custom.png)
///

2
packages/flutter/lib/src/material/raised_button.dart
View File

@ -31,7 +31,7 @@ import 'theme_data.dart';
/// Raised buttons have a minimum size of 88.0 by 36.0 which can be overridden
/// with [ButtonTheme].
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This sample shows how to render a disabled RaisedButton, an enabled RaisedButton
/// and lastly a RaisedButton with gradient background.

8
packages/flutter/lib/src/material/range_slider.dart
View File

@ -155,7 +155,7 @@ class RangeSlider extends StatefulWidget {
/// [StatefulWidget] using the [State.setState] method, so that the parent
/// gets rebuilt; for example:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// RangeSlider(
@ -187,7 +187,7 @@ class RangeSlider extends StatefulWidget {
/// The values passed will be the last [values] that the slider had before the
/// change began.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// RangeSlider(
@ -222,7 +222,7 @@ class RangeSlider extends StatefulWidget {
/// [onChanged] for that). Rather, it should be used to know when the user has
/// completed selecting a new [values] by ending a drag or a click.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// RangeSlider(
@ -310,7 +310,7 @@ class RangeSlider extends StatefulWidget {
/// This is used by accessibility frameworks like TalkBack on Android to
/// inform users what the currently selected value is with more context.
///
/// {@tool sample}
/// {@tool snippet}
///
/// In the example below, a slider for currency values is configured to
/// announce a value with a currency label.

2
packages/flutter/lib/src/material/reorderable_list.dart
View File

@ -27,7 +27,7 @@ import 'material_localizations.dart';
///
/// {@youtube 560 315 https://www.youtube.com/watch?v=3fB1mxOsqJE}
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// final List<MyDataObject> backingList = <MyDataObject>[/* ... */];

18
packages/flutter/lib/src/material/scaffold.dart
View File

@ -803,7 +803,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// [ScaffoldState] for the current [BuildContext] via [Scaffold.of] and use the
/// [ScaffoldState.showSnackBar] and [ScaffoldState.showBottomSheet] functions.
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// This example shows a [Scaffold] with a [body] and [FloatingActionButton].
/// The [body] is a [Text] placed in a [Center] in order to center the text
/// within the [Scaffold]. The [FloatingActionButton] is connected to a
@ -832,7 +832,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// This example shows a [Scaffold] with a blueGrey [backgroundColor], [body]
/// and [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in
/// order to center the text within the [Scaffold]. The [FloatingActionButton]
@ -862,7 +862,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// This example shows a [Scaffold] with an [AppBar], a [BottomAppBar] and a
/// [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in order
/// to center the text within the [Scaffold]. The [FloatingActionButton] is
@ -932,7 +932,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// scaffold with a differently titled AppBar. It would be better to add a
/// listener to the [TabController] that updates the AppBar.
///
/// {@tool sample}
/// {@tool snippet}
/// Add a listener to the app's tab controller so that the [AppBar] title of the
/// app's one and only scaffold is reset each time a new tab is selected.
///
@ -1097,7 +1097,7 @@ class Scaffold extends StatefulWidget {
/// To open the drawer programmatically, use the [ScaffoldState.openDrawer]
/// function.
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// To disable the drawer edge swipe, set the [Scaffold.drawerEdgeWidth]
/// to 0. Then, use [ScaffoldState.openDrawer] to open the drawer.
///
@ -1138,7 +1138,7 @@ class Scaffold extends StatefulWidget {
/// To open the drawer programmatically, use the [ScaffoldState.openEndDrawer]
/// function.
///
/// {@tool snippet --template=stateful_widget_material}
/// {@tool sample --template=stateful_widget_material}
/// To disable the drawer edge swipe, set the [Scaffold.drawerEdgeWidth]
/// to 0. Then, use [ScaffoldState.openEndDrawer] to open the drawer.
///
@ -1267,7 +1267,7 @@ class Scaffold extends StatefulWidget {
/// The state from the closest instance of this class that encloses the given context.
///
/// {@tool snippet --template=freeform}
/// {@tool sample --template=freeform}
/// Typical usage of the [Scaffold.of] function is to call it from within the
/// `build` method of a child of a [Scaffold].
///
@ -1320,7 +1320,7 @@ class Scaffold extends StatefulWidget {
/// ```
/// {@end-tool}
///
/// {@tool snippet --template=stateless_widget_material}
/// {@tool sample --template=stateless_widget_material}
/// When the [Scaffold] is actually created in the same `build` function, the
/// `context` argument to the `build` function can't be used to find the
/// [Scaffold] (since it's "above" the widget being returned in the widget
@ -1877,7 +1877,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
///
/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_bottom_sheet.mp4}
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
///
/// This example demonstrates how to use `showBottomSheet` to display a
/// bottom sheet when a user taps a button. It also demonstrates how to

2
packages/flutter/lib/src/material/search.dart
View File

@ -92,7 +92,7 @@ abstract class SearchDelegate<T> {
/// Constructor to be called by subclasses which may specify [searchFieldLabel], [keyboardType] and/or
/// [textInputAction].
///
/// {@tool sample}
/// {@tool snippet}
/// ```dart
/// class CustomSearchHintDelegate extends SearchDelegate {
/// CustomSearchHintDelegate({

4
packages/flutter/lib/src/material/selectable_text.dart
View File

@ -143,7 +143,7 @@ class _SelectableTextSelectionGestureDetectorBuilder extends TextSelectionGestur
/// behavior is useful, for example, to make the text bold while using the
/// default font family and size.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// SelectableText(
@ -159,7 +159,7 @@ class _SelectableTextSelectionGestureDetectorBuilder extends TextSelectionGestur
/// that follows displays "Hello beautiful world" with different styles
/// for each word.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// const SelectableText.rich(

8
packages/flutter/lib/src/material/slider.dart
View File

@ -180,7 +180,7 @@ class Slider extends StatefulWidget {
/// [StatefulWidget] using the [State.setState] method, so that the parent
/// gets rebuilt; for example:
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Slider(
@ -215,7 +215,7 @@ class Slider extends StatefulWidget {
/// The value passed will be the last [value] that the slider had before the
/// change began.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Slider(
@ -248,7 +248,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// Slider(
@ -348,7 +348,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// In the example below, a slider for currency values is configured to
/// announce a value with a currency label.

4
packages/flutter/lib/src/material/slider_theme.dart
View File

@ -155,7 +155,7 @@ class SliderTheme extends InheritedTheme {
/// Defaults to the ambient [ThemeData.sliderTheme] if there is no
/// [SliderTheme] in the given build context.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class Launch extends StatefulWidget {
@ -316,7 +316,7 @@ class SliderThemeData extends Diagnosticable {
/// [copyWith] on the one you get from [SliderTheme.of], or create an
/// entirely new one with [SliderThemeData.fromPrimaryColors].
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// class Blissful extends StatefulWidget {

2
packages/flutter/lib/src/material/stepper.dart
View File

@ -192,7 +192,7 @@ class Stepper extends StatefulWidget {
/// This callback which takes in a context and two functions,[onStepContinue]
/// and [onStepCancel]. These can be used to control the stepper.
///
/// {@tool snippet --template=stateless_widget_scaffold}
/// {@tool sample --template=stateless_widget_scaffold}
/// Creates a stepper control with custom buttons.
///
/// ```dart

6
packages/flutter/lib/src/material/switch_list_tile.dart
View File

@ -46,7 +46,7 @@ enum _SwitchListTileType { material, adaptive }
/// To show the [SwitchListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![SwitchListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile.png)
///
@ -85,7 +85,7 @@ enum _SwitchListTileType { material, adaptive }
/// into one. Therefore, it may be necessary to create a custom radio tile
/// widget to accommodate similar use cases.
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![Switch list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile_semantics.png)
///
@ -169,7 +169,7 @@ enum _SwitchListTileType { material, adaptive }
/// combining [Switch] with other widgets, such as [Text], [Padding] and
/// [InkWell].
///
/// {@tool snippet --template=stateful_widget_scaffold_center}
/// {@tool sample --template=stateful_widget_scaffold_center}
///
/// ![Custom switch list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile_custom.png)
///

4
packages/flutter/lib/src/material/tab_controller.dart
View File

@ -26,7 +26,7 @@ import 'constants.dart';
///
/// {@animation 700 540 https://flutter.github.io/assets-for-api-docs/assets/material/tabs.mp4}
///
/// {@tool sample}
/// {@tool snippet}
///
/// This widget introduces a [Scaffold] with an [AppBar] and a [TabBar].
///
@ -339,7 +339,7 @@ class DefaultTabController extends StatefulWidget {
/// The closest instance of this class that encloses the given context.
///
/// {@tool sample}
/// {@tool snippet}
/// Typical usage is as follows:
///
/// ```dart

4
packages/flutter/lib/src/material/text_field.dart
View File

@ -149,7 +149,7 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete
/// Remember to [dispose] of the [TextEditingController] when it is no longer needed.
/// This will ensure we discard any resources used by the object.
///
/// {@tool sample}
/// {@tool snippet}
/// This example shows how to create a [TextField] that will obscure input. The
/// [InputDecoration] surrounds the field in a border using [OutlineInputBorder]
/// and adds a label.
@ -654,7 +654,7 @@ class TextField extends StatefulWidget {
/// accessibility, but it also needs to be accessible itself. For example,
/// if returning a Text widget, set the [semanticsLabel] property.
///
/// {@tool sample}
/// {@tool snippet}
/// ```dart
/// Widget counter(
/// BuildContext context,

2
packages/flutter/lib/src/material/text_form_field.dart
View File

@ -36,7 +36,7 @@ export 'package:flutter/services.dart' show SmartQuotesType, SmartDashesType;
///
/// For a documentation about the various parameters, see [TextField].
///
/// {@tool sample}
/// {@tool snippet}
///
/// Creates a [TextFormField] with an [InputDecoration] and validator function.
///

4
packages/flutter/lib/src/material/text_theme.dart
View File

@ -176,7 +176,7 @@ class TextTheme extends Diagnosticable {
/// the typography styles in the material design specification, as a starting
/// point.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// /// A Widget that sets the ambient theme's title text color for its
@ -260,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// /// A Widget that sets the ambient theme's title text color for its

6
packages/flutter/lib/src/material/theme_data.dart
View File

@ -96,7 +96,7 @@ enum MaterialTapTargetSize {
///
/// To obtain the current theme, use [Theme.of].
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample creates a [Theme] widget that stores the `ThemeData`. The
/// `ThemeData` can be accessed by descendant Widgets that use the correct
@ -128,7 +128,7 @@ enum MaterialTapTargetSize {
/// [MaterialApp]. The `ThemeData` will be used throughout the app to style
/// material design widgets.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample creates a [MaterialApp] widget that stores `ThemeData` and
/// passes the `ThemeData` to descendant widgets. The [AppBar] widget uses the
@ -588,7 +588,7 @@ class ThemeData extends Diagnosticable {
/// forward we will be converting all the widget implementations to only use
/// colors or colors derived from those in [ColorScheme].
///
/// {@tool sample}
/// {@tool snippet}
/// This example will set up an application to use the baseline Material
/// Design light and dark themes.
///

2
packages/flutter/lib/src/material/time.dart
View File

@ -29,7 +29,7 @@ enum DayPeriod {
/// minute or using [DateTime] object.
/// Hours are specified between 0 and 23, as in a 24-hour clock.
///
/// {@tool sample}
/// {@tool snippet}
///
/// ```dart
/// TimeOfDay now = TimeOfDay.now();

6
packages/flutter/lib/src/material/time_picker.dart
View File

@ -1723,7 +1723,7 @@ class _TimePickerDialogState extends State<_TimePickerDialog> {
/// The returned Future resolves to the time selected by the user when the user
/// closes the dialog. If the user cancels the dialog, null is returned.
///
/// {@tool sample}
/// {@tool snippet}
/// Show a dialog with [initialTime] equal to the current time.
///
/// ```dart
@ -1741,7 +1741,7 @@ class _TimePickerDialogState extends State<_TimePickerDialog> {
/// to add inherited widgets like [Localizations.override],
/// [Directionality], or [MediaQuery].
///
/// {@tool sample}
/// {@tool snippet}
/// Show a dialog with the text direction overridden to be [TextDirection.rtl].
///
/// ```dart
@ -1758,7 +1758,7 @@ class _TimePickerDialogState extends State<_TimePickerDialog> {
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
/// Show a dialog with time unconditionally displayed in 24 hour format.
///
/// ```dart

2
packages/flutter/lib/src/material/tooltip_theme.dart
View File

@ -189,7 +189,7 @@ class TooltipThemeData extends Diagnosticable {
/// Values specified here are used for [Tooltip] properties that are not
/// given an explicit non-null value.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Here is an example of a tooltip theme that applies a blue foreground
/// with non-rounded corners.

2
packages/flutter/lib/src/painting/borders.dart
View File

@ -29,7 +29,7 @@ enum BorderStyle {
/// Note that setting [BorderSide.width] to 0.0 will result in hairline
/// rendering. A more involved explanation is present in [BorderSide.width].
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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,

6
packages/flutter/lib/src/painting/box_border.dart
View File

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

2
packages/flutter/lib/src/painting/box_decoration.dart
View File

@ -33,7 +33,7 @@ import 'image_provider.dart';
///
/// The [border] paints over the body; the [boxShadow], naturally, paints below it.
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following applies a [BoxDecoration] to a [Container] widget to draw an
/// [image] of an owl with a thick black [border] and rounded corners.

2
packages/flutter/lib/src/painting/box_fit.dart
View File

@ -104,7 +104,7 @@ class FittedSizes {
/// convenience function, [Alignment.inscribe], for resolving the sizes to
/// rects, as shown in the example below.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This function paints a [dart:ui.Image] `image` onto the [Rect] `outputRect` on a
/// [Canvas] `canvas`, using a [Paint] `paint`, applying the [BoxFit] algorithm

2
packages/flutter/lib/src/painting/continuous_rectangle_border.dart
View File

@ -12,7 +12,7 @@ import 'edge_insets.dart';
/// A rectangular border with smooth continuous transitions between the straight
/// sides and the rounded corners.
///
/// {@tool sample}
/// {@tool snippet}
/// ```dart
/// Widget build(BuildContext context) {
/// return Material(

14
packages/flutter/lib/src/painting/edge_insets.dart
View File

@ -305,7 +305,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]).
///
/// {@tool sample}
/// {@tool snippet}
///
/// Here are some examples of how to create [EdgeInsets] instances:
///
@ -315,7 +315,7 @@ abstract class EdgeInsetsGeometry {
/// const EdgeInsets.all(8.0)
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// Eight pixel margin above and below, no horizontal margins:
///
@ -323,7 +323,7 @@ abstract class EdgeInsetsGeometry {
/// const EdgeInsets.symmetric(vertical: 8.0)
/// ```
/// {@end-tool}
/// {@tool sample}
/// {@tool snippet}
///
/// Left margin indent of 40 pixels:
///
@ -344,7 +344,7 @@ class EdgeInsets extends EdgeInsetsGeometry {
/// Creates insets where all the offsets are `value`.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Typical eight-pixel margin on all sides:
///
@ -360,7 +360,7 @@ class EdgeInsets extends EdgeInsetsGeometry {
/// Creates insets with only the given values non-zero.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Left margin indent of 40 pixels:
///
@ -377,7 +377,7 @@ class EdgeInsets extends EdgeInsetsGeometry {
/// Creates insets with symmetrical vertical and horizontal offsets.
///
/// {@tool sample}
/// {@tool snippet}
///
/// Eight pixel margin above and below, no horizontal margins:
///
@ -638,7 +638,7 @@ class EdgeInsetsDirectional extends EdgeInsetsGeometry {
/// Creates insets with only the given values non-zero.
///
/// {@tool sample}
/// {@tool snippet}
///
/// A margin indent of 40 pixels on the leading side:
///

10
packages/flutter/lib/src/painting/gradient.dart
View File

@ -82,7 +82,7 @@ abstract class GradientTransform {
/// A [GradientTransform] that rotates the gradient around the center-point of
/// its bounding box.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample would rotate a sweep gradient by a quarter turn clockwise:
///
@ -327,7 +327,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].
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample draws a picture that looks like vertical window shades by having
/// a [Container] display a [BoxDecoration] with a [LinearGradient].
@ -551,7 +551,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].
///
/// {@tool sample}
/// {@tool snippet}
///
/// This function draws a gradient that looks like a sun in a blue sky.
///
@ -799,7 +799,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].
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample draws a different color in each quadrant.
///
@ -824,7 +824,7 @@ class RadialGradient extends Gradient {
/// ```
/// {@end-tool}
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample takes the above gradient and rotates it by `math.pi/4` radians,
/// i.e. 45 degrees.

2
packages/flutter/lib/src/painting/image_cache.dart
View File

@ -29,7 +29,7 @@ const int _kDefaultSizeBytes = 100 << 20; // 100 MiB
/// A shared instance of this cache is retained by [PaintingBinding] and can be
/// obtained via the [imageCache] top-level property in the [painting] library.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This sample shows how to supply your own caching logic and replace the
/// global [imageCache] varible.

4
packages/flutter/lib/src/painting/image_provider.dart
View File

@ -182,7 +182,7 @@ typedef DecoderCallback = Future<ui.Codec> Function(Uint8List bytes, {int cacheW
///
/// The following image formats are supported: {@macro flutter.dart:ui.imageFormats}
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following shows the code required to write a widget that fully conforms
/// to the [ImageProvider] and [Widget] protocols. (It is essentially a
@ -349,7 +349,7 @@ abstract class ImageProvider<T> {
/// The [configuration] is optional and defaults to
/// [ImageConfiguration.empty].
///
/// {@tool sample}
/// {@tool snippet}
///
/// The following sample code shows how an image loaded using the [Image]
/// widget can be evicted using a [NetworkImage] with a matching URL.

2
packages/flutter/lib/src/painting/inline_span.dart
View File

@ -108,7 +108,7 @@ class InlineSpanSemanticsInformation {
/// this is the [WidgetSpan] class in the widgets library.
/// * The subclass [WidgetSpan] specifies embedded inline widgets.
///
/// {@tool sample}
/// {@tool snippet}
///
/// This example shows a tree of [InlineSpan]s that make a query asking for a
/// name with a [TextField] embedded inline.

2
packages/flutter/lib/src/painting/shape_decoration.dart
View File

@ -24,7 +24,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.
///
/// {@tool sample}
/// {@tool snippet}
///
/// 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

Some files were not shown because too many files have changed in this diff Show More