annotation: Update library doc comment describing the $ helper usage (#173)

* finish documenting the json_serializable annotations
* more docs for json_literal

Author: kevmoo

json_annotation/lib/json_annotation.dart

@@ -6,7 +6,8 @@
 /// [json_serializable](https://pub.dartlang.org/packages/json_serializable).
 ///
 /// Also contains helper functions and classes – prefixed with `$` used by
-/// `json_serializable` when generating wrappers.
+/// `json_serializable` when the `use_wrappers` or `checked` options are
+/// enabled.
 library json_annotation;
 
 export 'src/checked_helpers.dart';

json_annotation/lib/src/json_literal.dart

@@ -6,7 +6,15 @@
 /// JSON file.
 ///
 /// The annotation can be applied to any member, but usually it's applied to
-/// getter.
+/// top-level getter.
+///
+/// In this example, the JSON content of `data.json` is populated into a
+/// top-level, final field `_$glossaryDataJsonLiteral` in the generated file.
+///
+/// ```dart
+/// @JsonLiteral('data.json')
+/// Map get glossaryData => _$glossaryDataJsonLiteral;
+/// ```
 class JsonLiteral {
   /// The relative path from the Dart file with the annotation to the file
   /// containing the source JSON.
@@ -15,6 +23,7 @@ class JsonLiteral {
   /// `true` if the JSON literal should be written as a constant.
   final bool asConst;
 
+  /// Creates a new [JsonLiteral] instance.
   const JsonLiteral(this.path, {bool asConst: false})
       : this.asConst = asConst ?? false;
 }

json_annotation/lib/src/json_serializable.dart

@@ -4,8 +4,32 @@
 
 /// An annotation used to specify a class to generate code for.
 class JsonSerializable {
-  // TODO(kevmoo): document these fields
+  /// If `true` (the default), a private, static `_$ExampleFromJson` method
+  /// is created in the generated part file.
+  ///
+  /// Call this method from a factory constructor added to the source class:
+  ///
+  /// ```dart
+  /// @JsonSerializable()
+  /// class Example {
+  ///   // ...
+  ///   factory Example.fromJson(Map<String, dynamic> json) =>
+  ///     _$ExampleFromJson(json);
+  /// }
+  /// ```
   final bool createFactory;
+
+  /// If `true` (the default), a private `_$ClassNameMixin` class is created
+  /// in the generated part file which contains a `toJson` method.
+  ///
+  /// Mix in this class to the source class:
+  ///
+  /// ```dart
+  /// @JsonSerializable()
+  /// class Example extends Object with _$ExampleMixin {
+  ///   // ...
+  /// }
+  /// ```
   final bool createToJson;
 
   /// Whether the generator should include fields with `null` values in the
@@ -22,7 +46,7 @@ class JsonSerializable {
   /// `null` runtime validation if it's critical.
   final bool nullable;
 
-  // TODO(kevmoo): document the constructor
+  /// Creates a new [JsonSerializable] instance.
   const JsonSerializable(
       {bool createFactory: true,
       bool createToJson: true,
@@ -93,7 +117,7 @@ class JsonKey {
   /// Values returned by [toJson] should "round-trip" through [fromJson].
   final Function toJson;
 
-  /// Creates a new [JsonKey].
+  /// Creates a new [JsonKey] instance.
   ///
   /// Only required when the default behavior is not desired.
   const JsonKey(