rebase upstream

Author: TimWhiting

json_serializable/README.md

@@ -26,6 +26,8 @@ Given a library `example.dart` with an `Person` class annotated with
 [`JsonSerializable`]:
 
 ```dart
+import 'dart:convert';
+
 import 'package:json_annotation/json_annotation.dart';
 
 part 'example.g.dart';
@@ -39,7 +41,15 @@ class Person {
   /// exist or is empty.
   final DateTime? dateOfBirth;
 
-  Person({required this.firstName, required this.lastName, this.dateOfBirth});
+  /// An example of a custom map like type with non-string key
+  final Person2<int, String> person;
+
+  Person({
+    required this.firstName,
+    required this.lastName,
+    this.dateOfBirth,
+    required this.person,
+  });
 
   /// Connect the generated [_$PersonFromJson] function to the `fromJson`
   /// factory.
@@ -48,6 +58,23 @@ class Person {
   /// Connect the generated [_$PersonToJson] function to the `toJson` method.
   Map<String, dynamic> toJson() => _$PersonToJson(this);
 }
+
+const jsonKeyType = 'jsonKeyType';
+
+class Person2<@jsonKeyType K, V> {
+  Person2({required this.name, required this.id});
+  final V name;
+  final K id;
+
+  factory Person2.fromJson(Map<String, dynamic> json,
+          K Function(Object?) fromJsonK, V Function(Object?) fromJsonV) =>
+      Person2(id: fromJsonK(json), name: fromJsonV(json));
+  Map<String, dynamic> toJson(
+          String Function(K) toJsonK, Object? Function(V) toJsonV) =>
+      {
+        toJsonK(id): toJsonV(name),
+      };
+}
 ```
 
 Building creates the corresponding part `example.g.dart`:
@@ -61,12 +88,20 @@ Person _$PersonFromJson(Map<String, dynamic> json) => Person(
       dateOfBirth: json['dateOfBirth'] == null
           ? null
           : DateTime.parse(json['dateOfBirth'] as String),
+      person: Person2<int, String>.fromJson(
+          json['person'] as Map<String, dynamic>,
+          (value) => int.parse(value as String),
+          (value) => value as String),
     );
 
 Map<String, dynamic> _$PersonToJson(Person instance) => <String, dynamic>{
       'firstName': instance.firstName,
       'lastName': instance.lastName,
       'dateOfBirth': instance.dateOfBirth?.toIso8601String(),
+      'person': instance.person.toJson(
+        (value) => value.toString(),
+        (value) => value,
+      ),
     };
 ```
 
@@ -199,14 +234,14 @@ targets:
 [`Enum`]: https://api.dart.dev/stable/dart-core/Enum-class.html
 [`int`]: https://api.dart.dev/stable/dart-core/int-class.html
 [`Iterable`]: https://api.dart.dev/stable/dart-core/Iterable-class.html
-[`JsonConverter`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonConverter-class.html
-[`JsonEnum`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonEnum-class.html
-[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey/fromJson.html
-[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey/toJson.html
-[`JsonKey`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey-class.html
-[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonLiteral-class.html
-[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonSerializable-class.html
-[`JsonValue`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonValue-class.html
+[`JsonConverter`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonConverter-class.html
+[`JsonEnum`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonEnum-class.html
+[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/fromJson.html
+[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/toJson.html
+[`JsonKey`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey-class.html
+[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonLiteral-class.html
+[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonSerializable-class.html
+[`JsonValue`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonValue-class.html
 [`List`]: https://api.dart.dev/stable/dart-core/List-class.html
 [`Map`]: https://api.dart.dev/stable/dart-core/Map-class.html
 [`num`]: https://api.dart.dev/stable/dart-core/num-class.html