Unverified Commit 271834ed authored by Greg Spencer's avatar Greg Spencer Committed by GitHub

Add example examples (#111276)

parent 42fe03dc
...@@ -74,21 +74,28 @@ wanted to add a new example to the `Curve2D` class: ...@@ -74,21 +74,28 @@ wanted to add a new example to the `Curve2D` class:
The "See code in" line needs to be formatted exactly as above, with no wrapping The "See code in" line needs to be formatted exactly as above, with no wrapping
or newlines, one space after the "`**`" at the beginning, and one space before or newlines, one space after the "`**`" at the beginning, and one space before
the "`**`" at the end, and the words "See code in" at the beginning of the line. the "`**`" at the end, and the words "See code in" at the beginning of the line.
This is what the snippets tool and the IDE use when finding the example source This is what the snippets tool use when finding the example source code that you
code that you are creating. are creating.
Use `{@tool dartpad}` for Dartpad examples, and use `{@tool sample}` for Use `{@tool dartpad}` for Dartpad examples, and use `{@tool sample}` for
examples that shouldn't be run/shown in Dartpad. examples that shouldn't be run/shown in Dartpad.
Once that comment block is inserted in the source code, create a new file at the Once that comment block is inserted in the source code, create a new file at the
appropriate path under [`examples/api`](.) that matches the location of the appropriate path under [`examples/api`](.). See the
source file they are linked from, and are named for the symbol they are attached [sample_templates](./lib/sample_templates/) directory for examples of different
to, in lower_snake_case, with an index relating to their order within the doc types of samples with some best practices applied.
comment. So, for the `Curve2D` case, since it's in the `animation` package, in
a file called `curves.dart`, and it's the first example, it goes in The filename should match the location of the source file it is linked from, and
is named for the symbol it is attached to, in lower_snake_case, with an index
relating to their order within the doc comment. So, for the `Curve2D` example
above, since it's in the `animation` library, in a file called `curves.dart`,
and it's the first example, it should have the name
`examples/api/lib/animation/curves/curve2_d.0.dart`. `examples/api/lib/animation/curves/curve2_d.0.dart`.
You should also add tests for your sample code under [`examples/api/test`](./test). You should also add tests for your sample code under
[`examples/api/test`](./test), that matches their location under [lib](./lib),
ending in `_test.dart`. See the section on [writing tests](#writing-tests) for
more information on what kinds of tests to write.
The entire example should be in a single file, so that Dartpad can load it. The entire example should be in a single file, so that Dartpad can load it.
...@@ -123,18 +130,20 @@ context that the analyzer uses. ...@@ -123,18 +130,20 @@ context that the analyzer uses.
## Writing Tests ## Writing Tests
Examples are required to have tests. There is already a "smoke test" that runs Examples are required to have tests. There is already a "smoke test" that simply
all the API examples, just to make sure that they start up without crashing. In builds and runs all the API examples, just to make sure that they start up
addition, we also require writing tests of functionality in the examples, and without crashing. Functionality tests are required the examples, and generally
generally just do what we normally do for writing tests. The one thing that just do what is normally done for writing tests. The one thing that makes it
makes it more challenging for the examples is that they can't really be written more challenging to do for examples is that they can't really be written for
for testability in any obvious way, since that would probably complicate the testability in any obvious way, since that would complicate the examples and
example and make it harder to explain. make them harder to explain.
As an example, in regular framework code, you might include a parameter for a As an example, in regular framework code, you might include a parameter for a
`Platform` object that can be overridden by a test to supply a dummy platform, `Platform` object that can be overridden by a test to supply a dummy platform,
but in the example, this would be unnecessary complexity for the example. In all but in the example. This would be unnecessarily complex for the example. In all
other ways, these are just normal tests. other ways, these are just normal tests. You don't need to re-test the
functionality of the widget being used in the example, but you should test the
functionality and integrity of the example itself.
Tests go into a directory under [test](./test) that matches their location under Tests go into a directory under [test](./test) that matches their location under
[lib](./lib). They are named the same as the example they are testing, with [lib](./lib). They are named the same as the example they are testing, with
......
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