Document default JsonReader configuration & improve doc

google · Aug 4, 2023 · e79ac0e · e79ac0e
1 parent 25e4e25
commit e79ac0e
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 12 deletions.
diff --git a/gson/src/main/java/com/google/gson/TypeAdapter.java b/gson/src/main/java/com/google/gson/TypeAdapter.java
@@ -130,9 +130,10 @@ public TypeAdapter() {
 
   /**
    * Converts {@code value} to a JSON document and writes it to {@code out}.
-   * A {@link JsonWriter} with default configuration is used for writing the JSON
-   * data. To customize this behavior, create a {@link JsonWriter}, configure it
-   * and then use {@link #write(JsonWriter, Object)} instead.
+   *
+   * <p>A {@link JsonWriter} with default configuration is used for writing the
+   * JSON data. To customize this behavior, create a {@link JsonWriter}, configure
+   * it and then use {@link #write(JsonWriter, Object)} instead.
    *
    * @param value the Java object to convert. May be {@code null}.
    * @since 2.2
@@ -201,9 +202,10 @@ public final TypeAdapter<T> nullSafe() {
 
   /**
    * Converts {@code value} to a JSON document.
-   * A {@link JsonWriter} with default configuration is used for writing the JSON
-   * data. To customize this behavior, create a {@link JsonWriter}, configure it
-   * and then use {@link #write(JsonWriter, Object)} instead.
+   *
+   * <p>A {@link JsonWriter} with default configuration is used for writing the
+   * JSON data. To customize this behavior, create a {@link JsonWriter}, configure
+   * it and then use {@link #write(JsonWriter, Object)} instead.
    *
    * @throws JsonIOException wrapping {@code IOException}s thrown by {@link #write(JsonWriter, Object)}
    * @param value the Java object to convert. May be {@code null}.
@@ -247,7 +249,8 @@ public final JsonElement toJsonTree(T value) {
 
   /**
    * Converts the JSON document in {@code in} to a Java object.
-   * A {@link JsonReader} with default configuration (that is with
+   *
+   * <p>A {@link JsonReader} with default configuration (that is with
    * {@link Strictness#LEGACY_STRICT} as strictness) is used for reading the JSON data.
    * To customize this behavior, create a {@link JsonReader}, configure it and then
    * use {@link #read(JsonReader)} instead.
@@ -265,7 +268,8 @@ public final T fromJson(Reader in) throws IOException {
 
   /**
    * Converts the JSON document in {@code json} to a Java object.
-   * A {@link JsonReader} with default configuration (that is with
+   *
+   * <p>A {@link JsonReader} with default configuration (that is with
    * {@link Strictness#LEGACY_STRICT} as strictness) is used for reading the JSON data.
    * To customize this behavior, create a {@link JsonReader}, configure it and then
    * use {@link #read(JsonReader)} instead.

diff --git a/gson/src/main/java/com/google/gson/stream/JsonReader.java b/gson/src/main/java/com/google/gson/stream/JsonReader.java
@@ -16,6 +16,8 @@
 
 package com.google.gson.stream;
 
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
 import com.google.gson.Strictness;
 import com.google.gson.internal.JsonReaderInternalAccess;
 import com.google.gson.internal.TroubleshootingGuide;
@@ -64,6 +66,16 @@
  * Null literals can be consumed using either {@link #nextNull()} or {@link
  * #skipValue()}.
  *
+ * <h2>Configuration</h2>
+ * The behavior of this reader can be customized with the following methods:
+ * <ul>
+ *   <li>{@link #setStrictness(Strictness)}, the default is {@link Strictness#LEGACY_STRICT}
+ * </ul>
+ *
+ * The default configuration of {@code JsonReader} instances used internally by
+ * the {@link Gson} class differs, and can be adjusted with the various
+ * {@link GsonBuilder} methods.
+ *
  * <h2>Example</h2>
  * Suppose we'd like to parse a stream of messages such as the following: <pre> {@code
  * [

diff --git a/gson/src/main/java/com/google/gson/stream/JsonWriter.java b/gson/src/main/java/com/google/gson/stream/JsonWriter.java
@@ -26,6 +26,8 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.gson.FormattingStyle;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
 import com.google.gson.Strictness;
 import java.io.Closeable;
 import java.io.Flushable;
@@ -64,15 +66,17 @@
  * <h2>Configuration</h2>
  * The behavior of this writer can be customized with the following methods:
  * <ul>
- *   <li>{@link #setFormattingStyle(FormattingStyle)}, by default a compact
- *       formatting style is used which does not write any whitespace
+ *   <li>{@link #setFormattingStyle(FormattingStyle)}, the default is {@link FormattingStyle#COMPACT}
  *   <li>{@link #setHtmlSafe(boolean)}, by default HTML characters are not escaped
  *       in the JSON output
- *   <li>{@link #setStrictness(Strictness)}, the default strictness is
- *       {@link Strictness#LEGACY_STRICT}
+ *   <li>{@link #setStrictness(Strictness)}, the default is {@link Strictness#LEGACY_STRICT}
  *   <li>{@link #setSerializeNulls(boolean)}, by default {@code null} is serialized
  * </ul>
  *
+ * The default configuration of {@code JsonWriter} instances used internally by
+ * the {@link Gson} class differs, and can be adjusted with the various
+ * {@link GsonBuilder} methods.
+ *
  * <h2>Example</h2>
  * Suppose we'd like to encode a stream of messages such as the following: <pre> {@code
  * [