Merge pull request square#1714 from square/jw/adapter-docs

Adapter Javadoc details.

Author: swankjesse

retrofit-adapters/guava/src/main/java/retrofit2/adapter/guava/GuavaCallAdapterFactory.java

@@ -17,6 +17,7 @@
 
 import com.google.common.util.concurrent.AbstractFuture;
 import com.google.common.util.concurrent.ListenableFuture;
+import java.io.IOException;
 import java.lang.annotation.Annotation;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
@@ -26,6 +27,27 @@
 import retrofit2.Response;
 import retrofit2.Retrofit;
 
+/**
+ * A {@linkplain CallAdapter.Factory call adapter} which creates Guava futures.
+ * <p>
+ * Adding this class to {@link Retrofit} allows you to return {@link ListenableFuture} from service
+ * methods.
+ * <pre>{@code
+ * interface MyService {
+ *   &#64;GET("user/me")
+ *   ListenableFuture<User> getUser()
+ * }
+ * }</pre>
+ * There are two configurations supported for the {@code ListenableFuture} type parameter:
+ * <ul>
+ * <li>Direct body (e.g., {@code ListenableFuture<User>}) returns the deserialized body for 2XX
+ * responses, sets {@link HttpException} errors for non-2XX responses, and sets {@link IOException}
+ * for network errors.</li>
+ * <li>Response wrapped body (e.g., {@code ListenableFuture<Response<User>>}) returns a
+ * {@link Response} object for all HTTP responses and sets {@link IOException} for network
+ * errors</li>
+ * </ul>
+ */
 public final class GuavaCallAdapterFactory extends CallAdapter.Factory {
   public static GuavaCallAdapterFactory create() {
     return new GuavaCallAdapterFactory();

retrofit-adapters/java8/src/main/java/retrofit2/adapter/java8/Java8CallAdapterFactory.java

@@ -15,6 +15,7 @@
  */
 package retrofit2.adapter.java8;
 
+import java.io.IOException;
 import java.lang.annotation.Annotation;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
@@ -25,6 +26,27 @@
 import retrofit2.Response;
 import retrofit2.Retrofit;
 
+/**
+ * A {@linkplain CallAdapter.Factory call adapter} which creates Java 8 futures.
+ * <p>
+ * Adding this class to {@link Retrofit} allows you to return {@link CompletableFuture} from
+ * service methods.
+ * <pre>{@code
+ * interface MyService {
+ *   &#64;GET("user/me")
+ *   CompletableFuture<User> getUser()
+ * }
+ * }</pre>
+ * There are two configurations supported for the {@code CompletableFuture} type parameter:
+ * <ul>
+ * <li>Direct body (e.g., {@code CompletableFuture<User>}) returns the deserialized body for 2XX
+ * responses, sets {@link HttpException} errors for non-2XX responses, and sets {@link IOException}
+ * for network errors.</li>
+ * <li>Response wrapped body (e.g., {@code CompletableFuture<Response<User>>}) returns a
+ * {@link Response} object for all HTTP responses and sets {@link IOException} for network
+ * errors</li>
+ * </ul>
+ */
 public final class Java8CallAdapterFactory extends CallAdapter.Factory {
   public static Java8CallAdapterFactory create() {
     return new Java8CallAdapterFactory();

retrofit-adapters/rxjava/src/main/java/retrofit2/adapter/rxjava/RxJavaCallAdapterFactory.java

@@ -15,6 +15,7 @@
  */
 package retrofit2.adapter.rxjava;
 
+import java.io.IOException;
 import java.lang.annotation.Annotation;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
@@ -43,6 +44,17 @@
  *   Observable<User> getUser()
  * }
  * }</pre>
+ * There are three configurations supported for the {@code Observable} type parameter:
+ * <ul>
+ * <li>Direct body (e.g., {@code Observable<User>}) calls {@code onNext} with the deserialized body
+ * for 2XX responses and calls {@code onError} with {@link HttpException} for non-2XX responses and
+ * {@link IOException} for network errors.</li>
+ * <li>Response wrapped body (e.g., {@code Observable<Response<User>>}) calls {@code onNext}
+ * with a {@link Response} object for all HTTP responses and calls {@code onError} with
+ * {@link IOException} for network errors</li>
+ * <li>Result wrapped body (e.g., {@code Observable<Result<User>>}) calls {@code onNext} with a
+ * {@link Result} object for all HTTP responses and errors.</li>
+ * </ul>
  */
 public final class RxJavaCallAdapterFactory extends CallAdapter.Factory {
   /**