The example code in this folder is organized following the conventions documented in the Examples page of the site-shared docs. Consult that page for general information about project file organization, testing, CI, and more. Site-www specific information is given below.
Change directory into the example's folder and run Dart commands there. For example:
$ cd examples/misc
$ dart pub get
$ dart analyze .
Change directory into the example's folder and run Dart commands there. For example:
$ cd examples/misc
$ dart pub get
$ dart test # Run VM tests
$ dart test -p chrome # Run browser tests
To run both the analyzer and tests for all examples use:
./tool/analyze-and-test-examples.sh
If you get a warning about test failures or analysis errors, you might need to
update one or more analyzer results files. For example, update
examples/misc/analyzer-results.txt
, if the change applies to both stable and
dev Dart releases. Otherwise, update only the release specific file: either
examples/misc/analyzer-results-stable.txt
or
examples/misc/analyzer-results-dev.txt
.
To update the analyzer results files:
- Run
dart pub upgrade
to get the latest version of the lints package. - Run
./tool/analyze-and-test-examples.sh --save-logs
. - Look at the diffs for the results files.
- If the diffs look good but some comments are missing, add back the comments that are still relevant.
- Run
./tool/analyze-and-test-examples.sh
to confirm that your changes are good.
Pro tip: You can embed in a doc page specific line(s) from an analyzer results file. (Link to example: To be completed)
The new Language Tour sources are under lib/language_tour
and test/language_tour
.
Below each of these folders, you'll find either a file or a folder with a name
that matches a top-level section of the Language Tour. This file/folder contains
all of the code excerpt sources for that section.
Under lib
you might find a function defined as:
void miscDeclAnalyzedButNotTested(bool c) {
{
// #docregion foo-1
var foo = 1;
// #enddocregion foo-1
}
(int bar) {
// #docregion foo-2
var foo = 2 + bar;
// #enddocregion foo-2
}
// ...
}
That is, code regions are placed with a (headless) code block or an anonymous function. This ensures that code region declarations (which sometimes re-declare the same entity) don't clash.
Generally speaking, a small code excerpt that is subject to testing is embedded
directly in its test. Code regions that are subject to analysis only
are in lib
. Larger examples are in lib
, and their tests (if any) under test
.
Not all code excerpts are tested because some are just small fragments with little or no useful behavior, and others illustrate features that would require significant test scaffolding to be written and the effort isn't worth the small gain.