Javadoc for JSONArray.

Change-Id: I3aced2607b48210f76887e0d42b591c098ce5db7

2 files changed, 290 insertions, 24 deletions

diff --git a/json/src/main/java/org/json/JSONArray.java b/json/src/main/java/org/json/JSONArray.java
index fa42054..b788a50 100644
--- a/json/src/main/java/org/json/JSONArray.java
+++ b/json/src/main/java/org/json/JSONArray.java
@@ -23,16 +23,46 @@ import java.util.Collection;
 // Note: this class was written without inspecting the non-free org.json sourcecode.
 
 /**
- * An indexed sequence of JSON-safe values.
+ * A dense indexed sequence of values. Values may be any mix of
+ * {@link JSONObject JSONObjects}, other {@link JSONArray JSONArrays}, Strings,
+ * Booleans, Integers, Longs, Doubles, {@code null} or {@link JSONObject#NULL}.
+ * Values may not be {@link Double#isNaN() NaNs}, {@link Double#isInfinite()
+ * infinities}, or of any type not listed here.
+ *
+ * <p>{@code JSONArray} has the same type coercion behavior and
+ * optional/mandatory accessors as {@link JSONObject}. See that class'
+ * documentation for details.
+ *
+ * <p><strong>Warning:</strong> this class represents null in two incompatible
+ * ways: the standard Java {@code null} reference, and the sentinel value {@link
+ * JSONObject#NULL}. In particular, {@code get()} fails if the requested index
+ * holds the null reference, but succeeds if it holds {@code JSONObject.NULL}.
+ *
+ * <p>Instances of this class are not thread safe. Although this class is
+ * nonfinal, it was not designed for inheritance and should not be subclassed.
+ * In particular, self-use by overridable methods is not specified. See
+ * <i>Effective Java</i> Item 17, "Design and Document or inheritance or else
+ * prohibit it" for further information.
  */
 public class JSONArray {
 
     private final List<Object> values;
 
+    /**
+     * Creates a {@code JSONArray} with no values.
+     */
     public JSONArray() {
         values = new ArrayList<Object>();
     }
 
+    /**
+     * Creates a new {@code JSONArray} by copying all values from the given
+     * collection.
+     *
+     * @param copyFrom a collection whose values are of supported types.
+     *     Unsupported values are not permitted and will yield an array in an
+     *     inconsistent state.
+     */
     /* Accept a raw type for API compatibility */
     public JSONArray(Collection copyFrom) {
         this();
@@ -40,6 +70,15 @@ public class JSONArray {
         values.addAll(copyFromTyped);
     }
 
+    /**
+     * Creates a new {@code JSONArray} with values from the next array in the
+     * tokener.
+     *
+     * @param readFrom a tokener whose nextValue() method will yield a
+     *     {@code JSONArray}.
+     * @throws JSONException if the parse fails or doesn't yield a
+     *     {@code JSONArray}.
+     */
     public JSONArray(JSONTokener readFrom) throws JSONException {
         /*
          * Getting the parser to populate this could get tricky. Instead, just
@@ -53,55 +92,138 @@ public class JSONArray {
         }
     }
 
+    /**
+     * Creates a new {@code JSONArray} with values from the JSON string.
+     *
+     * @param json a JSON-encoded string containing an array.
+     * @throws JSONException if the parse fails or doesn't yield a {@code
+     *     JSONArray}.
+     */
     public JSONArray(String json) throws JSONException {
         this(new JSONTokener(json));
     }
 
+    /**
+     * Returns the number of values in this array.
+     */
     public int length() {
         return values.size();
     }
 
+    /**
+     * Appends {@code value} to the end of this array.
+     *
+     * @return this array.
+     */
     public JSONArray put(boolean value) {
         values.add(value);
         return this;
     }
 
+    /**
+     * Appends {@code value} to the end of this array.
+     *
+     * @param value a finite value. May not be {@link Double#isNaN() NaNs} or
+     *     {@link Double#isInfinite() infinities}.
+     * @return this array.
+     */
     public JSONArray put(double value) throws JSONException {
         values.add(JSON.checkDouble(value));
         return this;
     }
 
+    /**
+     * Appends {@code value} to the end of this array.
+     *
+     * @return this array.
+     */
     public JSONArray put(int value) {
         values.add(value);
         return this;
     }
 
+    /**
+     * Appends {@code value} to the end of this array.
+     *
+     * @return this array.
+     */
     public JSONArray put(long value) {
         values.add(value);
         return this;
     }
 
+    /**
+     * Appends {@code value} to the end of this array.
+     *
+     * @param value a {@link JSONObject}, {@link JSONArray}, String, Boolean,
+     *     Integer, Long, Double, {@link JSONObject#NULL}, or {@code null}. May
+     *     not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite()
+     *     infinities}. Unsupported values are not permitted and will cause the
+     *     array to be in an inconsistent state.
+     * @return this array.
+     */
     public JSONArray put(Object value) {
         values.add(value);
         return this;
     }
 
+    /**
+     * Sets the value at {@code index} to {@code value}, null padding this array
+     * to the required length if necessary. If a value already exists at {@code
+     * index}, it will be replaced.
+     *
+     * @return this array.
+     */
     public JSONArray put(int index, boolean value) throws JSONException {
         return put(index, (Boolean) value);
     }
 
+    /**
+     * Sets the value at {@code index} to {@code value}, null padding this array
+     * to the required length if necessary. If a value already exists at {@code
+     * index}, it will be replaced.
+     *
+     * @param value a finite value. May not be {@link Double#isNaN() NaNs} or
+     *     {@link Double#isInfinite() infinities}.
+     * @return this array.
+     */
     public JSONArray put(int index, double value) throws JSONException {
         return put(index, (Double) value);
     }
 
+    /**
+     * Sets the value at {@code index} to {@code value}, null padding this array
+     * to the required length if necessary. If a value already exists at {@code
+     * index}, it will be replaced.
+     *
+     * @return this array.
+     */
     public JSONArray put(int index, int value) throws JSONException {
         return put(index, (Integer) value);
     }
 
+    /**
+     * Sets the value at {@code index} to {@code value}, null padding this array
+     * to the required length if necessary. If a value already exists at {@code
+     * index}, it will be replaced.
+     *
+     * @return this array.
+     */
     public JSONArray put(int index, long value) throws JSONException {
         return put(index, (Long) value);
     }
 
+    /**
+     * Sets the value at {@code index} to {@code value}, null padding this array
+     * to the required length if necessary. If a value already exists at {@code
+     * index}, it will be replaced.
+     *
+     * @param value a {@link JSONObject}, {@link JSONArray}, String, Boolean,
+     *     Integer, Long, Double, {@link JSONObject#NULL}, or {@code null}. May
+     *     not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite()
+     *     infinities}.
+     * @return this array.
+     */
     public JSONArray put(int index, Object value) throws JSONException {
         if (value instanceof Number) {
             // deviate from the original by checking all Numbers, not just floats & doubles
@@ -114,11 +236,22 @@ public class JSONArray {
         return this;
     }
 
+    /**
+     * Returns true if this array has no value at {@code index}, or if its value
+     * is the {@code null} reference or {@link JSONObject#NULL}.
+     */
     public boolean isNull(int index) {
         Object value = opt(index);
         return value == null || value == JSONObject.NULL;
     }
 
+    /**
+     * Returns the value at {@code index}.
+     *
+     * @throws JSONException if this array has no value at {@code index}, or if
+     *     that value is the {@code null} reference. This method returns
+     *     normally if the value is {@code JSONObject#NULL}.
+     */
     public Object get(int index) throws JSONException {
         try {
             Object value = values.get(index);
@@ -131,6 +264,10 @@ public class JSONArray {
         }
     }
 
+    /**
+     * Returns the value at {@code index}, or null if the array has no value
+     * at {@code index}.
+     */
     public Object opt(int index) {
         if (index < 0 || index >= values.size()) {
             return null;
@@ -138,6 +275,13 @@ public class JSONArray {
         return values.get(index);
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a boolean or can
+     * be coerced to a boolean.
+     *
+     * @throws JSONException if the value at {@code index} doesn't exist or
+     *     cannot be coerced to a boolean.
+     */
     public boolean getBoolean(int index) throws JSONException {
         Object object = get(index);
         Boolean result = JSON.toBoolean(object);
@@ -147,16 +291,31 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a boolean or can
+     * be coerced to a boolean. Returns false otherwise.
+     */
     public boolean optBoolean(int index) {
         return optBoolean(index, false);
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a boolean or can
+     * be coerced to a boolean. Returns {@code fallback} otherwise.
+     */
     public boolean optBoolean(int index, boolean fallback) {
         Object object = opt(index);
         Boolean result = JSON.toBoolean(object);
         return result != null ? result : fallback;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a double or can
+     * be coerced to a double.
+     *
+     * @throws JSONException if the value at {@code index} doesn't exist or
+     *     cannot be coerced to a double.
+     */
     public double getDouble(int index) throws JSONException {
         Object object = get(index);
         Double result = JSON.toDouble(object);
@@ -166,16 +325,31 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a double or can
+     * be coerced to a double. Returns {@code NaN} otherwise.
+     */
     public double optDouble(int index) {
         return optDouble(index, Double.NaN);
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a double or can
+     * be coerced to a double. Returns {@code fallback} otherwise.
+     */
     public double optDouble(int index, double fallback) {
         Object object = opt(index);
         Double result = JSON.toDouble(object);
         return result != null ? result : fallback;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is an int or
+     * can be coerced to an int.
+     *
+     * @throws JSONException if the value at {@code index} doesn't exist or
+     *     cannot be coerced to a int.
+     */
     public int getInt(int index) throws JSONException {
         Object object = get(index);
         Integer result = JSON.toInteger(object);
@@ -185,16 +359,31 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is an int or
+     * can be coerced to an int. Returns 0 otherwise.
+     */
     public int optInt(int index) {
         return optInt(index, 0);
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is an int or
+     * can be coerced to an int. Returns {@code fallback} otherwise.
+     */
     public int optInt(int index, int fallback) {
         Object object = opt(index);
         Integer result = JSON.toInteger(object);
         return result != null ? result : fallback;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a long or
+     * can be coerced to a long.
+     *
+     * @throws JSONException if the value at {@code index} doesn't exist or
+     *     cannot be coerced to a long.
+     */
     public long getLong(int index) throws JSONException {
         Object object = get(index);
         Long result = JSON.toLong(object);
@@ -204,16 +393,30 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a long or
+     * can be coerced to a long. Returns 0 otherwise.
+     */
     public long optLong(int index) {
         return optLong(index, 0L);
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a long or
+     * can be coerced to a long. Returns {@code fallback} otherwise.
+     */
     public long optLong(int index, long fallback) {
         Object object = opt(index);
         Long result = JSON.toLong(object);
         return result != null ? result : fallback;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists, coercing it if
+     * necessary.
+     *
+     * @throws JSONException if no such value exists.
+     */
     public String getString(int index) throws JSONException {
         Object object = get(index);
         String result = JSON.toString(object);
@@ -223,16 +426,31 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists, coercing it if
+     * necessary. Returns the empty string if no such value exists.
+     */
     public String optString(int index) {
         return optString(index, "");
     }
 
+    /**
+     * Returns the value at {@code index} if it exists, coercing it if
+     * necessary. Returns {@code fallback} if no such value exists.
+     */
     public String optString(int index, String fallback) {
         Object object = opt(index);
         String result = JSON.toString(object);
         return result != null ? result : fallback;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a {@code
+     * JSONArray}.
+     *
+     * @throws JSONException if the value doesn't exist or is not a {@code
+     *     JSONArray}.
+     */
     public JSONArray getJSONArray(int index) throws JSONException {
         Object object = get(index);
         if (object instanceof JSONArray) {
@@ -242,11 +460,22 @@ public class JSONArray {
         }
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a {@code
+     * JSONArray}. Returns null otherwise.
+     */
     public JSONArray optJSONArray(int index) {
         Object object = opt(index);
         return object instanceof JSONArray ? (JSONArray) object : null;
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a {@code
+     * JSONObject}.
+     *
+     * @throws JSONException if the value doesn't exist or is not a {@code
+     *     JSONObject}.
+     */
     public JSONObject getJSONObject(int index) throws JSONException {
         Object object = get(index);
         if (object instanceof JSONObject) {
@@ -256,11 +485,22 @@ public class JSONArray {
         }
     }
 
+    /**
+     * Returns the value at {@code index} if it exists and is a {@code
+     * JSONObject}. Returns null otherwise.
+     */
     public JSONObject optJSONObject(int index) {
         Object object = opt(index);
         return object instanceof JSONObject ? (JSONObject) object : null;
     }
 
+    /**
+     * Returns a new object whose values are the values in this array, and whose
+     * names are the values in {@code names}. Names and values are paired up by
+     * index from 0 through to the shorter array's length. Names that are not
+     * strings will be coerced to strings. This method returns null if either
+     * array is empty.
+     */
     public JSONObject toJSONObject(JSONArray names) throws JSONException {
         JSONObject result = new JSONObject();
         int length = Math.min(names.length(), values.size());
@@ -274,6 +514,13 @@ public class JSONArray {
         return result;
     }
 
+    /**
+     * Returns a new string by alternating this array's values with {@code
+     * separator}. This array's string values are quoted and have their special
+     * characters escaped. For example, the array containing the strings '12"
+     * pizza', 'taco' and 'soda' joined on '+' returns this:
+     * <pre>"12\" pizza"+"taco"+"soda"</pre>
+     */
     public String join(String separator) throws JSONException {
         JSONStringer stringer = new JSONStringer();
         stringer.open(JSONStringer.Scope.NULL, "");
@@ -287,6 +534,10 @@ public class JSONArray {
         return stringer.out.toString();
     }
 
+    /**
+     * Encodes this array as a compact JSON string, such as:
+     * <pre>[94043,90210]</pre>
+     */
     @Override public String toString() {
         try {
             JSONStringer stringer = new JSONStringer();
@@ -297,6 +548,18 @@ public class JSONArray {
         }
     }
 
+    /**
+     * Encodes this array as a human readable JSON string for debugging, such
+     * as:
+     * <pre>
+     * [
+     *     94043,
+     *     90210
+     * ]</pre>
+     *
+     * @param indentSpaces the number of spaces to indent for each level of
+     *     nesting.
+     */
     public String toString(int indentSpaces) throws JSONException {
         JSONStringer stringer = new JSONStringer(indentSpaces);
         writeTo(stringer);
diff --git a/json/src/main/java/org/json/JSONObject.java b/json/src/main/java/org/json/JSONObject.java
index fcc5d6a..7ac05b1 100644
--- a/json/src/main/java/org/json/JSONObject.java
+++ b/json/src/main/java/org/json/JSONObject.java
@@ -25,10 +25,10 @@ import java.util.Map;
 
 /**
  * A modifiable set of name/value mappings. Names are unique, non-null strings.
- * Values may be other {@link JSONObject JSONObjects}, {@link JSONArray
+ * Values may be any mix of {@link JSONObject JSONObjects}, {@link JSONArray
  * JSONArrays}, Strings, Booleans, Integers, Longs, Doubles or {@link #NULL}.
- * Values may not be {@code null}, {@link Double#isNaN() NaNs} or {@link
- * Double#isInfinite() infinities}.
+ * Values may not be {@code null}, {@link Double#isNaN() NaNs}, {@link
+ * Double#isInfinite() infinities}, or of any type not listed here.
  *
  * <p>This class can coerce values to another type when requested.
  * <ul>
@@ -62,11 +62,10 @@ import java.util.Map;
  * </ul>
  *
  * <p><strong>Warning:</strong> this class represents null in two incompatible
- * ways: the standard Java {@code null} literal, and the sentinel value {@link
- * JSONObject#NULL JSONObject.NULL}. In particular, calling {@code
- * put(name, null)} removes the named entry from the object but {@code
- * put(name, JSONObject.NULL)} stores an entry whose value is {@code
- * JSONObject.NULL}.
+ * ways: the standard Java {@code null} reference, and the sentinel value {@link
+ * JSONObject#NULL}. In particular, calling {@code put(name, null)} removes the
+ * named entry from the object but {@code put(name, JSONObject.NULL)} stores an
+ * entry whose value is {@code JSONObject.NULL}.
  *
  * <p>Instances of this class are not thread safe. Although this class is
  * nonfinal, it was not designed for inheritance and should not be subclassed.
@@ -105,18 +104,18 @@ public class JSONObject {
     private final Map<String, Object> nameValuePairs;
 
     /**
-     * Creates a JSONObject with no name/value mappings.
+     * Creates a {@code JSONObject} with no name/value mappings.
      */
     public JSONObject() {
         nameValuePairs = new HashMap<String, Object>();
     }
 
     /**
-     * Creates a new JSONObject by copying all name/value mappings from the
-     * given map.
+     * Creates a new {@code JSONObject} by copying all name/value mappings from
+     * the given map.
      *
      * @param copyFrom a map whose keys are of type {@link String} and whose
-     *     values are of supported types. Values do not need to be homogeneous.
+     *     values are of supported types.
      * @throws NullPointerException if any of the map's keys are null.
      */
     /* (accept a raw type for API compatibility) */
@@ -137,11 +136,13 @@ public class JSONObject {
     }
 
     /**
-     * Creates a new JSONObject with name/value mappings from the next value in
-     * the tokenizer.
+     * Creates a new {@code JSONObject} with name/value mappings from the next
+     * object in the tokener.
      *
-     * @param readFrom a tokenizer whose nextValue() method will yield a JSONObject.
-     * @throws JSONException if the parse fails or doesn't yield a JSONObject.
+     * @param readFrom a tokener whose nextValue() method will yield a
+     *     {@code JSONObject}.
+     * @throws JSONException if the parse fails or doesn't yield a
+     *     {@code JSONObject}.
      */
     public JSONObject(JSONTokener readFrom) throws JSONException {
         /*
@@ -157,19 +158,21 @@ public class JSONObject {
     }
 
     /**
-     * Creates a new JSONObject with name/value mappings from the JSON string.
+     * Creates a new {@code JSONObject} with name/value mappings from the JSON
+     * string.
      *
      * @param json a JSON-encoded string containing an object.
-     * @throws JSONException if the parse fails or doesn't yield a JSONObject.
+     * @throws JSONException if the parse fails or doesn't yield a {@code
+     *     JSONObject}.
      */
     public JSONObject(String json) throws JSONException {
         this(new JSONTokener(json));
     }
 
     /**
-     * Creates a new JSONObject by copying mappings for the listed names from
-     * the given object. Names that aren't present in {@code copyFrom} will be
-     * skipped.
+     * Creates a new {@code JSONObject} by copying mappings for the listed names
+     * from the given object. Names that aren't present in {@code copyFrom} will
+     * be skipped.
      */
     public JSONObject(JSONObject copyFrom, String[] names) throws JSONException {
         this();
@@ -622,7 +625,7 @@ public class JSONObject {
     }
 
     /**
-     * Encodes this object as a compact JSON string, such as
+     * Encodes this object as a compact JSON string, such as:
      * <pre>{"query":"Pizza","locations":[94043,90210]}</pre>
      */
     @Override public String toString() {
@@ -637,7 +640,7 @@ public class JSONObject {
 
     /**
      * Encodes this object as a human readable JSON string for debugging, such
-     * as
+     * as:
      * <pre>
      * {
      *     "query": "Pizza",