Minor follow-up changes

Troubleshooting.md

@@ -147,9 +147,12 @@ To spot syntax errors in the JSON data easily you can open it in an editor with
 
 **Reason:** Due to legacy reasons Gson performs parsing by default in lenient mode
 
-**Solution:** See [`Gson` class documentation](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/Gson.html#default-lenient) section "Lenient JSON handling"
-
-Note: Even in non-lenient mode Gson deviates slightly from the JSON specification, see [`JsonReader.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonReader.html#setStrictness(Strictness)) for more details.
+**Solution:** If you are using Gson 2.11.0 or newer, call [`GsonBuilder.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/GsonBuilder.html#setStrictness(com.google.gson.Strictness)),
+[`JsonReader.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonReader.html#setStrictness(com.google.gson.Strictness))
+and [`JsonWriter.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonWriter.html#setStrictness(com.google.gson.Strictness))
+with `Strictness.STRICT` to overwrite the default lenient behavior of `Gson` and make these classes strictly adhere to the JSON specification.
+Otherwise if you are using an older Gson version, see the [`Gson` class documentation](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/Gson.html#default-lenient)
+section "JSON Strictness handling" for alternative solutions.
 
 ## <a id="unexpected-json-structure"></a> `IllegalStateException`: "Expected ... but was ..."
 

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

@@ -136,6 +136,10 @@
  *       to make sure there is no trailing data
  * </ol>
  *
+ * Note that the {@code JsonReader} created this way is only 'legacy strict', it mostly adheres
+ * to the JSON specification but allows small deviations. See {@link JsonReader#setStrictness(Strictness)}
+ * for details.
+ *
  * @see TypeToken
  *
  * @author Inderjeet Singh
@@ -915,7 +919,7 @@ public void toJson(JsonElement jsonElement, Appendable writer) throws JsonIOExce
    *   <li>{@link GsonBuilder#serializeNulls()}</li>
    *   <li>{@link GsonBuilder#setStrictness(Strictness)}. If no
    *   {@linkplain GsonBuilder#setStrictness(Strictness) explicit strictness has been set} the created
-   *   writer will have a strictness of {@link Strictness#LEGACY_STRICT}. Otherwise, this strictness of
+   *   writer will have a strictness of {@link Strictness#LEGACY_STRICT}. Otherwise, the strictness of
    *   the {@code Gson} instance will be used for the created writer.</li>
    *   <li>{@link GsonBuilder#setPrettyPrinting()}</li>
    *   <li>{@link GsonBuilder#setFormattingStyle(FormattingStyle)}</li>
@@ -940,7 +944,7 @@ public JsonWriter newJsonWriter(Writer writer) throws IOException {
    * <ul>
    *   <li>{@link GsonBuilder#setStrictness(Strictness)}. If no
    *   {@linkplain GsonBuilder#setStrictness(Strictness) explicit strictness has been set} the created
-   *   reader will have a strictness of {@link Strictness#LEGACY_STRICT}. Otherwise, this strictness of
+   *   reader will have a strictness of {@link Strictness#LEGACY_STRICT}. Otherwise, the strictness of
    *   the {@code Gson} instance will be used for the created reader.</li>
    * </ul>
    */

gson/src/main/java/com/google/gson/stream/JsonReader.java

@@ -182,7 +182,7 @@
  * <p>Prefixing JSON files with <code>")]}'\n"</code> makes them non-executable
  * by {@code <script>} tags, disarming the attack. Since the prefix is malformed
  * JSON, strict parsing fails when it is encountered. This class permits the
- * non-execute prefix when {@link #setStrictness(Strictness) lenient parsing} is
+ * non-execute prefix when {@linkplain #setStrictness(Strictness) lenient parsing} is
  * enabled.
  *
  * <p>Each {@code JsonReader} may be used to read a single JSON stream. Instances
@@ -295,7 +295,7 @@ public JsonReader(Reader in) {
   /**
    * Sets the strictness of this reader.
    *
-   * @deprecated Please use {@link JsonReader#setStrictness(Strictness)} instead.
+   * @deprecated Please use {@link #setStrictness(Strictness)} instead.
    * {@code JsonReader.setLenient(true)} should be replaced by {@code JsonReader.setStrictness(Strictness.LENIENT)}
    * and {@code JsonReader.setLenient(false)} should be replaced by {@code JsonReader.setStrictness(Strictness.LEGACY_STRICT)}.<br>
    * However, if you used {@code setLenient(false)} before, you might prefer {@link Strictness#STRICT} now instead.

gson/src/main/java/com/google/gson/stream/JsonWriter.java

@@ -271,7 +271,7 @@ public final FormattingStyle getFormattingStyle() {
   /**
    * Sets the strictness of this writer.
    *
-   * @deprecated Please use {@link JsonWriter#setStrictness(Strictness)} instead.
+   * @deprecated Please use {@link #setStrictness(Strictness)} instead.
    * {@code JsonWriter.setLenient(true)} should be replaced by {@code JsonWriter.setStrictness(Strictness.LENIENT)}
    * and {@code JsonWriter.setLenient(false)} should be replaced by {@code JsonWriter.setStrictness(Strictness.LEGACY_STRICT)}.<br>
    * However, if you used {@code setLenient(false)} before, you might prefer {@link Strictness#STRICT} now instead.
@@ -320,7 +320,7 @@ public final void setStrictness(Strictness strictness) {
   }
 
   /**
-   * Returns how strict this writer is.
+   * Returns the {@linkplain Strictness strictness} of this writer.
    *
    * @see #setStrictness(Strictness)
    * @since $next-version$

gson/src/test/java/com/google/gson/stream/JsonReaderTest.java

@@ -41,7 +41,7 @@
 @SuppressWarnings("resource")
 public final class JsonReaderTest {
 
-  @SuppressWarnings("deprecation") // for JsonWriter.setLenient
+  @SuppressWarnings("deprecation") // for JsonReader.setLenient
   @Test
   public void testSetLenientTrue() {
     JsonReader reader = new JsonReader(reader("{}"));
@@ -145,35 +145,35 @@ public void testCapitalizedTrueFailWhenStrict() throws IOException {
   }
 
   @Test
-  public void testCapitalizedNullFailWhenStrict() throws IOException {
-    JsonReader reader = new JsonReader(reader("NULL"));
+  public void testCapitalizedFalseFailWhenStrict() throws IOException {
+    JsonReader reader = new JsonReader(reader("FALSE"));
     reader.setStrictness(Strictness.STRICT);
 
-    IOException expected = assertThrows(IOException.class, reader::nextNull);
+    IOException expected = assertThrows(IOException.class, reader::nextBoolean);
     assertThat(expected).hasMessageThat().startsWith("Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed" +
         " JSON at line 1 column 1 path $");
 
-    reader = new JsonReader(reader("nulL"));
+    reader = new JsonReader(reader("FaLse"));
     reader.setStrictness(Strictness.STRICT);
 
-    expected = assertThrows(IOException.class, reader::nextNull);
+    expected = assertThrows(IOException.class, reader::nextBoolean);
     assertThat(expected).hasMessageThat().startsWith("Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed" +
         " JSON at line 1 column 1 path $");
   }
 
   @Test
-  public void testCapitalizedFalseFailWhenStrict() throws IOException {
-    JsonReader reader = new JsonReader(reader("FALSE"));
+  public void testCapitalizedNullFailWhenStrict() throws IOException {
+    JsonReader reader = new JsonReader(reader("NULL"));
     reader.setStrictness(Strictness.STRICT);
 
-    IOException expected = assertThrows(IOException.class, reader::nextBoolean);
+    IOException expected = assertThrows(IOException.class, reader::nextNull);
     assertThat(expected).hasMessageThat().startsWith("Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed" +
         " JSON at line 1 column 1 path $");
 
-    reader = new JsonReader(reader("FaLse"));
+    reader = new JsonReader(reader("nulL"));
     reader.setStrictness(Strictness.STRICT);
 
-    expected = assertThrows(IOException.class, reader::nextBoolean);
+    expected = assertThrows(IOException.class, reader::nextNull);
     assertThat(expected).hasMessageThat().startsWith("Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed" +
         " JSON at line 1 column 1 path $");
   }
@@ -491,7 +491,7 @@ public void testCharacterUnescaping() throws IOException {
 
   @Test
   public void testReaderDoesNotTreatU2028U2029AsNewline() throws IOException {
-    // This test shows that the JSON String [\n"whatever'] is seen as valid
+    // This test shows that the JSON string [\n"whatever"] is seen as valid
     // And the JSON string [\u2028"whatever"] is not.
     String jsonInvalid2028 = "[\u2028\"whatever\"]";
     JsonReader readerInvalid2028 = new JsonReader(reader(jsonInvalid2028));

gson/src/test/java/com/google/gson/stream/JsonWriterTest.java

@@ -185,6 +185,19 @@ public void testMultipleTopLevelValuesStrict() throws IOException {
     assertThat(expected).hasMessageThat().isEqualTo("JSON must have only one top-level value.");
   }
 
+  @Test
+  public void testMultipleTopLevelValuesLenient() throws IOException {
+    StringWriter stringWriter = new StringWriter();
+    JsonWriter writer = new JsonWriter(stringWriter);
+    writer.setStrictness(Strictness.LENIENT);
+    writer.beginArray();
+    writer.endArray();
+    writer.beginArray();
+    writer.endArray();
+    writer.close();
+    assertThat(stringWriter.toString()).isEqualTo("[][]");
+  }
+
   @Test
   public void testBadNestingObject() throws IOException {
     StringWriter stringWriter = new StringWriter();
@@ -827,33 +840,6 @@ public void testPrettyPrintArray() throws IOException {
     assertThat(stringWriter.toString()).isEqualTo(expected);
   }
 
-  @Test
-  public void testLenientWriterPermitsMultipleTopLevelValues() throws IOException {
-    StringWriter stringWriter = new StringWriter();
-    JsonWriter writer = new JsonWriter(stringWriter);
-    writer.setStrictness(Strictness.LENIENT);
-    writer.beginArray();
-    writer.endArray();
-    writer.beginArray();
-    writer.endArray();
-    writer.close();
-    assertThat(stringWriter.toString()).isEqualTo("[][]");
-  }
-
-  @Test
-  public void testStrictWriterDoesNotPermitMultipleTopLevelValues() throws IOException {
-    StringWriter stringWriter = new StringWriter();
-    JsonWriter writer = new JsonWriter(stringWriter);
-    writer.beginArray();
-    writer.endArray();
-    try {
-      writer.beginArray();
-      fail();
-    } catch (IllegalStateException expected) {
-      assertThat(expected).hasMessageThat().isEqualTo("JSON must have only one top-level value.");
-    }
-  }
-
   @Test
   public void testClosedWriterThrowsOnStructure() throws IOException {
     StringWriter stringWriter = new StringWriter();