FormattingStyle follow-up (#2327)

* FormattingStyle follow-up

* Add links to FormattingStyle

* Use Truth for FormattingStyleTest

* Reduce pull request scope to Javadoc and minor code changes

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

@@ -16,14 +16,17 @@
 
 package com.google.gson;
 
+import com.google.gson.stream.JsonWriter;
 import java.util.Objects;
 
 /**
- * A class used to control what the serialization looks like.
+ * A class used to control what the serialization output looks like.
  *
  * <p>It currently defines the kind of newline to use, and the indent, but
  * might add more in the future.</p>
  *
+ * @see GsonBuilder#setPrettyPrinting(FormattingStyle)
+ * @see JsonWriter#setFormattingStyle(FormattingStyle)
  * @see <a href="https://en.wikipedia.org/wiki/Newline">Wikipedia Newline article</a>
  *
  * @since $next-version$
@@ -32,7 +35,11 @@ public class FormattingStyle {
   private final String newline;
   private final String indent;
 
-  static public final FormattingStyle DEFAULT =
+  /**
+   * The default pretty printing formatting style using {@code "\n"} as
+   * newline and two spaces as indent.
+   */
+  public static final FormattingStyle DEFAULT =
       new FormattingStyle("\n", "  ");
 
   private FormattingStyle(String newline, String indent) {
@@ -44,7 +51,7 @@ public class FormattingStyle {
     }
     if (!indent.matches("[ \t]*")) {
       throw new IllegalArgumentException(
-          "Only combinations of spaces and tabs allowed in indent.");
+          "Only combinations of spaces and tabs are allowed in indent.");
     }
     this.newline = newline;
     this.indent = indent;
@@ -54,7 +61,7 @@ public class FormattingStyle {
    * Creates a {@link FormattingStyle} with the specified newline setting.
    *
    * <p>It can be used to accommodate certain OS convention, for example
-   * hardcode {@code "\r"} for Linux and macos, {@code "\r\n"} for Windows, or
+   * hardcode {@code "\n"} for Linux and macOS, {@code "\r\n"} for Windows, or
    * call {@link java.lang.System#lineSeparator()} to match the current OS.</p>
    *
    * <p>Only combinations of {@code \n} and {@code \r} are allowed.</p>

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

@@ -481,6 +481,9 @@ public final class GsonBuilder {
    * Configures Gson to output JSON that fits in a page for pretty printing. This option only
    * affects JSON serialization.
    *
+   * <p>This is a convenience method which simply calls {@link #setPrettyPrinting(FormattingStyle)}
+   * with {@link FormattingStyle#DEFAULT}.
+   *
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
   public GsonBuilder setPrettyPrinting() {
@@ -488,11 +491,12 @@ public final class GsonBuilder {
   }
 
   /**
-   * Configures Gson to output JSON that uses a certain kind of formatting stile (for example newline and indent).
+   * Configures Gson to output JSON that uses a certain kind of formatting style (for example newline and indent).
-   * This option only affects JSON serialization.
+   * This option only affects JSON serialization. By default Gson produces compact JSON output without any formatting.
    *
    * <p>Has no effect if the serialized format is a single line.</p>
    *
+   * @param formattingStyle the formatting style to use.
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since $next-version$
    */

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

@@ -217,7 +217,7 @@ public class JsonWriter implements Closeable, Flushable {
    * @param indent a string containing only whitespace.
    */
   public final void setIndent(String indent) {
-    if (indent.length() == 0) {
+    if (indent.isEmpty()) {
       setFormattingStyle(null);
     } else {
       setFormattingStyle(FormattingStyle.DEFAULT.withIndent(indent));
@@ -226,7 +226,7 @@ public class JsonWriter implements Closeable, Flushable {
 
   /**
    * Sets the pretty printing style to be used in the encoded document.
-   * No pretty printing if null.
+   * No pretty printing is done if the given style is {@code null}.
    *
    * <p>Sets the various attributes to be used in the encoded document. 
    * For example the indentation string to be repeated for each level of indentation.
@@ -234,7 +234,7 @@ public class JsonWriter implements Closeable, Flushable {
    *
    * <p>Has no effect if the serialized format is a single line.</p>
    *
-   * @param formattingStyle the style used for pretty printing, no pretty printing if null.
+   * @param formattingStyle the style used for pretty printing, no pretty printing if {@code null}.
    * @since $next-version$
    */
   public final void setFormattingStyle(FormattingStyle formattingStyle) {
@@ -249,7 +249,7 @@ public class JsonWriter implements Closeable, Flushable {
   /**
    * Returns the pretty printing style used by this writer.
    *
-   * @return the FormattingStyle that will be used.
+   * @return the {@code FormattingStyle} that will be used.
    * @since $next-version$
    */
   public final FormattingStyle getFormattingStyle() {

gson/src/test/java/com/google/gson/functional/FormattingStyleTest.java

@@ -15,8 +15,7 @@
  */
 package com.google.gson.functional;
 
-import static org.junit.Assert.assertArrayEquals;
+import static com.google.common.truth.Truth.assertThat;
-import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.fail;
 
 import com.google.gson.FormattingStyle;
@@ -54,7 +53,7 @@ public class FormattingStyleTest {
     Gson gson = new GsonBuilder().setPrettyPrinting().create();
     String json = gson.toJson(INPUT);
     // Make sure the default uses LF, like before.
-    assertEquals(EXPECTED_LF, json);
+    assertThat(json).isEqualTo(EXPECTED_LF);
   }
 
   @Test
@@ -62,7 +61,7 @@ public class FormattingStyleTest {
     FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r\n");
     Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
     String json = gson.toJson(INPUT);
-    assertEquals(EXPECTED_CRLF, json);
+    assertThat(json).isEqualTo(EXPECTED_CRLF);
   }
 
   @Test
@@ -70,7 +69,7 @@ public class FormattingStyleTest {
     FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\n");
     Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
     String json = gson.toJson(INPUT);
-    assertEquals(EXPECTED_LF, json);
+    assertThat(json).isEqualTo(EXPECTED_LF);
   }
 
   @Test
@@ -78,7 +77,7 @@ public class FormattingStyleTest {
     FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r");
     Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
     String json = gson.toJson(INPUT);
-    assertEquals(EXPECTED_CR, json);
+    assertThat(json).isEqualTo(EXPECTED_CR);
   }
 
   @Test
@@ -86,7 +85,7 @@ public class FormattingStyleTest {
     FormattingStyle style = FormattingStyle.DEFAULT.withNewline(System.lineSeparator());
     Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
     String json = gson.toJson(INPUT);
-    assertEquals(EXPECTED_OS, json);
+    assertThat(json).isEqualTo(EXPECTED_OS);
   }
 
   @Test
@@ -96,7 +95,7 @@ public class FormattingStyleTest {
         FormattingStyle style = FormattingStyle.DEFAULT.withNewline(newline).withIndent(indent);
         Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
         String json = gson.toJson(INPUT);
-        assertEquals(buildExpected(newline, indent), json);
+        assertThat(json).isEqualTo(buildExpected(newline, indent));
       }
     }
   }
@@ -115,11 +114,11 @@ public class FormattingStyleTest {
 
         String toParse = buildExpected(newline, indent);
         actualParsed = gson.fromJson(toParse, INPUT.getClass());
-        assertArrayEquals(INPUT, actualParsed);
+        assertThat(actualParsed).isEqualTo(INPUT);
 
         // Parse the mixed string with the gson parsers configured with various newline / indents.
         actualParsed = gson.fromJson(jsonStringMix, INPUT.getClass());
-        assertArrayEquals(INPUT, actualParsed);
+        assertThat(actualParsed).isEqualTo(INPUT);
       }
     }
   }
@@ -127,22 +126,29 @@ public class FormattingStyleTest {
   @Test
   public void testStyleValidations() {
     try {
-      // TBD if we want to accept \u2028 and \u2029. For now we don't.
+      // TBD if we want to accept \u2028 and \u2029. For now we don't because JSON specification
+      // does not consider them to be newlines
       FormattingStyle.DEFAULT.withNewline("\u2028");
       fail("Gson should not accept anything but \\r and \\n for newline");
     } catch (IllegalArgumentException expected) {
+      assertThat(expected).hasMessageThat()
+          .isEqualTo("Only combinations of \\n and \\r are allowed in newline.");
     }
 
     try {
       FormattingStyle.DEFAULT.withNewline("NL");
       fail("Gson should not accept anything but \\r and \\n for newline");
     } catch (IllegalArgumentException expected) {
+      assertThat(expected).hasMessageThat()
+          .isEqualTo("Only combinations of \\n and \\r are allowed in newline.");
     }
 
     try {
       FormattingStyle.DEFAULT.withIndent("\f");
       fail("Gson should not accept anything but space and tab for indent");
     } catch (IllegalArgumentException expected) {
+      assertThat(expected).hasMessageThat()
+          .isEqualTo("Only combinations of spaces and tabs are allowed in indent.");
     }
   }