Many updates to example/

README.md

@@ -3,24 +3,29 @@
 Provides [source_gen] `Generator`s to create code for JSON serialization and
 deserialization.
 
-## [json_serializable]
+## json_serializable
+
+* Package: https://pub.dartlang.org/packages/json_serializable
+* [Source code](json_serializable)
 
 The core package providing Generators for JSON-specific tasks.
 
 Import it into your pubspec `dev_dependencies:` section.
 
-## [json_annotation]
+## json_annotation
+
+* Package: https://pub.dartlang.org/packages/json_annotation
+* [Source code](json_annotation)
 
 The annotation package which has no dependencies.
 
 Import it into your pubspec `dependencies:` section.
 
-## [example]
+## example
+
+* [Source code](example)
 
-A simple example showing how to setup and use [json_serializable] and
-[json_annotation].
+An example showing how to setup and use `json_serializable` and
+`json_annotation`.
 
-[json_serializable]: https://github.com/dart-lang/json_serializable/blob/master/json_serializable/README.md
-[json_annotation]: https://github.com/dart-lang/json_serializable/blob/master/json_annotation/README.md
-[example]: https://github.com/dart-lang/json_serializable/blob/master/example/README.md
 [source_gen]: https://pub.dartlang.org/packages/source_gen

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/pubspec.yaml

@@ -8,11 +8,16 @@ dependencies:
   json_annotation: ^0.2.1
 
 dev_dependencies:
-  build_runner: any
+  build_runner: ^0.6.1
   json_serializable: ^0.2.5
   source_gen: ^0.7.2+1
+
+  # A great Dart testing package, but not required to use `json_serializable`.
   test: ^0.12.29
 
+# Don't copy `dependency_overrides` into your `pubspec.yaml`
+# Here to ensure compatibility with the packages in this repository during
+# development.
 dependency_overrides:
   json_annotation:
     path: ../json_annotation

example/test/example_test.dart

@@ -11,18 +11,22 @@ void main() {
   test('JsonSerializable', () {
     final person = new Person('Inigo', 'Montoya', new DateTime(1560, 5, 5));
 
-    final prettyJson = const JsonEncoder.withIndent(' ').convert(person);
-    print(prettyJson);
+    final personJson = _encode(person);
 
     final person2 =
-        new Person.fromJson(JSON.decode(prettyJson) as Map<String, dynamic>);
+        new Person.fromJson(JSON.decode(personJson) as Map<String, dynamic>);
 
     expect(person.firstName, person2.firstName);
     expect(person.lastName, person2.lastName);
     expect(person.dateOfBirth, person2.dateOfBirth);
+
+    expect(_encode(person2), equals(personJson));
   });
 
   test('JsonLiteral', () {
     expect(glossaryData, hasLength(1));
   });
 }
+
+String _encode(Object object) =>
+    const JsonEncoder.withIndent(' ').convert(object);

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
+''';

example/tool/build_actions.dart

@@ -2,17 +2,17 @@
 // 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.
 
-/// Defines the `BuildAction` class.
+/// Defines [BuildAction]
 import 'package:build_runner/build_runner.dart';
 
-// Defines `JsonSerializableGenerator` and `JsonLiteralGenerator`
+/// Defines [JsonSerializableGenerator] and [JsonLiteralGenerator]
 import 'package:json_serializable/generators.dart';
 
-// Defines `PartBuilder`
+/// Defines [PartBuilder]
 import 'package:source_gen/source_gen.dart';
 
-// The list of `BuildAction`s  used by `build.dart` and `watch.dart` to
-// generate source code for this package.
+/// The list of [BuildAction]s  used by `build.dart` and `watch.dart` to
+/// generate source code for this package.
 List<BuildAction> get buildActions => [
       new BuildAction(
         // `PartBuilder` is a `Builder` defined by `package:source_gen` for
@@ -38,6 +38,8 @@ List<BuildAction> get buildActions => [
       ),
     ];
 
+/// Used in the `header` argument to the [PartBuilder] constructor to add the
+/// standard copyright notice to all generated files.
 final _copyrightContent =
     '''// 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

json_annotation/README.md

@@ -7,6 +7,6 @@ See the [example] to understand how to configure your package.
 
 Please file feature requests and bugs at the [issue tracker][tracker].
 
-[example]: https://github.com/dart-lang/json_serializable/blob/master/example/README.md
+[example]: https://github.com/dart-lang/json_serializable/blob/master/example
 [tracker]: https://github.com/dart-lang/json_serializable/issues
 [json_serializable]: https://pub.dartlang.org/packages/json_serializable

json_serializable/README.md

@@ -81,5 +81,5 @@ abstract class _$PersonSerializerMixin {
 }
 ```
 
-[example]: https://github.com/dart-lang/json_serializable/blob/master/example/README.md
+[example]: https://github.com/dart-lang/json_serializable/blob/master/example
 [source_gen]: https://pub.dartlang.org/packages/source_gen