Update readme docs to include configuration information (#175)

Author: kevmoo

example/build.yaml

@@ -4,7 +4,7 @@ targets:
     builders:
       json_serializable:
         options:
-          header: |+
+          header: |
            // 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.

json_serializable/README.md

@@ -1,10 +1,20 @@
 [![Build Status](https://travis-ci.org/dart-lang/json_serializable.svg?branch=master)](https://travis-ci.org/dart-lang/json_serializable)
 
-Provides [source_gen] `Generator`s to create code for JSON serialization and
-deserialization using the [Dart Build System].
+Provides [Dart Build System] builders for handling JSON.
 
-See the [example] to understand how to configure your project for the latest
-released version of `json_serializable`.
+The builders generate code when they find members annotated with classes defined
+in [package:json_annotation].
+
+- To generate to/from JSON code for a class, annotate it with
+  `JsonSerializable`. You can provide arguments to `JsonSerializable` to
+  configure the generated code. You can also customize individual fields
+  by annotating them with `JsonKey` and providing custom arguments.
+
+- To generate a Dart field with the contents of a file containting JSON, use the
+  `JsonLiteral` annotation.
+
+To configure your project for the latest released version of,
+`json_serializable` see the [example].
 
 ## Example
 
@@ -48,6 +58,40 @@ abstract class _$PersonSerializerMixin {
 }
 ```
 
+# Build configuration
+
+Besides setting arguments on the associated annotation classes, you can also
+configure code generation by setting values in `build.yaml`.
+
+```yaml
+targets:
+  $default:
+    builders:
+      json_serializable:
+        options:
+          # Specifies a string to add to the top of every generated file.
+          #
+          # If not specified, the default is the value of `defaultFileHeader`
+          # defined in `package:source_gen/source_gen.dart`.
+          #
+          # Note: use `|` to define a multi-line block.
+          header: |
+           // Copyright (c) 2018, the Dart project authors.
+
+           // GENERATED CODE - DO NOT MODIFY BY HAND
+
+          # Options configure how source code is generated for every
+          # `@JsonSerializable`-annotated class in the package.
+          #
+          # The default value for each of them: `false`.
+          #
+          # For usage information, reference the corresponding field in
+          # `JsonSerializableGenerator`.
+          use_wrappers: true
+          any_map: true
+          checked: true
+```
+
 [example]: https://github.com/dart-lang/json_serializable/blob/master/example
-[source_gen]: https://pub.dartlang.org/packages/source_gen
 [Dart Build System]: https://github.com/dart-lang/build
+[package:json_annotation]: https://pub.dartlang.org/packages/json_annotation

json_serializable/test/config_test.dart

@@ -3,12 +3,14 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:io';
 
 import 'package:build/build.dart';
 import 'package:json_serializable/builder.dart';
 import 'package:logging/logging.dart';
 import 'package:source_gen/source_gen.dart';
 import 'package:test/test.dart';
+import 'package:yaml/yaml.dart';
 
 final _throwsCastError = throwsA(const isInstanceOf<CastError>());
 
@@ -40,6 +42,35 @@ void main() {
     expect(records, isEmpty);
   });
 
+  test('readme config', () async {
+    var configExampleContent = new File('README.md')
+        .readAsLinesSync()
+        .skipWhile((line) => line != '```yaml')
+        .skip(1)
+        .takeWhile((line) => line != '```')
+        .join('\n');
+
+    var yaml = loadYaml(configExampleContent) as YamlMap;
+
+    for (var key in [
+      'targets',
+      r'$default',
+      'builders',
+      'json_serializable',
+      'options'
+    ]) {
+      yaml = yaml[key] as YamlMap;
+    }
+
+    var config = new Map<String, dynamic>.from(yaml);
+
+    expect(config.keys, unorderedEquals(_validConfig.keys));
+
+    var builder = jsonSerializable(new BuilderOptions(config)) as PartBuilder;
+    expect(builder, isNotNull);
+    expect(records, isEmpty);
+  });
+
   test('unsupported configuration', () async {
     var builder =
         jsonSerializable(const BuilderOptions(const {'unsupported': 'config'}))