Fill in a bunch of missing or slightly incorrect documentation.

retrofit-adapters/README.md

@@ -1,4 +1,14 @@
 Retrofit Adapters
 =================
 
-TODO
+Retrofit ships with a default adapter for executing `Call` instances. The child modules contained
+herein are additional adapters for other popular execution mechanisms.
+
+To use, supply an instance of your desired converter when building your `Retrofit` instance.
+
+```java
+Retrofit retrofit = new Retrofit.Builder()
+    .baseUrl("https://api.example.com")
+    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
+    .build();
+```

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

@@ -31,18 +31,29 @@
 import rx.subscriptions.Subscriptions;
 
 /**
- * TODO docs
+ * A {@linkplain CallAdapter.Factory call adapter} which uses RxJava for creating observables.
+ * <p>
+ * Adding this class to {@link Retrofit} allows you to return {@link Observable} from service
+ * methods.
+ * <pre>{@code
+ * interface MyService {
+ *   &#64;GET("user/me")
+ *   Observable<User> getUser()
+ * }
+ * }</pre>
  */
 public final class RxJavaCallAdapterFactory extends CallAdapter.Factory {
   /**
-   * TODO
+   * Returns an instance which creates synchronous observables that do not operate on any scheduler
+   * by default.
    */
   public static RxJavaCallAdapterFactory create() {
     return new RxJavaCallAdapterFactory(null);
   }
 
   /**
-   * TODO
+   * Returns an instance which creates synchronous observables that
+   * {@linkplain Observable#subscribeOn(Scheduler) subscribe on} {@code scheduler} by default.
    */
   public static RxJavaCallAdapterFactory createWithScheduler(Scheduler scheduler) {
     if (scheduler == null) throw new NullPointerException("scheduler == null");

retrofit-converters/README.md

@@ -1,14 +1,15 @@
 Retrofit Converters
 ===================
 
-Retrofit ships with a default converter for JSON that uses Gson but the library is content-format
-agnostic. The child modules contained herein are additional converters for other popular formats.
+Retrofit ships with support for OkHttp's `RequestBody` and `ResponseBody` types but the library is
+content-format agnostic. The child modules contained herein are additional converters for other
+popular formats.
 
 To use, supply an instance of your desired converter when building your `Retrofit` instance.
 
 ```java
 Retrofit retrofit = new Retrofit.Builder()
     .baseUrl("https://api.example.com")
-    .converter(new ProtoConverter())
+    .addConverterFactory(GsonConverterFactory.create())
     .build();
 ```

retrofit/src/main/java/retrofit2/Retrofit.java

@@ -21,7 +21,6 @@
 import java.lang.reflect.Proxy;
 import java.lang.reflect.Type;
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -35,6 +34,7 @@
 import retrofit2.http.Header;
 import retrofit2.http.Url;
 
+import static java.util.Collections.unmodifiableList;
 import static retrofit2.Utils.checkNotNull;
 
 /**
@@ -71,8 +71,8 @@ public final class Retrofit {
       Executor callbackExecutor, boolean validateEagerly) {
     this.callFactory = callFactory;
     this.baseUrl = baseUrl;
-    this.converterFactories = converterFactories;
-    this.adapterFactories = adapterFactories;
+    this.converterFactories = unmodifiableList(converterFactories); // Defensive copy at call site.
+    this.adapterFactories = unmodifiableList(adapterFactories); // Defensive copy at call site.
     this.callbackExecutor = callbackExecutor;
     this.validateEagerly = validateEagerly;
   }
@@ -178,12 +178,17 @@ public okhttp3.Call.Factory callFactory() {
     return callFactory;
   }
 
+  /** The API base URL. */
   public HttpUrl baseUrl() {
     return baseUrl;
   }
 
+  /**
+   * Returns a list of the factories tried when creating a
+   * {@linkplain #callAdapter(Type, Annotation[])} call adapter}.
+   */
   public List<CallAdapter.Factory> callAdapterFactories() {
-    return Collections.unmodifiableList(adapterFactories);
+    return adapterFactories;
   }
 
   /**
@@ -233,10 +238,13 @@ public CallAdapter<?> nextCallAdapter(CallAdapter.Factory skipPast, Type returnT
   }
 
   /**
-   * TODO
+   * Returns a list of the factories tried when creating a
+   * {@linkplain #requestBodyConverter(Type, Annotation[], Annotation[]) request body converter}, a
+   * {@linkplain #responseBodyConverter(Type, Annotation[]) response body converter}, or a
+   * {@linkplain #stringConverter(Type, Annotation[]) string converter}.
    */
   public List<Converter.Factory> converterFactories() {
-    return Collections.unmodifiableList(converterFactories);
+    return converterFactories;
   }
 
   /**
@@ -418,7 +426,7 @@ public Builder callFactory(okhttp3.Call.Factory factory) {
     }
 
     /**
-     * Set a fixed API base URL.
+     * Set the API base URL.
      *
      * @see #baseUrl(HttpUrl)
      */
@@ -432,7 +440,7 @@ public Builder baseUrl(String baseUrl) {
     }
 
     /**
-     * Set a fixed API base URL.
+     * Set the API base URL.
      * <p>
      * The specified endpoint values (such as with {@link GET @GET}) are resolved against this
      * value using {@link HttpUrl#resolve(String)}. The behavior of this matches that of an