Add example examples (#111276)

examples/api/README.md

@@ -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
 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.
-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
 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
-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`.
 
-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.
 
@@ -123,18 +130,20 @@ context that the analyzer uses.
 
 ## 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
 `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
 [lib](./lib). They are named the same as the example they are testing, with