Skip to content

F
Front-End
Unverified Commit 8bec125a authored by Michael Goderbauer's avatar Michael Goderbauer Committed by GitHub
Browse files
Options

Avoid analyzing API example code twice, clean-up (#103548)

parent 2b19ecdc
Hide whitespace changes
Inline Side-by-side
Showing with 958 additions and 43 deletions
dev/bots/analyze.dart
View file @ 8bec125a
......@@ -171,10 +171,10 @@ Future<void> run(List<String> arguments) async {
...arguments,
]);
// Analyze all the sample code in the repo.
print('$clock Sample code...');
// Analyze the code in `{@tool snippet}` sections in the repo.
print('$clock Snippet code...');
await runCommand(dart,
<String>[path.join(flutterRoot, 'dev', 'bots', 'analyze_sample_code.dart'), '--verbose'],
<String>[path.join(flutterRoot, 'dev', 'bots', 'analyze_snippet_code.dart'), '--verbose'],
workingDirectory: flutterRoot,
);
......
dev/bots/analyze_sample_code.dart → dev/bots/analyze_snippet_code.dart
View file @ 8bec125a
......@@ -5,12 +5,9 @@
// See ../snippets/README.md for documentation.
// To run this, from the root of the Flutter repository:
// bin/cache/dart-sdk/bin/dart dev/bots/analyze_sample_code.dart
// @dart= 2.14
// bin/cache/dart-sdk/bin/dart dev/bots/analyze_snippet_code.dart
import 'dart:async';
import 'dart:collection';
import 'dart:convert';
import 'dart:io';
......@@ -18,9 +15,6 @@ import 'package:args/args.dart';
import 'package:path/path.dart' as path;
import 'package:watcher/watcher.dart';
// If you update this version, also update it in dev/bots/docs.sh
const String _snippetsActivateVersion = '0.2.5';
final String _flutterRoot = path.dirname(path.dirname(path.dirname(path.fromUri(Platform.script))));
final String _defaultFlutterPackage = path.join(_flutterRoot, 'packages', 'flutter', 'lib');
final String _defaultDartUiLocation = path.join(_flutterRoot, 'bin', 'cache', 'pkg', 'sky_engine', 'lib', 'ui');
......@@ -60,13 +54,7 @@ Future<void> main(List<String> arguments) async {
argParser.addOption(
'interactive',
abbr: 'i',
help: 'Analyzes the sample code in the specified file interactively.',
);
argParser.addFlag(
'global-activate-snippets',
defaultsTo: true,
help: 'Whether or not to "pub global activate" the snippets package. If set, will '
'activate version $_snippetsActivateVersion',
help: 'Analyzes the snippet code in the specified file interactively.',
);
final ArgResults parsedArguments = argParser.parse(arguments);
......@@ -114,27 +102,6 @@ Future<void> main(List<String> arguments) async {
tempDirectory.createSync();
}
if (parsedArguments['global-activate-snippets']! as bool) {
try {
final ProcessResult activateResult = Process.runSync(
Platform.resolvedExecutable,
<String>[
'pub',
'global',
'activate',
'snippets',
_snippetsActivateVersion,
],
workingDirectory: _flutterRoot,
);
if (activateResult.exitCode != 0) {
exit(activateResult.exitCode);
}
} on ProcessException catch (e) {
stderr.writeln('Unable to global activate snippets package at version $_snippetsActivateVersion: $e');
exit(1);
}
}
if (parsedArguments['interactive'] != null) {
await _runInteractive(
tempDir: tempDirectory,
......@@ -144,110 +111,21 @@ Future<void> main(List<String> arguments) async {
);
} else {
try {
exitCode = await SampleChecker(
exitCode = await _SnippetChecker(
flutterPackage,
tempDirectory: tempDirectory,
verbose: parsedArguments['verbose'] as bool,
dartUiLocation: includeDartUi ? dartUiLocation : null,
).checkSamples();
} on SampleCheckerException catch (e) {
).checkSnippets();
} on _SnippetCheckerException catch (e) {
stderr.write(e);
exit(1);
}
}
}
typedef TaskQueueClosure<T> = Future<T> Function();
class _TaskQueueItem<T> {
_TaskQueueItem(this._closure, this._completer, {this.onComplete});
final TaskQueueClosure<T> _closure;
final Completer<T> _completer;
void Function()? onComplete;
Future<void> run() async {
try {
_completer.complete(await _closure());
} catch (e, st) {
_completer.completeError(e, st);
} finally {
onComplete?.call();
}
}
}
/// A task queue of Futures to be completed in parallel, throttling
/// the number of simultaneous tasks.
///
/// The tasks return results of type T.
class TaskQueue<T> {
/// Creates a task queue with a maximum number of simultaneous jobs.
/// The [maxJobs] parameter defaults to the number of CPU cores on the
/// system.
TaskQueue({int? maxJobs})
: maxJobs = maxJobs ?? Platform.numberOfProcessors;
/// The maximum number of jobs that this queue will run simultaneously.
final int maxJobs;
final Queue<_TaskQueueItem<T>> _pendingTasks = Queue<_TaskQueueItem<T>>();
final Set<_TaskQueueItem<T>> _activeTasks = <_TaskQueueItem<T>>{};
final Set<Completer<void>> _completeListeners = <Completer<void>>{};
/// Returns a future that completes when all tasks in the [TaskQueue] are
/// complete.
Future<void> get tasksComplete {
// In case this is called when there are no tasks, we want it to
// signal complete immediately.
if (_activeTasks.isEmpty && _pendingTasks.isEmpty) {
return Future<void>.value();
}
final Completer<void> completer = Completer<void>();
_completeListeners.add(completer);
return completer.future;
}
/// Adds a single closure to the task queue, returning a future that
/// completes when the task completes.
Future<T> add(TaskQueueClosure<T> task) {
final Completer<T> completer = Completer<T>();
_pendingTasks.add(_TaskQueueItem<T>(task, completer));
if (_activeTasks.length < maxJobs) {
_processTask();
}
return completer.future;
}
// Process a single task.
void _processTask() {
if (_pendingTasks.isNotEmpty && _activeTasks.length <= maxJobs) {
final _TaskQueueItem<T> item = _pendingTasks.removeFirst();
_activeTasks.add(item);
item.onComplete = () {
_activeTasks.remove(item);
_processTask();
};
item.run();
} else {
_checkForCompletion();
}
}
void _checkForCompletion() {
if (_activeTasks.isEmpty && _pendingTasks.isEmpty) {
for (final Completer<void> completer in _completeListeners) {
if (!completer.isCompleted) {
completer.complete();
}
}
_completeListeners.clear();
}
}
}
class SampleCheckerException implements Exception {
SampleCheckerException(this.message, {this.file, this.line});
class _SnippetCheckerException implements Exception {
_SnippetCheckerException(this.message, {this.file, this.line});
final String message;
final String? file;
final int? line;
......@@ -264,28 +142,21 @@ class SampleCheckerException implements Exception {
}
}
class AnalysisResult {
const AnalysisResult(this.exitCode, this.errors);
class _AnalysisResult {
const _AnalysisResult(this.exitCode, this.errors);
final int exitCode;
final Map<String, List<AnalysisError>> errors;
final Map<String, List<_AnalysisError>> errors;
}
/// Checks samples and code snippets for analysis errors.
/// Checks code snippets for analysis errors.
///
/// Extracts dartdoc content from flutter package source code, identifies code
/// sections, and writes them to a temporary directory, where 'flutter analyze'
/// is used to analyze the sources for problems. If problems are found, the
/// error output from the analyzer is parsed for details, and the problem
/// locations are translated back to the source location.
///
/// 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 {
/// Creates a [SampleChecker].
class _SnippetChecker {
/// Creates a [_SnippetChecker].
///
/// The positional argument is the path to the package directory for the
/// flutter package within the Flutter root dir.
......@@ -301,12 +172,12 @@ class SampleChecker {
/// `dart:ui` code to be analyzed along with the framework code. If not
/// supplied, the default location of the `dart:ui` code in the Flutter
/// repository is used (i.e. "<flutter repo>/bin/cache/pkg/sky_engine/lib/ui").
SampleChecker(
_SnippetChecker(
this._flutterPackage, {
Directory? tempDirectory,
this.verbose = false,
Directory? dartUiLocation,
}) : _tempDirectory = tempDirectory ?? Directory.systemTemp.createTempSync('flutter_analyze_sample_code.'),
}) : _tempDirectory = tempDirectory ?? Directory.systemTemp.createTempSync('flutter_analyze_snippet_code.'),
_keepTmp = tempDirectory != null,
_dartUiLocation = dartUiLocation;
......@@ -316,11 +187,11 @@ class SampleChecker {
/// The prefix of each comment line with a space appended.
static const String _dartDocPrefixWithSpace = '$_dartDocPrefix ';
/// A RegExp that matches the beginning of a dartdoc snippet or sample.
static final RegExp _dartDocSampleBeginRegex = RegExp(r'{@tool (sample|snippet|dartpad)(?:| ([^}]*))}');
/// A RegExp that matches the beginning of a dartdoc snippet.
static final RegExp _dartDocSnippetBeginRegex = RegExp(r'{@tool snippet(?:| ([^}]*))}');
/// A RegExp that matches the end of a dartdoc snippet or sample.
static final RegExp _dartDocSampleEndRegex = RegExp(r'{@end-tool}');
/// A RegExp that matches the end of a dartdoc snippet.
static final RegExp _dartDocSnippetEndRegex = RegExp(r'{@end-tool}');
/// A RegExp that matches the start of a code block within dartdoc.
static final RegExp _codeBlockStartRegex = RegExp(r'///\s+```dart.*$');
......@@ -364,8 +235,8 @@ class SampleChecker {
return directory.listSync(recursive: recursive, followLinks: false).whereType<File>().where((File file) => path.extension(file.path) == '.dart').toList();
}
/// Computes the headers needed for each sample file.
List<Line> get headers {
/// Computes the headers needed for each snippet file.
List<_Line> get headers {
return _headers ??= <String>[
'// ignore_for_file: directives_ordering',
'// ignore_for_file: unnecessary_import',
......@@ -380,32 +251,31 @@ class SampleChecker {
"import 'package:flutter_test/flutter_test.dart';",
for (final File file in _listDartFiles(Directory(_defaultFlutterPackage)))
"import 'package:flutter/${path.basename(file.path)}';",
].map<Line>((String code) => Line.generated(code: code, filename: 'headers')).toList();
].map<_Line>((String code) => _Line.generated(code: code, filename: 'headers')).toList();
}
List<Line>? _headers;
List<_Line>? _headers;
/// Checks all the samples in the Dart files in [_flutterPackage] for errors.
Future<int> checkSamples() async {
AnalysisResult? analysisResult;
/// Checks all the snippets in the Dart files in [_flutterPackage] for errors.
Future<int> checkSnippets() async {
_AnalysisResult? analysisResult;
try {
final Map<String, Section> sections = <String, Section>{};
final Map<String, Sample> snippets = <String, Sample>{};
final Map<String, _Section> sections = <String, _Section>{};
if (_dartUiLocation != null && !_dartUiLocation!.existsSync()) {
stderr.writeln('Unable to analyze engine dart samples at ${_dartUiLocation!.path}.');
stderr.writeln('Unable to analyze engine dart snippets at ${_dartUiLocation!.path}.');
}
final List<File> filesToAnalyze = <File>[
..._listDartFiles(_flutterPackage, recursive: true),
if (_dartUiLocation != null && _dartUiLocation!.existsSync()) ... _listDartFiles(_dartUiLocation!, recursive: true),
];
await _extractSamples(filesToAnalyze, sectionMap: sections, sampleMap: snippets);
analysisResult = _analyze(_tempDirectory, sections, snippets);
await _extractSnippets(filesToAnalyze, sectionMap: sections);
analysisResult = _analyze(_tempDirectory, sections);
} finally {
if (analysisResult != null && analysisResult.errors.isNotEmpty) {
for (final String filePath in analysisResult.errors.keys) {
analysisResult.errors[filePath]!.forEach(stderr.writeln);
}
stderr.writeln('\nFound ${analysisResult.errors.length} sample code errors.');
stderr.writeln('\nFound ${analysisResult.errors.length} snippet code errors.');
}
if (_keepTmp) {
print('Leaving temporary directory ${_tempDirectory.path} around for your perusal.');
......@@ -423,160 +293,39 @@ 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 sampleId = path.split(filename).join('.');
sampleId = path.basenameWithoutExtension(sampleId);
sampleId = '$prefix.$sampleId.$start';
return sampleId;
}
// The cached JSON Flutter version information from 'flutter --version --machine'.
String? _flutterVersion;
Future<Process> _runSnippetsScript(List<String> args) async {
final String workingDirectory = path.join(_flutterRoot, 'dev', 'docs');
if (_flutterVersion == null) {
// Capture the flutter version information once so that the snippets tool doesn't
// have to run it for every snippet.
if (verbose) {
print(<String>[_flutter, '--version', '--machine'].join(' '));
}
final ProcessResult versionResult = Process.runSync(_flutter, <String>['--version', '--machine']);
if (verbose) {
stdout.write(versionResult.stdout);
stderr.write(versionResult.stderr);
}
_flutterVersion = versionResult.stdout as String? ?? '';
}
if (verbose) {
print(<String>[
Platform.resolvedExecutable,
'pub',
'global',
'run',
'snippets',
...args,
].join(' '));
}
return Process.start(
Platform.resolvedExecutable,
<String>[
'pub',
'global',
'run',
'snippets',
...args,
],
workingDirectory: workingDirectory,
environment: <String, String>{
if (!Platform.environment.containsKey('FLUTTER_ROOT')) 'FLUTTER_ROOT': _flutterRoot,
if (_flutterVersion!.isNotEmpty) 'FLUTTER_VERSION': _flutterVersion!,
},
);
String snippetId = path.split(filename).join('.');
snippetId = path.basenameWithoutExtension(snippetId);
snippetId = '$prefix.$snippetId.$start';
return snippetId;
}
/// Writes out the given sample to an output file in the [_tempDirectory] and
/// returns the output file.
Future<File> _writeSample(Sample sample) async {
// Generate the snippet.
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 String inputFilePath = path.join(_tempDirectory.path, inputName);
if (verbose) {
stdout.writeln('Creating $inputFilePath.');
}
final File inputFile = File(inputFilePath)..createSync(recursive: true);
if (verbose) {
stdout.writeln('Writing $inputFilePath.');
}
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}',
// Formatting the output will fail on analysis errors, and we want it to fail
// here, not there.
'--no-format-output',
...sample.args,
];
if (verbose) {
print('Generating sample for ${sample.start.filename}:${sample.start.line}');
}
final Process process = await _runSnippetsScript(args);
if (verbose) {
process.stdout.transform(utf8.decoder).forEach(stdout.write);
}
process.stderr.transform(utf8.decoder).forEach(stderr.write);
const Duration timeoutDuration = Duration(minutes: 5);
final int exitCode = await process.exitCode.timeout(timeoutDuration, onTimeout: () {
stderr.writeln('Snippet script timed out after $timeoutDuration.');
return -1;
});
if (exitCode != 0) {
throw SampleCheckerException(
'Unable to create sample for ${sample.start.filename}:${sample.start.line} '
'(using input from ${inputFile.path}).',
file: sample.start.filename,
line: sample.start.line,
);
}
return outputFile;
}
/// Extracts the samples from the Dart files in [files], writes them
/// to disk, and adds them to the appropriate [sectionMap] or [sampleMap].
Future<void> _extractSamples(
/// Extracts the snippets from the Dart files in [files], writes them
/// to disk, and adds them to the [sectionMap].
Future<void> _extractSnippets(
List<File> files, {
required Map<String, Section> sectionMap,
required Map<String, Sample> sampleMap,
required Map<String, _Section> sectionMap,
bool silent = false,
}) async {
final List<Section> sections = <Section>[];
final List<Sample> samples = <Sample>[];
int dartpadCount = 0;
int sampleCount = 0;
final List<_Section> sections = <_Section>[];
for (final File file in files) {
final String relativeFilePath = path.relative(file.path, from: _flutterRoot);
final List<String> sampleLines = file.readAsLinesSync();
final List<Section> preambleSections = <Section>[];
final List<String> snippetLine = file.readAsLinesSync();
final List<_Section> preambleSections = <_Section>[];
// Whether or not we're in the file-wide preamble section ("Examples can assume").
bool inPreamble = false;
// Whether or not we're in a code sample
bool inSampleSection = false;
// Whether or not we're in a snippet code sample (with template) specifically.
bool inSnippet = false;
// Whether or not we're in a code snippet
bool inSnippetSection = false;
// Whether or not we're in a '```dart' segment.
bool inDart = false;
String? dartVersionOverride;
int lineNumber = 0;
final List<String> block = <String>[];
List<String> snippetArgs = <String>[];
late Line startLine;
for (final String line in sampleLines) {
late _Line startLine;
for (final String line in snippetLine) {
lineNumber += 1;
final String trimmedLine = line.trim();
if (inSnippet) {
if (!trimmedLine.startsWith(_dartDocPrefix)) {
throw SampleCheckerException('Snippet section unterminated.', file: relativeFilePath, line: lineNumber);
}
if (_dartDocSampleEndRegex.hasMatch(trimmedLine)) {
samples.add(
Sample(
start: startLine,
input: block,
args: snippetArgs,
serial: samples.length,
),
);
snippetArgs = <String>[];
block.clear();
inSnippet = false;
inSampleSection = false;
} else {
block.add(line.replaceFirst(RegExp(r'\s*/// ?'), ''));
}
} else if (inPreamble) {
if (inPreamble) {
if (line.isEmpty) {
inPreamble = false;
// If there's only a dartVersionOverride in the preamble, don't add
......@@ -586,24 +335,24 @@ class SampleChecker {
}
block.clear();
} else if (!line.startsWith('// ')) {
throw SampleCheckerException('Unexpected content in sample code preamble.', file: relativeFilePath, line: lineNumber);
throw _SnippetCheckerException('Unexpected content in snippet code preamble.', file: relativeFilePath, line: lineNumber);
} else if (_dartVersionRegExp.hasMatch(line)) {
dartVersionOverride = line.substring(3);
} else {
block.add(line.substring(3));
}
} else if (inSampleSection) {
if (_dartDocSampleEndRegex.hasMatch(trimmedLine)) {
} else if (inSnippetSection) {
if (_dartDocSnippetEndRegex.hasMatch(trimmedLine)) {
if (inDart) {
throw SampleCheckerException("Dart section didn't terminate before end of sample", file: relativeFilePath, line: lineNumber);
throw _SnippetCheckerException("Dart section didn't terminate before end of snippet", file: relativeFilePath, line: lineNumber);
}
inSampleSection = false;
inSnippetSection = false;
}
if (inDart) {
if (_codeBlockEndRegex.hasMatch(trimmedLine)) {
inDart = false;
final Section processed = _processBlock(startLine, block);
final Section combinedSection = preambleSections.isEmpty ? processed : Section.combine(preambleSections..add(processed));
final _Section processed = _processBlock(startLine, block);
final _Section combinedSection = preambleSections.isEmpty ? processed : _Section.combine(preambleSections..add(processed));
sections.add(combinedSection.copyWith(dartVersionOverride: dartVersionOverride));
block.clear();
} else if (trimmedLine == _dartDocPrefix) {
......@@ -611,7 +360,7 @@ class SampleChecker {
} else {
final int index = line.indexOf(_dartDocPrefixWithSpace);
if (index < 0) {
throw SampleCheckerException(
throw _SnippetCheckerException(
'Dart section inexplicably did not contain "$_dartDocPrefixWithSpace" prefix.',
file: relativeFilePath,
line: lineNumber,
......@@ -621,7 +370,7 @@ class SampleChecker {
}
} else if (_codeBlockStartRegex.hasMatch(trimmedLine)) {
assert(block.isEmpty);
startLine = Line(
startLine = _Line(
filename: relativeFilePath,
line: lineNumber + 1,
indent: line.indexOf(_dartDocPrefixWithSpace) + _dartDocPrefixWithSpace.length,
......@@ -629,36 +378,16 @@ class SampleChecker {
inDart = true;
}
}
if (!inSampleSection) {
final RegExpMatch? sampleMatch = _dartDocSampleBeginRegex.firstMatch(trimmedLine);
if (!inSnippetSection) {
final RegExpMatch? snippetMatch = _dartDocSnippetBeginRegex.firstMatch(trimmedLine);
if (line == '// Examples can assume:') {
assert(block.isEmpty);
startLine = Line.generated(filename: relativeFilePath, line: lineNumber + 1, indent: 3);
startLine = _Line.generated(filename: relativeFilePath, line: lineNumber + 1, indent: 3);
inPreamble = true;
} else if (sampleMatch != null) {
inSnippet = sampleMatch != null && (sampleMatch[1] == 'sample' || sampleMatch[1] == 'dartpad');
if (inSnippet) {
if (sampleMatch[1] == 'sample') {
sampleCount++;
}
if (sampleMatch[1] == 'dartpad') {
dartpadCount++;
}
startLine = Line(
filename: relativeFilePath,
line: lineNumber + 1,
indent: line.indexOf(_dartDocPrefixWithSpace) + _dartDocPrefixWithSpace.length,
);
if (sampleMatch[2] != null) {
// There are arguments to the snippet tool to keep track of.
snippetArgs = _splitUpQuotedArgs(sampleMatch[2]!).toList();
} else {
snippetArgs = <String>[];
}
}
inSampleSection = !inSnippet;
} else if (snippetMatch != null) {
inSnippetSection = true;
} else if (RegExp(r'///\s*#+\s+[Ss]ample\s+[Cc]ode:?$').hasMatch(trimmedLine)) {
throw SampleCheckerException(
throw _SnippetCheckerException(
"Found deprecated '## Sample code' section: use {@tool snippet}...{@end-tool} instead.",
file: relativeFilePath,
line: lineNumber,
......@@ -668,131 +397,59 @@ class SampleChecker {
}
}
if (!silent)
print('Found ${sections.length} snippet code blocks, '
'$sampleCount sample code sections, and '
'$dartpadCount dartpad sections.');
for (final Section section in sections) {
print('Found ${sections.length} snippet code blocks');
for (final _Section section in sections) {
final String path = _writeSection(section).path;
if (sectionMap != null)
sectionMap[path] = section;
}
final TaskQueue<File> sampleQueue = TaskQueue<File>();
for (final Sample sample in samples) {
final Future<File> futureFile = sampleQueue.add(() => _writeSample(sample));
if (sampleMap != null) {
sampleQueue.add(() async {
final File snippetFile = await futureFile;
sample.contents = await snippetFile.readAsLines();
sampleMap[snippetFile.absolute.path] = sample;
return futureFile;
});
}
}
await sampleQueue.tasksComplete;
}
/// Helper to process arguments given as a (possibly quoted) string.
///
/// First, this will split the given [argsAsString] into separate arguments,
/// taking any quoting (either ' or " are accepted) into account, including
/// handling backslash-escaped quotes.
///
/// Then, it will prepend "--" to any args that start with an identifier
/// followed by an equals sign, allowing the argument parser to treat any
/// "foo=bar" argument as "--foo=bar" (which is a dartdoc-ism).
Iterable<String> _splitUpQuotedArgs(String argsAsString) {
// Regexp to take care of splitting arguments, and handling the quotes
// around arguments, if any.
//
// Match group 1 is the "foo=" (or "--foo=") part of the option, if any.
// Match group 2 contains the quote character used (which is discarded).
// Match group 3 is a quoted arg, if any, without the quotes.
// Match group 4 is the unquoted arg, if any.
final RegExp argMatcher = RegExp(r'([a-zA-Z\-_0-9]+=)?' // option name
r'(?:' // Start a new non-capture group for the two possibilities.
r'''(["'])((?:\\{2})*|(?:.*?[^\\](?:\\{2})*))\2|''' // with quotes.
r'([^ ]+))'); // without quotes.
final Iterable<Match> matches = argMatcher.allMatches(argsAsString);
// Remove quotes around args, and if convertToArgs is true, then for any
// args that look like assignments (start with valid option names followed
// by an equals sign), add a "--" in front so that they parse as options.
return matches.map<String>((Match match) {
String option = '';
if (match[1] != null && !match[1]!.startsWith('-')) {
option = '--';
}
if (match[2] != null) {
// This arg has quotes, so strip them.
return '$option${match[1] ?? ''}${match[3] ?? ''}${match[4] ?? ''}';
}
return '$option${match[0]}';
});
}
/// Creates the configuration files necessary for the analyzer to consider
/// the temporary directory a package, and sets which lint rules to enforce.
void _createConfigurationFiles(Directory directory) {
final File pubSpec = File(path.join(directory.path, 'pubspec.yaml'));
if (!pubSpec.existsSync()) {
pubSpec.createSync(recursive: true);
pubSpec.writeAsStringSync('''
name: analyze_sample_code
environment:
sdk: ">=2.12.0-0 <3.0.0"
dependencies:
flutter:
sdk: flutter
flutter_test:
sdk: flutter
vector_math: any
dev_dependencies:
flutter_lints: ^2.0.0
''');
}
// Import the analysis options from the Flutter root.
final File analysisOptions = File(path.join(directory.path, 'analysis_options.yaml'));
if (!analysisOptions.existsSync()) {
analysisOptions.createSync(recursive: true);
analysisOptions.writeAsStringSync('''
include: package:flutter_lints/flutter.yaml
linter:
rules:
# Samples want to print things pretty often.
avoid_print: false
analyzer:
errors:
# TODO(https://github.com/flutter/flutter/issues/74381):
# Clean up existing unnecessary imports, and remove line to ignore.
unnecessary_import: ignore
''');
final File targetPubSpec = File(path.join(directory.path, 'pubspec.yaml'));
if (!targetPubSpec.existsSync()) {
// Copying pubspec.yaml from examples/api into temp directory.
final File sourcePubSpec = File(path.join(_flutterRoot, 'examples', 'api', 'pubspec.yaml'));
if (!sourcePubSpec.existsSync()) {
throw 'Cannot find pubspec.yaml at ${sourcePubSpec.path}, which is also used to analyze code snippets.';
}
sourcePubSpec.copySync(targetPubSpec.path);
}
final File targetAnalysisOptions = File(path.join(directory.path, 'analysis_options.yaml'));
if (!targetAnalysisOptions.existsSync()) {
// Use the same analysis_options.yaml configuration that's used for examples/api.
final File sourceAnalysisOptions = File(path.join(_flutterRoot, 'examples', 'api', 'analysis_options.yaml'));
if (!sourceAnalysisOptions.existsSync()) {
throw 'Cannot find analysis_options.yaml at ${sourceAnalysisOptions.path}, which is also used to analyze code snippets.';
}
targetAnalysisOptions
..createSync(recursive: true)
..writeAsStringSync('include: ${sourceAnalysisOptions.absolute.path}');
}
}
/// Writes out a sample section to the disk and returns the file.
File _writeSection(Section section) {
/// Writes out a snippet section to the disk and returns the file.
File _writeSection(_Section section) {
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>[
Line.generated(code: section.dartVersionOverride ?? '', filename: section.start.filename),
final List<_Line> mainContents = <_Line>[
_Line.generated(code: section.dartVersionOverride ?? '', filename: section.start.filename),
...headers,
Line.generated(filename: section.start.filename),
Line.generated(code: '// From: ${section.start.filename}:${section.start.line}', filename: section.start.filename),
_Line.generated(filename: section.start.filename),
_Line.generated(code: '// From: ${section.start.filename}:${section.start.line}', filename: section.start.filename),
...section.code,
_Line.generated(filename: section.start.filename), // empty line at EOF
];
outputFile.writeAsStringSync(mainContents.map<String>((Line line) => line.code).join('\n'));
outputFile.writeAsStringSync(mainContents.map<String>((_Line line) => line.code).join('\n'));
return outputFile;
}
/// Invokes the analyzer on the given [directory] and returns the stdout.
int _runAnalyzer(Directory directory, {bool silent = true, required List<String> output}) {
if (!silent)
print('Starting analysis of code samples.');
print('Starting analysis of code snippets.');
_createConfigurationFiles(directory);
final ProcessResult result = Process.runSync(
_flutter,
......@@ -826,23 +483,22 @@ analyzer:
return result.exitCode;
}
/// Starts the analysis phase of checking the samples by invoking the analyzer
/// and parsing its output to create a map of filename to [AnalysisError]s.
AnalysisResult _analyze(
/// Starts the analysis phase of checking the snippets by invoking the analyzer
/// and parsing its output to create a map of filename to [_AnalysisError]s.
_AnalysisResult _analyze(
Directory directory,
Map<String, Section> sections,
Map<String, Sample> samples, {
Map<String, _Section> sections, {
bool silent = false,
}) {
final List<String> errors = <String>[];
int exitCode = _runAnalyzer(directory, silent: silent, output: errors);
final Map<String, List<AnalysisError>> analysisErrors = <String, List<AnalysisError>>{};
void addAnalysisError(File file, AnalysisError error) {
final Map<String, List<_AnalysisError>> analysisErrors = <String, List<_AnalysisError>>{};
void addAnalysisError(File file, _AnalysisError error) {
if (analysisErrors.containsKey(file.path)) {
analysisErrors[file.path]!.add(error);
} else {
analysisErrors[file.path] = <AnalysisError>[error];
analysisErrors[file.path] = <_AnalysisError>[error];
}
}
......@@ -868,157 +524,117 @@ analyzer:
final String message = match.namedGroup('description')!;
final File file = File(path.join(_tempDirectory.path, match.namedGroup('file')));
final List<String> fileContents = file.readAsLinesSync();
final bool isSnippet = path.basename(file.path).startsWith('snippet.');
final bool isSample = path.basename(file.path).startsWith('sample.');
final String line = match.namedGroup('line')!;
final String column = match.namedGroup('column')!;
final String lineString = match.namedGroup('line')!;
final String columnString = match.namedGroup('column')!;
final String errorCode = match.namedGroup('code')!;
final int lineNumber = int.parse(line, radix: 10) - (isSnippet ? headerLength : 0);
final int columnNumber = int.parse(column, radix: 10);
final int lineNumber = int.parse(lineString, radix: 10) - headerLength;
final int columnNumber = int.parse(columnString, radix: 10);
// For when errors occur outside of the things we're trying to analyze.
if (!isSnippet && !isSample) {
if (lineNumber < 1 || lineNumber > fileContents.length) {
addAnalysisError(
file,
AnalysisError(
_AnalysisError(
type,
lineNumber,
columnNumber,
message,
errorCode,
Line(
filename: file.path,
line: lineNumber,
),
_Line(filename: file.path, line: lineNumber),
),
);
throw SampleCheckerException(
'Cannot analyze dartdocs; analysis errors exist: $error',
throw _SnippetCheckerException('Failed to parse error message: $error', file: file.path, line: lineNumber);
}
final _Section actualSection = sections[file.path]!;
if (actualSection == null) {
throw _SnippetCheckerException(
"Unknown section for ${file.path}. Maybe the temporary directory wasn't empty?",
file: file.path,
line: lineNumber,
);
}
if (isSample) {
addAnalysisError(
file,
AnalysisError(
type,
lineNumber,
columnNumber,
message,
errorCode,
null,
sample: samples[file.path],
),
);
} else {
if (lineNumber < 1 || lineNumber > fileContents.length) {
addAnalysisError(
file,
AnalysisError(
type,
lineNumber,
columnNumber,
message,
errorCode,
Line(filename: file.path, line: lineNumber),
),
);
throw SampleCheckerException('Failed to parse error message: $error', file: file.path, line: lineNumber);
}
final Section actualSection = sections[file.path]!;
if (actualSection == null) {
throw SampleCheckerException(
"Unknown section for ${file.path}. Maybe the temporary directory wasn't empty?",
file: file.path,
line: lineNumber,
);
}
final Line actualLine = actualSection.code[lineNumber - 1];
late int line;
late int column;
String errorMessage = message;
Line source = actualLine;
if (actualLine.generated) {
// Since generated lines don't appear in the original, we just provide the line
// in the generated file.
line = lineNumber - 1;
column = columnNumber;
if (errorCode == 'missing_identifier' && lineNumber > 1) {
// For a missing identifier on a generated line, it is very often because of a
// trailing comma on the previous line, and so we want to provide a better message
// and the previous line as the error location, since that appears in the original
// source, and can be more easily located.
final Line previousCodeLine = sections[file.path]!.code[lineNumber - 2];
if (previousCodeLine.code.contains(RegExp(r',\s*$'))) {
line = previousCodeLine.line;
column = previousCodeLine.indent + previousCodeLine.code.length - 1;
errorMessage = 'Unexpected comma at end of sample code.';
source = previousCodeLine;
}
final _Line actualLine = actualSection.code[lineNumber - 1];
late int line;
late int column;
String errorMessage = message;
_Line source = actualLine;
if (actualLine.generated) {
// Since generated lines don't appear in the original, we just provide the line
// in the generated file.
line = lineNumber - 1;
column = columnNumber;
if (errorCode == 'missing_identifier' && lineNumber > 1) {
// For a missing identifier on a generated line, it is very often because of a
// trailing comma on the previous line, and so we want to provide a better message
// and the previous line as the error location, since that appears in the original
// source, and can be more easily located.
final _Line previousCodeLine = sections[file.path]!.code[lineNumber - 2];
if (previousCodeLine.code.contains(RegExp(r',\s*$'))) {
line = previousCodeLine.line;
column = previousCodeLine.indent + previousCodeLine.code.length - 1;
errorMessage = 'Unexpected comma at end of snippet code.';
source = previousCodeLine;
}
} else {
line = actualLine.line;
column = actualLine.indent + columnNumber;
}
addAnalysisError(
file,
AnalysisError(
type,
line,
column,
errorMessage,
errorCode,
source,
),
);
} else {
line = actualLine.line;
column = actualLine.indent + columnNumber;
}
addAnalysisError(
file,
_AnalysisError(
type,
line,
column,
errorMessage,
errorCode,
source,
),
);
}
if (exitCode == 1 && analysisErrors.isEmpty && !unknownAnalyzerErrors) {
exitCode = 0;
}
if (exitCode == 0) {
if (!silent)
print('No analysis errors in samples!');
print('No analysis errors in snippets!');
assert(analysisErrors.isEmpty);
}
return AnalysisResult(exitCode, analysisErrors);
return _AnalysisResult(exitCode, analysisErrors);
}
/// Process one block of sample code (the part inside of "```" markers).
/// Process one block of snippet code (the part inside of "```" markers).
/// Splits any sections denoted by "// ..." into separate blocks to be
/// processed separately. Uses a primitive heuristic to make sample blocks
/// processed separately. Uses a primitive heuristic to make snippet blocks
/// into valid Dart code.
Section _processBlock(Line line, List<String> block) {
_Section _processBlock(_Line line, List<String> block) {
if (block.isEmpty) {
throw SampleCheckerException('$line: Empty ```dart block in sample code.');
throw _SnippetCheckerException('$line: Empty ```dart block in snippet code.');
}
if (block.first.startsWith('new ') || block.first.startsWith(_constructorRegExp)) {
_expressionId += 1;
return Section.surround(line, 'dynamic expression$_expressionId = ', block.toList(), ';');
return _Section.surround(line, 'dynamic expression$_expressionId = ', block.toList(), ';');
} else if (block.first.startsWith('await ')) {
_expressionId += 1;
return Section.surround(line, 'Future<void> expression$_expressionId() async { ', block.toList(), ' }');
return _Section.surround(line, 'Future<void> expression$_expressionId() async { ', block.toList(), ' }');
} else if (block.first.startsWith('class ') || block.first.startsWith('enum ')) {
return Section.fromStrings(line, block.toList());
return _Section.fromStrings(line, block.toList());
} else if ((block.first.startsWith('_') || block.first.startsWith('final ')) && block.first.contains(' = ')) {
_expressionId += 1;
return Section.surround(line, 'void expression$_expressionId() { ', block.toList(), ' }');
return _Section.surround(line, 'void expression$_expressionId() { ', block.toList(), ' }');
} else {
final List<String> buffer = <String>[];
int subblocks = 0;
Line? subline;
final List<Section> subsections = <Section>[];
_Line? subline;
final List<_Section> subsections = <_Section>[];
for (int index = 0; index < block.length; index += 1) {
// Each section of the dart code that is either split by a blank line, or with '// ...' is
// treated as a separate code block.
if (block[index] == '' || block[index] == '// ...') {
if (subline == null)
throw SampleCheckerException('${Line(filename: line.filename, line: line.line + index, indent: line.indent)}: '
'Unexpected blank line or "// ..." line near start of subblock in sample code.');
throw _SnippetCheckerException('${_Line(filename: line.filename, line: line.line + index, indent: line.indent)}: '
'Unexpected blank line or "// ..." line near start of subblock in snippet code.');
subblocks += 1;
subsections.add(_processBlock(subline, buffer));
buffer.clear();
......@@ -1028,7 +644,7 @@ analyzer:
if (buffer.length > 1) // don't include leading comments
buffer.add('/${block[index]}'); // so that it doesn't start with "// " and get caught in this again
} else {
subline ??= Line(
subline ??= _Line(
code: block[index],
filename: line.filename,
line: line.line + index,
......@@ -1042,19 +658,19 @@ analyzer:
subsections.add(_processBlock(subline, buffer));
}
// Combine all of the subsections into one section, now that they've been processed.
return Section.combine(subsections);
return _Section.combine(subsections);
} else {
return Section.fromStrings(line, block.toList());
return _Section.fromStrings(line, block.toList());
}
}
}
}
/// A class to represent a line of input code.
class Line {
const Line({this.code = '', required this.filename, this.line = -1, this.indent = 0})
class _Line {
const _Line({this.code = '', required this.filename, this.line = -1, this.indent = 0})
: generated = false;
const Line.generated({this.code = '', required this.filename, this.line = -1, this.indent = 0})
const _Line.generated({this.code = '', required this.filename, this.line = -1, this.indent = 0})
: generated = true;
/// The file that this line came from, or the file that the line was generated for, if [generated] is true.
......@@ -1075,20 +691,20 @@ class Line {
String toString() => '$filename:$line: $code';
}
/// A class to represent a section of sample code, marked by "{@tool snippet}...{@end-tool}".
class Section {
const Section(this.code, {this.dartVersionOverride});
factory Section.combine(List<Section> sections) {
final List<Line> code = sections
.expand((Section section) => section.code)
.toList();
return Section(code);
}
factory Section.fromStrings(Line firstLine, List<String> code) {
final List<Line> codeLines = <Line>[];
/// A class to represent a section of snippet code, marked by "{@tool snippet}...{@end-tool}".
class _Section {
const _Section(this.code, {this.dartVersionOverride});
factory _Section.combine(List<_Section> sections) {
final List<_Line> code = sections
.expand((_Section section) => section.code)
.toList();
return _Section(code);
}
factory _Section.fromStrings(_Line firstLine, List<String> code) {
final List<_Line> codeLines = <_Line>[];
for (int i = 0; i < code.length; ++i) {
codeLines.add(
Line(
_Line(
code: code[i],
filename: firstLine.filename,
line: firstLine.line + i,
......@@ -1096,15 +712,15 @@ class Section {
),
);
}
return Section(codeLines);
return _Section(codeLines);
}
factory Section.surround(Line firstLine, String prefix, List<String> code, String postfix) {
factory _Section.surround(_Line firstLine, String prefix, List<String> code, String postfix) {
assert(prefix != null);
assert(postfix != null);
final List<Line> codeLines = <Line>[];
final List<_Line> codeLines = <_Line>[];
for (int i = 0; i < code.length; ++i) {
codeLines.add(
Line(
_Line(
code: code[i],
filename: firstLine.filename,
line: firstLine.line + i,
......@@ -1112,82 +728,45 @@ class Section {
),
);
}
return Section(<Line>[
Line.generated(code: prefix, filename: firstLine.filename, line: 0),
return _Section(<_Line>[
_Line.generated(code: prefix, filename: firstLine.filename, line: 0),
...codeLines,
Line.generated(code: postfix, filename: firstLine.filename, line: 0),
_Line.generated(code: postfix, filename: firstLine.filename, line: 0),
]);
}
Line get start => code.firstWhere((Line line) => !line.generated);
final List<Line> code;
_Line get start => code.firstWhere((_Line line) => !line.generated);
final List<_Line> code;
final String? dartVersionOverride;
Section copyWith({String? dartVersionOverride}) {
return Section(code, dartVersionOverride: dartVersionOverride ?? this.dartVersionOverride);
}
}
/// 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 Sample {
Sample({
required this.start,
required List<String> input,
required List<String> args,
required this.serial,
}) : input = input.toList(),
args = args.toList(),
contents = <String>[];
final Line start;
final int serial;
List<String> input;
List<String> args;
List<String> contents;
@override
String toString() {
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');
count++;
}
return buf.toString();
_Section copyWith({String? dartVersionOverride}) {
return _Section(code, dartVersionOverride: dartVersionOverride ?? this.dartVersionOverride);
}
}
/// A class representing an analysis error along with the context of the error.
///
/// Changes how it converts to a string based on the source of the error.
class AnalysisError {
const AnalysisError(
class _AnalysisError {
const _AnalysisError(
this.type,
this.line,
this.column,
this.message,
this.errorCode,
this.source, {
this.sample,
});
this.source,
);
final String type;
final int line;
final int column;
final String message;
final String errorCode;
final Line? source;
final Sample? sample;
final _Line? source;
@override
String toString() {
if (source != null) {
return '${source!.toStringWithColumn(column)}\n>>> $type: $message ($errorCode)';
} else if (sample != null) {
return 'In sample starting at '
'${sample!.start.filename}:${sample!.start.line}:${sample!.contents[line - 1]}\n'
'>>> $type: $message ($errorCode)';
} else {
return '<source unknown>:$line:$column\n>>> $type: $message ($errorCode)';
}
......@@ -1212,7 +791,7 @@ Future<void> _runInteractive({
}
if (tempDir == null) {
tempDir = Directory.systemTemp.createTempSync('flutter_analyze_sample_code.');
tempDir = Directory.systemTemp.createTempSync('flutter_analyze_snippet_code.');
ProcessSignal.sigint.watch().listen((_) {
print('Deleting temp files...');
tempDir!.deleteSync(recursive: true);
......@@ -1222,11 +801,10 @@ Future<void> _runInteractive({
}
print('Starting up in interactive mode on ${path.relative(filePath, from: _flutterRoot)} ...');
Future<void> analyze(SampleChecker checker, File file) async {
final Map<String, Section> sections = <String, Section>{};
final Map<String, Sample> snippets = <String, Sample>{};
await checker._extractSamples(<File>[file], silent: true, sectionMap: sections, sampleMap: snippets);
final AnalysisResult analysisResult = checker._analyze(checker._tempDirectory, sections, snippets, silent: true);
Future<void> analyze(_SnippetChecker checker, File file) async {
final Map<String, _Section> sections = <String, _Section>{};
await checker._extractSnippets(<File>[file], silent: true, sectionMap: sections);
final _AnalysisResult analysisResult = checker._analyze(checker._tempDirectory, sections, silent: true);
stderr.writeln('\u001B[2J\u001B[H'); // Clears the old results from the terminal.
if (analysisResult.errors.isNotEmpty) {
for (final String filePath in analysisResult.errors.keys) {
......@@ -1238,7 +816,7 @@ Future<void> _runInteractive({
}
}
final SampleChecker checker = SampleChecker(flutterPackage, tempDirectory: tempDir)
final _SnippetChecker checker = _SnippetChecker(flutterPackage, tempDirectory: tempDir)
.._createConfigurationFiles(tempDir);
await analyze(checker, file);
......@@ -1248,7 +826,7 @@ Future<void> _runInteractive({
print('\n\nRerunning...');
try {
analyze(checker, file);
} on SampleCheckerException catch (e) {
} on _SnippetCheckerException catch (e) {
print('Caught Exception (${e.runtimeType}), press "r" to retry:\n$e');
}
}
......
dev/bots/docs.sh
View file @ 8bec125a
......@@ -25,7 +25,6 @@ function generate_docs() {
# Install and activate the snippets tool, which resides in the
# assets-for-api-docs repo:
# https://github.com/flutter/assets-for-api-docs/tree/master/packages/snippets
# >>> If you update this version, also update it in dev/bots/analyze_sample_code.dart <<<
"$DART" pub global activate snippets 0.2.5
# This script generates a unified doc set, and creates
......
dev/bots/test/analyze-sample-code-test-dart-ui/ui.dart → dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart
View file @ 8bec125a
......@@ -11,7 +11,7 @@ library dart.ui;
/// Annotation used by Flutter's Dart compiler to indicate that an
/// [Object.toString] override should not be replaced with a supercall.
///
/// {@tool sample --template=stateless_widget_material}
/// {@tool snippet}
/// A sample if using keepToString to prevent replacement by a supercall.
///
/// ```dart
......
dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart → dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart
View file @ 8bec125a
......@@ -2,7 +2,7 @@
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// This file is used by ../analyze_sample_code_test.dart, which depends on the
// This file is used by ../analyze_snippet_code_test.dart, which depends on the
// precise contents (including especially the comments) of this file.
// Examples can assume:
......@@ -34,7 +34,7 @@
/// ```
/// {@end-tool}
///
/// {@tool dartpad --template=stateless_widget_material}
/// {@tool snippet}
/// Bla blabla blabla some [Text] when the `_blabla` blabla blabla is true, and
/// blabla it when it is blabla:
///
......@@ -121,7 +121,7 @@
/// ```
/// {@end-tool}
///
/// {@tool dartpad --template=stateless_widget_material}
/// {@tool snippet}
/// Dartpad with null-safe syntax
///
/// ```dart preamble
......
dev/bots/test/analyze_sample_code_test.dart → dev/bots/test/analyze_snippet_code_test.dart
View file @ 8bec125a
......@@ -14,58 +14,58 @@ void main() {
return;
}
test('analyze_sample_code smoke test', () {
test('analyze_snippet_code smoke test', () {
final ProcessResult process = Process.runSync(
'../../bin/cache/dart-sdk/bin/dart',
<String>['analyze_sample_code.dart', '--no-include-dart-ui', 'test/analyze-sample-code-test-input'],
<String>['analyze_snippet_code.dart', '--no-include-dart-ui', 'test/analyze-snippet-code-test-input'],
);
final List<String> stdoutLines = process.stdout.toString().split('\n');
final List<String> stderrLines = process.stderr.toString().split('\n');
expect(process.exitCode, isNot(equals(0)));
expect(stderrLines, containsAll(<Object>[
'In sample starting at dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:125: child: Text(title),',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:138:25: child: Text(title),',
matches(RegExp(r">>> error: The final variable 'title' can't be read because (it is|it's) potentially unassigned at this point \(read_potentially_unassigned_final\)")),
'dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:30:9: new Opacity(',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:30:9: new Opacity(',
'>>> info: Unnecessary new keyword (unnecessary_new)',
'dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:62:9: new Opacity(',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:62:9: new Opacity(',
'>>> info: Unnecessary new keyword (unnecessary_new)',
"dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:111:9: final String? bar = 'Hello';",
"dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:9: final String? bar = 'Hello';",
'>>> info: Prefer const over final for declarations (prefer_const_declarations)',
'dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:112:9: final int foo = null;',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:9: final int foo = null;',
'>>> info: Prefer const over final for declarations (prefer_const_declarations)',
'dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:112:25: final int foo = null;',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:25: final int foo = null;',
">>> error: A value of type 'Null' can't be assigned to a variable of type 'int' (invalid_assignment)",
'dev/bots/test/analyze-sample-code-test-input/known_broken_documentation.dart:120:24: const SizedBox(),',
'>>> error: Unexpected comma at end of sample code. (missing_identifier)',
'Found 2 sample code errors.',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:120:24: const SizedBox(),',
'>>> error: Unexpected comma at end of snippet code. (missing_identifier)',
'Found 1 snippet code errors.',
]));
expect(stdoutLines, containsAll(<String>[
'Found 9 snippet code blocks, 0 sample code sections, and 2 dartpad sections.',
'Starting analysis of code samples.',
'Found 13 snippet code blocks',
'Starting analysis of code snippets.',
]));
});
test('Analyzes dart:ui code', () {
final ProcessResult process = Process.runSync(
'../../bin/cache/dart-sdk/bin/dart',
<String>[
'analyze_sample_code.dart',
'--dart-ui-location=test/analyze-sample-code-test-dart-ui',
'test/analyze-sample-code-test-input',
'analyze_snippet_code.dart',
'--dart-ui-location=test/analyze-snippet-code-test-dart-ui',
'test/analyze-snippet-code-test-input',
],
);
final List<String> stdoutLines = process.stdout.toString().split('\n');
final List<String> stderrLines = process.stderr.toString().split('\n');
expect(process.exitCode, isNot(equals(0)));
expect(stderrLines, containsAll(<String>[
'In sample starting at dev/bots/test/analyze-sample-code-test-dart-ui/ui.dart:15:class MyStatelessWidget extends StatelessWidget {',
">>> error: Missing concrete implementation of 'StatelessWidget.build' (non_abstract_class_inherits_abstract_member)",
'In sample starting at dev/bots/test/analyze-sample-code-test-dart-ui/ui.dart:15:class MyStringBuffer {',
">>> error: Classes can't be declared inside other classes (class_in_class)",
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:19:11: error;',
">>> error: Variables must be declared using the keywords 'const', 'final', 'var' or a type name (missing_const_final_var_or_type)",
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:23:11: @keepToString',
">>> error: Undefined name 'keepToString' used as an annotation (undefined_annotation)",
]));
expect(stdoutLines, containsAll(<String>[
// There is one sample code section in the test's dummy dart:ui code.
'Found 9 snippet code blocks, 1 sample code sections, and 2 dartpad sections.',
'Starting analysis of code samples.',
// There is one snippet code section in the test's dummy dart:ui code.
'Found 14 snippet code blocks',
'Starting analysis of code snippets.',
]));
});
}
examples/api/analysis_options.yaml
View file @ 8bec125a
# This file is also used by dev/bots/analyze_snippet_code.dart to analyze code snippets (`{@tool snippet}` sections).
include: ../../analysis_options.yaml
linter:
rules:
# Samples want to print things pretty often.
avoid_print: false
# TODO(goderbauer): enable when super params are more established and
# seeing them in the API samples is no longer surprising,
# https://github.com/flutter/flutter/issues/101068
......
examples/api/pubspec.yaml
View file @ 8bec125a
# This file is also used by dev/bots/analyze_snippet_code.dart to analyze code snippets (`{@tool snippet}` sections).
name: flutter_api_samples
description: API code samples for the Flutter repo.
publish_to: 'none'
......
packages/flutter/lib/src/foundation/diagnostics.dart
View file @ 8bec125a
......@@ -3213,7 +3213,6 @@ mixin Diagnosticable {
/// value: isCurrent,
/// ifTrue: 'active',
/// ifFalse: 'inactive',
/// showName: false,
/// ));
///
/// properties.add(DiagnosticsProperty<bool>('keepAlive', keepAlive));
......
packages/flutter/lib/src/material/checkbox.dart
View file @ 8bec125a
......@@ -171,7 +171,7 @@ class Checkbox extends StatefulWidget {
/// Checkbox(
/// value: true,
/// onChanged: (_){},
/// fillColor: MaterialStateProperty.resolveWith<Color>((states) {
/// fillColor: MaterialStateProperty.resolveWith<Color>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.disabled)) {
/// return Colors.orange.withOpacity(.32);
/// }
......
packages/flutter/lib/src/material/radio.dart
View file @ 8bec125a
......@@ -200,7 +200,7 @@ class Radio<T> extends StatefulWidget {
/// value: 1,
/// groupValue: 1,
/// onChanged: (_){},
/// fillColor: MaterialStateProperty.resolveWith<Color>((states) {
/// fillColor: MaterialStateProperty.resolveWith<Color>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.disabled)) {
/// return Colors.orange.withOpacity(.32);
/// }
......
packages/flutter/lib/src/material/switch.dart
View file @ 8bec125a
......@@ -238,7 +238,7 @@ class Switch extends StatelessWidget {
/// Switch(
/// value: true,
/// onChanged: (_) => true,
/// thumbColor: MaterialStateProperty.resolveWith<Color>((states) {
/// thumbColor: MaterialStateProperty.resolveWith<Color>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.disabled)) {
/// return Colors.orange.withOpacity(.48);
/// }
......@@ -279,7 +279,7 @@ class Switch extends StatelessWidget {
/// Switch(
/// value: true,
/// onChanged: (_) => true,
/// thumbColor: MaterialStateProperty.resolveWith<Color>((states) {
/// thumbColor: MaterialStateProperty.resolveWith<Color>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.disabled)) {
/// return Colors.orange.withOpacity(.48);
/// }
......
packages/flutter/lib/src/material/theme_data.dart
View file @ 8bec125a
......@@ -201,9 +201,7 @@ enum MaterialTapTargetSize {
/// ```dart
/// MaterialApp(
/// theme: ThemeData(
/// colorScheme: ColorScheme.fromSwatch(
/// primarySwatch: Colors.blue,
/// ).copyWith(
/// colorScheme: ColorScheme.fromSwatch().copyWith(
/// secondary: Colors.green,
/// ),
/// textTheme: const TextTheme(bodyText2: TextStyle(color: Colors.purple)),
......
packages/flutter/lib/src/painting/box_border.dart
View file @ 8bec125a
......@@ -267,20 +267,20 @@ abstract class BoxBorder extends ShapeBorder {
/// Container(
/// decoration: const BoxDecoration(
/// border: Border(
/// top: BorderSide(width: 1.0, color: Color(0xFFFFFFFF)),
/// left: BorderSide(width: 1.0, color: Color(0xFFFFFFFF)),
/// right: BorderSide(width: 1.0, color: Color(0xFF000000)),
/// bottom: BorderSide(width: 1.0, color: Color(0xFF000000)),
/// top: BorderSide(color: Color(0xFFFFFFFF)),
/// left: BorderSide(color: Color(0xFFFFFFFF)),
/// right: BorderSide(),
/// bottom: BorderSide(),
/// ),
/// ),
/// child: Container(
/// padding: const EdgeInsets.symmetric(horizontal: 20.0, vertical: 2.0),
/// decoration: const BoxDecoration(
/// border: Border(
/// top: BorderSide(width: 1.0, color: Color(0xFFDFDFDF)),
/// left: BorderSide(width: 1.0, color: Color(0xFFDFDFDF)),
/// right: BorderSide(width: 1.0, color: Color(0xFF7F7F7F)),
/// bottom: BorderSide(width: 1.0, color: Color(0xFF7F7F7F)),
/// top: BorderSide(color: Color(0xFFDFDFDF)),
/// left: BorderSide(color: Color(0xFFDFDFDF)),
/// right: BorderSide(color: Color(0xFF7F7F7F)),
/// bottom: BorderSide(color: Color(0xFF7F7F7F)),
/// ),
/// color: Color(0xFFBFBFBF),
/// ),
......
packages/flutter/lib/src/painting/box_decoration.dart
View file @ 8bec125a
......@@ -49,7 +49,6 @@ import 'image_provider.dart';
/// fit: BoxFit.cover,
/// ),
/// border: Border.all(
/// color: Colors.black,
/// width: 8,
/// ),
/// borderRadius: BorderRadius.circular(12),
......
packages/flutter/lib/src/painting/gradient.dart
View file @ 8bec125a
......@@ -857,8 +857,6 @@ class RadialGradient extends Gradient {
/// decoration: const BoxDecoration(
/// gradient: SweepGradient(
/// center: FractionalOffset.center,
/// startAngle: 0.0,
/// endAngle: math.pi * 2,
/// colors: <Color>[
/// Color(0xFF4285F4), // blue
/// Color(0xFF34A853), // green
......@@ -883,8 +881,6 @@ class RadialGradient extends Gradient {
/// decoration: const BoxDecoration(
/// gradient: SweepGradient(
/// center: FractionalOffset.center,
/// startAngle: 0.0,
/// endAngle: math.pi * 2,
/// colors: <Color>[
/// Color(0xFF4285F4), // blue
/// Color(0xFF34A853), // green
......
packages/flutter/lib/src/rendering/layer.dart
View file @ 8bec125a
......@@ -118,7 +118,6 @@ class AnnotationResult<T> {
/// offset,
/// Offset.zero & size,
/// super.paint,
/// clipBehavior: Clip.hardEdge,
/// oldLayer: _clipRectLayer.layer,
/// );
/// }
......
packages/flutter/lib/src/semantics/semantics.dart
View file @ 8bec125a
......@@ -2098,7 +2098,6 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
/// ```dart
/// PhysicalModel( // A
/// color: Colors.amber,
/// elevation: 0.0,
/// child: Semantics(
/// explicitChildNodes: true,
/// child: const PhysicalModel( // B
......
packages/flutter/lib/src/services/platform_channel.dart
View file @ 8bec125a
......@@ -198,6 +198,9 @@ class MethodChannel {
///
/// ```dart
/// class Music {
/// // Class cannot be instantiated.
/// const Music._();
///
/// static const MethodChannel _channel = MethodChannel('music');
///
/// static Future<bool> isLicensed() async {
......@@ -213,7 +216,7 @@ class MethodChannel {
/// // the actual values involved would support such a typed container.
/// // The correct type cannot be inferred with any value of `T`.
/// final List<dynamic>? songs = await _channel.invokeMethod<List<dynamic>>('getSongs');
/// return songs?.map(Song.fromJson).toList() ?? <Song>[];
/// return songs?.cast<Map<String, Object?>>().map<Song>(Song.fromJson).toList() ?? <Song>[];
/// }
///
/// static Future<void> play(Song song, double volume) async {
......@@ -225,7 +228,7 @@ class MethodChannel {
/// 'volume': volume,
/// });
/// } on PlatformException catch (e) {
/// throw 'Unable to play ${song.title}: ${e.message}';
/// throw ArgumentError('Unable to play ${song.title}: ${e.message}');
/// }
/// }
/// }
......@@ -237,8 +240,8 @@ class MethodChannel {
/// final String title;
/// final String artist;
///
/// static Song fromJson(dynamic json) {
/// return Song(json['id'] as String, json['title'] as String, json['artist'] as String);
/// static Song fromJson(Map<String, Object?> json) {
/// return Song(json['id']! as String, json['title']! as String, json['artist']! as String);
/// }
/// }
/// ```
......
packages/flutter/lib/src/widgets/animated_cross_fade.dart
View file @ 8bec125a
......@@ -44,7 +44,6 @@ enum CrossFadeState {
/// ```dart
/// Widget defaultLayoutBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey) {
/// return Stack(
/// fit: StackFit.loose,
/// children: <Widget>[
/// Positioned(
/// key: bottomChildKey,
......
packages/flutter/lib/src/widgets/basic.dart
View file @ 8bec125a
......@@ -4566,7 +4566,6 @@ class Flex extends MultiChildRenderObjectWidget {
/// ),
/// Expanded(
/// child: FittedBox(
/// fit: BoxFit.contain, // otherwise the logo will be tiny
/// child: FlutterLogo(),
/// ),
/// ),
......@@ -4765,7 +4764,6 @@ class Row extends Flex {
/// Text('Craft beautiful UIs'),
/// Expanded(
/// child: FittedBox(
/// fit: BoxFit.contain, // otherwise the logo will be tiny
/// child: FlutterLogo(),
/// ),
/// ),
......
packages/flutter/lib/src/widgets/localizations.dart
View file @ 8bec125a
......@@ -11,7 +11,7 @@ import 'debug.dart';
import 'framework.dart';
// Examples can assume:
// class Intl { static String message(String s, { String? name, String? locale }) => ''; }
// class Intl { Intl._(); static String message(String s, { String? name, String? locale }) => ''; }
// Future<void> initializeMessages(String locale) => Future<void>.value();
// Used by loadAll() to record LocalizationsDelegate.load() futures we're
......
packages/flutter/lib/src/widgets/page_view.dart
View file @ 8bec125a
......@@ -108,7 +108,6 @@ import 'viewport.dart';
/// );
/// }
/// }
///
/// ```
/// {@end-tool}
class PageController extends ScrollController {
......
packages/flutter/lib/src/widgets/routes.dart
View file @ 8bec125a
......@@ -27,7 +27,7 @@ import 'scroll_controller.dart';
import 'transitions.dart';
// Examples can assume:
// dynamic routeObserver;
// late RouteObserver<Route<void>> routeObserver;
// late NavigatorState navigator;
// late BuildContext context;
// Future<bool> askTheUserIfTheyAreSure() async { return true; }
......@@ -1058,7 +1058,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
/// defined in the same way.
///
/// ```dart
/// PageRouteBuilder(
/// PageRouteBuilder<void>(
/// pageBuilder: (BuildContext context,
/// Animation<double> animation,
/// Animation<double> secondaryAnimation,
......@@ -1105,7 +1105,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
/// route has been popped off.
///
/// ```dart
/// PageRouteBuilder(
/// PageRouteBuilder<void>(
/// pageBuilder: (BuildContext context,
/// Animation<double> animation,
/// Animation<double> secondaryAnimation,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

HIAST - GitLab