Perform minor code clean-up (google#2544)

* Perform minor code clean-up

Notable changes:
- Replace most usages of `<code>` with `{@code ...}` in Javadoc
- Add proper summary sentence to `GsonBuilder.enableComplexMapKeySerialization`
- Extend documentation for `GsonBuilder.setDateFormat` methods
- Fix `TypeToken.isAssignableFrom(Type)` throwing AssertionError in some cases
  Maybe the method should not throw an exception in the first place, but it
  might not matter much since it is deprecated already anyway.
- Remove outdated `throws NumberFormatException` from internal
  `JsonReader.nextQuotedValue`; the behavior had been changed by
  85ebaf7
- Fix incorrect documentation on JsonScope fields
- Fix unit tests having 'expected' and 'actual' switched
- Use dedicated Truth methods instead of `isTrue()` / `isFalse()`
- Use common helper methods in JsonWriterTest to avoid duplication

* Implement `toString()` for ReflectionAccessFilter constants

* Address most of the review comments

* Add comment about `source.scm.tag=HEAD` warning

Actually it looks like the warning is not actually caused by usage of
`HEAD` as value, but rather because the project has a snapshot version
during development (which is expected though), see
https://github.com/apache/maven-artifact-plugin/blob/maven-artifact-plugin-3.5.0/src/main/java/org/apache/maven/plugins/artifact/buildinfo/BuildInfoWriter.java#L140

But this is not a problem either since during release a non-snapshot
version is used.

examples/android-proguard-example/src/com/google/gson/examples/android/GsonProguardExampleActivity.java

@@ -41,13 +41,13 @@ public void onCreate(Bundle icicle) {
  Cart cart = buildCart();
  StringBuilder sb = new StringBuilder();
  sb.append("Gson.toJson() example: \n");
- sb.append(" Cart Object: ").append(cart).append("\n");
- sb.append(" Cart JSON: ").append(gson.toJson(cart)).append("\n");
+ sb.append(" Cart Object: ").append(cart).append('\n');
+ sb.append(" Cart JSON: ").append(gson.toJson(cart)).append('\n');
  sb.append("\n\nGson.fromJson() example: \n");
  String json = "{buyer:'Happy Camper',creditCard:'4111-1111-1111-1111',"
  + "lineItems:[{name:'nails',priceInMicros:100000,quantity:100,currencyCode:'USD'}]}";
- sb.append("Cart JSON: ").append(json).append("\n");
- sb.append("Cart Object: ").append(gson.fromJson(json, Cart.class)).append("\n");
+ sb.append("Cart JSON: ").append(json).append('\n');
+ sb.append("Cart Object: ").append(gson.fromJson(json, Cart.class)).append('\n');
  tv.setText(sb.toString());
  tv.invalidate();
  }

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

@@ -222,9 +222,9 @@ public final class Gson {
  * following settings:
  *
  * <ul>
- * <li>The JSON generated by <code>toJson</code> methods is in compact representation. This
- * means that all the unneeded white-space is removed. You can change this behavior with
- * {@link GsonBuilder#setPrettyPrinting()}.
+ * <li>The JSON generated by {@code toJson} methods is in compact representation. This means
+ * that all the unneeded white-space is removed. You can change this behavior with {@link
+ * GsonBuilder#setPrettyPrinting()}.
  * <li>When the JSON generated contains more than one line, the kind of newline and indent to
  * use can be configured with {@link GsonBuilder#setFormattingStyle(FormattingStyle)}.
  * <li>The generated JSON omits all the fields that are null. Note that nulls in arrays are kept
@@ -246,13 +246,12 @@ public final class Gson {
  * <li>By default, Gson ignores the {@link com.google.gson.annotations.Since} annotation. You
  * can enable Gson to use this annotation through {@link GsonBuilder#setVersion(double)}.
  * <li>The default field naming policy for the output JSON is same as in Java. So, a Java class
- * field <code>versionNumber</code> will be output as <code>&quot;versionNumber&quot;</code>
- * in JSON. The same rules are applied for mapping incoming JSON to the Java classes. You
- * can change this policy through {@link
- * GsonBuilder#setFieldNamingPolicy(FieldNamingPolicy)}.
- * <li>By default, Gson excludes <code>transient</code> or <code>static</code> fields from
- * consideration for serialization and deserialization. You can change this behavior through
- * {@link GsonBuilder#excludeFieldsWithModifiers(int...)}.
+ * field {@code versionNumber} will be output as {@code "versionNumber"} in JSON. The same
+ * rules are applied for mapping incoming JSON to the Java classes. You can change this
+ * policy through {@link GsonBuilder#setFieldNamingPolicy(FieldNamingPolicy)}.
+ * <li>By default, Gson excludes {@code transient} or {@code static} fields from consideration
+ * for serialization and deserialization. You can change this behavior through {@link
+ * GsonBuilder#excludeFieldsWithModifiers(int...)}.
  * <li>No explicit strictness is set. You can change this by calling {@link
  * GsonBuilder#setStrictness(Strictness)}.
  * </ul>
@@ -680,8 +679,8 @@ public <T> TypeAdapter<T> getAdapter(TypeToken<T> type) {
  * is an example:
  *
  * <p>Let's say we want to write a type adapter that counts the number of objects being read from
- * or written to JSON. We can achieve this by writing a type adapter factory that uses the <code>
- * getDelegateAdapter</code> method:
+ * or written to JSON. We can achieve this by writing a type adapter factory that uses the {@code
+ * getDelegateAdapter} method:
  *
  * <pre>{@code
  * class StatsTypeAdapterFactory implements TypeAdapterFactory {

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

@@ -227,8 +227,8 @@ public GsonBuilder excludeFieldsWithoutExposeAnnotation() {
  }
 
  /**
- * Configure Gson to serialize null fields. By default, Gson omits all fields that are null during
- * serialization.
+ * Configures Gson to serialize null fields. By default, Gson omits all fields that are null
+ * during serialization.
  *
  * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
  * @since 1.2
@@ -240,10 +240,11 @@ public GsonBuilder serializeNulls() {
  }
 
  /**
- * Enabling this feature will only change the serialized form if the map key is a complex type
- * (i.e. non-primitive) in its <strong>serialized</strong> JSON form. The default implementation
- * of map serialization uses {@code toString()} on the key; however, when this is called then one
- * of the following cases apply:
+ * Configures Gson to serialize {@code Map} objects with complex keys as JSON arrays. Enabling
+ * this feature will only change the serialized form if the map key is a complex type (i.e.
+ * non-primitive) in its <strong>serialized</strong> JSON form. The default implementation of map
+ * serialization uses {@code toString()} on the key; however, when this is called then one of the
+ * following cases apply:
  *
  * <p><b>Maps as JSON objects</b>
  *
@@ -622,23 +623,24 @@ private static int checkDateFormatStyle(int style) {
  }
 
  /**
- * Configures Gson to serialize {@code Date} objects according to the style value provided. You
- * can call this method or {@link #setDateFormat(String)} multiple times, but only the last
- * invocation will be used to decide the serialization format.
+ * Configures Gson to serialize {@code Date} objects according to the date style value provided.
+ * You can call this method or {@link #setDateFormat(String)} multiple times, but only the last
+ * invocation will be used to decide the serialization format. This methods leaves the current
+ * 'time style' unchanged.
  *
- * <p>Note that this style value should be one of the predefined constants in the {@code
- * DateFormat} class. See the documentation in {@link java.text.DateFormat} for more information
- * on the valid style constants.
+ * <p>Note that this style value should be one of the predefined constants in the {@link
+ * DateFormat} class, such as {@link DateFormat#MEDIUM}. See the documentation of the {@link
+ * DateFormat} class for more information on the valid style constants.
  *
- * @param style the predefined date style that date objects will be serialized/deserialized
+ * @param dateStyle the predefined date style that date objects will be serialized/deserialized
  * to/from
  * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
  * @throws IllegalArgumentException if the style is invalid
  * @since 1.2
  */
  @CanIgnoreReturnValue
- public GsonBuilder setDateFormat(int style) {
- this.dateStyle = checkDateFormatStyle(style);
+ public GsonBuilder setDateFormat(int dateStyle) {
+ this.dateStyle = checkDateFormatStyle(dateStyle);
  this.datePattern = null;
  return this;
  }
@@ -648,9 +650,9 @@ public GsonBuilder setDateFormat(int style) {
  * can call this method or {@link #setDateFormat(String)} multiple times, but only the last
  * invocation will be used to decide the serialization format.
  *
- * <p>Note that this style value should be one of the predefined constants in the {@code
- * DateFormat} class. See the documentation in {@link java.text.DateFormat} for more information
- * on the valid style constants.
+ * <p>Note that this style value should be one of the predefined constants in the {@link
+ * DateFormat} class, such as {@link DateFormat#MEDIUM}. See the documentation of the {@link
+ * DateFormat} class for more information on the valid style constants.
  *
  * @param dateStyle the predefined date style that date objects will be serialized/deserialized
  * to/from

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

@@ -117,6 +117,11 @@ public FilterResult check(Class<?> rawClass) {
  ? FilterResult.BLOCK_INACCESSIBLE
  : FilterResult.INDECISIVE;
  }
+
+ @Override
+ public String toString() {
+ return "ReflectionAccessFilter#BLOCK_INACCESSIBLE_JAVA";
+ }
  };
 
  /**
@@ -143,6 +148,11 @@ public FilterResult check(Class<?> rawClass) {
  ? FilterResult.BLOCK_ALL
  : FilterResult.INDECISIVE;
  }
+
+ @Override
+ public String toString() {
+ return "ReflectionAccessFilter#BLOCK_ALL_JAVA";
+ }
  };
 
  /**
@@ -169,6 +179,11 @@ public FilterResult check(Class<?> rawClass) {
  ? FilterResult.BLOCK_ALL
  : FilterResult.INDECISIVE;
  }
+
+ @Override
+ public String toString() {
+ return "ReflectionAccessFilter#BLOCK_ALL_ANDROID";
+ }
  };
 
  /**
@@ -196,6 +211,11 @@ public FilterResult check(Class<?> rawClass) {
  ? FilterResult.BLOCK_ALL
  : FilterResult.INDECISIVE;
  }
+
+ @Override
+ public String toString() {
+ return "ReflectionAccessFilter#BLOCK_ALL_PLATFORM";
+ }
  };
 
  /**

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

@@ -68,11 +68,11 @@
  * #write(JsonWriter,Object) write()} must write exactly one value. For primitive types this is
  * means readers should make exactly one call to {@code nextBoolean()}, {@code nextDouble()}, {@code
  * nextInt()}, {@code nextLong()}, {@code nextString()} or {@code nextNull()}. Writers should make
- * exactly one call to one of <code>value()</code> or <code>nullValue()</code>. For arrays, type
- * adapters should start with a call to {@code beginArray()}, convert all elements, and finish with
- * a call to {@code endArray()}. For objects, they should start with {@code beginObject()}, convert
- * the object, and finish with {@code endObject()}. Failing to convert a value or converting too
- * many values may cause the application to crash.
+ * exactly one call to one of {@code value()} or {@code nullValue()}. For arrays, type adapters
+ * should start with a call to {@code beginArray()}, convert all elements, and finish with a call to
+ * {@code endArray()}. For objects, they should start with {@code beginObject()}, convert the
+ * object, and finish with {@code endObject()}. Failing to convert a value or converting too many
+ * values may cause the application to crash.
  *
  * <p>Type adapters should be prepared to read null from the stream and write it to the stream.
  * Alternatively, they should use {@link #nullSafe()} method while registering the type adapter with

gson/src/main/java/com/google/gson/reflect/TypeToken.java

@@ -20,7 +20,6 @@
 package com.google.gson.reflect;
 
 import com.google.gson.internal.$Gson$Types;
-import com.google.gson.internal.InvalidStateException;
 import com.google.gson.internal.TroubleshootingGuide;
 import java.lang.reflect.GenericArrayType;
 import java.lang.reflect.ParameterizedType;
@@ -204,7 +203,7 @@ public boolean isAssignableFrom(Type from) {
  return rawType.isAssignableFrom($Gson$Types.getRawType(from))
  && isAssignableFrom(from, (GenericArrayType) type);
  } else {
- throw buildUnexpectedTypeError(
+ throw buildUnsupportedTypeException(
  type, Class.class, ParameterizedType.class, GenericArrayType.class);
  }
  }
@@ -313,21 +312,21 @@ private static boolean typeEquals(
  return false;
  }
 
- private static InvalidStateException buildUnexpectedTypeError(Type token, Class<?>... expected) {
+ private static IllegalArgumentException buildUnsupportedTypeException(
+ Type token, Class<?>... expected) {
 
  // Build exception message
- StringBuilder exceptionMessage = new StringBuilder("Unexpected type. Expected one of: ");
+ StringBuilder exceptionMessage = new StringBuilder("Unsupported type, expected one of: ");
  for (Class<?> clazz : expected) {
  exceptionMessage.append(clazz.getName()).append(", ");
  }
  exceptionMessage
  .append("but got: ")
  .append(token.getClass().getName())
  .append(", for type token: ")
- .append(token.toString())
- .append('.');
+ .append(token.toString());
 
- return new InvalidStateException(exceptionMessage.toString());
+ return new IllegalArgumentException(exceptionMessage.toString());
  }
 
  /**

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

@@ -1060,7 +1060,6 @@ public long nextLong() throws IOException {
  * consumes the closing quote, but does not include it in the returned string.
  *
  * @param quote either ' or ".
- * @throws NumberFormatException if any unicode escape sequences are malformed.
  */
  private String nextQuotedValue(char quote) throws IOException {
  // Like nextNonWhitespace, this uses locals 'p' and 'l' to save inner-loop field access.
@@ -1531,7 +1530,7 @@ private int nextNonWhitespace(boolean throwOnEof) throws IOException {
  }
  }
 
- private void checkLenient() throws IOException {
+ private void checkLenient() throws MalformedJsonException {
  if (strictness != Strictness.LENIENT) {
  throw syntaxError(
  "Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed JSON");
@@ -1659,7 +1658,7 @@ public String getPath() {
  * backslash. The backslash '\' should have already been read. This supports both Unicode escapes
  * "u000A" and two-character escapes "\n".
  *
- * @throws MalformedJsonException if any Unicode escape sequences are malformed.
+ * @throws MalformedJsonException if the escape sequence is malformed
  */
  @SuppressWarnings("fallthrough")
  private char readEscapeCharacter() throws IOException {
@@ -1729,10 +1728,10 @@ private char readEscapeCharacter() throws IOException {
  }
 
  /**
- * Throws a new IO exception with the given message and a context snippet with this reader's
- * content.
+ * Throws a new {@link MalformedJsonException} with the given message and information about the
+ * current location.
  */
- private IOException syntaxError(String message) throws IOException {
+ private MalformedJsonException syntaxError(String message) throws MalformedJsonException {
  throw new MalformedJsonException(
  message + locationString() + "\nSee " + TroubleshootingGuide.createUrl("malformed-json"));
  }

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

@@ -24,28 +24,25 @@
  */
 final class JsonScope {
 
- /** An array with no elements requires no separators or newlines before it is closed. */
+ /** An array with no elements requires no separator before the next element. */
  static final int EMPTY_ARRAY = 1;
 
- /** An array with at least one value requires a comma and newline before the next element. */
+ /** An array with at least one value requires a separator before the next element. */
  static final int NONEMPTY_ARRAY = 2;
 
- /** An object with no name/value pairs requires no separators or newlines before it is closed. */
+ /** An object with no name/value pairs requires no separator before the next element. */
  static final int EMPTY_OBJECT = 3;
 
  /** An object whose most recent element is a key. The next element must be a value. */
  static final int DANGLING_NAME = 4;
 
- /**
- * An object with at least one name/value pair requires a comma and newline before the next
- * element.
- */
+ /** An object with at least one name/value pair requires a separator before the next element. */
  static final int NONEMPTY_OBJECT = 5;
 
- /** No object or array has been started. */
+ /** No top-level value has been started yet. */
  static final int EMPTY_DOCUMENT = 6;
 
- /** A document with at an array or object. */
+ /** A top-level value has already been started. */
  static final int NONEMPTY_DOCUMENT = 7;
 
  /** A document that's been closed and cannot be accessed. */

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

@@ -356,9 +356,9 @@ public final Strictness getStrictness() {
 
  /**
  * Configures this writer to emit JSON that's safe for direct inclusion in HTML and XML documents.
- * This escapes the HTML characters {@code <}, {@code >}, {@code &} and {@code =} before writing
- * them to the stream. Without this setting, your XML/HTML encoder should replace these characters
- * with the corresponding escape sequences.
+ * This escapes the HTML characters {@code <}, {@code >}, {@code &}, {@code =} and {@code '}
+ * before writing them to the stream. Without this setting, your XML/HTML encoder should replace
+ * these characters with the corresponding escape sequences.
  */
  public final void setHtmlSafe(boolean htmlSafe) {
  this.htmlSafe = htmlSafe;

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

@@ -297,7 +297,7 @@ public void testEqualsAcrossTypes() {
  new JsonPrimitive(new BigInteger("0")), new JsonPrimitive(0));
  MoreAsserts.assertEqualsAndHashCode(new JsonPrimitive(0), new JsonPrimitive(0L));
  MoreAsserts.assertEqualsAndHashCode(
- new JsonPrimitive(new BigInteger("0")), new JsonPrimitive(0));
+ new JsonPrimitive(new BigDecimal("0")), new JsonPrimitive(0));
  MoreAsserts.assertEqualsAndHashCode(
  new JsonPrimitive(Float.NaN), new JsonPrimitive(Double.NaN));
  }

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

@@ -74,11 +74,9 @@ public void testReadMixedStreamed() throws IOException {
  JsonReader jsonReader = new JsonReader(stringReader);
 
  jsonReader.beginArray();
- // actual and expected object are inverted in the test.
- // gson.fromJson(jsonReader, Car.class) as arg of assertThat() cause an ambiguous method call
- assertThat(BLUE_MUSTANG).isEqualTo(gson.fromJson(jsonReader, Car.class));
- assertThat(BLACK_BMW).isEqualTo(gson.fromJson(jsonReader, Car.class));
- assertThat(RED_MIATA).isEqualTo(gson.fromJson(jsonReader, Car.class));
+ assertThat(gson.<Car>fromJson(jsonReader, Car.class)).isEqualTo(BLUE_MUSTANG);
+ assertThat(gson.<Car>fromJson(jsonReader, Car.class)).isEqualTo(BLACK_BMW);
+ assertThat(gson.<Car>fromJson(jsonReader, Car.class)).isEqualTo(RED_MIATA);
  jsonReader.endArray();
  }