Merge pull request square#1674 from square/jwilson_0525_url_doc_bugs

Better docs on new URL exceptions.

CHANGELOG.md

@@ -18,7 +18,10 @@ _2015-05-22_
 
 _2015-05-16_
 
- *  **New HttpUrl API.** It's like `java.net.URL` but good.
+ *  **New HttpUrl API.** It's like `java.net.URL` but good. Note that
+    `Request.Builder.url()` now throws `IllegalArgumentException` on malformed
+    URLs. (Previous releases would throw a `MalformedURLException` when calling
+    a malformed URL.)
 
  *  **We've improved connect failure recovery.** We now differentiate between
     setup, connecting, and connected and implement appropriate recovery rules

okhttp/src/main/java/com/squareup/okhttp/Request.java

@@ -143,6 +143,12 @@ public Builder url(HttpUrl url) {
       return this;
     }
 
+    /**
+     * Sets the URL target of this request.
+     *
+     * @throws IllegalArgumentException if {@code url} is not a valid HTTP or HTTPS URL. Avoid this
+     *     exception by calling {@link HttpUrl#parse}; it returns null for invalid URLs.
+     */
     public Builder url(String url) {
       if (url == null) throw new IllegalArgumentException("url == null");
 
@@ -158,6 +164,12 @@ public Builder url(String url) {
       return url(parsed);
     }
 
+    /**
+     * Sets the URL target of this request.
+     *
+     * @throws IllegalArgumentException if the scheme of {@code url} is not {@code http} or {@code
+     *     https}.
+     */
     public Builder url(URL url) {
       if (url == null) throw new IllegalArgumentException("url == null");
       HttpUrl parsed = HttpUrl.get(url);