Merge pull request square#2299 from NightlyNexus/eric/2017.04.21-quer…

…y-docs

Fix annotation docs to advertise string converters.

retrofit/src/main/java/retrofit2/http/Field.java

@@ -15,17 +15,22 @@
  */
 package retrofit2.http;
 
+import java.lang.annotation.Annotation;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.lang.reflect.Type;
+import retrofit2.Retrofit;
 
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Named pair for a form-encoded request.
  * <p>
- * Values are converted to strings using {@link String#valueOf(Object)} and then form URL encoded.
+ * Values are converted to strings using {@link Retrofit#stringConverter(Type, Annotation[])}
+ * (or {@link Object#toString()}, if no matching string converter is installed)
+ * and then form URL encoded.
  * {@code null} values are ignored. Passing a {@link java.util.List List} or array will result in a
  * field pair for each non-{@code null} item.
  * <p>

retrofit/src/main/java/retrofit2/http/HeaderMap.java

@@ -18,15 +18,19 @@
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+import java.lang.annotation.Annotation;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.lang.reflect.Type;
 import java.util.Map;
+import retrofit2.Retrofit;
 
 /**
  * Adds headers specified in the {@link Map}.
  * <p>
- * Values are converted to strings using {@link String#valueOf(Object)}.
+ * Values are converted to strings using {@link Retrofit#stringConverter(Type, Annotation[])}
+ * (or {@link Object#toString()}, if no matching string converter is installed).
  * <p>
  * Simple Example:
  * <pre>

retrofit/src/main/java/retrofit2/http/Path.java

@@ -15,16 +15,20 @@
  */
 package retrofit2.http;
 
+import java.lang.annotation.Annotation;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.lang.reflect.Type;
+import retrofit2.Retrofit;
 
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Named replacement in a URL path segment. Values are converted to string using
- * {@link String#valueOf(Object)} and URL encoded.
+ * Named replacement in a URL path segment. Values are converted to strings using
+ * {@link Retrofit#stringConverter(Type, Annotation[])} (or {@link Object#toString()},
+ * if no matching string converter is installed) and then URL encoded.
  * <p>
  * Simple example:
  * <pre><code>

retrofit/src/main/java/retrofit2/http/Query.java

@@ -15,17 +15,22 @@
  */
 package retrofit2.http;
 
+import java.lang.annotation.Annotation;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.lang.reflect.Type;
+import retrofit2.Retrofit;
 
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Query parameter appended to the URL.
  * <p>
- * Values are converted to strings using {@link String#valueOf(Object)} and then URL encoded.
+ * Values are converted to strings using {@link Retrofit#stringConverter(Type, Annotation[])}
+ * (or {@link Object#toString()}, if no matching string converter is installed)
+ * and then URL encoded.
  * {@code null} values are ignored. Passing a {@link java.util.List List} or array will result in a
  * query parameter for each non-{@code null} item.
  * <p>

retrofit/src/main/java/retrofit2/http/QueryMap.java

@@ -15,17 +15,21 @@
  */
 package retrofit2.http;
 
+import java.lang.annotation.Annotation;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.lang.reflect.Type;
+import retrofit2.Retrofit;
 
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Query parameter keys and values appended to the URL.
  * <p>
- * Both keys and values are converted to strings using {@link String#valueOf(Object)}.
+ * Values are converted to strings using {@link Retrofit#stringConverter(Type, Annotation[])}
+ * (or {@link Object#toString()}, if no matching string converter is installed).
  * <p>
  * Simple Example:
  * <pre><code>