updated docs on decoder

adriancole · adriancole · commit eb03e2010e94 · 2013-09-21T11:24:38.000-07:00
diff --git a/README.md b/README.md
@@ -121,7 +121,7 @@ MyService api = Feign.create(MyService.class, "https://myAppProd", new RibbonMod
 ### Decoders
 The last argument to `Feign.create` allows you to specify additional configuration such as how to decode a responses, modeled in Dagger.
 
-If any methods in your interface return types besides `Response`, `void` or `String`, you'll need to configure a `Decoder`.
+If any methods in your interface return types besides `Response` or `void`, you'll need to configure a `Decoder`.
 
 The `GsonModule` in the `feign-gson` extension configures a `Decoder` which parses objects from JSON using reflection.
 
diff --git a/core/src/main/java/feign/codec/Decoder.java b/core/src/main/java/feign/codec/Decoder.java
@@ -25,7 +25,7 @@
 import static java.lang.String.format;
 
 /**
- * Decodes an HTTP response into a single object of the given {@code Type}. Invoked when
+ * Decodes an HTTP response into a single object of the given {@code type}. Invoked when
  * {@link Response#status()} is in the 2xx range and the return type is neither {@code void} nor {@code Response}.
  * <p/>
  * <p/>
@@ -49,14 +49,25 @@
  *   }
  * }
  * </pre>
+ * <br/>
+ * <h3>Implementation Note</h3>
+ * The {@code type} parameter will correspond to the
+ * {@link java.lang.reflect.Method#getGenericReturnType() generic return type}
+ * of an {@link feign.Target#type() interface} processed by
+ * {@link feign.Feign#newInstance(feign.Target)}.  When writing your
+ * implementation of Decoder, ensure you also test parameterized types such as
+ * {@code List<Foo>}.
+ *
  */
 public interface Decoder {
   /**
-   * Decodes a response into a single object.
+   * Decodes an http response into an object corresponding to its
+   * {@link java.lang.reflect.Method#getGenericReturnType() generic return type}.
    * If you need to wrap exceptions, please do so via {@link DecodeException}.
    *
    * @param response the response to decode
-   * @param type     Target object type.
+   * @param type     {@link java.lang.reflect.Method#getGenericReturnType() generic return type}
+   *                 of the method corresponding to this {@code response}.
    * @return instance of {@code type}
    * @throws IOException     will be propagated safely to the caller.
    * @throws DecodeException when decoding failed due to a checked exception besides IOException.
