Skip to content

Commit 6f238a3

Browse files
johnjaylwardjohnjaylward
committed
Update javadoc according to issue stleary#356.
1 parent 5024f2d commit 6f238a3

2 files changed

Lines changed: 72 additions & 16 deletions

File tree

‎JSONArray.java‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1230,7 +1230,7 @@ public Object optQuery(String jsonPointer) {
12301230
* Queries and returns a value from this object using {@code jsonPointer}, or
12311231
* returns null if the query fails due to a missing key.
12321232
*
1233-
* @param The JSON pointer
1233+
* @param jsonPointer The JSON pointer
12341234
* @return the queried value or {@code null}
12351235
* @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
12361236
*/
@@ -1323,8 +1323,9 @@ public JSONObject toJSONObject(JSONArray names) throws JSONException {
13231323
* whitespace is added. If it is not possible to produce a syntactically
13241324
* correct JSON text then null will be returned instead. This could occur if
13251325
* the array contains an invalid number.
1326-
* <p>
1326+
* <p><b>
13271327
* Warning: This method assumes that the data structure is acyclical.
1328+
* </b>
13281329
*
13291330
* @return a printable, displayable, transmittable representation of the
13301331
* array.
@@ -1339,9 +1340,24 @@ public String toString() {
13391340
}
13401341

13411342
/**
1342-
* Make a pretty-printed JSON text of this JSONArray. Warning: This method
1343-
* assumes that the data structure is acyclical.
1344-
*
1343+
* Make a pretty-printed JSON text of this JSONArray.
1344+
*
1345+
* <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
1346+
* one element, then the array will be output on a single line:
1347+
* <pre>{@code [1]}</pre>
1348+
*
1349+
* <p>If an array has 2 or more elements, then it will be output across
1350+
* multiple lines: <pre>{@code
1351+
* [
1352+
* 1,
1353+
* "value 2",
1354+
* 3
1355+
* ]
1356+
* }</pre>
1357+
* <p><b>
1358+
* Warning: This method assumes that the data structure is acyclical.
1359+
* </b>
1360+
*
13451361
* @param indentFactor
13461362
* The number of spaces to add to each level of indentation.
13471363
* @return a printable, displayable, transmittable representation of the
@@ -1360,8 +1376,9 @@ public String toString(int indentFactor) throws JSONException {
13601376
/**
13611377
* Write the contents of the JSONArray as JSON text to a writer. For
13621378
* compactness, no whitespace is added.
1363-
* <p>
1379+
* <p><b>
13641380
* Warning: This method assumes that the data structure is acyclical.
1381+
*</b>
13651382
*
13661383
* @return The writer.
13671384
* @throws JSONException
@@ -1371,10 +1388,23 @@ public Writer write(Writer writer) throws JSONException {
13711388
}
13721389

13731390
/**
1374-
* Write the contents of the JSONArray as JSON text to a writer. For
1375-
* compactness, no whitespace is added.
1376-
* <p>
1391+
* Write the contents of the JSONArray as JSON text to a writer.
1392+
*
1393+
* <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
1394+
* one element, then the array will be output on a single line:
1395+
* <pre>{@code [1]}</pre>
1396+
*
1397+
* <p>If an array has 2 or more elements, then it will be output across
1398+
* multiple lines: <pre>{@code
1399+
* [
1400+
* 1,
1401+
* "value 2",
1402+
* 3
1403+
* ]
1404+
* }</pre>
1405+
* <p><b>
13771406
* Warning: This method assumes that the data structure is acyclical.
1407+
* </b>
13781408
*
13791409
* @param writer
13801410
* Writes the serialized JSON

‎JSONObject.java‎

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1676,7 +1676,7 @@ public Object optQuery(String jsonPointer) {
16761676
* Queries and returns a value from this object using {@code jsonPointer}, or
16771677
* returns null if the query fails due to a missing key.
16781678
*
1679-
* @param The JSON pointer
1679+
* @param jsonPointer The JSON pointer
16801680
* @return the queried value or {@code null}
16811681
* @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
16821682
*/
@@ -2002,9 +2002,10 @@ public JSONArray toJSONArray(JSONArray names) throws JSONException {
20022002
* Make a JSON text of this JSONObject. For compactness, no whitespace is
20032003
* added. If this would not result in a syntactically correct JSON text,
20042004
* then null will be returned instead.
2005-
* <p>
2005+
* <p><b>
20062006
* Warning: This method assumes that the data structure is acyclical.
2007-
*
2007+
* </b>
2008+
*
20082009
* @return a printable, displayable, portable, transmittable representation
20092010
* of the object, beginning with <code>{</code>&nbsp;<small>(left
20102011
* brace)</small> and ending with <code>}</code>&nbsp;<small>(right
@@ -2021,8 +2022,20 @@ public String toString() {
20212022

20222023
/**
20232024
* Make a pretty-printed JSON text of this JSONObject.
2024-
* <p>
2025+
*
2026+
* <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
2027+
* has only one key, then the object will be output on a single line:
2028+
* <pre>{@code {"key": 1}}</pre>
2029+
*
2030+
* <p>If an object has 2 or more keys, then it will be output across
2031+
* multiple lines: <code><pre>{
2032+
* "key1": 1,
2033+
* "key2": "value 2",
2034+
* "key3": 3
2035+
* }</pre></code>
2036+
* <p><b>
20252037
* Warning: This method assumes that the data structure is acyclical.
2038+
* </b>
20262039
*
20272040
* @param indentFactor
20282041
* The number of spaces to add to each level of indentation.
@@ -2172,9 +2185,10 @@ public static Object wrap(Object object) {
21722185
/**
21732186
* Write the contents of the JSONObject as JSON text to a writer. For
21742187
* compactness, no whitespace is added.
2175-
* <p>
2188+
* <p><b>
21762189
* Warning: This method assumes that the data structure is acyclical.
2177-
*
2190+
* </b>
2191+
*
21782192
* @return The writer.
21792193
* @throws JSONException
21802194
*/
@@ -2238,8 +2252,20 @@ static final void indent(Writer writer, int indent) throws IOException {
22382252

22392253
/**
22402254
* Write the contents of the JSONObject as JSON text to a writer.
2241-
* <p>
2255+
*
2256+
* <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
2257+
* has only one key, then the object will be output on a single line:
2258+
* <pre>{@code {"key": 1}}</pre>
2259+
*
2260+
* <p>If an object has 2 or more keys, then it will be output across
2261+
* multiple lines: <code><pre>{
2262+
* "key1": 1,
2263+
* "key2": "value 2",
2264+
* "key3": 3
2265+
* }</pre></code>
2266+
* <p><b>
22422267
* Warning: This method assumes that the data structure is acyclical.
2268+
* </b>
22432269
*
22442270
* @param writer
22452271
* Writes the serialized JSON

0 commit comments

Comments
 (0)