|
| 1 | +# cupertino_ui API Example Code |
| 2 | +This directory contains the example code that is referenced in the documentation |
| 3 | +in cupertino_ui's source code. |
| 4 | + |
| 5 | +These examples were originally located [in |
| 6 | +flutter/flutter](https://github.com/flutter/flutter/tree/master/examples/api) |
| 7 | +before the Cupertino library was decoupled and moved into its current home in |
| 8 | +flutter/packages. |
| 9 | + |
| 10 | +The examples can be run individually by just specifying the path to the example |
| 11 | +on the command line (or in the run configuration of an IDE). |
| 12 | + |
| 13 | +For example (no pun intended!), to run the first example from the |
| 14 | +`CupertinoActivityIndicator` class in Chrome, you would run it like so from the |
| 15 | +[example](.) directory: |
| 16 | + |
| 17 | +```sh |
| 18 | +% flutter run -d chrome lib/activity_indicator/cupertino_activity_indicator.0.dart |
| 19 | +``` |
| 20 | + |
| 21 | +All of these same examples are available on the API docs site. |
| 22 | + |
| 23 | +<!-- TODO(justinmc): Include a link to the docs page with the example above like this: For instance, the example above is available on [this page](https://api.flutter.dev/flutter/animation/Curve2D-class.html#animation.Curve2D.1). |
| 24 | +--> |
| 25 | + |
| 26 | +## Naming |
| 27 | + |
| 28 | +> `lib/file/class_name.n.dart` |
| 29 | +> |
| 30 | +> `lib/file/class_name.member_name.n.dart` |
| 31 | +
|
| 32 | +The naming scheme corresponds to the files under [lib/src](../lib/src) where |
| 33 | +each file is represented as a directory (without the `.dart` suffix), and each |
| 34 | +sample in the file is a separate file in that directory. So, for the example |
| 35 | +above, where the examples are from the |
| 36 | +[lib/src/activity_indicator.dart](../lib/src/activity_indicator.dart) file, the |
| 37 | +`CupertinoActivityIndicator` class, the first sample (hence the index "0") for |
| 38 | +that symbol resides in the file named |
| 39 | +[lib/activity_indicator/cupertino_activity_indicator.0.dart](lib/activity_indicator/cupertino_activity_indicator.0.dart). |
| 40 | + |
| 41 | +Symbol names are converted from "CamelCase" to "snake_case". Dots are left |
| 42 | +between symbol names, so the first example for symbol |
| 43 | +`InputDecoration.prefixIconConstraints` would be converted to |
| 44 | +`input_decoration.prefix_icon_constraints.0.dart`. |
| 45 | + |
| 46 | +If the same example is linked to from multiple symbols, the source will be in |
| 47 | +the canonical location for one of the symbols, and the link in the API docs |
| 48 | +block for the other symbols will point to the first symbol's example location. |
| 49 | + |
| 50 | +## Authoring |
| 51 | + |
| 52 | +When authoring examples, first place a block in the Dartdoc documentation for |
| 53 | +the symbol you would like to attach it to. Here's what it might look like if you |
| 54 | +wanted to add a new example to the `CupertinoActivityIndicator` class: |
| 55 | + |
| 56 | +```dart |
| 57 | +/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart} |
| 58 | +/// Write a description of the example here. This description will appear in the |
| 59 | +/// API web documentation to introduce the example. |
| 60 | +/// {@end-example} |
| 61 | +``` |
| 62 | + |
| 63 | +The path parameter is from the root of the package when beginning with `/`, |
| 64 | +otherwise it is relative to the current file. |
| 65 | + |
| 66 | +Once that comment block is inserted in the source code, create a new file at the |
| 67 | +appropriate path under [`example/lib`](./lib). See all of the existing examples |
| 68 | +in that directory for different types of examples with some best practices |
| 69 | +applied. |
| 70 | + |
| 71 | +The filename should match the location of the source file it is linked from, and |
| 72 | +is named for the symbol it is attached to, in lower_snake_case, with an index |
| 73 | +relating to their order within the doc comment. So, for the |
| 74 | +`CupertinoActivityIndicator` example above, since it's in a file called |
| 75 | +`activity_indicator.dart`, and it's the first example, it should have the name |
| 76 | +`example/lib/activity_indicator/cupertino_activity_indicator.0.dart`. |
| 77 | + |
| 78 | +You should also add tests for your example code under [`example/test`](./test), |
| 79 | +that matches their location under [lib](./lib), ending in `_test.dart`. See the |
| 80 | +section on [writing tests](#writing-tests) for more information on what kinds of |
| 81 | +tests to write. |
| 82 | + |
| 83 | +The entire example should be in a single file. |
| 84 | + |
| 85 | +Only packages that can be loaded by Dartpad may be imported. If you use one that |
| 86 | +hasn't been used in an example before, you may have to add it to the |
| 87 | +[pubspec.yaml](pubspec.yaml) in the [example](./) directory. |
| 88 | + |
| 89 | +## Writing Tests |
| 90 | + |
| 91 | +Examples are required to have tests. There is already a "smoke test" that simply |
| 92 | +builds and runs all the API examples, just to make sure that they start up |
| 93 | +without crashing. Test coverage is required for examples, but should take care |
| 94 | +not to complicate the example strictly for the purpose of testing. |
| 95 | + |
| 96 | +As an example, in regular framework code, you might include a parameter for a |
| 97 | +`Platform` object that can be overridden by a test to supply a dummy platform, |
| 98 | +but in the example. This would be unnecessarily complex for the example. In all |
| 99 | +other ways, these are just normal tests. You don't need to re-test the |
| 100 | +functionality of the widget being used in the example, but you should test the |
| 101 | +functionality and integrity of the example itself. |
| 102 | + |
| 103 | +Tests go into a directory under [test](./test) that matches their location under |
| 104 | +[lib](./lib). They are named the same as the example they are testing, with |
| 105 | +`_test.dart` at the end, like other tests. For instance, an |
| 106 | +`CupertinoActivityIndicator` example that resides in |
| 107 | +[`lib/activity_indicator/cupertino_activity_indicator.0.dart`]( ./lib/activity_indicator/cupertino_activity_indicator.0.dart) would |
| 108 | +have its tests in a file named |
| 109 | +[`test/activity_indicator/cupertino_activity_indicator.0_test.dart`]( |
| 110 | +./test/activity_indicator/cupertino_activity_indicator.0_test.dart) |
0 commit comments