Merge pull request #1283 from square/jw/docs

Fill out some documentation on public types.

retrofit/src/main/java/retrofit/Call.java

@@ -27,10 +27,31 @@ import java.io.IOException;
  * #enqueue}. In either case the call can be canceled at any time with {@link #cancel}. A call that
  * is busy writing its request or reading its response may receive a {@link IOException}; this is
  * working as designed.
+ *
+ * @param <T> Successful response body type.
  */
 public interface Call<T> extends Cloneable {
+  /**
+   * Synchronously send the request and return its response.
+   *
+   * @throws IOException if a problem occurred talking to the server.
+   * @throws RuntimeException (and subclasses) if an unexpected error occurs creating the request
+   * or processing the response.
+   */
   Response<T> execute() throws IOException;
+
+  /**
+   * Asynchronously send the request and notify {@code callback} of its response or if an error
+   * occurred talking to the server, creating the request, or processing the response.
+   */
   void enqueue(Callback<T> callback);
+
+  /**
+   * Cancel this call. An attempt will be made to cancel in-flight calls, and if the call has not
+   * yet been executed it never will be.
+   */
   void cancel();
+
+  /** Create a new, identical call to this one. */
   Call<T> clone();
 }

retrofit/src/main/java/retrofit/CallAdapter.java

@@ -33,10 +33,11 @@ public interface CallAdapter<T> {
   /** Returns an instance of the {@code T} which adapts the execution of {@code call}. */
   <R> T adapt(Call<R> call);
 
+  /** Creates {@link CallAdapter} instances based on a desired type. */
   interface Factory {
     /**
-     * Returns a call adapter for interface methods that return {@code returnType}, or null if this
-     * factory doesn't adapt that type.
+     * Returns a call adapter for interface methods that return {@code returnType}, or null if it
+     * cannot be handled by this factory.
      */
     CallAdapter<?> get(Type returnType, Annotation[] annotations, Retrofit retrofit);
   }

retrofit/src/main/java/retrofit/Callback.java

@@ -26,12 +26,20 @@ package retrofit;
  * <li>JVM: Callbacks are executed on the background thread which performed the request.</li>
  * </ul>
  *
- * @param <T> expected response type
+ * @param <T> Successful response body type.
  */
 public interface Callback<T> {
-  /** Successful HTTP response. */
+  /**
+   * Invoked for a received HTTP response.
+   * <p>
+   * Note: An HTTP response may still indicate an application-level failure such as a 404 or 500.
+   * Call {@link Response#isSuccess()} to determine if the response indicates success.
+   */
   void onResponse(Response<T> response);
 
-  /** Invoked when a network or unexpected exception occurred during the HTTP request. */
+  /**
+   * Invoked when a network exception occurred talking to the server or when an unexpected
+   * exception occurred creating the request or processing the response.
+   */
   void onFailure(Throwable t);
 }

retrofit/src/main/java/retrofit/Converter.java

@@ -22,24 +22,25 @@ import java.lang.annotation.Annotation;
 import java.lang.reflect.Type;
 
 /**
- * Convert objects to and from their representation as HTTP bodies. Register a converter with
- * Retrofit using {@link Retrofit.Builder#addConverterFactory(Factory)}.
+ * Convert objects to and from their representation in HTTP. Register a converter with Retrofit
+ * using {@link Retrofit.Builder#addConverterFactory(Factory)}.
  */
 public interface Converter<F, T> {
   T convert(F value) throws IOException;
 
+  /** Creates {@link Converter} instances based on a type and target usage. */
   abstract class Factory {
     /**
-     * Create a {@link Converter} for converting an HTTP response body to {@code type} or null if it
-     * cannot be handled by this factory.
+     * Returns a {@link Converter} for converting an HTTP response body to {@code type}, or null if
+     * {@code type} cannot be handled by this factory.
      */
     public Converter<ResponseBody, ?> fromResponseBody(Type type, Annotation[] annotations) {
       return null;
     }
 
     /**
-     * Create a {@link Converter} for converting {@code type} to an HTTP request body or null if it
-     * cannot be handled by this factory.
+     * Returns a {@link Converter} for converting {@code type} to an HTTP request body, or null if
+     * {@code type} cannot be handled by this factory.
      */
     public Converter<?, RequestBody> toRequestBody(Type type, Annotation[] annotations) {
       return null;