Javadoc fixes

Author: smarek

library/AndroidManifest.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.loopj.android.http"
-    android:versionName="1.4.4-SNAPSHOT"
+    android:versionName="1.4.4"
     android:versionCode="144">
 
     <uses-sdk

library/src/com/loopj/android/http/AsyncHttpClient.java

@@ -37,15 +37,12 @@
 import java.net.URI;
 
 /**
- * Used to intercept and handle the responses from requests made using
- * {@link AsyncHttpClient}. The {@link #onSuccess(int, org.apache.http.Header[], byte[])} method is
- * designed to be anonymously overridden with your own response handling code.
- * <p>&nbsp;</p>
- * Additionally, you can override the {@link #onFailure(int, org.apache.http.Header[], byte[], Throwable)},
- * {@link #onStart()}, {@link #onFinish()}, {@link #onRetry()} and {@link #onProgress(int, int)} methods as required.
- * <p>&nbsp;</p>
- * For example:
- * <p>&nbsp;</p>
+ * Used to intercept and handle the responses from requests made using {@link AsyncHttpClient}. The
+ * {@link #onSuccess(int, org.apache.http.Header[], byte[])} method is designed to be anonymously
+ * overridden with your own response handling code. <p>&nbsp;</p> Additionally, you can override the
+ * {@link #onFailure(int, org.apache.http.Header[], byte[], Throwable)}, {@link #onStart()}, {@link
+ * #onFinish()}, {@link #onRetry()} and {@link #onProgress(int, int)} methods as required.
+ * <p>&nbsp;</p> For example: <p>&nbsp;</p>
  * <pre>
  * AsyncHttpClient client = new AsyncHttpClient();
  * client.get("http://www.google.com", new AsyncHttpResponseHandler() {
@@ -60,7 +57,8 @@
  *     }
  *
  *     &#064;Override
- *     public void onFailure(int statusCode, Header[] headers, byte[] responseBody, Throwable error) {
+ *     public void onFailure(int statusCode, Header[] headers, byte[] responseBody, Throwable error)
+ * {
  *         // Response failed :(
  *     }
  *
@@ -193,7 +191,8 @@ public void onStart() {
     }
 
     /**
-     * Fired in all cases when the request is finished, after both success and failure, override to handle in your own code
+     * Fired in all cases when the request is finished, after both success and failure, override to
+     * handle in your own code
      */
     public void onFinish() {
     }

library/src/com/loopj/android/http/AsyncHttpResponseHandler.java

@@ -30,13 +30,9 @@
 import java.util.regex.PatternSyntaxException;
 
 /**
- * Used to intercept and handle the responses from requests made using
- * {@link AsyncHttpClient}. Receives response body as byte array with a
- * content-type whitelist. (e.g. checks Content-Type against allowed list,
- * Content-length).
- * <p>&nbsp;</p>
- * For example:
- * <p>&nbsp;</p>
+ * Used to intercept and handle the responses from requests made using {@link AsyncHttpClient}.
+ * Receives response body as byte array with a content-type whitelist. (e.g. checks Content-Type
+ * against allowed list, Content-length). <p>&nbsp;</p> For example: <p>&nbsp;</p>
  * <pre>
  * AsyncHttpClient client = new AsyncHttpClient();
  * String[] allowedTypes = new String[] { "image/png" };
@@ -61,8 +57,8 @@ public class BinaryHttpResponseHandler extends AsyncHttpResponseHandler {
     };
 
     /**
-     * Method can be overriden to return allowed content types,
-     * can be sometimes better than passing data in constructor
+     * Method can be overriden to return allowed content types, can be sometimes better than passing
+     * data in constructor
      *
      * @return array of content-types or Pattern string templates (eg. '.*' to match every response)
      */
@@ -78,8 +74,8 @@ public BinaryHttpResponseHandler() {
     }
 
     /**
-     * Creates a new BinaryHttpResponseHandler, and overrides the default allowed
-     * content types with passed String array (hopefully) of content types.
+     * Creates a new BinaryHttpResponseHandler, and overrides the default allowed content types with
+     * passed String array (hopefully) of content types.
      *
      * @param allowedContentTypes content types array, eg. 'image/jpeg' or pattern '.*'
      */

library/src/com/loopj/android/http/BinaryHttpResponseHandler.java

@@ -28,16 +28,11 @@
 import org.json.JSONTokener;
 
 /**
- * Used to intercept and handle the responses from requests made using
- * {@link AsyncHttpClient}, with automatic parsing into a {@link JSONObject}
- * or {@link JSONArray}.
- * <p>&nbsp;</p>
- * This class is designed to be passed to get, post, put and delete requests
- * with the {@link #onSuccess(JSONObject)} or {@link #onSuccess(JSONArray)}
- * methods anonymously overridden.
- * <p>&nbsp;</p>
- * Additionally, you can override the other event methods from the
- * parent class.
+ * Used to intercept and handle the responses from requests made using {@link AsyncHttpClient}, with
+ * automatic parsing into a {@link JSONObject} or {@link JSONArray}. <p>&nbsp;</p> This class is
+ * designed to be passed to get, post, put and delete requests with the {@link
+ * #onSuccess(JSONObject)} or {@link #onSuccess(JSONArray)} methods anonymously overridden.
+ * <p>&nbsp;</p> Additionally, you can override the other event methods from the parent class.
  */
 public class JsonHttpResponseHandler extends TextHttpResponseHandler {
     private static final String LOG_TAG = "JsonHttpResponseHandler";
@@ -59,9 +54,8 @@ public JsonHttpResponseHandler(String encoding) {
     //
 
     /**
-     * Fired when a request returns successfully and contains a json object
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json object at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param response the parsed json object found in the server response (if any)
      */
@@ -70,19 +64,17 @@ public void onSuccess(JSONObject response) {
 
 
     /**
-     * Fired when a request returns successfully and contains a json array
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json array at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param response the parsed json array found in the server response (if any)
      */
     public void onSuccess(JSONArray response) {
     }
 
     /**
-     * Fired when a request returns successfully and contains a json object
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json object at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param statusCode the status code of the response
      * @param headers    the headers of the HTTP response
@@ -93,9 +85,8 @@ public void onSuccess(int statusCode, Header[] headers, JSONObject response) {
     }
 
     /**
-     * Fired when a request returns successfully and contains a json object
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json object at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param statusCode the status code of the response
      * @param response   the parsed json object found in the server response (if any)
@@ -105,9 +96,8 @@ public void onSuccess(int statusCode, JSONObject response) {
     }
 
     /**
-     * Fired when a request returns successfully and contains a json array
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json array at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param statusCode the status code of the response
      * @param headers    the headers of the HTTP response
@@ -118,9 +108,8 @@ public void onSuccess(int statusCode, Header[] headers, JSONArray response) {
     }
 
     /**
-     * Fired when a request returns successfully and contains a json array
-     * at the base of the response string. Override to handle in your
-     * own code.
+     * Fired when a request returns successfully and contains a json array at the base of the
+     * response string. Override to handle in your own code.
      *
      * @param statusCode the status code of the response
      * @param response   the parsed json array found in the server response (if any)

library/src/com/loopj/android/http/JsonHttpResponseHandler.java

@@ -15,8 +15,8 @@
 import javax.net.ssl.X509TrustManager;
 
 /**
- * This file is introduced to fix HTTPS Post bug on API < ICS
- * see http://code.google.com/p/android/issues/detail?id=13117#c14
+ * This file is introduced to fix HTTPS Post bug on API < ICS see
+ * http://code.google.com/p/android/issues/detail?id=13117#c14
  */
 public class MySSLSocketFactory extends SSLSocketFactory {
     SSLContext sslContext = SSLContext.getInstance("TLS");

library/src/com/loopj/android/http/MySSLSocketFactory.java

@@ -35,13 +35,10 @@
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * A persistent cookie store which implements the Apache HttpClient
- * {@link CookieStore} interface. Cookies are stored and will persist on the
- * user's device between application sessions since they are serialized and
- * stored in {@link SharedPreferences}.
- * <p>&nbsp;</p>
- * Instances of this class are designed to be used with
- * {@link AsyncHttpClient#setCookieStore}, but can also be used with a
+ * A persistent cookie store which implements the Apache HttpClient {@link CookieStore} interface.
+ * Cookies are stored and will persist on the user's device between application sessions since they
+ * are serialized and stored in {@link SharedPreferences}. <p>&nbsp;</p> Instances of this class are
+ * designed to be used with {@link AsyncHttpClient#setCookieStore}, but can also be used with a
  * regular old apache HttpClient/HttpContext if you prefer.
  */
 public class PersistentCookieStore implements CookieStore {

library/src/com/loopj/android/http/PersistentCookieStore.java

@@ -13,27 +13,27 @@ public RequestHandle(Future<?> request) {
     }
 
     /**
-     * Attempts to cancel this request. This attempt will fail if the request has
-     * already completed, has already been cancelled, or could not be cancelled
-     * for some other reason. If successful, and this request has not started
-     * when cancel is called, this request should never run. If the request has
-     * already started, then the mayInterruptIfRunning parameter determines
-     * whether the thread executing this request should be interrupted in an
-     * attempt to stop the request.
-     * <p/>
-     * After this method returns, subsequent calls to isDone() will always
-     * return true. Subsequent calls to isCancelled() will always return true
-     * if this method returned true.
+     * Attempts to cancel this request. This attempt will fail if the request has already completed,
+     * has already been cancelled, or could not be cancelled for some other reason. If successful,
+     * and this request has not started when cancel is called, this request should never run. If the
+     * request has already started, then the mayInterruptIfRunning parameter determines whether the
+     * thread executing this request should be interrupted in an attempt to stop the request.
+     * <p>&nbsp;</p> After this method returns, subsequent calls to isDone() will always return
+     * true. Subsequent calls to isCancelled() will always return true if this method returned
+     * true.
      *
-     * @param mayInterruptIfRunning true if the thread executing this request should be interrupted; otherwise, in-progress requests are allowed to complete
-     * @return false if the request could not be cancelled, typically because it has already completed normally; true otherwise
+     * @param mayInterruptIfRunning true if the thread executing this request should be interrupted;
+     *                              otherwise, in-progress requests are allowed to complete
+     * @return false if the request could not be cancelled, typically because it has already
+     * completed normally; true otherwise
      */
     public boolean cancel(boolean mayInterruptIfRunning) {
         return this.request != null && request.cancel(mayInterruptIfRunning);
     }
 
     /**
-     * Returns true if this task completed. Completion may be due to normal termination, an exception, or cancellation -- in all of these cases, this method will return true.
+     * Returns true if this task completed. Completion may be due to normal termination, an
+     * exception, or cancellation -- in all of these cases, this method will return true.
      *
      * @return true if this task completed
      */

library/src/com/loopj/android/http/RequestHandle.java

@@ -40,11 +40,8 @@
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * A collection of string request parameters or files to send along with
- * requests made from an {@link AsyncHttpClient} instance.
- * <p>&nbsp;</p>
- * For example:
- * <p>&nbsp;</p>
+ * A collection of string request parameters or files to send along with requests made from an
+ * {@link AsyncHttpClient} instance. <p>&nbsp;</p> For example: <p>&nbsp;</p>
  * <pre>
  * RequestParams params = new RequestParams();
  * params.put("username", "james");
@@ -54,34 +51,34 @@
  * params.put("profile_picture2", someInputStream); // Upload an InputStream
  * params.put("profile_picture3", new ByteArrayInputStream(someBytes)); // Upload some bytes
  *
- * Map<String, String> map = new HashMap<String, String>();
+ * Map&lt;String, String&gt; map = new HashMap&lt;String, String&gt;();
  * map.put("first_name", "James");
  * map.put("last_name", "Smith");
- * params.put("user", map); // url params: "user[first_name]=James&user[last_name]=Smith"
+ * params.put("user", map); // url params: "user[first_name]=James&amp;user[last_name]=Smith"
  *
- * Set<String> set = new HashSet<String>(); // unordered collection
+ * Set&lt;String&gt; set = new HashSet&lt;String&gt;(); // unordered collection
  * set.add("music");
  * set.add("art");
- * params.put("like", set); // url params: "like=music&like=art"
+ * params.put("like", set); // url params: "like=music&amp;like=art"
  *
- * List<String> list = new ArrayList<String>(); // Ordered collection
+ * List&lt;String&gt; list = new ArrayList&lt;String&gt;(); // Ordered collection
  * list.add("Java");
  * list.add("C");
- * params.put("languages", list); // url params: "languages[]=Java&languages[]=C"
+ * params.put("languages", list); // url params: "languages[]=Java&amp;languages[]=C"
  *
  * String[] colors = { "blue", "yellow" }; // Ordered collection
- * params.put("colors", colors); // url params: "colors[]=blue&colors[]=yellow"
+ * params.put("colors", colors); // url params: "colors[]=blue&amp;colors[]=yellow"
  *
- * List<Map<String, String>> listOfMaps = new ArrayList<Map<String, String>>();
- * Map<String, String> user1 = new HashMap<String, String>();
+ * List&lt;Map&lt;String, String&gt;&gt; listOfMaps = new ArrayList&lt;Map&lt;String, String&gt;&gt;();
+ * Map&lt;String, String&gt; user1 = new HashMap&lt;String, String&gt;();
  * user1.put("age", "30");
  * user1.put("gender", "male");
- * Map<String, String> user2 = new HashMap<String, String>();
+ * Map&lt;String, String&gt; user2 = new HashMap&lt;String, String&gt;();
  * user2.put("age", "25");
  * user2.put("gender", "female");
  * listOfMaps.add(user1);
  * listOfMaps.add(user2);
- * params.put("users", listOfMaps); // url params: "users[][age]=30&users[][gender]=male&users[][age]=25&users[][gender]=female"
+ * params.put("users", listOfMaps); // url params: "users[][age]=30&amp;users[][gender]=male&amp;users[][age]=25&amp;users[][gender]=female"
  *
  * AsyncHttpClient client = new AsyncHttpClient();
  * client.post("http://myendpoint.com", params, responseHandler);
@@ -96,15 +93,15 @@ public class RequestParams {
     protected ConcurrentHashMap<String, Object> urlParamsWithObjects;
 
     /**
-     * Constructs a new empty <code>RequestParams</code> instance.
+     * Constructs a new empty {@code RequestParams} instance.
      */
     public RequestParams() {
         this((Map<String, String>) null);
     }
 
     /**
-     * Constructs a new RequestParams instance containing the key/value
-     * string params from the specified map.
+     * Constructs a new RequestParams instance containing the key/value string params from the
+     * specified map.
      *
      * @param source the source key/value string map to add.
      */
@@ -118,8 +115,8 @@ public RequestParams(Map<String, String> source) {
     }
 
     /**
-     * Constructs a new RequestParams instance and populate it with a single
-     * initial key/value string param.
+     * Constructs a new RequestParams instance and populate it with a single initial key/value
+     * string param.
      *
      * @param key   the key name for the intial param.
      * @param value the value string for the initial param.
@@ -131,11 +128,11 @@ public RequestParams(final String key, final String value) {
     }
 
     /**
-     * Constructs a new RequestParams instance and populate it with multiple
-     * initial key/value string param.
+     * Constructs a new RequestParams instance and populate it with multiple initial key/value
+     * string param.
      *
-     * @param keysAndValues a sequence of keys and values. Objects are
-     *                      automatically converted to Strings (including the value {@code null}).
+     * @param keysAndValues a sequence of keys and values. Objects are automatically converted to
+     *                      Strings (including the value {@code null}).
      * @throws IllegalArgumentException if the number of arguments isn't even.
      */
     public RequestParams(Object... keysAndValues) {
@@ -319,7 +316,8 @@ public void setHttpEntityIsRepeatable(boolean isRepeatable) {
      * Returns an HttpEntity containing all request parameters
      *
      * @param progressHandler HttpResponseHandler for reporting progress on entity submit
-     * @return HttpEntity resulting HttpEntity to be included along with {@link org.apache.http.client.methods.HttpEntityEnclosingRequestBase}
+     * @return HttpEntity resulting HttpEntity to be included along with {@link
+     * org.apache.http.client.methods.HttpEntityEnclosingRequestBase}
      * @throws IOException if one of the streams cannot be read
      */
     public HttpEntity getEntity(ResponseHandlerInterface progressHandler) throws IOException {

library/src/com/loopj/android/http/RequestParams.java

@@ -15,6 +15,7 @@ public interface ResponseHandlerInterface {
      * Returns data whether request completed successfully
      *
      * @param response HttpResponse object with data
+     * @throws java.io.IOException if retrieving data from response fails
      */
     void sendResponseMessage(HttpResponse response) throws IOException;
 
@@ -76,11 +77,15 @@ public interface ResponseHandlerInterface {
 
     /**
      * Helper for handlers to receive Request URI info
+     *
+     * @param requestURI claimed request URI
      */
     public void setRequestURI(URI requestURI);
 
     /**
      * Helper for handlers to receive Request Header[] info
+     *
+     * @param requestHeaders Headers, claimed to be from original request
      */
     public void setRequestHeaders(Header[] requestHeaders);