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 @@ private FormattingStyle(String newline, String indent) {
  }
  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 @@ private FormattingStyle(String newline, String indent) {
  * 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

@@ -482,18 +482,22 @@ public GsonBuilder addDeserializationExclusionStrategy(ExclusionStrategy strateg
  * 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() {
  return setPrettyPrinting(FormattingStyle.DEFAULT);
  }
 
  /**
- * Configures Gson to output JSON that uses a certain kind of formatting stile (for example newline and indent).
- * This option only affects JSON serialization.
+ * Configures Gson to output JSON that uses a certain kind of formatting style (for example newline and indent).
+ * 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 JsonWriter(Writer out) {
  * @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,15 +226,15 @@ public final void setIndent(String indent) {
 
  /**
  * 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.
  * Or the newline style, to accommodate various OS styles.</p>
  *
  * <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 final void setFormattingStyle(FormattingStyle formattingStyle) {
  /**
  * 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 org.junit.Assert.assertEquals;
+import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.fail;
 
 import com.google.gson.FormattingStyle;
@@ -54,39 +53,39 @@ public void testDefault() {
  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
  public void testNewlineCrLf() {
  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
  public void testNewlineLf() {
  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
  public void testNewlineCr() {
  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
  public void testNewlineOs() {
  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 void testVariousCombinationsToString() {
  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,34 +114,41 @@ public void testVariousCombinationsParse() {
 
  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);
  }
  }
  }
 
  @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.");
  }
  }