Update for review comments.

built_json/lib/built_json.dart

@@ -42,6 +42,8 @@ abstract class Serializers {
   /// [genericType] will be needed to deserialize.
   ///
   /// Create one using [SerializersBuilder].
+  ///
+  /// TODO(davidmorgan): document the wire format.
   Object serialize(Object object,
       {GenericType genericType: const GenericType()});
 
@@ -84,9 +86,9 @@ class GenericType {
   final Type root;
 
   /// Type parameters of the type.
-  final List<GenericType> leaves;
+  final List<GenericType> parameters;
 
-  const GenericType([this.root = Object, this.leaves = const []]);
+  const GenericType([this.root = Object, this.parameters = const []]);
 
   bool get isObject => root == Object;
 }
@@ -103,7 +105,9 @@ abstract class Serializer<T> {
 
   /// The [Type]s that can be serialized.
   ///
-  /// They must all be equal to T or subclasses of T.
+  /// They must all be equal to T or a subclass of T. Subclasses are used when
+  /// T is an abstract class, which is the case with built_value generated
+  /// serializers.
   Iterable<Type> get types;
 
   /// The wire name of the serializable type. For most classes, the class name.
@@ -115,6 +119,8 @@ abstract class Serializer<T> {
   ///
   /// Use [serializers] as needed for nested serialization. Information about
   /// the type being serialized is provided in [genericType].
+  ///
+  /// TODO(davidmorgan): document the wire format.
   Object serialize(Serializers serializers, T object,
       {GenericType genericType: const GenericType()});
 

built_json/lib/src/built_json_serializers.dart

@@ -10,7 +10,6 @@ class BuiltJsonSerializers implements Serializers {
   final BuiltMap<Type, Serializer> _typeToSerializer;
   final BuiltMap<String, Serializer> _wireNameToSerializer;
   final BuiltMap<String, Serializer> _typeNameToSerializer;
-
   final BuiltMap<GenericType, Function> _builderFactories;
 
   BuiltJsonSerializers._(this._typeToSerializer, this._wireNameToSerializer,
@@ -48,8 +47,9 @@ class BuiltJsonSerializers implements Serializers {
       final wireName = (object as List).first;
 
       final serializer = _wireNameToSerializer[wireName];
-      if (serializer ==
-          null) throw new StateError("No serializer for '${wireName}'.");
+      if (serializer == null) {
+        throw new StateError("No serializer for '${wireName}'.");
+      }
       final json = serializer.structured
           ? (object as List).sublist(1)
           : (object as List)[1];
@@ -78,7 +78,7 @@ class BuiltJsonSerializers implements Serializers {
   }
 
   Serializer _getSerializerByType(Type type) {
-    return _typeToSerializer[type] ?? _typeNameToSerializer[_getName(type)];
+    return _typeToSerializer[type] ?? _typeNameToSerializer[_getRawName(type)];
   }
 }
 
@@ -106,7 +106,7 @@ class BuiltJsonSerializersBuilder implements SerializersBuilder {
     _wireNameToSerializer[serializer.wireName] = serializer;
     for (final type in serializer.types) {
       _typeToSerializer[type] = serializer;
-      _typeNameToSerializer[_getName(type)] = serializer;
+      _typeNameToSerializer[_getRawName(type)] = serializer;
     }
   }
 
@@ -123,9 +123,8 @@ class BuiltJsonSerializersBuilder implements SerializersBuilder {
   }
 }
 
-String _getName(Type type) => _makeRaw(type.toString());
-
-String _makeRaw(String name) {
+String _getRawName(Type type) {
+  final name = type.toString();
   final genericsStart = name.indexOf('<');
   return genericsStart == -1 ? name : name.substring(0, genericsStart);
 }

built_json/lib/src/built_list_serializer.dart

@@ -13,9 +13,9 @@ class BuiltListSerializer implements Serializer<BuiltList> {
   @override
   Object serialize(Serializers serializers, BuiltList object,
       {GenericType genericType: const GenericType()}) {
-    final valueGenericType = genericType.leaves.isEmpty
+    final valueGenericType = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
+        : genericType.parameters[0];
 
     return object.map(
         (item) => serializers.serialize(item, genericType: valueGenericType));
@@ -24,9 +24,9 @@ class BuiltListSerializer implements Serializer<BuiltList> {
   @override
   BuiltList deserialize(Serializers serializers, Object object,
       {GenericType genericType: const GenericType()}) {
-    final valueGenericType = genericType.leaves.isEmpty
+    final valueGenericType = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
+        : genericType.parameters[0];
 
     final result = serializers.newBuilder(genericType) as ListBuilder ??
         new ListBuilder<Object>();

built_json/lib/src/built_map_serializer.dart

@@ -13,12 +13,12 @@ class BuiltMapSerializer implements Serializer<BuiltMap> {
   @override
   Object serialize(Serializers serializers, BuiltMap object,
       {GenericType genericType: const GenericType()}) {
-    final keyTypes = genericType.leaves.isEmpty
+    final keyTypes = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
-    final valueTypes = genericType.leaves.isEmpty
+        : genericType.parameters[0];
+    final valueTypes = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[1];
+        : genericType.parameters[1];
 
     final result = <Object>[];
     for (final key in object.keys) {
@@ -32,12 +32,12 @@ class BuiltMapSerializer implements Serializer<BuiltMap> {
   @override
   BuiltMap deserialize(Serializers serializers, Object object,
       {GenericType genericType: const GenericType()}) {
-    final keyTypes = genericType.leaves.isEmpty
+    final keyTypes = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
-    final valueTypes = genericType.leaves.isEmpty
+        : genericType.parameters[0];
+    final valueTypes = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[1];
+        : genericType.parameters[1];
 
     final result = serializers.newBuilder(genericType) as MapBuilder ??
         new MapBuilder<Object, Object>();

built_json/lib/src/built_set_serializer.dart

@@ -13,9 +13,9 @@ class BuiltSetSerializer implements Serializer<BuiltSet> {
   @override
   Object serialize(Serializers serializers, BuiltSet object,
       {GenericType genericType: const GenericType()}) {
-    final valueGenericType = genericType.leaves.isEmpty
+    final valueGenericType = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
+        : genericType.parameters[0];
 
     return object.map(
         (item) => serializers.serialize(item, genericType: valueGenericType));
@@ -24,9 +24,9 @@ class BuiltSetSerializer implements Serializer<BuiltSet> {
   @override
   BuiltSet deserialize(Serializers serializers, Object object,
       {GenericType genericType: const GenericType()}) {
-    final valueGenericType = genericType.leaves.isEmpty
+    final valueGenericType = genericType.parameters.isEmpty
         ? const GenericType()
-        : genericType.leaves[0];
+        : genericType.parameters[0];
 
     final result = serializers.newBuilder(genericType) as SetBuilder ??
         new SetBuilder<Object>();

example/lib/compound_value.dart

@@ -11,13 +11,6 @@ import 'package:example/test_enum.dart';
 
 part 'compound_value.g.dart';
 
-/// Example of how to use built_json.
-///
-/// Declare a top level [Serializers] field called
-/// serializers. The built_json code generator will provide the
-/// implementation. You usually only need to do this once per project.
-Serializers serializers = _$serializers;
-
 /// Example built_value type.
 abstract class CompoundValue
     implements Built<CompoundValue, CompoundValueBuilder> {

example/lib/serializers.dart

@@ -0,0 +1,19 @@
+// Copyright (c) 2015, Google Inc. 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.
+
+library serializers;
+
+import 'package:built_json/built_json.dart';
+import 'package:example/test_enum.dart';
+import 'package:example/value.dart';
+import 'package:example/compound_value.dart';
+
+part 'serializers.g.dart';
+
+/// Example of how to use built_json.
+///
+/// Declare a top level [Serializers] field called
+/// serializers. The built_json code generator will provide the
+/// implementation. You usually only need to do this once per project.
+Serializers serializers = _$serializers;

example/lib/test_enum.dart

@@ -11,13 +11,6 @@ import 'package:example/value.dart';
 
 part 'test_enum.g.dart';
 
-/// Example of how to use built_json.
-///
-/// Declare a top level [Serializers] field called
-/// serializers. The built_json code generator will provide the
-/// implementation. You usually only need to do this once per project.
-Serializers serializers = _$serializers;
-
 /// Example [EnumClass].
 class TestEnum extends EnumClass {
   /// Example of how to make an [EnumClass] serializable.

example/lib/value.dart

@@ -12,13 +12,6 @@ import 'package:example/test_enum.dart';
 
 part 'value.g.dart';
 
-/// Example of how to use built_json.
-///
-/// Declare a top level [Serializers] field called
-/// serializers. The built_json code generator will provide the
-/// implementation. You usually only need to do this once per project.
-Serializers serializers = _$serializers;
-
 /// Example built_value type.
 abstract class Value implements Built<Value, ValueBuilder> {
   /// Example of how to make a built_value type serializable.

example/test/compound_value_test.dart

@@ -3,47 +3,42 @@
 // license that can be found in the LICENSE file.
 
 import 'package:example/compound_value.dart';
-import 'package:example/test_enum.dart' hide serializers;
+import 'package:example/serializers.dart';
+import 'package:example/test_enum.dart';
 import 'package:test/test.dart';
 
 void main() {
-  group('Value', () {
-    test('can be serialized', () {
-      final compoundValue = new CompoundValue((b) => b
-        ..aValue.anInt = 1
-        ..aValue.aString = 'two'
-        ..aValue.anObject = 3
-        ..aTestEnum = TestEnum.no);
+  group('CompoundValue', () {
+    final data = new CompoundValue((b) => b
+      ..aValue.anInt = 1
+      ..aValue.aString = 'two'
+      ..aValue.anObject = 3
+      ..aTestEnum = TestEnum.no);
+    final serialized = [
+      'CompoundValue',
+      'aValue',
+      [
+        'anInt',
+        1,
+        'aString',
+        'two',
+        'anObject',
+        ['int', 3],
+        'aDefaultInt',
+        7,
+        'listOfInt',
+        [],
+      ],
+      'aTestEnum',
+      'no',
+    ];
 
-      expect(serializers.serialize(compoundValue), [
-        'CompoundValue',
-        'aValue',
-        [
-          'anInt',
-          1,
-          'aString',
-          'two',
-          'anObject',
-          ['int', 3],
-          'aDefaultInt',
-          7,
-          'listOfInt',
-          [],
-        ],
-        'aTestEnum',
-        'no',
-      ]);
+    test('can be serialized', () {
+      expect(serializers.serialize(data), serialized);
     });
 
     test('can be deserialized', () {
-      final compoundValue = new CompoundValue((b) => b
-        ..aValue.anInt = 1
-        ..aValue.aString = 'two'
-        ..aValue.anObject = 3
-        ..aTestEnum = TestEnum.no);
-
-      expect(serializers.deserialize(serializers.serialize(compoundValue)),
-          compoundValue);
+      expect(serializers.deserialize(serialized), data);
     });
   });
 }