Merge pull request #357 from johnjaylward/WriteJavadocUpdate

Update javadoc according to issue #356.
stleary · Jul 15, 2017 · d345bc5 · d345bc5
2 parents 5024f2d + 6f238a3
commit d345bc5
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 16 deletions.
diff --git a/JSONArray.java b/JSONArray.java
@@ -1230,7 +1230,7 @@ public Object optQuery(String jsonPointer) {
      * Queries and returns a value from this object using {@code jsonPointer}, or
      * returns null if the query fails due to a missing key.
      * 
-     * @param The JSON pointer
+     * @param jsonPointer The JSON pointer
      * @return the queried value or {@code null}
      * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
      */
@@ -1323,8 +1323,9 @@ public JSONObject toJSONObject(JSONArray names) throws JSONException {
      * whitespace is added. If it is not possible to produce a syntactically
      * correct JSON text then null will be returned instead. This could occur if
      * the array contains an invalid number.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      *
      * @return a printable, displayable, transmittable representation of the
      *         array.
@@ -1339,9 +1340,24 @@ public String toString() {
     }
 
     /**
-     * Make a pretty-printed JSON text of this JSONArray. Warning: This method
-     * assumes that the data structure is acyclical.
-     *
+     * Make a pretty-printed JSON text of this JSONArray.
+     * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * one element, then the array will be output on a single line:
+     * <pre>{@code [1]}</pre>
+     * 
+     * <p>If an array has 2 or more elements, then it will be output across
+     * multiple lines: <pre>{@code
+     * [
+     * 1,
+     * "value 2",
+     * 3
+     * ]
+     * }</pre>
+     * <p><b>
+     * Warning: This method assumes that the data structure is acyclical.
+     * </b>
+     * 
      * @param indentFactor
      *            The number of spaces to add to each level of indentation.
      * @return a printable, displayable, transmittable representation of the
@@ -1360,8 +1376,9 @@ public String toString(int indentFactor) throws JSONException {
     /**
      * Write the contents of the JSONArray as JSON text to a writer. For
      * compactness, no whitespace is added.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     *</b>
      *
      * @return The writer.
      * @throws JSONException
@@ -1371,10 +1388,23 @@ public Writer write(Writer writer) throws JSONException {
     }
 
     /**
-     * Write the contents of the JSONArray as JSON text to a writer. For
-     * compactness, no whitespace is added.
-     * <p>
+     * Write the contents of the JSONArray as JSON text to a writer.
+     * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * one element, then the array will be output on a single line:
+     * <pre>{@code [1]}</pre>
+     * 
+     * <p>If an array has 2 or more elements, then it will be output across
+     * multiple lines: <pre>{@code
+     * [
+     * 1,
+     * "value 2",
+     * 3
+     * ]
+     * }</pre>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      *
      * @param writer
      *            Writes the serialized JSON

diff --git a/JSONObject.java b/JSONObject.java
@@ -1676,7 +1676,7 @@ public Object optQuery(String jsonPointer) {
      * Queries and returns a value from this object using {@code jsonPointer}, or
      * returns null if the query fails due to a missing key.
      * 
-     * @param The JSON pointer
+     * @param jsonPointer The JSON pointer
      * @return the queried value or {@code null}
      * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
      */
@@ -2002,9 +2002,10 @@ public JSONArray toJSONArray(JSONArray names) throws JSONException {
      * Make a JSON text of this JSONObject. For compactness, no whitespace is
      * added. If this would not result in a syntactically correct JSON text,
      * then null will be returned instead.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
-     *
+     * </b>
+     * 
      * @return a printable, displayable, portable, transmittable representation
      *         of the object, beginning with <code>{</code>&nbsp;<small>(left
      *         brace)</small> and ending with <code>}</code>&nbsp;<small>(right
@@ -2021,8 +2022,20 @@ public String toString() {
 
     /**
      * Make a pretty-printed JSON text of this JSONObject.
-     * <p>
+     * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
+     * has only one key, then the object will be output on a single line:
+     * <pre>{@code {"key": 1}}</pre>
+     * 
+     * <p>If an object has 2 or more keys, then it will be output across
+     * multiple lines: <code><pre>{
+     *  "key1": 1,
+     *  "key2": "value 2",
+     *  "key3": 3
+     * }</pre></code>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      *
      * @param indentFactor
      *            The number of spaces to add to each level of indentation.
@@ -2172,9 +2185,10 @@ public static Object wrap(Object object) {
     /**
      * Write the contents of the JSONObject as JSON text to a writer. For
      * compactness, no whitespace is added.
-     * <p>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
-     *
+     * </b>
+     * 
      * @return The writer.
      * @throws JSONException
      */
@@ -2238,8 +2252,20 @@ static final void indent(Writer writer, int indent) throws IOException {
 
     /**
      * Write the contents of the JSONObject as JSON text to a writer.
-     * <p>
+     * 
+     * <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
+     * has only one key, then the object will be output on a single line:
+     * <pre>{@code {"key": 1}}</pre>
+     * 
+     * <p>If an object has 2 or more keys, then it will be output across
+     * multiple lines: <code><pre>{
+     *  "key1": 1,
+     *  "key2": "value 2",
+     *  "key3": 3
+     * }</pre></code>
+     * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
+     * </b>
      *
      * @param writer
      *            Writes the serialized JSON