Guarantee that JsonElement.toString() produces JSON (google#2659)

* Extend `JsonElement` documentation

* Add space to JsonParser code example

* Guarantee that `JsonElement.toString()` produces JSON

* Refer to `JsonElement` documentation from subclasses

gson/src/main/java/com/google/gson/JsonArray.java

@@ -33,6 +33,9 @@
  * <p>{@code JsonArray} only implements the {@link Iterable} interface but not the {@link List}
  * interface. A {@code List} view of it can be obtained with {@link #asList()}.
  *
+ * <p>See the {@link JsonElement} documentation for details on how to convert {@code JsonArray} and
+ * generally any {@code JsonElement} from and to JSON.
+ *
  * @author Inderjeet Singh
  * @author Joel Leitch
  */

gson/src/main/java/com/google/gson/JsonElement.java

@@ -20,6 +20,7 @@
 import com.google.gson.internal.Streams;
 import com.google.gson.stream.JsonWriter;
 import java.io.IOException;
+import java.io.Reader;
 import java.io.StringWriter;
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -28,6 +29,69 @@
  * A class representing an element of JSON. It could either be a {@link JsonObject}, a {@link
  * JsonArray}, a {@link JsonPrimitive} or a {@link JsonNull}.
  *
+ * <p>This class provides multiple {@code getAs} methods which allow
+ *
+ * <ul>
+ *   <li>obtaining the represented primitive value, for example {@link #getAsString()}
+ *   <li>casting to the {@code JsonElement} subclasses in a convenient way, for example {@link
+ *       #getAsJsonObject()}
+ * </ul>
+ *
+ * <h2>Converting {@code JsonElement} from / to JSON</h2>
+ *
+ * There are two ways to parse JSON data as a {@link JsonElement}:
+ *
+ * <ul>
+ *   <li>{@link JsonParser}, for example:
+ *       <pre>
+ * JsonObject jsonObject = JsonParser.parseString("{}").getAsJsonObject();
+ * </pre>
+ *   <li>{@link Gson#fromJson(Reader, Class) Gson.fromJson(..., JsonElement.class)}<br>
+ *       It is possible to directly specify a {@code JsonElement} subclass, for example:
+ *       <pre>
+ * JsonObject jsonObject = gson.fromJson("{}", JsonObject.class);
+ * </pre>
+ * </ul>
+ *
+ * To convert a {@code JsonElement} to JSON either {@link #toString() JsonElement.toString()} or the
+ * method {@link Gson#toJson(JsonElement)} and its overloads can be used.
+ *
+ * <p>It is also possible to obtain the {@link TypeAdapter} for {@code JsonElement} from a {@link
+ * Gson} instance and then use it for conversion from and to JSON:
+ *
+ * <pre>{@code
+ * TypeAdapter<JsonElement> adapter = gson.getAdapter(JsonElement.class);
+ *
+ * JsonElement value = adapter.fromJson("{}");
+ * String json = adapter.toJson(value);
+ * }</pre>
+ *
+ * <h2>{@code JsonElement} as JSON data</h2>
+ *
+ * {@code JsonElement} can also be treated as JSON data, allowing to deserialize from a {@code
+ * JsonElement} and serializing to a {@code JsonElement}. The {@link Gson} class offers these
+ * methods for this:
+ *
+ * <ul>
+ *   <li>{@link Gson#fromJson(JsonElement, Class) Gson.fromJson(JsonElement, ...)}, for example:
+ *       <pre>
+ * JsonObject jsonObject = ...;
+ * MyClass myObj = gson.fromJson(jsonObject, MyClass.class);
+ * </pre>
+ *   <li>{@link Gson#toJsonTree(Object)}, for example:
+ *       <pre>
+ * MyClass myObj = ...;
+ * JsonElement json = gson.toJsonTree(myObj);
+ * </pre>
+ * </ul>
+ *
+ * The {@link TypeAdapter} class provides corresponding methods as well:
+ *
+ * <ul>
+ *   <li>{@link TypeAdapter#fromJsonTree(JsonElement)}
+ *   <li>{@link TypeAdapter#toJsonTree(Object)}
+ * </ul>
+ *
  * @author Inderjeet Singh
  * @author Joel Leitch
  */
@@ -320,7 +384,41 @@ public short getAsShort() {
     throw new UnsupportedOperationException(getClass().getSimpleName());
   }
 
-  /** Returns a String representation of this element. */
+  /**
+   * Converts this element to a JSON string.
+   *
+   * <p>For example:
+   *
+   * <pre>
+   * JsonObject object = new JsonObject();
+   * object.add("a", JsonNull.INSTANCE);
+   * JsonArray array = new JsonArray();
+   * array.add(1);
+   * object.add("b", array);
+   *
+   * String json = object.toString();
+   * // json: {"a":null,"b":[1]}
+   * </pre>
+   *
+   * If this element or any nested elements contain {@link Double#NaN NaN} or {@link
+   * Double#isInfinite() Infinity} that value is written to JSON, even though the JSON specification
+   * does not permit these values.
+   *
+   * <p>To customize formatting or to directly write to an {@link Appendable} instead of creating an
+   * intermediate {@code String} first, use {@link Gson#toJson(JsonElement, Appendable)
+   * Gson.toJson(JsonElement, ...)}.
+   *
+   * <p>To get the contained String value (without enclosing {@code "} and without escaping), use
+   * {@link #getAsString()} instead:
+   *
+   * <pre>
+   * JsonPrimitive jsonPrimitive = new JsonPrimitive("with \" quote");
+   * String json = jsonPrimitive.toString();
+   * // json: "with \" quote"
+   * String value = jsonPrimitive.getAsString();
+   * // value: with " quote
+   * </pre>
+   */
   @Override
   public String toString() {
     try {

gson/src/main/java/com/google/gson/JsonObject.java

@@ -22,7 +22,7 @@
 import java.util.Set;
 
 /**
- * A class representing an object type in Json. An object consists of name-value pairs where names
+ * A class representing an object type in JSON. An object consists of name-value pairs where names
  * are strings, and values are any other type of {@link JsonElement}. This allows for a creating a
  * tree of JsonElements. The member elements of this object are maintained in order they were added.
  * This class does not support {@code null} values. If {@code null} is provided as value argument to
@@ -31,6 +31,9 @@
  * <p>{@code JsonObject} does not implement the {@link Map} interface, but a {@code Map} view of it
  * can be obtained with {@link #asMap()}.
  *
+ * <p>See the {@link JsonElement} documentation for details on how to convert {@code JsonObject} and
+ * generally any {@code JsonElement} from and to JSON.
+ *
  * @author Inderjeet Singh
  * @author Joel Leitch
  */

gson/src/main/java/com/google/gson/JsonParser.java

@@ -53,7 +53,7 @@
  * following example demonstrates how to achieve it:
  *
  * <pre>
- * String json = "{\"skipObj\": {\"skipKey\": \"skipValue\"},\"obj\": {\"key\": \"value\"}}";
+ * String json = "{\"skipObj\": {\"skipKey\": \"skipValue\"}, \"obj\": {\"key\": \"value\"}}";
  * try (JsonReader jsonReader = new JsonReader(new StringReader(json))) {
  *   jsonReader.beginObject();
  *   while (jsonReader.hasNext()) {

gson/src/main/java/com/google/gson/JsonPrimitive.java

@@ -26,6 +26,9 @@
  * A class representing a JSON primitive value. A primitive value is either a String, a Java
  * primitive, or a Java primitive wrapper type.
  *
+ * <p>See the {@link JsonElement} documentation for details on how to convert {@code JsonPrimitive}
+ * and generally any {@code JsonElement} from and to JSON.
+ *
  * @author Inderjeet Singh
  * @author Joel Leitch
  */

gson/src/test/java/com/google/gson/JsonArrayTest.java

@@ -379,4 +379,21 @@ public void testSameAddition() {
     assertThat(jsonArray.toString())
         .isEqualTo("[\"a\",\"a\",true,true,1212,1212,34.34,34.34,null,null]");
   }
+
+  @Test
+  public void testToString() {
+    JsonArray array = new JsonArray();
+    assertThat(array.toString()).isEqualTo("[]");
+
+    array.add(JsonNull.INSTANCE);
+    array.add(Float.NaN);
+    array.add("a\0");
+    JsonArray nestedArray = new JsonArray();
+    nestedArray.add('"');
+    array.add(nestedArray);
+    JsonObject nestedObject = new JsonObject();
+    nestedObject.addProperty("n\0", 1);
+    array.add(nestedObject);
+    assertThat(array.toString()).isEqualTo("[null,NaN,\"a\\u0000\",[\"\\\"\"],{\"n\\u0000\":1}]");
+  }
 }

gson/src/test/java/com/google/gson/JsonNullTest.java

@@ -43,4 +43,9 @@ public void testDeepCopy() {
     assertThat(a.deepCopy()).isSameInstanceAs(JsonNull.INSTANCE);
     assertThat(JsonNull.INSTANCE.deepCopy()).isSameInstanceAs(JsonNull.INSTANCE);
   }
+
+  @Test
+  public void testToString() {
+    assertThat(JsonNull.INSTANCE.toString()).isEqualTo("null");
+  }
 }

gson/src/test/java/com/google/gson/JsonObjectTest.java

@@ -344,4 +344,21 @@ public void testEntrySet() {
       assertThat(new ArrayList<>(o.entrySet())).isEqualTo(new ArrayList<>(expectedEntriesQueue));
     }
   }
+
+  @Test
+  public void testToString() {
+    JsonObject object = new JsonObject();
+    assertThat(object.toString()).isEqualTo("{}");
+
+    object.add("a", JsonNull.INSTANCE);
+    object.addProperty("b\0", Float.NaN);
+    JsonArray nestedArray = new JsonArray();
+    nestedArray.add('"');
+    object.add("c", nestedArray);
+    JsonObject nestedObject = new JsonObject();
+    nestedObject.addProperty("n\0", 1);
+    object.add("d", nestedObject);
+    assertThat(object.toString())
+        .isEqualTo("{\"a\":null,\"b\\u0000\":NaN,\"c\":[\"\\\"\"],\"d\":{\"n\\u0000\":1}}");
+  }
 }

gson/src/test/java/com/google/gson/JsonPrimitiveTest.java

@@ -260,12 +260,34 @@ public void testDoubleEqualsBigDecimal() {
   }
 
   @Test
-  public void testValidJsonOnToString() {
+  public void testToString() {
     JsonPrimitive json = new JsonPrimitive("Some\nEscaped\nValue");
     assertThat(json.toString()).isEqualTo("\"Some\\nEscaped\\nValue\"");
 
+    json = new JsonPrimitive("");
+    assertThat(json.toString()).isEqualTo("\"\"");
+
     json = new JsonPrimitive(new BigDecimal("1.333"));
     assertThat(json.toString()).isEqualTo("1.333");
+
+    // Preserves trailing 0
+    json = new JsonPrimitive(new BigDecimal("1.0000"));
+    assertThat(json.toString()).isEqualTo("1.0000");
+
+    json = new JsonPrimitive(Float.NaN);
+    assertThat(json.toString()).isEqualTo("NaN");
+
+    json = new JsonPrimitive(Double.NEGATIVE_INFINITY);
+    assertThat(json.toString()).isEqualTo("-Infinity");
+
+    json = new JsonPrimitive('a');
+    assertThat(json.toString()).isEqualTo("\"a\"");
+
+    json = new JsonPrimitive('\0');
+    assertThat(json.toString()).isEqualTo("\"\\u0000\"");
+
+    json = new JsonPrimitive(true);
+    assertThat(json.toString()).isEqualTo("true");
   }
 
   @Test