example: improve readme documentation...

...and ensure pubspec/readme consistency with a test

Author: kevmoo

example/README.md

@@ -1,23 +1,68 @@
-An simple example of a Dart package using [json_serializable].
+To use [package:json_serializable][json_serializable] in your package, add these
+dependencies to your `pubspec.yaml`.
 
-* `lib/example.dart`: A library configured with annotations – 
-  `JsonSerializable` and `JsonLiteral` – to enable code generation.
+```yaml
+dependencies:
+  json_annotation: ^0.2.1
 
-  * Note: the annotations are defined in `package:json_annotation`.
-    This is the only package required in the `dependencies` section of your
-    `pubspec.yaml`.
+dev_dependencies:
+  build_runner: ^0.6.1
+  json_serializable: ^0.2.5
+  source_gen: ^0.7.2+1
+```
 
-* `tool/`: Contains the code run during development to create and update
-  generated code.
+Next, create the scripts to run code generation. The [`tool`][tool] directory
+contains the conventional layout of these scripts.
 
-  * `build_actions.dart`: A convention when using `package:build` to 
-    have one location to define the actions to be run by `build.dart` and 
-    `watch.dart`. See the comments in the source file for more information.
+* [`build_actions.dart`][tool]: A convention when using `package:build` to 
+  have one location to define the actions to be run by [`build.dart`][build] and 
+  [`watch.dart`][watch]. See the comments in the source file for more
+  information.
 
-  * `build.dart`: Runs one build using the actions defined in
-    `build_actions.dart`.
+* [`build.dart`][build]: Runs one build using the actions defined in
+  [`build_actions.dart`][build_actions].
 
-  * `watch.dart`: Starts a watcher that (re)runs the actions defined in
-    `build_actions.dart` when files change.
+* [`watch.dart`][watch]: Starts a watcher that (re)runs the actions defined in
+  [`build_actions.dart`][build_actions] when files change.
 
+Finally, annotate your code with classes defined in
+[package:json_annotation][json_annotation].
+
+* See [`lib/example.dart`][example] for an example of a file using these
+  annotations.
+
+* See [`lib/example.g.dart`][example_g] for the generated file.
+
+Run the build script to update the generated code after you modify of of the
+source files.
+
+```console
+> dart bin/build.dart
+[INFO] BuildDefinition: Reading cached asset graph completed, took 54ms
+[INFO] BuildDefinition: Checking for updates since last build completed, took 663ms
+[INFO] Build: Running build completed, took 10ms
+[INFO] Build: Caching finalized dependency graph completed, took 44ms
+[INFO] Build: Succeeded after 68ms with 0 outputs
+```
+
+*NOTE*: If you're using Flutter, running a Dart script is a bit tricky. You can
+find the Dart entry point at `$FLUTTER_ROOT/bin/cache/dart-sdk/bin/dart`.
+You can determine `FLUTTER_ROOT` by looking at the first few lines of
+`flutter doctor`.
+
+```console
+> flutter doctor
+[✓] Flutter (on Mac OS X 10.12.6 16G1114, locale en-US, channel master)
+    • Flutter at YOUR_FLUTTER_ROOT_HERE
+    • Framework revision 235b64ed2f (13 hours ago), 2017-12-14 20:38:39 -0800
+...
+```
+
+[tool]: tool
+[build_actions]: tool/build_actions.dart
+[build]: tool/build.dart
+[watch]: tool/watch.dart
+[example]: lib/example.dart
+[example_g]: lib/example.g.dart
+[json_annotation]: https://pub.dartlang.org/packages/json_annotation
 [json_serializable]: https://pub.dartlang.org/packages/json_serializable

example/test/readme_test.dart

@@ -0,0 +1,29 @@
+// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:test/test.dart';
+
+void main() {
+  _expect('README.md');
+  _expect('pubspec.yaml');
+}
+
+void _expect(String fileName) {
+  test(fileName, () {
+    final file = new File(fileName);
+    expect(file.readAsStringSync(), contains(_pubspecContent));
+  });
+}
+
+final _pubspecContent = r'''
+dependencies:
+  json_annotation: ^0.2.1
+
+dev_dependencies:
+  build_runner: ^0.6.1
+  json_serializable: ^0.2.5
+  source_gen: ^0.7.2+1
+''';