Added javadoc comment in JsonAdapter explaining the usage for fields.

Added a (broken) test the ensure a field annotation for JsonAdapter supersedes a class annotation.

gson/src/main/java/com/google/gson/annotations/JsonAdapter.java

@@ -22,6 +22,8 @@
 import java.lang.annotation.Target;
 
 import com.google.gson.TypeAdapter;
+import com.google.gson.functional.JsonAdapterAnnotationOnFieldsTest.Part;
+import com.google.gson.functional.JsonAdapterAnnotationOnFieldsTest.PartJsonAdapter;
 
 /**
  * An annotation that indicates the Gson {@link TypeAdapter} to use with a class or a field.
@@ -59,11 +61,24 @@
  * </pre>
  *
  * Since User class specified UserJsonAdapter.class in &#64JsonAdapter annotation, it
- * will automatically be invoked to serialize/deserialize User instances.
+ * will automatically be invoked to serialize/deserialize User instances. <br>
  *
  * If the UserJsonAdapter needs a constructor other than a no-args constructor, you must register
  * an {@link com.google.gson.InstanceCreator} for it.
- * 
+ *
+ * <p> Here is an example of how to apply this annotation to a field.
+ * <pre>
+ * private static final class Gadget {
+ *   &#64JsonAdapter(UserJsonAdapter2.class)
+ *   final User user;
+ *   Gadget(User user) {
+ *     this.user = user;
+ *   }
+ * }
+ * </pre>
+ * The above annotation will ensure UserJsonAdapter2 supersedes UserJsonAdapter for the user
+ * field of the Gadget class.
+ *
  * @since 2.3
  *
  * @author Inderjeet Singh

gson/src/test/java/com/google/gson/functional/JsonAdapterAnnotationOnFieldsTest.java

@@ -43,7 +43,7 @@ public void testJsonAdapterInvoked() {
   public void testRegisteredTypeAdapterOverridesFieldAnnotation() {
     Gson gson = new GsonBuilder()
       .registerTypeAdapter(Part.class, new TypeAdapter<Part>() {
-        @Override public void write(JsonWriter out, Part user) throws IOException {
+        @Override public void write(JsonWriter out, Part part) throws IOException {
           out.value("registeredAdapter");
         }
         @Override public Part read(JsonReader in) throws IOException {
@@ -56,6 +56,14 @@ public void testRegisteredTypeAdapterOverridesFieldAnnotation() {
     assertEquals("registeredAdapterValue", gadget.part.name);
   }
 
+  public void testFieldAnnotationSupersedesClassAnnotation() {
+    Gson gson = new Gson();
+    String json = gson.toJson(new Computer2(new User("Inderjeet Singh")));
+    assertEquals("{\"user\":\"userJsonAdapter2\"}", json);
+    Computer2 target = gson.fromJson("{'user':'userJsonAdapter2Value'}", Computer2.class);
+    assertEquals("userJsonAdapter2Value", target.user.name);
+  }
+
   private static final class Gadget {
     @JsonAdapter(PartJsonAdapter.class)
     final Part part;
@@ -82,7 +90,6 @@ private static class PartJsonAdapter extends TypeAdapter<Part> {
   }
 
   private static final class Computer {
-    @JsonAdapter(UserJsonAdapter.class)
     final User user;
     Computer(User user) {
       this.user = user;
@@ -119,4 +126,21 @@ private static class UserJsonAdapter extends TypeAdapter<User> {
       return new User(firstName + " " + lastName);
     }
   }
+
+  private static final class Computer2 {
+    // overrides the JsonAdapter annotation of User with this
+    @JsonAdapter(UserJsonAdapter2.class)
+    final User user;
+    Computer2(User user) {
+      this.user = user;
+    }
+  }
+  private static final class UserJsonAdapter2 extends TypeAdapter<User> {
+    @Override public void write(JsonWriter out, User user) throws IOException {
+      out.value("userJsonAdapter2");
+    }
+    @Override public User read(JsonReader in) throws IOException {
+      return new User(in.nextString());
+    }
+  }
 }