Merge pull request #705 from square/jwilson.1008.register_as_factory

Document how to register JsonAdapters

adapters/src/main/java/com/squareup/moshi/adapters/EnumJsonAdapter.java

@@ -26,7 +26,16 @@ import javax.annotation.Nullable;
 
 /**
  * A JsonAdapter for enums that allows having a fallback enum value when a deserialized string does
- * not match any enum value.
+ * not match any enum value. To use, add this as an adapter for your enum type on your {@link
+ * com.squareup.moshi.Moshi.Builder Moshi.Builder}:
+ *
+ * <pre> {@code
+ *
+ *   Moshi moshi = new Moshi.Builder()
+ *       .add(CurrencyCode.class, EnumJsonAdapter.create(CurrencyCode.class)
+ *           .withUnknownFallback(CurrencyCode.USD))
+ *       .build();
+ * }</pre>
  */
 public final class EnumJsonAdapter<T extends Enum<T>> extends JsonAdapter<T> {
   final Class<T> enumType;

adapters/src/main/java/com/squareup/moshi/adapters/Rfc3339DateJsonAdapter.java

@@ -23,7 +23,15 @@ import java.util.Date;
 
 /**
  * Formats dates using <a href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a>, which is
- * formatted like {@code 2015-09-26T18:23:50.250Z}.
+ * formatted like {@code 2015-09-26T18:23:50.250Z}. To use, add this as an adapter for {@code
+ * Date.class} on your {@link com.squareup.moshi.Moshi.Builder Moshi.Builder}:
+ *
+ * <pre> {@code
+ *
+ *   Moshi moshi = new Moshi.Builder()
+ *       .add(Date.class, new Rfc3339DateJsonAdapter())
+ *       .build();
+ * }</pre>
  */
 public final class Rfc3339DateJsonAdapter extends JsonAdapter<Date> {
   @Override public synchronized Date fromJson(JsonReader reader) throws IOException {

adapters/src/main/java/com/squareup/moshi/adapters/RuntimeJsonAdapterFactory.java

@@ -32,7 +32,17 @@ import javax.annotation.CheckReturnValue;
 /**
  * A JsonAdapter factory for polymorphic types. This is useful when the type is not known before
  * decoding the JSON. This factory's adapters expect JSON in the format of a JSON object with a
- * key whose value is a label that determines the type to which to map the JSON object.
+ * key whose value is a label that determines the type to which to map the JSON object. To use, add
+ * this factory to your {@link Moshi.Builder}:
+ *
+ * <pre> {@code
+ *
+ *   Moshi moshi = new Moshi.Builder()
+ *       .add(RuntimeJsonAdapterFactory.of(Message.class, "type")
+ *           .registerSubtype(Success.class, "success")
+ *           .registerSubtype(Error.class, "error"))
+ *       .build();
+ * }</pre>
  */
 // TODO(jwilson): make this class public in Moshi 1.8.
 final class RuntimeJsonAdapterFactory<T> implements JsonAdapter.Factory {